Serveur MCP de l0g.fr

Serveur Model Context Protocol en lecture seule, qui expose les données de l0g.fr (Agent Surface, OpenAPI, Risk Diff, Black Box Recorder, NDJSON, evidence graph, claims, sources, fraîcheur, intégrité, changefeed, historique des signaux, analyses, guides) à des agents IA via resources, prompts, resource templates et tools, avec le transport Streamable HTTP (spec 2025-11-25, le transport SSE est déprécié).

Endpoints publics visés :

• https://l0g.fr/api/mcp/compact : façade recommandée à six tools ;
• https://l0g.fr/api/mcp : surface complète conservée pour compatibilité et usages experts.

get_risk_state est le produit principal de la façade compacte. Son contrat regroupe l’état courant, le diff 1/7/30 jours, l’historique par instrument et le replay point-in-time avec date de référence, source, méthode et limites.

Le contrat anti-dérive est publié sur https://l0g.fr/api/v1/toolset-manifest.json.

État de déploiement

La version active, son SHA source et son statut d'attestation ne sont pas figés dans cette documentation. Ils sont publiés par la ressource l0g://mcp/server et vérifiables avec scripts/verify-public-mcp-release.mjs. Le daemon de production est servi depuis le runtime atomique /opt/l0g-mcp-runtime/releases/.

Réutilisation et licences

Tout client compatible MCP peut utiliser le service distant public sans compte ni clé API. Une nouvelle intégration doit commencer par https://l0g.fr/api/mcp/compact; https://l0g.fr/api/mcp conserve la surface complète pour la compatibilité et les usages experts. Les deux sont en lecture seule et consacrés aux données de l0g.fr.

Le code du serveur, ses tests et ses scripts de déploiement sont réutilisables sous licence MIT. Les textes, données et artefacts éditoriaux renvoyés par le service sont sous licence CC BY 4.0 avec attribution, dans la limite des droits détenus par leur auteur. Les éléments tiers conservent leurs propres droits. Consulter LICENSE et NOTICE.md dans l'archive de release.

L'archive Linux/Node publiée est le runtime de production de l0g.fr : elle est auditable et redistribuable selon ces licences, mais elle n'est pas présentée comme un paquet npm générique prêt à héberger un autre corpus ou domaine.

Architecture

