mcp_cobol — comprendre une base COBOL legacy avec un LLM

Un serveur MCP (Model Context Protocol) qui donne a un LLM les moyens d'explorer une base COBOL mainframe qu'il n'a jamais vue : graphe d'appels, usage des copybooks, acces aux donnees, analyse d'impact.

Le LLM de la demo est Mistral (La Plateforme). Le serveur, lui, est agnostique du modele : n'importe quel client MCP peut le consommer.

Base de demonstration : AWS CardDemo, application CICS / DB2 / VSAM / IMS de gestion de cartes de credit publiee par AWS. 44 programmes, 62 copybooks, 22 893 lignes. Aucun code client n'est utilise.

Pour faire la demonstration : DEMO.md — deroule minute par minute, commandes dans l'ordre, et plan B si le reseau lache.

Le probleme, en une commande

Sur une base COBOL reelle, grep ne suffit pas a savoir qui appelle qui :

grep -rhoE "PROGRAM *\([A-Z0-9()-]+\)" vendor/carddemo/app --include=*.cbl | sort -u

(Pour la rejouer : bash setup.sh d'abord — voir Demarrage — c'est lui qui clone CardDemo dans vendor/.)

PROGRAM (CCARD-NEXT-PROG)
PROGRAM (CDEMO-TO-PROGRAM)
PROGRAM (LIT-ADDTPGM)
PROGRAM (LIT-MENUPGM)
PROGRAM(CDEMO-ADMIN-OPT-PGMNAME(WS-OPTION))
PROGRAM(CDEMO-MENU-OPT-PGMNAME(WS-OPTION))
PROGRAM(CDEMO-TO-PROGRAM)
PROGRAM(WS-PGM-AUTH-FRAUD)

Huit operandes pour tous les transferts CICS de l'application, et aucun n'est un nom de programme : ce sont des variables, remplies quelques lignes plus haut.

MOVE LIT-MENUPGM TO CDEMO-TO-PROGRAM        *> LIT-MENUPGM VALUE 'COMEN01C'
EXEC CICS XCTL PROGRAM(CDEMO-TO-PROGRAM) END-EXEC

Un LLM seul ne peut pas davantage repondre : la base ne tient pas dans son contexte, et il ne l'a jamais vue. Lui donner des outils qui interrogent la base — plutot qu'esperer qu'il la memorise — c'est ce que resout MCP.

Related MCP server: arch-viewer

Demarrage

Prerequis : Python ≥ 3.10 et git.

bash setup.sh                                   # venv + deps + clone CardDemo
.venv/Scripts/python.exe -m parser.build_index  # construit data/index.json

Sous Linux/macOS : .venv/bin/python au lieu de .venv/Scripts/python.exe.

Tout ce qui precede fonctionne sans cle API — et la suite aussi :

.venv/Scripts/python.exe -m server.selftest            # 32/32
.venv/Scripts/python.exe -m server.tools impact CVACT01Y
.venv/Scripts/python.exe -m demo.ask --simulate "Que fait le programme COACTVWC ?"

Seule la demo avec le LLM demande une cle (console.mistral.ai), a placer dans .env (gitignore, la cle ne quitte jamais la machine) :

MISTRAL_API_KEY=...

.venv/Scripts/python.exe -m mistral.client      # verifie config, modeles, appel reel
.venv/Scripts/python.exe -m demo.ask "Qu'est-ce qui casse si je modifie le copybook CVACT01Y ?"

Les trois questions de demonstration

Validees de bout en bout avec mistral-medium-latest :

.venv/Scripts/python.exe -m demo.ask "Que fait le programme COACTVWC et quelles donnees manipule-t-il ?"
.venv/Scripts/python.exe -m demo.ask "Qu'est-ce qui casse si je modifie le copybook CVACT01Y ?"
.venv/Scripts/python.exe -m demo.ask "Montre-moi la chaine d'appels depuis l'ecran de connexion, et dis-moi quels programmes sont des points d'entree batch."

La troisieme se resout en 5 appels d'outils sur 6 tours, avec une auto-correction : le modele cherche d'abord « connexion » puis « login », obtient zero resultat, liste les programmes CICS et identifie COSGN00C lui-meme.

Architecture

  vendor/carddemo          parser/              data/index.json
  (COBOL brut)      ──▶    cobol_parser.py ──▶  faits extraits
                           build_index.py        + index inverse
                                                       │
                                                       ▼
   demo/ask.py    ◀──   mistral/client.py   ◀──   server/mcp_server.py
  (question NL)        (function calling)         (outils MCP)

Trois etages, volontairement decouples :

1. Parsing — lent, heuristique, sans reseau. Produit un JSON.

2. Serveur MCP — lit le JSON, expose 5 outils. Aucun import de Mistral.

3. Client LLM — le modele decide quels outils appeler et dans quel ordre.

