plc-mcp
<div align="center">
# đ plc-mcp
**Posez vos questions Ă un automate industriel en langage naturel.**
Un serveur [MCP](https://modelcontextprotocol.io) en Python qui se connecte Ă un automate en OPC UA et
expose ses données à n'importe quel assistant IA : Claude Desktop, Claude Code ou votre propre agent
LangGraph. Livré avec un simulateur de ligne de production, pour fonctionner sans vraie machine.






</div>
> « Quelle est la température du four 2 ? »
> « Pourquoi la ligne s'est-elle arrĂȘtĂ©e cette nuit ? »
> « GénÚre la doc des variables de cet automate. »
<p align="center"><img src="docs/demo.gif" alt="Démo : trois questions à l'automate depuis Claude Code" width="800"></p>
<p align="center"><sub>Vraies sessions Claude Code branchées sur le simulateur, rejouées à partir du
<a href="docs/demo/transcript.json">transcript</a> : les appels d'outils et les réponses n'ont pas été retouchés.</sub></p>
---
## ⚠Fonctionnalités
- **Lecture en direct** des capteurs, compteurs et alarmes, avec l'unité, l'horodatage et la qualité OPC UA.
- **Diagnostic d'arrĂȘt** : `journal_evenements` reconstruit chaque arrĂȘt avec sa cause, sa durĂ©e,
l'alarme déclenchante et les **variables à examiner**. L'assistant creuse ensuite avec `historique`
pour remonter du symptÎme (l'alarme) à la cause racine (la commande de chauffe saturée).
- **Historique résumé pour un LLM** : min, max et moyenne, plus une courbe sous-échantillonnée qui
**garde les pics**. Pour un booléen ou un code, on obtient la liste des changements d'état.
On ne renvoie jamais 10 000 points bruts.
- **Documentation automatique** : l'automate est parcouru (browse OPC UA) pour produire une
[fiche Markdown](docs/variables.md) des variables (type, unité, plage, droits, valeur, description).
Les variables mal documentées dans l'automate sont signalées.
- **Ăcriture sous garde-fous** : lecture seule par dĂ©faut, liste blanche, bornes, variation maximale,
confirmation en deux temps et journal d'audit (détails plus bas).
- **Simulateur réaliste** : deux fours, un convoyeur, de l'air comprimé, des alarmes et
**36 h d'historique déjà rejouées**, avec un incident la nuit derniÚre à expliquer.
- **Deux transports** : stdio (Claude Desktop, Claude Code) et Streamable HTTP (Docker, agents distants).
### Ce que voit l'assistant
| Type | Nom | RĂŽle |
|---|---|---|
| đ§ tool | `lister_variables(dossier?)` | Catalogue dĂ©couvert sur l'automate |
| đ§ tool | `lire_variable(chemin)` · `lire_variables(chemins)` | Valeurs actuelles |
| đ§ tool | `lister_alarmes()` | Alarmes actives et depuis quand |
| đ§ tool | `historique(chemin, periode \| debut, fin)` | Historique rĂ©sumĂ© (`30min`, `8h`, `2j`, `nuit`, ou dates ISO) |
| đ§ tool | `journal_evenements(periode)` | ArrĂȘts, causes, durĂ©es et chronologie des alarmes |
| đ§ tool | `ecrire_variable(chemin, valeur)` | **PrĂ©pare** une Ă©criture et renvoie un jeton |
| đ§ tool | `confirmer_ecriture(jeton)` · `annuler_ecriture(jeton)` | ExĂ©cute ou abandonne l'Ă©criture |
| đ§ tool | `generer_documentation()` | Fiche Markdown complĂšte |
| đ resource | `plc://variables` · `plc://variables/{chemin}` | Catalogue et fiche d'une variable |
| đ resource | `plc://documentation` · `plc://politique-ecriture` | Doc gĂ©nĂ©rĂ©e, garde-fous en vigueur |
| đŹ prompt | `diagnostic_arret(periode)` | MĂ©thode guidĂ©e pour expliquer un arrĂȘt |
## đ§ Comment ça marche
```mermaid
flowchart LR
subgraph Clients["Assistants IA"]
CD[Claude Desktop]
CC[Claude Code]
LG[Agent LangGraph]
end
subgraph MCP["plc-mcp (serveur MCP)"]
T[Tools · Resources · Prompt]
G{{Garde-fous<br/>écriture}}
A[Analyse<br/>résumé · journal]
D[Docgen]
P[Client OPC UA<br/>browse · read · history]
end
subgraph PLC["Automate (ici : simulateur)"]
S[(Espace d'adresses OPC UA<br/>21 variables + historique)]
M[ModÚle physique<br/>fours · convoyeur · alarmes]
end
CD & CC -- stdio --> T
LG -- Streamable HTTP --> T
T --> A --> P
T --> D --> P
T -- écriture --> G --> P
P -- opc.tcp --> S
M <--> S
```
**Pourquoi OPC UA plutÎt que Modbus ?** En Modbus, un automate n'expose que des numéros de registres :
la signification de chaque registre vit dans un tableur Ă part. En OPC UA, l'automate dĂ©crit lui-mĂȘme ses
variables (nom, description, unité, plage, droits, historisation). Le serveur MCP découvre donc tout par
browse, sans rien coder en dur, et la documentation automatique reflÚte la machine réelle. Un connecteur
Modbus reste possible, avec une table de correspondance en YAML (voir les pistes d'amélioration).
**Le serveur MCP ne connaĂźt pas le simulateur.** Il n'importe rien de `plc_mcp.simulator` : il parcourt
l'espace d'adresses comme il le ferait sur un vrai automate. Les seules conventions sont réglables par
variables d'environnement : le dossier des alarmes, la variable de marche et le code d'arrĂȘt. Les libellĂ©s
des codes d'arrĂȘt sont mĂȘme lus dans la description OPC UA de la variable.
### Le scénario rejoué par le simulateur
Au démarrage, le simulateur rejoue les 36 derniÚres heures pas à pas. L'historique OPC UA contient donc déjà :
| Quand | ĂvĂ©nement |
|---|---|
| Veille, 12:00 â 12:30 | Pause dĂ©jeuner (arrĂȘt opĂ©rateur) |
| Veille, ~16:25 | Bourrage du convoyeur : surintensitĂ© moteur, arrĂȘt de 9 min |
| **Nuit, 03:05** | **Le relais de chauffe du four 2 colle. Le four atteint 225 °C, l'alarme se dĂ©clenche, la sĂ©curitĂ© coupe la chauffe et la ligne s'arrĂȘte (03:07).** |
| Nuit, 03:45 | La maintenance remplace le relais. Le four remonte en température. |
| Nuit, 04:17 | Redémarrage par l'opérateur |
Si on demande « pourquoi la ligne s'est arrĂȘtĂ©e cette nuit ? », l'assistant appelle `journal_evenements`
puis `historique` sur `Four2.Temperature` et `Four2.PuissanceChauffe`. Il voit la puissance bloquĂ©e Ă
100 % avant l'alarme et en déduit la cause racine.
## đĄïž Garde-fous d'Ă©criture
Laisser un LLM écrire dans un automate est risqué. Une écriture doit donc franchir **cinq contrÎles**
([`guards.py`](src/plc_mcp/guards.py)) :
| # | ContrÎle | Par défaut |
|---|---|---|
| 1 | Interrupteur général `PLC_MCP_WRITE_ENABLED` | **désactivé** : lecture seule stricte |
| 2 | Liste blanche [`config/ecriture.yaml`](config/ecriture.yaml) | 3 consignes, pas la commande de marche |
| 3 | Droit d'écriture déclaré **par l'automate** (AccessLevel OPC UA) | les mesures sont en lecture seule |
| 4 | Type, bornes `min`/`max` et variation maximale `max_step` | 230 °C au plus, ±10 °C par écriture |
| 5 | Confirmation : `ecrire_variable` ne fait que **prĂ©parer** la demande. `confirmer_ecriture` exĂ©cute un jeton Ă usage unique, valable 2 min. | â |
AprÚs l'écriture, la valeur est relue dans l'automate. Chaque demande (refusée, confirmée, expirée,
échouée) est tracée dans `logs/audit-ecritures.jsonl`.
`Ligne.CommandeMarche` illustre la **défense en profondeur** : l'automate accepte qu'on l'écrive, mais
elle est volontairement absente de la liste blanche. Démarrer une ligne reste une action humaine.
> **Limite assumée.** La confirmation en deux temps ne garantit pas, à elle seule, qu'un humain a
> validé : un modÚle mal aligné pourrait enchaßner les deux appels. Elle s'appuie donc sur les
> annotations MCP (`destructiveHint` sur `confirmer_ecriture`), qui poussent les clients comme Claude
> Desktop Ă demander l'accord de l'utilisateur avant chaque appel. Le vrai verrou reste l'ensemble
> liste blanche + bornes + droits automate. L'élicitation MCP figure dans les pistes d'amélioration.
## đ DĂ©marrage rapide
Prérequis : [uv](https://docs.astral.sh/uv/), ou Docker.
### Option A : Docker Compose (simulateur + serveur MCP en HTTP)
```bash
docker compose up --build
claude mcp add --transport http plc http://localhost:8000/mcp # Claude Code
```
Si le port 8000 est déjà occupé : `PLC_MCP_PORT=8010 docker compose up --build`.
Pour autoriser les écritures de la liste blanche : `PLC_MCP_WRITE_ENABLED=true docker compose up`.
### Option B : en local avec Claude Desktop (stdio)
```bash
uv sync
uv run plc-sim # terminal 1 : l'automate simulé sur opc.tcp://localhost:4840
```
Puis, dans `claude_desktop_config.json` (menu Réglages > Développeur > Modifier la config) :
```json
{
"mcpServers": {
"automate": {
"command": "uv",
"args": ["--directory", "/chemin/absolu/vers/plc-mcp", "run", "plc-mcp"],
"env": {
"PLC_MCP_ENDPOINT": "opc.tcp://localhost:4840/plc-mcp/",
"PLC_MCP_WRITE_ENABLED": "false"
}
}
}
}
```
Le simulateur peut aussi tourner seul dans Docker : `docker compose up plc-sim`.
### Générer la fiche des variables
```bash
uv run plc-doc -o docs/variables.md
```
### Tests
```bash
uv run pytest # 58 tests, dont un bout en bout : vrai simulateur OPC UA <-> client MCP
uv run ruff check .
```
La CI GitHub Actions lance le lint, les tests, puis démarre la stack Docker Compose et appelle le serveur
MCP en HTTP.
### Configuration
| Variable | Défaut | RÎle |
|---|---|---|
| `PLC_MCP_ENDPOINT` | `opc.tcp://localhost:4840/plc-mcp/` | Adresse de l'automate |
| `PLC_MCP_WRITE_ENABLED` | `false` | Interrupteur général des écritures |
| `PLC_MCP_WRITE_POLICY` | `config/ecriture.yaml` | Liste blanche |
| `PLC_MCP_CONFIRMATION_TTL_S` | `120` | Validité d'un jeton d'écriture |
| `PLC_MCP_TIMEZONE` | `Europe/Paris` | Fuseau de l'usine (affichage, « cette nuit ») |
| `PLC_MCP_MAX_HISTORY_POINTS` | `120` | Budget de points par historique |
| `PLC_MCP_NAMESPACE_URI` · `PLC_MCP_ROOT` | `urn:plc-mcp:ligne-production` · `LigneProduction` | OĂč explorer |
| `PLC_MCP_ALARM_FOLDER` · `PLC_MCP_RUN_VARIABLE` · `PLC_MCP_STOP_CODE_VARIABLE` | `Alarmes` · `Ligne.EnMarche` · `Ligne.CodeArret` | Signaux du journal d'arrĂȘts |
### Avec Claude Code (le plus simple)
Le dépÎt contient un [`.mcp.json`](.mcp.json) : lancé dans ce dossier, Claude Code propose
d'activer le serveur `automate`.
```bash
uv run plc-sim # terminal 1
claude # terminal 2, dans le dossier plc-mcp : accepter le serveur « automate »
```
### Regénérer le GIF de démo
Le GIF n'est pas une capture d'écran : c'est le rendu de vraies sessions Claude Code, ce qui le rend
reproductible et léger (0,1 Mo).
```bash
uv run plc-sim & # l'automate simulé
for q in "Quelle est la tempĂ©rature du four 2 ?" "Pourquoi la ligne s'est arrĂȘtĂ©e cette nuit ?"; do
claude -p "$q" --strict-mcp-config --mcp-config .mcp.json --allowedTools mcp__automate \
--output-format stream-json --verbose > "session-$((++i)).jsonl"
done
python scripts/extract_transcript.py session-*.jsonl -o docs/demo/transcript.json \
--questions "Quelle est la tempĂ©rature du four 2 ?" "Pourquoi la ligne s'est arrĂȘtĂ©e cette nuit ?"
uv run scripts/render_demo.py # -> docs/demo.gif
```
Pour la démo, les sessions ont été lancées avec la consigne systÚme « réponds de façon concise, 6 lignes
au maximum », afin que les réponses tiennent à l'écran.
Pour une vraie capture d'écran, sous Ubuntu : `Ctrl` + `Maj` + `Alt` + `R` pour enregistrer, puis
`scripts/make-gif.sh ~/Vidéos/Screencasts/<fichier>.webm` pour convertir la vidéo en GIF.
## đ Structure du projet
```
plc-mcp/
âââ src/plc_mcp/
â âââ server.py # serveur MCP : tools, resources, prompt, transports
â âââ plc.py # client OPC UA : browse, lecture, historique, Ă©criture, reconnexion
â âââ guards.py # garde-fous d'Ă©criture + audit
â âââ analysis.py # pĂ©riodes, rĂ©sumĂ©s d'historique, journal des arrĂȘts (fonctions pures)
â âââ docgen.py # fiche Markdown des variables (+ CLI plc-doc)
â âââ config.py # rĂ©glages PLC_MCP_*
â âââ simulator/
â âââ model.py # modĂšle physique de la ligne + scĂ©nario d'incidents
â âââ server.py # serveur OPC UA : mĂ©tadonnĂ©es, historique, rejeu (CLI plc-sim)
âââ config/ecriture.yaml # liste blanche d'Ă©criture
âââ scripts/
â âââ extract_transcript.py # session Claude Code -> transcript propre
â âââ render_demo.py # transcript -> docs/demo.gif
â âââ make-gif.sh # capture d'Ă©cran -> GIF
âââ .mcp.json # dĂ©claration du serveur pour Claude Code
âââ docs/
â âââ variables.md # fiche gĂ©nĂ©rĂ©e automatiquement
â âââ demo.gif # dĂ©mo
â âââ demo/transcript.json # sessions rĂ©elles utilisĂ©es pour la dĂ©mo
âââ tests/ # modĂšle, garde-fous, analyse, docgen, bout en bout
âââ Dockerfile # une image pour les deux services
âââ docker-compose.yml
âââ .github/workflows/ci.yml
```
## đșïž Pistes d'amĂ©lioration
- **Confirmation par élicitation MCP** : le serveur demande l'accord directement à l'utilisateur, sans
passer par le modĂšle, quand le client le permet.
- **Connecteur Modbus TCP** (pymodbus), avec une table de correspondance des registres en YAML, derriĂšre
la mĂȘme interface que le client OPC UA.
- **Sécurité OPC UA** : certificats, `Basic256Sha256` et authentification utilisateur. Authentification
OAuth sur le transport HTTP.
- **Alarmes OPC UA natives** (Alarms & Conditions) à la place des booléens, et historique d'événements.
- **Historien persistant** (SQLite ou TimescaleDB) pour garder l'historique au-delà d'un redémarrage.
- **Ăvaluation** : un jeu de questions annotĂ©es (« pourquoi l'arrĂȘt ? ») pour mesurer la justesse des
diagnostics de différents modÚles, dont des modÚles locaux.
- **Déploiement Kubernetes** (Helm) avec le simulateur en sidecar.
## đ€ Auteur
**Cyril D'Houdetot** · [GitHub](https://github.com/DHoudetot-Cyril)
Projet personnel, sous licence MIT.
TDQS
Scored across 10 tools
The read surface is cleanly split: lister_variables lists metadata, lire_variable/lire_variables read values, and historique pulls time series; the singular/plural pair is spelled out well in the descriptions. The only real overlap is between lister_alarmes and journal_evenements, which both surface alarm chronologies (the latter adds stops and causes), so an agent could occasionally pick the wrong one. The three-step write flow (ecrire/confirmer/annuler) is explicitly delineated.
Eight of ten tools use a verb_noun French pattern (lister_*, lire_*, ecrire_*, confirmer_*, annuler_*, generer_documentation) with consistent lowercase snake_case. The exceptions are 'historique' and 'journal_evenements', which are noun-only names and break the verb-first convention. The style is otherwise uniform and readable.
Ten tools is well within a comfortable scope for a PLC monitoring/control server. Each tool earns its place: the split write-offer/confirm/cancel trio is justified by the safety requirement of operator confirmation, and no tool is redundant filler.
The surface covers listing, single and batch reads, history, alarm/event timelines, a guarded write lifecycle, and documentation generation â a solid lifecycle for the domain. Gaps remain: no alarm acknowledgement/reset, no batch write preparation, and no live subscription or polling for value changes. Agents can work around these but they are real omissions.