@yaoka/partners-mcp

Serveur Model Context Protocol pour l'API YAOKA Partners. Expose la facturation française (devis, factures, fournisseurs, notes de frais) comme des tools consommables depuis Claude Desktop, Claude Code, Cursor, Windsurf, ou n'importe quel client MCP — y compris depuis votre backend via Vercel AI SDK avec Claude, Perplexity, GPT, Gemini…

Installation

Pas d'installation locale nécessaire — lancez-le directement :

npx -y @yaoka/partners-mcp
# ou
pnpm dlx @yaoka/partners-mcp
# ou
bunx @yaoka/partners-mcp

Une clé API YAOKA est requise via la variable d'environnement YAOKA_API_KEY.

Configuration

Claude Desktop

Éditez ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) :

{
  "mcpServers": {
    "yaoka": {
      "command": "npx",
      "args": ["-y", "@yaoka/partners-mcp"],
      "env": {
        "YAOKA_API_KEY": "sk_qbx_test_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Redémarrez Claude Desktop. Vous voyez désormais les 9 tools YAOKA dans l'icône marteau 🔨.

Claude Code / Cursor / Windsurf

Identique — ces clients lisent le même format mcpServers.

Vercel AI SDK (backend Next.js avec n'importe quel LLM)

import { experimental_createMCPClient } from "ai";
import { Experimental_StdioMCPTransport } from "ai/mcp-stdio";

const yaoka = await experimental_createMCPClient({
  transport: new Experimental_StdioMCPTransport({
    command: "npx",
    args: ["-y", "@yaoka/partners-mcp"],
    env: { YAOKA_API_KEY: process.env.YAOKA_API_KEY! },
  }),
});

const result = await generateText({
  model: yourLlmProvider("model-name"),
  tools: await yaoka.tools(),
  prompt: "Émets une facture pour la session 9988 du client ACME pour 1200€ HT",
});

Marche identiquement avec Claude, Perplexity (Sonar), GPT-4, Gemini, Mistral, etc.

Variables d'environnement

| Variable | Requis | Description | |---|---|---| | YAOKA_API_KEY | ✅ | Clé API YAOKA. Master key (sk_qbx_*) pour le provisioning, ou per-org key (sk_org_*) pour les opérations métier. | | YAOKA_API_BASE_URL | ❌ | URL de base (défaut : https://app.yaoka.fr/api/v1). À utiliser pour pointer vers une sandbox custom ou un environnement de dev. |

Tools disponibles

Provisioning (master key requise)

yaoka_provision_org

Provisionne un nouvel OF (organisme de formation). Crée l'org YAOKA + la company Pennylane en parallèle via l'API Reseller. Pennylane envoie ensuite l'email de désignation Plateforme Agréée (PA).

Inputs: name, siret, email, iban?, logoUrl?, qualiboxRefId?

yaoka_get_org_status

Récupère le status d'un OF (provisioning, OAuth Pennylane, stats 30j).

Inputs: orgId

Devis (per-org key requise)

yaoka_create_quote

Crée un devis DEV-YYYY-NNNN avec PDF généré.

Inputs: orgId, customerId, lines[], validUntilDays?, qualiopiRefId?, discountPercent?, notes?

Factures clients (per-org key requise)

yaoka_create_invoice

Émet une facture Factur-X v1.0.6 (FAC-YYYY-NNNN) conforme art. 242 nonies A CGI. Push automatique Pennylane + envoi email.

Inputs: orgId, customerId, lines[], dueInDays?, qualiopiRefId?, purchaseOrderRef?, sendByEmail?

yaoka_mark_invoice_paid

Marque une facture comme payée. Push Pennylane + webhook invoice.paid.

Inputs: orgId, invoiceId, paidAt, amount, method, reference?

yaoka_list_invoices

Liste les factures d'un OF avec filtres optionnels.

Inputs: orgId, status?, fromDate?, toDate?, limit?

Factures fournisseurs (per-org key requise)

yaoka_upload_supplier_invoice

Upload PDF (base64 ou URL) avec OCR automatique. Workflow d'approbation puis push compta Pennylane.

Inputs: orgId, filename, fileBase64? ou fileUrl?, ocr?, supplierExternalId?

Notes de frais (per-org key requise)

yaoka_create_expense_report

Crée l'entête d'une note de frais.

Inputs: orgId, userId, title, periodFrom, periodTo

yaoka_add_expense_item

Ajoute une ligne de dépense avec justificatif.

Inputs: orgId, expenseReportId, category, date, label, amount, vatRate?, receiptBase64? ou receiptUrl?, mileageKm?

Exemples d'usage

Depuis Claude Desktop

"Crée un OF pour la société FormaPro Excellence, SIRET 12345678901234, email [email protected], et provisionne-leur un compte Pennylane."

Claude appellera yaoka_provision_org avec les bons arguments et te montrera le résultat (orgId + apiKey).

Depuis un script de prod

// Backend Qualibox, route handler Next.js
import { experimental_createMCPClient } from "ai";
import { generateText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

export async function POST(req: Request) {
  const { sessionId, customerId, amount } = await req.json();

  const yaoka = await experimental_createMCPClient({
    transport: new Experimental_StdioMCPTransport({
      command: "npx",
      args: ["-y", "@yaoka/partners-mcp"],
      env: { YAOKA_API_KEY: process.env.YAOKA_ORG_KEY! },
    }),
  });

  const { text } = await generateText({
    model: anthropic("claude-sonnet-4-6"),
    tools: await yaoka.tools(),
    prompt: `Émets une facture pour le client ${customerId}, montant ${amount}€ HT, libellé "Formation session ${sessionId}", à payer sous 30 jours, à envoyer par email.`,
  });

  await yaoka.close();
  return Response.json({ result: text });
}

Sécurité

• La clé API n'est jamais loggée.
• Les requêtes sont en HTTPS uniquement.
• Idempotency-Key généré automatiquement sur chaque POST (anti-double-facture).
• Multi-tenant strict côté YAOKA : une per-org key ne peut JAMAIS accéder à une autre org.
• Pour révoquer une clé : depuis votre dashboard admin YAOKA.

Versioning

• L'API YAOKA elle-même est versionnée (/api/v1/). Pas de breaking change sur v1.
• Ce serveur MCP suit du semver : breaking change uniquement entre versions majeures (1.x → 2.x).

Support

• Documentation produit : https://app.yaoka.fr/partners/qualibox
• Doc dev complète : https://app.yaoka.fr/partners/dev
• Email : [email protected]
• Issues : (TODO — repo GitHub à venir)

YAOKA — 2026