MCP Server

Le package packages/mcp-server (@runeya/packages-mcp-server) expose les outils Runeya aux clients IA via le Model Context Protocol (MCP). Il permet à un agent IA externe (ex. Claude Desktop) de contrôler Runeya — lister les services, les démarrer, les arrêter, et consulter leurs logs.

Rôle dans l'architecture

Client IA (ex. Claude Desktop)
        │ MCP (stdio)
┌───────▼──────────────────────┐
│      MCP Server (stdio)      │
│  packages/mcp-server         │
└───────┬──────────────────────┘
        │ HTTP tRPC
┌───────▼──────────────────────┐
│   Local Server (port 9545)   │
│   apps/server                │
└──────────────────────────────┘

Le MCP Server est un processus Node.js indépendant qui communique avec son client IA via stdio (transport standard MCP) et transmet les commandes au serveur local Runeya via HTTP.

Variables d'environnement

Variable	Par défaut	Description
RUNEYA_BASE_URL	http://localhost:4000	URL du serveur local Runeya
RUNEYA_CONVERSATION_ID	(vide)	ID de conversation — active l'outil ask_user en mode scénario
RUNEYA_INTERNAL_TOKEN	(vide)	Token interne — requis avec RUNEYA_CONVERSATION_ID

Port du serveur

Par défaut, le serveur Runeya écoute sur le port 9545. Définir RUNEYA_BASE_URL=http://localhost:9545 si le serveur tourne sur ce port.

Outils MCP exposés

Les outils sont définis dans packages/shared via RUNEYA_TOOL_DEFINITIONS et enregistrés dynamiquement.

Outil MCP	Route tRPC	Description
list_services	service.list	Liste tous les services Runeya
get_service_status	process.status	Récupère le statut d'un service
start_service	process.start	Démarre un service
stop_service	process.stop	Arrête un service
restart_service	process.restart	Redémarre un service
get_logs	process.logs	Récupère les logs d'un service
ask_user (scénario)	scenario.requestInput	Pose une question à l'utilisateur et attend sa réponse

Paramètres communs

Tous les outils qui opèrent sur un service acceptent :

Paramètre	Type	Description
serviceId	string	UUID du service
agentId	string	UUID de l'agent Runeya qui exécute le service
authToken	string (optionnel)	Bearer token JWT pour l'authentification

Outil ask_user (mode scénario uniquement)

L'outil ask_user n'est disponible que si RUNEYA_CONVERSATION_ID et RUNEYA_INTERNAL_TOKEN sont définis. Il est utilisé dans le contexte des scénarios Runeya pour les nœuds de type ask_user, permettant à l'IA de demander une clarification à l'utilisateur et d'attendre sa réponse (timeout : 5 minutes).

Authentification

Chaque appel tRPC peut inclure un authToken (Bearer JWT). En mode standard, le MCP Server transmet ce token depuis l'entrée de l'outil vers le header Authorization de la requête HTTP.

En mode scénario, RUNEYA_INTERNAL_TOKEN est utilisé directement pour les appels à scenario.requestInput.

Transport

Le MCP Server utilise exclusivement le transport stdio — il lit les requêtes MCP sur stdin et écrit les réponses sur stdout. Il ne démarre aucun port réseau.

Intégration avec Claude Desktop

Exemple de configuration (claude_desktop_config.json) :

{
  "mcpServers": {
    "runeya": {
      "command": "node",
      "args": ["/chemin/vers/runeya/packages/mcp-server/dist/index.js"],
      "env": {
        "RUNEYA_BASE_URL": "http://localhost:9545"
      }
    }
  }
}

Une fois configuré, Claude Desktop peut utiliser les outils Runeya directement dans ses conversations pour piloter les services de votre environnement de développement.

Dépendances

Package	Rôle
@modelcontextprotocol/sdk	SDK officiel MCP (server + stdio transport)
@runeya/packages-shared	Définitions des outils (RUNEYA_TOOL_DEFINITIONS)
zod	Validation des schémas d'entrée des outils