@casys/mcp-einvoice 0.1.1 → 0.1.3

package/README.md

@@ -1,54 +1,47 @@
-# @casys/mcp-einvoice
+# mcp-einvoice
 
-MCP server for French e-invoicing — PA-agnostic via the adapter pattern.
+Serveur MCP pour la facturation électronique — agnostique plateforme via le
+pattern adapter.
 
-## Architecture
+<p align="center">
+  <img src="docs/logos/iopole.svg" alt="Iopole" height="40">&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="docs/logos/storecove.png" alt="Storecove" height="40">&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="docs/logos/superpdp.svg" alt="Super PDP" height="40">
+</p>
 
-```
-┌──────────────────────────────────────────────────┐
-│  MCP Tools (27 tools, einvoice_*)                │
-│  invoice · directory · status · reporting · webhook │
-├──────────────────────────────────────────────────┤
-│  MCP Apps (4 viewers)                            │
-│  invoice-viewer · doclist-viewer                 │
-│  status-timeline · directory-card                │
-├──────────────────────────────────────────────────┤
-│  EInvoiceAdapter (interface)                     │
-│  PA-agnostic: emitInvoice, searchInvoices, ...   │
-├──────────┬───────────────────────────────────────┤
-│  Iopole  │  Autres PA via EInvoiceAdapter        │
-│ (REST)   │  (ajout sans toucher aux tools)       │
-└──────────┴───────────────────────────────────────┘
-```
+## Pourquoi
+
+La réforme de la facturation électronique en France (sept. 2026) impose
+l'utilisation de Plateformes Agréées (PA). Il en existe 106+, chacune avec sa
+propre API. Ce serveur MCP expose **une interface unique** pour toutes, avec 39
+tools et 6 viewers interactifs.
 
-Chaque PA (Plateforme Agréée) implémente `EInvoiceAdapter`. Les tools MCP appellent l'adapter, jamais l'API directement.
+## Adapters
 
-## Configuration
+|                                                  | Adapter       | Scope               | Tools | Base             |
+| ------------------------------------------------ | ------------- | ------------------- | ----- | ---------------- |
+| <img src="docs/logos/iopole.svg" height="16">    | **Iopole**    | PA française, B2B   | 39/39 | BaseAdapter      |
+| <img src="docs/logos/storecove.png" height="16"> | **Storecove** | Peppol AP, 40+ pays | 19/39 | BaseAdapter      |
+| <img src="docs/logos/superpdp.svg" height="16">  | **Super PDP** | PA française, B2B   | 20/39 | AfnorBaseAdapter |
 
