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.

Diagnostic de fiabilité

Le rapport /api/mcp/usage conserve les compteurs de succès et d’erreurs. Un succès technique indique seulement une réponse MCP sans erreur déclarée ; il ne valide ni l’analyse économique, ni la source, ni la fraîcheur du résultat.

Chaque ligne tools expose désormais error_reasons, des catégories fixes agrégées sur la même fenêtre que le compteur d’erreurs. Chaque catégorie publiée atteint k=5. errors_without_detailed_reason inclut les anciennes erreurs sans cause enregistrée et les catégories sous ce seuil. Le fichier de schéma 2 reste lisible sans le nouveau champ interne errorReasons. Aucun nom d’outil inconnu, argument, slug, texte de réponse ou identifiant réseau n’est enregistré.

Catégorie	Action de diagnostic
invalid_arguments, invalid_date, invalid_cursor	Consulter le contrat de l’outil ; reprendre les curseurs opaques retournés et une date civile valide.
document_not_found	Rechercher le slug exact et sa langue avec search_l0g ou search_content.
content_unavailable	Contrôler la présence du fichier HTML dans la release active.
tool_unavailable	Relire tools/list sur le même endpoint compact ou complet.
output_contract, internal_error	Reproduire sur la release exacte et contrôler les tests du serveur.
access_denied, rate_limited, transport_contract, invalid_request, connection_closed	Contrôler le transport, les en-têtes et les limites sans désactiver les protections.
tool_error, unclassified	Cause encore non qualifiée ; ne pas lui attribuer une explication sans reproduction.

Les causes des 30 erreurs get_document et 32 erreurs build_research_pack mentionnées dans le rapport du 8 octobre 2026 ne peuvent pas être reconstruites à partir de ces seuls agrégats. Les correctifs locaux de pagination et de validation ont des tests de régression ; ils ne démontrent pas la cause de ces événements historiques. Pour comparer une nouvelle release, relever sa version et son SHA avec les dates des captures avant/après, puis calculer les erreurs sur les seuls résultats connus. Ne pas mélanger deux fenêtres glissantes comme s’il s’agissait d’un flux exact entre deux dates.

La catégorie client other reste inconnue tant que le diagnostic local ne fournit pas d’éléments suffisants. Ne pas l’attribuer à un fournisseur par supposition. Les familles déclarées et les jours actifs ne comptent ni personnes ni installations uniques.

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

URI	Contenu
l0g://agent-manifest	manifeste Agent Surface
l0g://mcp/server	version, SHA et transport du serveur MCP actif
l0g://openapi	contrat OpenAPI complet
l0g://freshness	fraîcheur du corpus
l0g://integrity	empreintes SHA-256 canoniques
l0g://changes/latest	dernières publications et révisions
l0g://risk-diff	diff du risque sur 1, 7 et 30 jours
l0g://black-box	frames point-in-time hashées du risque
l0g://signals/current	état courant des signaux
l0g://signals/history	observations point-in-time et alertes de seuil

Resource templates

Template	Contenu
l0g://articles/{slug}	première page d'un article avec métadonnées, références et texte
l0g://articles/{slug}{?section,offset,limit}	page ciblée d'un article (body, head, tail, sources)
l0g://articles/{slug}{?cursor}	continuation d'article via nextCursor
l0g://en/articles/{slug}	première page d'une analyse anglaise, reliée aux preuves françaises canoniques
l0g://en/articles/{slug}{?section,offset,limit}	page ciblée d'une analyse anglaise
l0g://en/articles/{slug}{?cursor}	continuation d'analyse anglaise via nextCursor
l0g://guides/{slug}	première page d'un guide avec métadonnées et texte
l0g://guides/{slug}{?section,offset,limit}	page ciblée d'un guide (body, head, tail, sources)
l0g://guides/{slug}{?cursor}	continuation de guide via nextCursor
l0g://en/guides/{slug}	première page d'un guide anglais
l0g://en/guides/{slug}{?section,offset,limit}	page ciblée d'un guide anglais
l0g://en/guides/{slug}{?cursor}	continuation de guide anglais via nextCursor
l0g://claims/{claim_id}	relation affirmation-source
l0g://sources/{source_id}	source primaire ou hôte cité
l0g://signals/{instrument}/current	signal courant + historique de franchissement
l0g://methodologies/{instrument}	fiche méthodologique

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/.