Le serveur ne relit jamais le COBOL : chaque appel d'outil est quasi instantane, ce qui rend la demo fluide en live.

Dans server/, la logique (tools.py) est separee de la plomberie du protocole (mcp_server.py). On peut donc tester un outil en ligne de commande, et le jour ou mcp cassera son API — il est en majeure 2.x — seul le fichier de plomberie bougera.

Les cinq outils

Chacun est interrogeable directement, sans serveur ni cle API :

.venv/Scripts/python.exe -m server.tools list --role batch
.venv/Scripts/python.exe -m server.tools explain COACTVWC
.venv/Scripts/python.exe -m server.tools graph COMEN01C --depth 2
.venv/Scripts/python.exe -m server.tools copybook CVACT01Y
.venv/Scripts/python.exe -m server.tools impact CVACT01Y

# COACTVWC — Accept and process Account View request

- Role : transactionnel-cics
- Source : app/cbl/COACTVWC.cbl (703 lignes de code, 35 paragraphes)
- Transaction CICS : CAVW
- Ecran BMS : CACTVWA (mapset COACTVW)

## Donnees manipulees
- VSAM ACCTDAT — lecture (READ)
- VSAM CUSTDAT — lecture (READ)
- VSAM CXACAIX — lecture (READ)

## Navigation
- Appele par : COMEN01C
- Appelle : COMEN01C via XCTL (l. 349) — probable

## Flot interne
Point d'entree : 0000-MAIN — 17 PERFORM, 9 GO TO, 1 gestionnaire CICS
    358  1000-SEND-MAP THRU 1000-SEND-MAP-EXIT
    362  2000-PROCESS-INPUTS THRU 2000-PROCESS-INPUTS-EXIT
    369  9000-READ-ACCT THRU 9000-READ-ACCT-EXIT

## A savoir avant de conclure
- 2 copybooks absents du depot (DFHAID, DFHBMSCA) : dependances CICS
- Ecran designe par une variable non resolue (CCARD-NEXT-MAP) : valeur
  transmise par l'appelant via la COMMAREA
- 3 paragraphes cible d'aucun PERFORM/GO TO/LABEL

Chaque outil termine par « A savoir avant de conclure » : ce qu'il ne sait pas. C'est cette section qui empeche le LLM d'affirmer ce que l'analyse statique n'etablit pas — et le modele la relaie effectivement dans ses reponses.

Ce que le parseur extrait

Resoudre les appels indirects

Le parseur remonte la chaine (clauses VALUE, MOVE successifs, tables OCCURS declarees dans les copybooks) et etiquette chaque arete par sa methode de resolution :

Une arete heuristique est presentee comme telle, avec sa provenance (« table declaree dans COMEN02Y »). Un outil d'analyse d'impact qui affirme sans nuancer est pire qu'inutile.

Deterministe

Deux constructions de l'index dans des processus distincts produisent exactement le meme contenu (hors horodatage), et un outil appele quatre fois rend une sortie identique au caractere. Ce n'est pas gratuit : un parcours de set rendait le chemin d'appel affiche dependant de la randomisation du hachage de Python, donc variable d'une execution a l'autre. Un outil d'analyse dont la sortie bouge sans que l'entree bouge interdit toute comparaison et ruine la confiance.

Le serveur MCP

.venv/Scripts/python.exe -m server.selftest     # 32/32, sans cle API
.venv/Scripts/python.exe server/mcp_server.py   # lance le serveur

Lance seul, le serveur n'affiche rien : il dialogue en JSON-RPC sur stdin/stdout. L'autotest le verifie de deux facons — branche en memoire sur l'objet serveur, puis lance comme un vrai sous-processus. Le second mode est le seul qui detecte une ecriture parasite sur stdout, laquelle corrompt le protocole de maniere tres difficile a diagnostiquer.

Exemple : « qu'est-ce qui casse si je modifie le copybook CVACT01Y ? »

# Impact d'une modification de copybook CVACT01Y

23 programme(s) concerne(s) : 14 a recompiler, 9 a retester.
Repartition : 7 batch, 16 transactionnel-cics

## A recompiler — embarquent la modification
- CBACT01C (batch) — inclut CVACT01Y directement
- COACTVWC (transactionnel-cics) — inclut CVACT01Y directement
  ... 12 autres

## A retester — appellent un programme modifie
- COMEN01C (transactionnel-cics) — chaine : COMEN01C -> COBIL00C
- COPAUS1C (transactionnel-cics) — chaine : COPAUS1C -> COPAUS0C
  ... 7 autres

## Perimetre de recette
- Transactions CICS : CAUP, CAVW, CB00, CC00, CCDL, CCLI, CCUP, CM00,
                      CPVD, CPVS, CR00, CT00, CT01, CT02
