layerone-mcp

# LayerOne MCP — DocX + Sign

Serveur **MCP (Model Context Protocol)** qui expose les API **DocX** et **Sign** de
LayerOne directement aux agents IA (Claude Desktop, ChatGPT, Cursor, Windsurf, etc.).

Une fois branché, votre assistant IA peut, en langage naturel :

- **DocX** — générer des documents (PDF / DOCX), des factures électroniques **Factur-X**
  (réforme 2026), déposer / mettre à jour / télécharger des modèles Word, gérer leur
  historique de versions, et consulter le quota d'usage.
- **Sign** — envoyer un PDF à la signature électronique **eIDAS / PAdES**, suivre son
  statut, vérifier l'identité du signataire par SMS (OTP), télécharger le document signé,
  récupérer le certificat de preuve et valider l'intégrité cryptographique de la signature.

---

## Installation

Le serveur se lance via `npx` — aucune installation manuelle requise. Ajoutez le bloc
ci-dessous à la configuration MCP de votre client, en renseignant vos deux clés API.

### Claude Desktop

Fichier `claude_desktop_config.json` :

```json
{
  "mcpServers": {
    "layerone": {
      "command": "npx",
      "args": ["-y", "layerone-mcp"],
      "env": {
        "DOCX_API_KEY": "votre_cle_docx",
        "SIGN_API_KEY": "votre_cle_sign"
      }
    }
  }
}
```

### Cursor

Fichier `~/.cursor/mcp.json` (ou réglages MCP du projet) — même format :

```json
{
  "mcpServers": {
    "layerone": {
      "command": "npx",
      "args": ["-y", "layerone-mcp"],
      "env": {
        "DOCX_API_KEY": "votre_cle_docx",
        "SIGN_API_KEY": "votre_cle_sign"
      }
    }
  }
}
```

### ChatGPT / autres clients compatibles MCP

La plupart des clients MCP acceptent la même structure (`command` = `npx`,
`args` = `["-y", "layerone-mcp"]`, `env` = vos deux clés). Reportez-vous à la
documentation MCP de votre client pour l'emplacement exact du fichier de configuration.

---

## Obtenir les clés API

Créez un compte gratuit sur **https://dev.layerone.fr**, puis générez vos clés
dans l'onglet **« Clés API »** :

- une clé **DocX** → variable d'environnement `DOCX_API_KEY` ;
- une clé **Sign** → variable d'environnement `SIGN_API_KEY`.

Le compte gratuit offre 20 documents DocX et 10 signatures Sign par mois.

> Les clés ne sont **jamais** écrites en dur dans le code : elles sont lues uniquement
> depuis les variables d'environnement passées par votre client MCP.

---

## Outils exposés

### DocX (`https://docx.layerone.fr`)

| Outil | Description | Endpoint |
|-------|-------------|----------|
| `docx_render_facturx` | Générer une facture Factur-X (PDF/A-3) | `POST /render-facturx` |
| `docx_render_document` | Générer un document PDF ou DOCX | `POST /render-document` |
| `docx_list_templates` | Lister / filtrer les modèles | `GET /client/templates` |
| `docx_upload_template` | Déposer un modèle Word | `POST /client/templates` |
| `docx_update_template` | Mettre à jour un modèle (archive l'ancien) | `PUT /client/templates/{id}` |
| `docx_download_template` | Télécharger un modèle | `GET /client/templates/{id}` |
| `docx_delete_template` | Supprimer un modèle | `DELETE /client/templates/{id}` |
| `docx_list_template_versions` | Lister les versions archivées | `GET /client/templates/{id}/versions` |
| `docx_download_template_version` | Télécharger une version archivée | `GET /client/templates/{id}/versions/{version_id}` |
| `docx_restore_template_version` | Restaurer une version archivée | `POST /client/templates/{id}/restore/{version_id}` |
| `docx_get_usage_stats` | Consulter le quota et l'usage | `GET /usage-stats` |

### Sign (`https://sign.layerone.fr`)

| Outil | Description | Endpoint |
|-------|-------------|----------|
| `sign_send_for_signature` | Envoyer un PDF à signer | `POST /v1/documents/send` |
| `sign_detect_fields` | Détecter les champs de signature ([[...]]) | `POST /v1/documents/detect-fields` |
| `sign_get_document_status` | Consulter le statut d'une signature | `GET /v1/documents/{id}` |
| `sign_download_signed_document` | Télécharger le PDF signé | `GET /v1/documents/{id}/download` |
| `sign_send_otp` | Envoyer un code OTP par SMS | `POST /v1/otp/request` |
| `sign_verify_otp` | Vérifier le code OTP | `POST /v1/otp/verify` |
| `sign_validate_signature` | Vérifier l'intégrité de la signature | `GET /v1/documents/{id}/validate` |
| `sign_get_audit_certificate` | Récupérer le certificat de preuve | `GET /v1/documents/{id}/audit` |
| `sign_cancel_document` | Annuler une demande de signature | `DELETE /v1/documents/{id}` |

> **Fichiers** : les modèles et PDF sont fournis aux outils **encodés en base64**
> (`template_base64`, `pdf_base64`). Pour les téléchargements, le serveur renvoie un
> **résumé** (taille + aperçu base64 tronqué) plutôt que le binaire complet, afin de ne
> pas saturer la conversation.

---

## Développement local

```bash
cd integrations/mcp
npm install
npm run build          # compile src/ → dist/
DOCX_API_KEY=... SIGN_API_KEY=... node dist/index.js
```

Le serveur communique sur **stdio** (entrée/sortie standard) selon le protocole MCP.

---

## Publication

- **npm** : publication automatique avec provenance via
  `.github/workflows/publish.yml` (déclenché par une release GitHub).
- **MCP Registry** : le manifeste `server.json` (champ `name`
  `io.github.GOLayerone/layerone`, identique au `mcpName` de `package.json`) permet la
  publication au registre officiel via l'outil `mcp-publisher`.

---

## Licence

MIT — © LayerOne.