Prompt	Arguments	Workflow
audit_financial_narrative	topic, language?	auditer un récit financier et séparer claims, preuves, inférences, scénarios et limites
explain_risk_change	window?, language?	expliquer un Risk Diff publié sur 1, 7 ou 30 jours sans extrapolation
verify_claim	claim, language?	vérifier une affirmation contre les claims canoniques, leurs preuves et leurs sources
replay_as_of	date, question?, language?	rejouer uniquement une frame Black Box réellement archivée à la date demandée

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

Tool	Rôle
discover_l0g	capacités, versions, fraîcheur, règles et contrats
search_l0g	recherche bilingue filtrée dans tout le corpus
get_document	article ou guide paginé avec références
get_evidence	claims, sources et sous-graphe de preuve
build_research_pack	paquet de recherche déterministe prêt à citer
get_risk_state	courant, diff, historique ou replay

Surface complète

Tool	Arguments	Renvoie
get_agent_manifest	aucun	capacités, endpoints, règles d'usage et politiques de preuve
get_risk_indices	aucun	indices de risque (US, EU, Yen, Energie, Dette US) + résumé confluence
get_signal_history	key?, limit?	observations datées, identité citable, version méthodologique, franchissements + état courant
get_risk_diff	window?	Risk Diff sur 1, 7 ou 30 jours : signaux, sources, claims, modèles, articles et confiance
get_black_box	date?, limitFrames?	replay point-in-time des frames de risque hashées, avec refus des dates non rejouables
get_openapi_schema	mode?, path?	contrat OpenAPI résumé, ciblé par endpoint ou complet
get_ndjson_feed	feed, recordType?, limit?	flux NDJSON allowlistés : catalogue, claims, evidence graph, changes, signalHistory
get_freshness	limit?	derniers contenus, compteurs, temporalité par signal et politique de fraîcheur
search_content	query, language?, mode?, limit?	recherche bilingue sur l'index canonique partagé avec l'Agent Surface et WebMCP
build_research_pack	query, language, asOf?, riskWindow?, limit?	paquet de preuves déterministe : documents, claims canoniques, sources, graphe, fraîcheur, Risk Diff, éléments adverses, limites et URLs citables
get_claims	claimId?, articleSlug?, language?, sourceId?, kind?, query?, includeEvidence?, limit?	recherche, claim précise, filtrage article/source et voisinage de preuve dans un contrat unique
get_evidence_graph	articleSlug?, language?, nodeType?, limit?	sous-graphe canonique ; un slug anglais pointe vers le graphe français sans duplication
list_sources	sourceId?, mode?, includeClaims?, limit?	liste ou source précise, avec claims associées sur demande
get_integrity	path?	empreintes SHA-256 canoniques des surfaces Agent Surface
verify_artifact	path, sha256?	vérification allowlistée d'un artefact via le manifeste d'intégrité
get_changefeed	contentType?, limit?	derniers changements avec objectId, version/hash courant et statut de diff
get_changes	contentType?, slug?, since?, limit?	changefeed filtrable avec métadonnées de version
list_recent_analyses	language?, limit?	dernières analyses, filtrables en fr ou en
list_guides	language?	guides de référence français ou anglais
search_by_topic	topic, language?, limit?	analyses d'un sujet, filtrables par langue
get_article	slug, language?, offset?, cursor?, limit?, length?, section?	texte paginé français ou anglais, avec références canoniques séparées

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

Variable	Défaut	Rôle
MCP_HOST	127.0.0.1	interface d'écoute
MCP_PORT	8848	port local
MCP_PATH	/mcp	chemin de l'endpoint
MCP_USAGE_PATH	absent	fichier privé de compteurs agrégés ; /var/lib/l0g-mcp/usage.json en production
L0G_DATA_DIR	/var/www/html/l0g/current	racine du site déployé (lecture)
L0G_SITE	https://l0g.fr	base des URL renvoyées
MCP_ALLOWED_HOSTS	l0g.fr,127.0.0.1,localhost	en-têtes Host acceptés
MCP_ALLOWED_ORIGINS	https://l0g.fr	en-têtes Origin acceptés
MCP_MAX_BODY_BYTES	1048576	limite de payload par requête (1 Mo)
MCP_RATE_MAX	120	requêtes/min/IP
MCP_HEADER_TIMEOUT	10000	timeout headers HTTP (ms)
MCP_REQUEST_TIMEOUT	15000	timeout requête HTTP complet (ms)
MCP_KEEP_ALIVE_TIMEOUT	5000	timeout keep-alive TCP (ms)
MCP_MAX_HEADERS_COUNT	64	nombre maximum d'en-têtes parsables
MCP_RELEASE_ATTESTED	absent	1 uniquement dans une archive dont le poller a vérifié la provenance