- Fichiers VSAM : ACCTDAT, CARDAIX, CARDDAT, CCXREF, CUSTDAT, CXACAIX,
                  TRANSACT, USRSEC
- Segments IMS : PAUTDTL1, PAUTSUM0

La separation a recompiler / a retester n'est pas cosmetique : inclure un copybook modifie impose une recompilation, appeler un programme modifie n'impose qu'une recette. Ce sont deux charges de travail, souvent deux equipes.

Brancher un autre client MCP

{
  "mcpServers": {
    "cobol-legacy": {
      "command": "/chemin/vers/mcp_cobol/.venv/Scripts/python.exe",
      "args": ["/chemin/vers/mcp_cobol/server/mcp_server.py"]
    }
  }
}

Mistral ne parle pas MCP : le pont

Il n'existe aucun lien direct entre les deux protocoles. demo/ask.py fait trois traductions :

Puis on boucle : tant que le modele demande des outils, on execute et on renvoie. Le tool_call_id est ce qui relie une reponse a sa question quand le modele appelle plusieurs outils d'un seul coup.

Le serveur MCP tourne dans un vrai sous-processus et n'importe rien de Mistral. Changer de fournisseur ne touche que demo/ask.py et mistral/client.py.

Souverainete

Le SDK expose trois endpoints : api.mistral.ai, api.eu.mistral.ai, api.us.mistral.ai. Mettre MISTRAL_SERVER=eu dans .env route tout le trafic par l'Union europeenne. De meme, passer du modele generaliste a Codestral est une variable (MISTRAL_MODEL), pas une modification de code.

Verifier le pont sans cle API

.venv/Scripts/python.exe -m demo.ask --simulate "Qu'est-ce qui casse si je modifie le copybook CVACT01Y ?"

[demo] 5 outils MCP disponibles : list_programs, explain_program, call_graph,
       who_uses_copybook, impact_analysis
  [tour 1] impact_analysis(target='CVACT01Y')
      -> 2726 caracteres | # Impact d'une modification de copybook CVACT01Y
[demo] termine en 2 tour(s)

--simulate remplace le modele par une doublure scriptee et exerce la meme boucle sur les vrais outils MCP, a travers le vrai sous-processus : les trois traductions sont donc reellement testees. La doublure annonce explicitement qu'aucun modele n'a repondu — elle ne peut pas etre confondue avec une reponse du LLM.

Depannage

CERTIFICATE_VERIFY_FAILED au premier appel API. Un antivirus ou une appliance reseau inspecte le trafic HTTPS et reemet les certificats. L'autorite est dans le magasin du systeme mais inconnue de certifi, que Python utilise par defaut. MISTRAL_USE_SYSTEM_CERTS=true (defaut) fait utiliser le magasin de l'OS via truststore. La verification TLS reste active — ne jamais « corriger » cela en la desactivant : ce code transmet une cle API.

429 Rate limit exceeded avec x-ratelimit-limit-req-minute: 0. Ce n'est pas une limitation passagere : le compte n'a aucun droit d'appel sur les completions. A noter que /v1/models repond 200 dans ce cas — lister et appeler relevent de droits differents, donc un diagnostic qui s'arrete a la liste des modeles conclut a tort. python -m mistral.client tranche en une seconde.

ImportError: cannot import name 'Mistral' from 'mistralai'. En 2.x, mistralai est un package d'espace de noms : from mistralai.client import Mistral. Les exemples qui ecrivent from mistralai import Mistral sont du 1.x.

Nom de modele refuse. mistral-large-latest et les devstral-* ne sont plus servis. python -m mistral.client liste ceux qui le sont reellement pour votre cle.

Limites assumees

• Analyse statique et non sensible au flot : la resolution est faite par variable, pas par chemin d'execution. Si un programme charge deux valeurs differentes dans la meme variable a deux endroits, les deux cibles sont listees. Sur-approximation volontaire : en analyse d'impact, mieux vaut un candidat de trop qu'un oubli.

• Les 47 JCL ne sont pas analyses. Un programme classe batch l'est parce qu'aucun COBOL ne l'appelle, pas parce qu'on a lu sa carte EXEC PGM=.

• flow.never_targeted signifie « cible d'aucun PERFORM, GO TO ni LABEL », et non « code mort » : en COBOL un paragraphe s'execute aussi par enchainement sequentiel.

• Le parseur cible le fixed-format (colonnes 7-72), format historique mainframe. Le free-format n'est pas l'objectif.

• Pas de vocation a remplacer un outil commercial d'analyse d'impact : la valeur demontree ici est le couplage base legacy ↔ LLM.

Etat

~3 450 lignes de Python, validees depuis un clone vierge : setup.sh, index reproduit a l'identique, autotest 32/32 sans cle API, et les trois questions de demonstration repondues par mistral-medium-latest.