agent / client MCP
        |  HTTPS  (Streamable HTTP, POST JSON-RPC)
        v
   Apache (443, l0g.fr)  ──reverse proxy──>  127.0.0.1:8848  (service Node, systemd)
                                                     |
                                                     | lit (lecture seule)
                                                     v
                          /var/www/html/l0g/current/agents.json
                          /var/www/html/l0g/current/openapi.json
                          /var/www/html/l0g/current/api/v1/*.json|*.ndjson
                          /var/www/html/l0g/current/risk-events.json
                          /var/www/html/l0g/current/confluence.json
                          /var/www/html/l0g/current/posts|guides/<slug>/index.html
                          /var/www/html/l0g/current/en/analysis|guides/<slug>/index.html

• Le service Node n'écoute qu'en 127.0.0.1, jamais exposé directement.
• Les données proviennent du site déjà déployé : agents.json, catalog.json, search-index.json, claims.json, evidence-graph.json, sources.json, freshness.json, integrity.json, changes.json, risk-diff.json, black-box.json, leurs variantes NDJSON, openapi.json, risk.json, debt-risk.json, risk-events.json et confluence.json. Le service ne fait que lire ces fichiers. Le cache est lié au répertoire réel de la release atomique : il est conservé tant que le symlink current pointe sur la même release, puis rechargé après la bascule.
• Mode stateless + réponse JSON : pas de session à stocker, un serveur et un transport neufs par requête.
• Un agrégat MCP séparé compte par jour et endpoint les initialisations, tools/list, appels, succès/erreurs, latences p50/p95, tailles de réponse, tools, resources, prompts et familles stables issues de clientInfo. Les user-agents internes l0g sont exclus avant agrégation. Aucune IP, session, empreinte, chaîne user-agent, requête ou réponse n’est conservée. Les libellés normalisés classés other restent sept jours dans le fichier privé afin de corriger la taxonomie ; seuls ceux atteignant k=5 sont visibles dans le diagnostic local /_l0g/mcp-client-taxonomy. Rapport public : /api/mcp/usage.

Resources exposées

Les documents et datasets stables sont exposés comme resources MCP. Les tools restent réservés aux opérations de recherche, filtrage et synthèse.

Resources statiques

Resource templates

resources/list est volontairement borné aux dix resources statiques afin de ne pas injecter le catalogue entier dans le contexte des clients. Les articles, guides, claims, sources, signaux et méthodologies restent lisibles par URI via les templates ; resources/templates/list les découvre et les variables principales conservent leurs callbacks de complétion. Les tools de recherche et de filtrage fournissent la découverte ciblée. Le service est stateless en requête/réponse et n’annonce pas resources.subscribe ni resources.listChanged : pour surveiller le corpus, lire l0g://changes/latest ou appeler get_changefeed.

Prompts exposés

Les prompts MCP sont des workflows sélectionnés explicitement par l'utilisateur. Le serveur annonce la capability prompts, sans listChanged, et valide chaque argument avant de rendre le message. Leur définition unique vit dans src/lib/agent-prompts.mjs, également utilisée par la page /agents/.

Tools exposés

Tous les tools renvoient désormais :

• un résumé humain court dans content;
• les données exploitables dans structuredContent;
• un outputSchema déclaré et validé par le SDK.
• un title et les hints readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false ;
• des resource_link natifs lorsque la réponse référence des documents, claims ou sources.

Le JSON n'est donc plus caché dans un bloc texte à reparser.

Façade compacte

Surface complète

l0g Agent Bench

Le workflow publié exécute agent-bench.mjs contre ce serveur après le test de protocole. Les 44 cas FR/EN n’appellent aucun LLM et couvrent le top 3 documentaire, les sources primaires, la parité des traductions, asOf, le refus sans preuve, la fraîcheur et le typage des claims. Le résultat versionné et attesté est publié sur /api/v1/agent-bench.json et présenté sur /agent-bench/.

Les documents longs exposent section, offset, limit, nextOffset et nextCursor. Exemple : l0g://articles/economie-des-intentions?section=sources&offset=0&limit=12000. Les références structurées sont aussi renvoyées séparément dans references, afin de ne pas dépendre du chunk de texte courant.

get_risk_diff est le chemin court pour répondre à une question de type "qu'est-ce qui a changé dans le risque depuis hier, 7 jours ou 30 jours". get_black_box sert au replay : avec date, le tool sélectionne la dernière frame publiée avant ou le jour demandé ; si aucune frame n'existe, la réponse marque la date comme non rejouable plutôt que de recalculer après coup.

get_claims regroupe les anciens chemins unitaires, par article, par source et par preuve. Les identifiants inconnus sont marqués avec isError: true. Les resources inexistantes renvoient une erreur protocolaire MCP, pas un document JSON avec champ error.

Sécurité

• Écoute 127.0.0.1 uniquement ; TLS et exposition gérés par Apache.
• Validation Host et Origin sur chaque requête (anti DNS rebinding, exigé par la spec).
• Corpus en lecture seule : aucune donnée éditoriale n'est modifiée, les slugs sont en allowlist (le path traversal est rejeté) et la taille du corps est bornée à 1 Mo.
• Télémétrie minimale : seule la StateDirectory systemd reçoit un agrégat sur 91 jours, sans IP, cookie, session, empreinte ou user-agent. Les familles client sous cinq initialisations sont masquées dans le rapport public.
• Rate limit par IP (120 req/min par défaut, via X-Forwarded-For posé par Apache).
• Apache reverse-proxy : LimitRequestBody aligné à 1 Mo, entêtes de sécurité sur réponse, timeout applicatif 30 s, keepalive proxy désactivé sur l’endpoint.
• systemd durci : DynamicUser, TimeoutStartSec=45, TimeoutStopSec=15, UMask=0077, PrivateIPC, LimitCORE=0, ProtectSystem=strict, capacités vidées, ReadOnlyPaths, MemoryMax, filtre d'appels système.

Déploiement atomique (Debian, serveur « zen »)

Hypothèses : Apache sert déjà l0g.fr en HTTPS, le site est déployé dans /var/www/html/l0g/current. Node 22+ requis.

1. Installer Node 24 LTS pour les services MCP

sudo deploy/install-node24-runtime.sh

Le script installe le binaire officiel Node.js 24.18.1 sous /opt, vérifie son SHA-256 figé, ne remplace pas le paquet Debian et bascule uniquement les services MCP via des drop-ins systemd. Il conserve l'identité du daemon actif et restaure la configuration précédente si le contrôle de santé échoue.

2. Installer une fois le poller de releases attestées

Le runbook complet, le bloc de migration avec sauvegardes et la procédure de release sont dans docs/MCP-RELEASE.md. Après cette migration, le serveur ne lance plus git pull ni npm ci : il poll les GitHub Releases publiques, vérifie SHA-256 et l'attestation GitHub/Sigstore, teste le candidat, puis bascule un symlink atomiquement avec rollback automatique.

Prérequis supplémentaires : GitHub CLI doit fournir gh attestation verify. Le timer et le daemon n'ouvrent aucun port entrant de déploiement et n'utilisent aucun token GitHub permanent.

3. Test à blanc d'une source locale

L0G_DATA_DIR=/var/www/html/l0g/current \
MCP_USAGE_PATH=/tmp/l0g-mcp-usage-test.json node server.mjs &
curl -s http://127.0.0.1:8848/healthz       # -> versions MCP/Agent Surface, SHA et fraîcheur chargée
node test-client.mjs                          # liste les tools et teste chaque appel
# le script force l'en-tête Accept requis par le Streamable HTTP :
# application/json, text/event-stream
kill %1

4. Contrôler le service et le timer

systemctl status l0g-mcp l0g-mcp-deploy.timer --no-pager
journalctl -u l0g-mcp-deploy.service -n 100 --no-pager
curl -s http://127.0.0.1:8848/healthz        # -> versions MCP/Agent Surface, SHA et fraîcheur chargée

5. Brancher Apache (reverse proxy)

sudo a2enmod proxy proxy_http headers

Le vhost complet maintenu dans le dépôt est ../deploy/l0g.fr.apache.conf. En production, il doit être installé transactionnellement dans /etc/apache2/sites-available/l0g.fr-hardened.conf, après sauvegarde du fichier actif. Le fragment deploy/apache-l0g-mcp.conf reste une référence isolée pour les deux routes MCP, pas la source du vhost de production. Puis :

sudo apache2ctl configtest        # Syntax OK
sudo systemctl reload apache2

Après reload :

sudo apache2ctl -M | rg -e "proxy_module|proxy_http_module|headers_module|rewrite_module"
curl -s -I https://l0g.fr/api/mcp/compact | sed -n '1,20p'
curl -s -I https://l0g.fr/api/mcp | sed -n '1,20p'

6. Vérifier de l'extérieur

Cycle MCP minimal en JSON-RPC brut sur la façade compacte recommandée :

curl -s -X POST https://l0g.fr/api/mcp/compact \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'

curl -s -X POST https://l0g.fr/api/mcp/compact \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -s -X POST https://l0g.fr/api/mcp/compact \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | head -c 400

Ou pointer un client compatible (Claude Desktop via mcp-remote, l'inspecteur MCP, etc.) sur https://l0g.fr/api/mcp/compact. Remplacer l'URL par https://l0g.fr/api/mcp uniquement pour les outils spécialisés de la surface complète.

Après sept jours de collecte, l’opérateur peut lire les libellés normalisés qui composent encore other. Le chemin n’est pas proxifié par Apache et refuse toute requête non locale :

curl -fsS http://127.0.0.1:8848/_l0g/mcp-client-taxonomy

Mises à jour

• Données (nouvel article, indices) : automatique. Le site se redéploie et la bascule atomique vers un nouveau répertoire invalide immédiatement le cache du service.
• Code du serveur : automatique après un tag mcp-vX.Y.Z. Le workflow construit une archive versionnée avec SBOM, l'atteste par OIDC, la publie en GitHub Release, attend le déploiement atomique de zen, puis publie le manifeste dans le MCP Registry par OIDC.
• Registry : canal de découverte en preview, principalement destiné aux agrégateurs downstream. Il est vérifié après publication, mais ne remplace ni les tests vivants ni la stratégie d'adoption.

Variables d'environnement