-### Variables d'environnement
+`BaseAdapter` fournit des stubs `NotSupportedError` pour les 45 méthodes de
+l'interface `EInvoiceAdapter`. Les PA françaises avec AFNOR héritent
+d'`AfnorBaseAdapter` (socle
+[AFNOR XP Z12-013](https://norminfo.afnor.org/norme/pr-xp-a00-002/standardisation-api-odpdp/211970))
+qui ajoute les opérations flow. Les autres étendent `BaseAdapter` directement.
+
+Le filtrage par `capabilities` assure que le LLM ne voit que les tools supportés
+par l'adapter actif.
+
+## Configuration rapide
 
 ```bash
-# Choix du provider (default: iopole)
-EINVOICE_ADAPTER=iopole
-
-# Config Iopole — OAuth2 client credentials
-IOPOLE_API_URL=https://api.ppd.iopole.fr/v1      # sandbox
-IOPOLE_CLIENT_ID=your-client-id
-IOPOLE_CLIENT_SECRET=your-client-secret
-IOPOLE_CUSTOMER_ID=your-customer-id               # required since 2026-02-01
-
-# Optionnel — token endpoint Keycloak (default: production)
-# Sandbox : https://auth.ppd.iopole.fr/realms/iopole/protocol/openid-connect/token
-IOPOLE_AUTH_URL=https://auth.iopole.com/realms/iopole/protocol/openid-connect/token
-
-# Sécurité (optionnel — mode HTTP du serveur MCP)
-MCP_AUTH_PROVIDER=oidc
-MCP_AUTH_ISSUER=https://auth.example.com
-MCP_AUTH_AUDIENCE=mcp-einvoice
-MCP_AUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.json
+cp .env.example .env
+# Remplir les variables de l'adapter choisi, puis :
+deno task serve          # HTTP mode (port 3015)
 ```
 
-### MCP config (stdio mode)
+### MCP config (Claude Desktop / stdio)
 
 ```json
 {
@@ -59,167 +52,133 @@ MCP_AUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.json
       "env": {
         "EINVOICE_ADAPTER": "iopole",
         "IOPOLE_API_URL": "https://api.ppd.iopole.fr/v1",
-        "IOPOLE_CLIENT_ID": "your-client-id",
-        "IOPOLE_CLIENT_SECRET": "your-client-secret",
-        "IOPOLE_CUSTOMER_ID": "your-customer-id"
+        "IOPOLE_CLIENT_ID": "...",
+        "IOPOLE_CLIENT_SECRET": "...",
+        "IOPOLE_CUSTOMER_ID": "..."
       }
     }
   }
 }
 ```
 
-### HTTP mode
-
-```bash
-deno run --allow-all server.ts --http --port=3015
-```
+Remplacer `EINVOICE_ADAPTER` par `storecove` ou `superpdp` avec les variables
+correspondantes (voir `.env.example`).
 
-Options :
-- `--http` — mode HTTP (default: stdio)
-- `--port=3015` — port HTTP (default: 3015)
-- `--hostname=0.0.0.0` — hostname (default: 0.0.0.0)
-- `--adapter=iopole` — override le provider (default: env `EINVOICE_ADAPTER` ou `iopole`)
-- `--categories=invoice,status` — filtrer les catégories de tools
+### Options serveur
 
-**Note** : en mode HTTP, le `generated-store` (flow generate → emit) est in-memory et single-instance. Ne pas déployer derrière un load-balancer sans sticky sessions.
+```
+--http                   Mode HTTP (default: stdio)
+--port=3015              Port HTTP
+--hostname=localhost     Bind address (default: localhost)
+--adapter=iopole         Override adapter (default: env EINVOICE_ADAPTER)
+--categories=invoice     Filtrer les catégories de tools
+```
 
-## Tools (27)
+## Architecture
 
-| Catégorie | N | Tools | Description |
-|-----------|---|-------|-------------|
-| **invoice** | 13 | `emit`, `search`, `get`, `download`, `download_readable`, `files`, `attachments`, `download_file`, `mark_seen`, `not_seen`, `generate_cii`, `generate_ubl`, `generate_facturx` | Émission, recherche, téléchargement, génération CII/UBL/Factur-X |
-| **directory** | 3 | `fr_search`, `int_search`, `peppol_check` | Annuaire PPF (France) + Peppol (international) |
-| **status** | 4 | `send`, `history`, `not_seen`, `mark_seen` | Cycle de vie facture (APPROVED, REFUSED, DISPUTED, PAYMENT_SENT...) |
-| **reporting** | 2 | `invoice_transaction`, `transaction` | E-reporting DGFiP (B2C, international) |
-| **webhook** | 5 | `list`, `get`, `create`, `update`, `delete` | Notifications temps réel |
+```
+┌───────────────────────────────────────────────┐
+│  39 MCP Tools (einvoice_*)                    │
+│  invoice · directory · status · reporting     │
+│  webhook · config                             │
+├───────────────────────────────────────────────┤
+│  6 MCP Apps (viewers React)                   │
+│  invoice · doclist · timeline · card ·        │
+│  directory-list · action                      │
+├───────────────────────────────────────────────┤
+│  EInvoiceAdapter (interface, 45 methods)      │
+│  + capabilities → filtrage tools dynamique    │
+├──────────┬────────────────────────────────────┤
+│ BaseAdapter (abstract, NotSupported stubs)    │
+├──────────┼────────────────────────────────────┤
+│ AfnorBase│ Direct                             │
+│ (AFNOR)  │                                    │
+│ ┌──────┐ │ ┌─────────┐  ┌───────────┐        │
+│ │ SPDP │ │ │ Iopole  │  │ Storecove │        │
+│ └──────┘ │ └─────────┘  └───────────┘        │
+└──────────┴────────────────────────────────────┘
+```
 
-Tous les noms de tools sont préfixés `einvoice_<category>_` (ex: `einvoice_invoice_search`).
+## Tools
 
-### Flow generate → preview → emit
+| Catégorie         | Tools                                                                                                                                                                                                                                                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **invoice** (11)  | submit, search, get, download, download_readable, files, attachments, download_file, generate_cii, generate_ubl, generate_facturx                                                                                                                                                          |
+| **directory** (3) | fr_search, int_search, peppol_check                                                                                                                                                                                                                                                        |
+| **status** (2)    | send, history                                                                                                                                                                                                                                                                              |
+| **reporting** (2) | invoice_transaction, transaction                                                                                                                                                                                                                                                           |
+| **webhook** (5)   | list, get, create, update, delete                                                                                                                                                                                                                                                          |
+| **config** (16)   | customer_id, entities_list, entity_get, entity_create_legal, entity_create_office, enroll_fr, entity_claim, entity_delete, network_register, network_register_by_id, network_unregister, identifier_create, identifier_create_by_scheme, identifier_delete, entity_configure, claim_delete |
 
-1. **Generate** (`generate_cii`, `generate_ubl`, `generate_facturx`) : Génère le XML/PDF, stocke le fichier côté serveur, retourne un `generated_id` + preview pour le viewer
-2. **Preview** : Le `invoice-viewer` affiche la facture avec un bouton "Déposer"
-3. **Emit** (`emit`) : Accepte `generated_id` (consomme le fichier stocké) ou `file_base64` + `filename` direct
+Tous préfixés `einvoice_<category>_`. Chaque tool déclare ses `requires` — seuls
+ceux supportés par l'adapter actif sont exposés au LLM.
 
-Les fichiers générés expirent après 10 minutes.
+### Flow generate → preview → submit
 
-## MCP Apps (4 viewers)
+1. `generate_*` → stocke le fichier, retourne `generated_id` + preview viewer
+2. Le viewer affiche la facture avec bouton "Déposer"
+3. `submit` consomme le `generated_id` (ou accepte `file_base64` direct)
 
-| Viewer | Tools associés | Description |
-|--------|---------------|-------------|
-| **invoice-viewer** | `get`, `generate_*` | Facture détaillée avec actions (accepter, rejeter, contester, marquer lu, télécharger, déposer) |
-| **doclist-viewer** | `search`, `not_seen`, `fr_search`, `int_search`, `webhook_list` | Table générique avec drill-down (clic → appel tool) |
-| **status-timeline** | `history` | Timeline verticale des changements de statut |
-| **directory-card** | `fr_search` (single result) | Fiche entreprise avec SIREN/SIRET, réseaux, détails |
+## Viewers (MCP Apps)
 
-Build des viewers :
+| Viewer              | Usage                                                      |
+| ------------------- | ---------------------------------------------------------- |
+| **invoice-viewer**  | Facture détaillée + actions (accepter, rejeter, déposer)   |
+| **doclist-viewer**  | Table avec drill-down, recherche, filtres direction/statut |
+| **status-timeline** | Timeline verticale des changements de statut               |
+| **directory-card**  | Fiche entreprise (SIREN/SIRET, réseaux)                    |
+| **directory-list**  | Résultats annuaire — cartes avec expand, recherche client  |
+| **action-result**   | Feedback visuel d'action (enroll, register)                |
 
 ```bash
-cd src/ui && node build-all.mjs
+cd src/ui && node build-all.mjs   # Rebuild après modification TSX
 ```
 
-## Utilisation directe de l'adapter
+## Ajouter un adapter
 
-```typescript
-import { createIopoleAdapter } from "@casys/mcp-einvoice";
-
-const adapter = createIopoleAdapter();
-
-// Rechercher des factures (Lucene syntax)
-const results = await adapter.searchInvoices({
-  q: 'status:accepted AND direction:received',
-  expand: "businessData",
-  offset: 0,
-  limit: 20,
-});
-
-// Envoyer un statut
-await adapter.sendStatus({
-  invoiceId: "uuid-de-la-facture",
-  code: "APPROVED",
-  message: "Facture validée",
-});
-
-// Chercher dans l'annuaire PPF
-const company = await adapter.searchDirectoryFr({
-  q: 'siret:"43446637100011"',
-});
-
-// Générer une facture CII
-const xml = await adapter.generateCII({
-  invoice: { invoiceId: "F-001", seller: { ... }, buyer: { ... }, ... },
-  flavor: "EN16931",
-});
-```
-
-## Ajouter un adapter (nouveau PA)
-
-1. Créer `src/adapters/my-pa.ts` implémentant `EInvoiceAdapter`
-2. Ajouter le case dans `server.ts` → `createAdapter()`
+**PA française avec AFNOR** → `extends AfnorBaseAdapter` (socle AFNOR gratuit,
+override le natif) :
 
 ```typescript
-import type { EInvoiceAdapter } from "../adapter.ts";
-
-export class MyPAAdapter implements EInvoiceAdapter {
+export class MyPAAdapter extends AfnorBaseAdapter {
   readonly name = "my-pa";
-  // Implémenter les 27 méthodes de l'interface
-}
-```
+  readonly capabilities = new Set(["emitInvoice", "searchInvoices", ...]);
+  private client: MyPAClient;
 
-L'interface `EInvoiceAdapter` est définie dans `src/adapter.ts` — 27 méthodes couvrant factures, annuaire, statuts, reporting et webhooks.
+  constructor(client: MyPAClient, afnor: AfnorClient | null) {
+    super(afnor);  // ou super(null) si pas encore d'AFNOR
+    this.client = client;
+  }
 
-## Node.js
+  override async generateCII(req) { return this.client.convert(req); }
+  // ... override les extras, hériter le reste
+}
+```
 
-Build single-file CLI via esbuild :
+**PA française sans AFNOR** → `extends BaseAdapter` (override toutes les
+méthodes avec l'API native, comme Iopole).
 
-```bash
-./scripts/build-node.sh
-# Produit dist-node/bin/mcp-einvoice.mjs (~1.3MB)
-```
+**Plateforme non-française** → `extends BaseAdapter` directement (comme
+Storecove).
 
-Le script swap `runtime.ts` par `runtime.node.ts` et strip les extensions `.ts` des imports.
+Guide complet : `src/adapters/README.md`.
 
 ## Structure
 
 ```
