🇬🇧 English version
Transcrire de l'audio avec Whisper par un serveur MCP
Voir aussi : Intégration MCP ·
orkeon-repl· Écrire une crew en TypeScript · Retour à l'index
Orkeon ne livre aucun outil de transcription, et orkeon-repl ne capte pas de micro. L'entrée
est un serveur MCP : orkeon-repl connecte les serveurs que ses réglages déclarent sous
MCP:Servers avant de charger ses commandes, et les outils qu'ils exposent entrent dans le
registre d'outils sous leur propre nom. Un agent de crew liste un tel outil par son nom, une
commande *.cmd.ts l'atteint par son espace de noms tools, et ctx.llm.act le donne au modèle
— voir Intégration MCP. orkeon run et orkeon-host lisent
la même section : les mêmes réglages leur donnent le même outil.
Ce guide branche un Whisper local (faster-whisper)
derrière un outil, transcribe_audio : les réglages, un serveur minimal, la façon dont un agent
l'appelle, et les limites d'Orkeon autour desquelles le serveur est écrit.
agent ── .tools(["transcribe_audio"]) ──► registre d'outils ──► client MCP (stdio)
│
whisper_mcp.py ◄────────────┘
lit <dossier audio>/meeting.m4a (= /audio/meeting.m4a)
écrit <dossier transcriptions>/meeting.txt (= /transcripts/meeting.txt)
agent ── file_read("/transcripts/meeting.txt") ──► la transcription entière
1. Le serveur
Le serveur est le vôtre : Orkeon ne le livre pas, et sa CI ne l'exécute pas. Il demande Python 3.9
ou plus, le paquet mcp (sa classe FastMCP) et faster-whisper ;
uv récupère les deux au premier lancement.
# whisper_mcp.py - un serveur MCP exposant un outil, transcribe_audio, sur stdio.
import os
from pathlib import Path
from mcp.server.fastmcp import FastMCP
AUDIO_DIR = Path(os.environ["WHISPER_AUDIO_DIR"]).resolve() # le dossier qu'Orkeon monte en /audio
OUT_DIR = Path(os.environ["WHISPER_OUT_DIR"]).resolve() # le dossier qu'Orkeon monte en /transcripts
INLINE_LIMIT = 3500 # under Orkeon's 4000-character cap
mcp = FastMCP("whisper")
_model = None
def model():
# Chargé au premier appel, jamais au démarrage : Orkeon attend 30 s la poignée de main.
global _model
if _model is None:
from faster_whisper import WhisperModel
_model = WhisperModel(
os.environ.get("WHISPER_MODEL", "small"),
device=os.environ.get("WHISPER_DEVICE", "cpu"),
compute_type=os.environ.get("WHISPER_COMPUTE_TYPE", "int8"))
return _model
@mcp.tool()
def transcribe_audio(path: str, language: str = "") -> str:
"""Transcribe an audio file under /audio (an Orkeon virtual path, e.g. /audio/meeting.m4a).
language: an ISO code such as 'fr' or 'en'; empty to detect it."""
if not path.startswith("/audio/"):
raise ValueError("path must be under /audio/")
source = (AUDIO_DIR / path.removeprefix("/audio/")).resolve()
if not source.is_relative_to(AUDIO_DIR) or not source.is_file():
raise ValueError(f"no audio file at {path}")
segments, info = model().transcribe(str(source), language=language or None)
text = " ".join(segment.text.strip() for segment in segments)
target = OUT_DIR / source.relative_to(AUDIO_DIR).with_suffix(".txt")
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(text, encoding="utf-8")
virtual = "/transcripts/" + target.relative_to(OUT_DIR).as_posix()
if len(text) <= INLINE_LIMIT:
return f"{text}\n\n(also written to {virtual})"
return (f"Transcript of {len(text)} characters (language {info.language}) written to {virtual}; "
f"read it with file_read. It begins: {text[:500]}")
if __name__ == "__main__":
mcp.run() # stdio
language est une simple chaîne à défaut vide plutôt qu'une chaîne optionnelle : le client MCP
convertit chaque propriété du schéma d'entrée de l'outil en paramètre Orkeon d'après son type, et
un string simple garde lisible le schéma que l'agent reçoit. Une exception levée par l'outil
parvient à l'agent comme un appel échoué portant son message.
2. Les réglages
Ajoutez les deux sections au fichier de réglages que orkeon-repl lit déjà — le fichier global
qu'écrit orkeon init, ou celui que nomme --settings (un fichier nommé sur la ligne de commande
remplace le global) :
{
"Orkeon": {
"FileSystem": {
"Mounts": [
"/home/me/audio:/audio:ro",
"/home/me/transcripts:/transcripts:ro"
]
}
},
"MCP": {
"Servers": {
"whisper": {
"Transport": "Stdio",
"Command": "uv",
"Args": [ "run", "--with", "mcp", "--with", "faster-whisper", "/home/me/mcp/whisper_mcp.py" ],
"Env": {
"WHISPER_AUDIO_DIR": "/home/me/audio",
"WHISPER_OUT_DIR": "/home/me/transcripts",
"WHISPER_MODEL": "small"
}
}
}
}
}
- Les deux dossiers apparaissent deux fois, et doivent concorder : côté physique d'un montage,
et dans
Env. Les agents connaissent/audioet/transcripts; le serveur connaît les dossiers. Commandest un programme, pas une ligne de shell : le client lanceuvavecArgspour arguments, trouvé dans lePATHdu processus qui le lance.Envs'ajoute à l'environnement dont le serveur hérite. Une clé dont un serveur à API a besoin (OPENAI_API_KEY) est exportée dans le shell qui lance le REPL, jamais écrite dans le fichier de réglages.WHISPER_MODELprend un nom de modèle faster-whisper (tiny,base,small,medium,large-v3, …) ;WHISPER_DEVICE=cudaavecWHISPER_COMPUTE_TYPE=float16le fait tourner sur GPU.
Lancez le REPL comme d'habitude. Un serveur qui ne peut être connecté coûte une ligne d'erreur qui le nomme, dans le journal et sur stderr, et le REPL démarre sans lui ; un serveur qui s'arrête avant de répondre y ajoute son code de sortie et la dernière ligne qu'il a écrite sur stderr.
3. L'appeler
Dans une crew .ork.ts, l'agent liste l'outil à côté de file_read, qui lit une transcription
longue :
const secretary = agentBuilder()
.name("secretary")
.role("Meeting secretary")
.goal("Turn a recorded meeting into minutes: decisions, owners, open questions")
.backstory("Transcribes first, then writes only what the transcript says.")
.tools(["transcribe_audio", "file_read"])
.build();
Les mêmes noms vont dans une crew YAML (tools: [transcribe_audio, file_read]). Sous
StrictTools — le défaut des runners — une crew qui nomme transcribe_audio alors que le serveur
n'est pas connecté échoue au chargement avec la ligne ordinaire unknown tool(s), qui liste les
outils disponibles.
Pourquoi le serveur est écrit ainsi
| Comportement d'Orkeon | Où | Ce qu'en fait le serveur |
|---|---|---|
| Le serveur est un processus à part : il lit le disque, pas le VFS. Les agents ne connaissent que des chemins virtuels, et le client transmet les arguments tels quels. | McpToolAdapter.CallAsync |
Il fait correspondre /audio/… à son propre dossier et refuse un chemin qui en sort. Le ro du montage lie les agents, pas le serveur : le serveur lit et écrit ce que peut son utilisateur système. |
Seuls les blocs text d'un résultat parviennent à l'agent. |
McpToolAdapter.CallAsync |
Il renvoie du texte. |
Un résultat d'outil est coupé à 4000 caractères ; file_read a droit à 32 000. |
AgentDefaults.MaxToolResultLength, MaxToolResultLengthOverrides |
Il écrit la transcription entière dans un fichier et renvoie son chemin virtuel quand le texte dépasse INLINE_LIMIT. |
| Le handshake doit répondre en 30 s au démarrage. | le pas de démarrage MCP des runners | Il charge le modèle au premier appel. |
| Un nom d'outil que le registre détient déjà est refusé ; l'outil antérieur le garde. | McpToolProvider |
Il nomme son outil transcribe_audio, aucun nom d'outil intégré. |
Le handshake legacy demande 2025-11-25 et refuse un serveur qui répond 2025-03-26. |
McpClient.InitializeAsync |
Il demande un paquet mcp qui ne répond pas 2025-03-26 (le client accepte 2025-11-25, 2025-06-18 et 2024-11-05) ; uv run --with mcp prend le dernier. |
Le transport HTTP n'envoie un en-tête Authorization que depuis Auth (un identifiant bearer ou basic lu dans l'environnement) ; pas d'OAuth. |
StreamableHttpMcpTransport, IMcpRequestAuthenticator |
Il passe par stdio. |
Une transcription est une donnée venue de l'extérieur : elle traverse l'assainisseur de résultats
comme tout résultat d'outil (Security:ToolResults), de sorte qu'un enregistrement qui dit
« ignore previous instructions » est filtré comme une page web — de façon heuristique, voir
Sécurité.
Variantes
- L'API de transcription d'OpenAI au lieu d'un modèle local : remplacez
model().transcribe(...)par un appel du paquetopenai(client.audio.transcriptions.create), ajoutez-le ÃArgs(--with openai), et exportezOPENAI_API_KEYavant de lancer le REPL. Le fichier audio quitte la machine. - Un plugin au lieu d'un serveur MCP : un outil C# chargé depuis la section
Plugins(Plugins) lit l'audio parIFileSystemService, en chemins virtuels et sous les droits du montage, ce qui supprime la correspondance de chemins ci-dessus ; il tourne avec les droits du REPL, et c'est du C# à écrire et compiler.
Dépannage
| Symptôme | Cause |
|---|---|
… the MCP server exited with code 1; its last line on stderr: KeyError: 'WHISPER_AUDIO_DIR' |
Env n'a pas une variable que lit le serveur. |
La ligne d'erreur du serveur dit An error occurred trying to start process 'uv' … |
uv n'est pas dans le PATH du processus du REPL : donnez à Command son chemin complet. |
MCP server selected protocol version '2025-03-26', which this client does not support |
Un paquet mcp ancien. Mettez-le à jour, ou laissez uv run --with mcp prendre le dernier. |
Crew configuration references unknown tool(s): transcribe_audio |
Le serveur n'a pas été connecté : lisez la ligne d'erreur qui la précède dans le journal. |
| Le premier appel prend des minutes | faster-whisper télécharge le modèle à sa première utilisation (plusieurs centaines de Mo pour small), puis le lit dans son cache. Sur une connexion limitée, récupérez-le une fois à l'avance. |
no audio file at /audio/… |
Le fichier n'est pas dans WHISPER_AUDIO_DIR, ou le montage et Env nomment des dossiers différents. |