Connecteurs YAML

Le moteur YAML est la voie de création sans code. Il compile un manifeste déclaratif vers la même surface MCP qu’un serveur typé : outils avec paramètres, Presenters au moyen de transformations de réponse, ressources, prompts et connexions. Utilisez-le pour envelopper rapidement une API REST interne ; passez au code MVA typé lorsque le domaine nécessite un comportement personnalisé.

Un manifeste complet

version: "1.0"
server:
  name: billing
  description: Invoice operations for an AI agent
  capabilities:
    tools: true
    resources: true
secrets:
  BILLING_TOKEN:
    label: Billing API token
    type: api_key
    required: true
    sensitive: true
connections:
  billing:
    type: rest
    base_url: https://api.example.com
    auth:
      type: bearer
      token: ${SECRETS.BILLING_TOKEN}
tools:
  - name: list_invoices
    description: List invoices for the current account
    rules:
      - Never expose internal_notes to the model
    parameters:
      account_id:
        type: string
        required: true
        description: Account identifier
    execute:
      connection: billing
      method: GET
      path: /accounts/{{account_id}}/invoices
    response:
      extract: [data]
      max_items: 50

Le parseur valide le schéma racine avec Zod, vérifie les références croisées, interpole ${SECRETS.KEY} depuis l’environnement, compile les paramètres en JSON Schema, résout la connexion et construit un serveur MCP local.

La surface du manifeste

• server : nom, description, capabilities et instructions
• secrets : déclarations typées telles que api_key, token, password, url, avec les indicateurs required et sensitive
• connections : URL de base REST, authentification (none, bearer, basic ou custom header), headers, timeout et politique de retry
• tools : description, instruction, règles, tags, annotations, paramètres, bloc HTTP execute et transformation de réponse
• resources : modèles d’URI, contenu statique ou récupéré, type MIME et cache facultatif
• prompts : arguments primitifs plats et modèles de messages utilisateur/assistant avec {{argument}}
• settings : déclarations d’exposition, de DLP, de FinOps, de circuit breaker et de cycle de vie

La CLI

mcpfusion yaml validate mcpfusion.yaml
mcpfusion yaml dev mcpfusion.yaml --transport http --port 3001

La CLI découvre automatiquement mcpfusion.yaml ou mcpfusion.yml dans le répertoire courant. validate s’arrête après les vérifications du schéma et des références croisées. dev exécute stdio par défaut ou Streamable HTTP sur le port choisi.

Le paquet YAML actuel propose les commandes validate et dev dans la CLI OSS. Déployez le connecteur compilé par le flux habituel Deploy ; ne supposez pas l’existence d’une commande de déploiement YAML distincte à moins que votre CLI installée ne l’expose.

Ce que l’OSS impose

Le moteur ouvert impose la forme du schéma, les champs requis, les types de paramètres, les références croisées, l’interpolation des secrets et l’exécution REST. Les clés de settings pour le DLP, le FinOps, le circuit breaker et le cycle de vie sont analysées comme partie du manifeste ; l’application de ces contrôles de plateforme relève de Vinkius Cloud. Cette séparation permet d’exécuter le même YAML localement tandis que le connecteur hébergé bénéficie du périmètre de la plateforme.

Quand YAML ne suffit plus

Choisissez le code MVA typé lorsque vous avez besoin de Presenters dynamiques, de schémas dépendant du rôle, de middleware personnalisé, de transactions, de gardes d’état FSM, de handlers de générateurs ou d’une récupération d’erreur propre au domaine. La migration ne réécrit pas le protocole : les mêmes outils, ressources et prompts peuvent être reconstruits avec initMCPFusion() et déployés avec la même commande.

Étapes suivantes

• The MVA pattern: le chemin typé vers lequel YAML compile
• Credentials: déclarez les secrets gérés par l’acheteur
• CLI: les commandes de développement partagées