-├── deno.json              # Package @casys/mcp-einvoice
-├── mod.ts                 # Public API
-├── server.ts              # MCP server (stdio + HTTP)
-├── scripts/
-│   └── build-node.sh      # esbuild single-file build
-└── src/
-    ├── adapter.ts         # EInvoiceAdapter interface (26 méthodes)
-    ├── generated-store.ts # Temp file store (generate → emit flow)
-    ├── adapters/
-    │   └── iopole.ts      # IopoleAdapter
-    ├── api/
-    │   └── iopole-client.ts  # HTTP client + OAuth2 token provider
-    ├── runtime.ts         # Deno runtime (env vars)
-    ├── runtime.node.ts    # Node.js runtime
-    ├── tools/
-    │   ├── types.ts       # EInvoiceTool, EInvoiceToolContext
-    │   ├── mod.ts         # Registry (27 tools)
-    │   ├── invoice.ts     # 13 tools
-    │   ├── directory.ts   # 3 tools
-    │   ├── status.ts      # 4 tools
-    │   ├── reporting.ts   # 2 tools
-    │   └── webhook.ts     # 5 tools
-    ├── testing/
-    │   └── helpers.ts     # Mock fetch, mock adapter
-    └── ui/
-        ├── build-all.mjs
-        ├── shared/          # Theme, brand, refresh
-        ├── invoice-viewer/  # Viewer facture interactif
-        ├── doclist-viewer/  # Table générique drill-down
-        ├── status-timeline/ # Timeline verticale statuts
-        └── directory-card/  # Fiche entreprise
+server.ts                    # MCP server (stdio + HTTP)
+src/
+├── adapter.ts               # EInvoiceAdapter (45 methods + capabilities)
+├── client.ts                # Tools registry + capability filtering
+├── adapters/
+│   ├── base-adapter.ts      # BaseAdapter (abstract, NotSupported stubs)
+│   ├── afnor/               # Socle AFNOR XP Z12-013 (shared)
+│   │   ├── base-adapter.ts  # AfnorBaseAdapter (extends BaseAdapter)
+│   │   └── client.ts        # AfnorClient (3 flow endpoints)
+│   ├── shared/oauth2.ts     # OAuth2 token provider (shared)
+│   ├── iopole/              # PA française — extends BaseAdapter
+│   ├── storecove/           # Peppol AP — extends BaseAdapter
+│   └── superpdp/            # PA française — extends AfnorBaseAdapter
+├── tools/                   # 39 tools (6 catégories)
+└── ui/                      # 6 viewers React (single-file HTML)
 ```
-
-## Iopole API
-
-- Production : `https://api.iopole.com/v1`
-- Sandbox : `https://api.ppd.iopole.fr/v1`
-- Search : `https://api.ppd.iopole.fr/v1.1/invoice/search` (version v1.1)
-- Auth : OAuth2 `client_credentials` (token TTL 10 min, auto-refresh 60s avant expiry)
-- Token endpoint : `https://auth.iopole.com/realms/iopole/protocol/openid-connect/token`
-- Header `customer-id` obligatoire sur toutes les requêtes (depuis 2026-02-01)