l0g.fr Risk Intelligence

l0g.fr MCP 服务

只读的 Model Context Protocol 服务，通过资源、提示词、资源模板和工具向 AI Agent 提供 l0g.fr 的数据（Agent Surface、OpenAPI、Risk Diff、Black Box Recorder、NDJSON、证据图谱、声明、来源、新鲜度、完整性、变更流、信号历史、分析、指南），使用 Streamable HTTP 传输（规范 2025-11-25，SSE 传输已弃用）。

目标公共端点：

• https://l0g.fr/api/mcp/compact：推荐使用的六工具接口；
• https://l0g.fr/api/mcp：为兼容性和专家用途保留的完整接口。

get_risk_state 是精简接口的主要产品。其契约整合了当前状态、1/7/30 天差异、按工具划分的历史记录，以及带有基准日期、来源、方法和限制的时间点回放。

防漂移契约发布于 https://l0g.fr/api/v1/toolset-manifest.json。

部署状态

当前版本、源代码 SHA 和证明状态不会固定在本文档中。它们通过资源 l0g://mcp/server 发布，也可通过 scripts/verify-public-mcp-release.mjs 验证。 生产守护进程从原子运行时目录 /opt/l0g-mcp-runtime/releases/ 提供服务。

复用与许可

任何兼容 MCP 的客户端都可以无需账户或 API 密钥使用公共远程服务。新的集成应从 https://l0g.fr/api/mcp/compact 开始；https://l0g.fr/api/mcp 保留完整接口， 以满足兼容性和专家用途。两者均为只读，专用于 l0g.fr 数据。

服务代码、测试和部署脚本均可依据 MIT 许可证复用。服务返回的文本、数据和编辑类产物依据 CC BY 4.0 许可证授权，须注明出处，且以作者拥有的权利为限。第三方内容仍受其各自权利约束。请参阅发行归档中的 LICENSE 和 NOTICE.md。

发布的 Linux/Node 归档是 l0g.fr 的生产运行时：它可依据上述许可证接受审计和再分发，但并未作为可用于托管其他语料或域名的通用 npm 软件包提供。

架构

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

• Node 服务仅监听 127.0.0.1，绝不直接对外开放。
• 数据来自已部署的网站：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、它们的 NDJSON 变体、openapi.json、risk.json、debt-risk.json、 risk-events.json 和 confluence.json。服务只会读取这些文件。 缓存与原子发行版的实际目录绑定：只要符号链接 current 指向同一发行版，缓存就会保留；切换后则重新加载。
• 无状态 + JSON 响应模式：无需存储会话，每个请求都会创建新的服务器和传输。
• 独立的 MCP 汇总器按日和端点统计初始化次数、 tools/list、调用次数、成功/错误次数、p50/p95 延迟、响应大小、 工具、资源、提示词，以及根据 clientInfo 得出的稳定类别。 聚合前会排除 l0g 内部 user-agent。不会保留任何 IP、会话、 指纹、user-agent 字符串、请求或响应。归一化标签中归类为 other 的标签会在私有文件中保留七天，以便修正分类体系；只有达到 k=5 的标签才会显示在本地诊断端点 /_l0g/mcp-client-taxonomy 中。公开报告：/api/mcp/usage。

可靠性诊断

/api/mcp/usage 报告会保留成功和错误计数。技术层面的成功仅表示返回了未声明错误的 MCP 响应；它并不能验证经济分析、来源或结果的新鲜度。

每个 tools 行现在都包含 error_reasons，这是在与错误计数相同的时间窗口内汇总的固定类别。每个已发布类别的样本量均达到 k=5。errors_without_detailed_reason 包含未记录原因的旧错误，以及未达到此阈值的类别。即使没有新的内部字段 errorReasons，架构文件 2 仍可读取。系统不会记录任何未知工具名称、参数、slug、响应文本或网络标识符。

类别	诊断操作
invalid_arguments、invalid_date、invalid_cursor	查阅工具契约；使用返回的不透明游标和有效的公历日期重试。
document_not_found	使用 search_l0g 或 search_content 搜索准确的 slug 和语言。
content_unavailable	检查活动 release 中是否存在 HTML 文件。
tool_unavailable	在同一个紧凑或完整 endpoint 上重新读取 tools/list。
output_contract、internal_error	在对应的准确 release 上复现，并检查服务端测试。
access_denied、rate_limited、transport_contract、invalid_request、connection_closed	检查传输、请求头和限制，但不要禁用保护措施。
tool_error、unclassified	原因尚未明确；未经复现，不要擅自为其归因。

2026 年 10 月 8 日报告中提到的 30 次 get_document 错误和 32 次 build_research_pack 错误，无法仅凭这些聚合数据还原原因。本地分页和验证修复已有回归测试；但这些测试不能证明上述历史事件的原因。比较新 release 时，记录其版本和 SHA，以及前后两次采集的日期，然后仅根据已知结果计算错误数。不要把两个滚动时间窗口混在一起，当作两个日期之间的精确数据流。

在本地诊断提供充分依据之前，客户端类别 other 仍属未知。不要猜测其所属提供商。已声明的类别和活跃天数既不代表人数，也不代表独立安装数量。

暴露的 Resources

稳定文档和数据集以 MCP resources 的形式暴露。tools 仍仅用于搜索、筛选和摘要操作。

静态 Resources

URI	内容
l0g://agent-manifest	Agent Surface 清单
l0g://mcp/server	活动 MCP 服务的版本、SHA 和传输方式
l0g://openapi	完整的 OpenAPI 契约
l0g://freshness	语料库的新鲜度
l0g://integrity	规范 SHA-256 哈希
l0g://changes/latest	最新发布和修订
l0g://risk-diff	1、7 和 30 天的风险差异
l0g://black-box	经哈希处理的风险时间点帧
l0g://signals/current	信号当前状态
l0g://signals/history	时间点观测和阈值告警

资源模板

模板	内容
l0g://articles/{slug}	文章首页，包含元数据、引用和正文
l0g://articles/{slug}{?section,offset,limit}	文章的指定页面（body、head、tail、sources）
l0g://articles/{slug}{?cursor}	通过 nextCursor 继续读取文章
l0g://en/articles/{slug}	英文分析首页，关联至规范的法语证据
l0g://en/articles/{slug}{?section,offset,limit}	英文分析的指定页面
l0g://en/articles/{slug}{?cursor}	通过 nextCursor 继续读取英文分析
l0g://guides/{slug}	指南首页，包含元数据和正文
l0g://guides/{slug}{?section,offset,limit}	指南的指定页面（body、head、tail、sources）
l0g://guides/{slug}{?cursor}	通过 nextCursor 继续读取指南
l0g://en/guides/{slug}	英文指南首页
l0g://en/guides/{slug}{?section,offset,limit}	英文指南的指定页面
l0g://en/guides/{slug}{?cursor}	通过 nextCursor 继续读取英文指南
l0g://claims/{claim_id}	主张与来源的关系
l0g://sources/{source_id}	引用的原始来源或托管方
l0g://signals/{instrument}/current	当前信号 + 突破历史
l0g://methodologies/{instrument}	方法论说明

resources/list 有意限制为十个静态资源，以免将整个目录注入客户端的上下文。文章、指南、 claims、来源、信号和方法论仍可通过模板按 URI 读取； resources/templates/list 可发现这些模板，主要变量也保留了补全回调。搜索和筛选工具可提供定向发现。服务 采用无状态的请求/响应模式，且 不声明 resources.subscribe 或 resources.listChanged：如需监控语料库，请读取 l0g://changes/latest 或调用 get_changefeed。

暴露的提示词

MCP 提示词是由用户明确选择的工作流。服务器 声明 prompts capability，不包含 listChanged，并在生成消息前验证每个参数。其唯一定义位于 src/lib/agent-prompts.mjs，/agents/ 页面也使用该定义。

提示词	参数	工作流
audit_financial_narrative	topic、language?	审计一篇金融叙述，并区分 claims、证据、推断、情景和局限
explain_risk_change	window?、language?	解释以 1、7 或 30 天为周期发布的 Risk Diff，不作外推
verify_claim	claim、language?	对照规范 claims、相关证据及来源，核实一项主张
replay_as_of	date、question?、language?	仅重放所请求日期实际归档的 Black Box frame

暴露的工具

现在，所有工具都会返回：

• content 中的简短自然语言摘要；
• structuredContent 中可供处理的数据；
• 已声明并经 SDK 验证的 outputSchema。
• title，以及 hints：readOnlyHint: true、destructiveHint: false、 idempotentHint: true、openWorldHint: false；
• 当响应引用文档、claims 或来源时，返回原生 resource_link。

因此，JSON 不再隐藏在需要重新解析的文本块中。

精简接口

工具	作用
discover_l0g	能力、版本、新鲜度、规则和契约
search_l0g	对整个语料库进行双语筛选搜索
get_document	带引用的分页文章或指南
get_evidence	claims、来源和证据子图
build_research_pack	可直接引用的确定性研究资料包
get_risk_state	当前状态、差异、历史或重放

完整接口

工具	参数	返回内容
get_agent_manifest	无	能力、端点、使用规则和证据政策
get_risk_indices	无	风险指数（US、EU、Yen、Energie、Dette US）+ 共振摘要
get_signal_history	key?、limit?	带日期的观测、可引用身份、方法版本、越界情况 + 当前状态
get_risk_diff	window?	1、7 或 30 天的 Risk Diff：信号、来源、claims、模型、文章和置信度
get_black_box	date?、limitFrames?	风险帧哈希的时点回放，并拒绝无法回放的日期
get_openapi_schema	mode?、path?	按端点定向的摘要版或完整 OpenAPI 合约
get_ndjson_feed	feed、recordType?、limit?	allowlist 中的 NDJSON 数据流：目录、claims、证据图谱、变更、signalHistory
get_freshness	limit?	最新内容、计数、按信号划分的时效性和新鲜度政策
search_content	query、language?、mode?、limit?	在与 Agent Surface 和 WebMCP 共用的规范索引中进行双语搜索
build_research_pack	query、language、asOf?、riskWindow?、limit?	确定性证据包：文档、规范 claims、来源、图谱、时效性、Risk Diff、对立材料、限制和可引用 URL
get_claims	claimId?、articleSlug?、language?、sourceId?、kind?、query?、includeEvidence?、limit?	在统一合约中搜索、查询具体 claim、按文章/来源筛选及查看证据邻域
get_evidence_graph	articleSlug?、language?、nodeType?、limit?	规范子图；英文 slug 指向法语图谱，不会重复创建
list_sources	sourceId?、mode?、includeClaims?、limit?	来源列表或具体来源，可按需附带相关 claims
get_integrity	path?	Agent Surface 各界面的规范 SHA-256 哈希
verify_artifact	path、sha256?	通过完整性清单验证 allowlist 中的制品
get_changefeed	contentType?、limit?	最近的变更，包含 objectId、当前版本/哈希和差异状态
get_changes	contentType?、slug?、since?、limit?	可筛选的变更流，附带版本元数据
list_recent_analyses	language?、limit?	最近的分析，可按 fr 或 en 筛选
list_guides	language?	法语或英语参考指南
search_by_topic	topic、language?、limit?	某个主题的分析，可按语言筛选
get_article	slug、language?、offset?、cursor?、limit?、length?、section?	分页的法语或英语正文，并单独提供规范引用

l0g Agent Bench

已发布的工作流会在协议测试后，针对此服务运行 agent-bench.mjs。这 44 个法语/英语测试用例不会调用任何大模型，涵盖文档排名前三、主要来源、翻译一致性、asOf、无证据时拒绝回答、时效性以及声明类型。带版本号并经过证明的结果发布在 /api/v1/agent-bench.json，并展示在 /agent-bench/。

长文档会公开 section、offset、limit、nextOffset 和 nextCursor。示例： l0g://articles/economie-des-intentions?section=sources&offset=0&limit=12000。 结构化引用也会单独返回在 references 中，因此无需依赖当前文本块。

get_risk_diff 是回答“自昨天、7 天或 30 天前以来风险发生了哪些变化”这类问题的捷径。get_black_box 用于回放：提供 date 时，工具会选择请求日期当天或之前发布的最新帧；如果不存在帧，响应会将该日期标记为不可回放，而不是事后重新计算。

get_claims 整合了旧有的按篇文章、按来源和按证据查询的单项接口。未知标识符会标记为 isError: true。 不存在的资源会返回 MCP 协议错误，而不是带有 error 字段的 JSON 文档。

安全

• 仅监听 127.0.0.1；TLS 和对外暴露由 Apache 管理。
• 对每个请求进行 Host 和 Origin 验证（防 DNS 重绑定，规范要求）。
• 语料库只读：不会修改任何编辑数据，slug 采用 允许列表（拒绝路径遍历），请求正文大小限制为 1 MB。
• 最小化遥测：只有 systemd 的 StateDirectory 会接收为期 91 天的汇总数据， 不包含 IP、cookie、会话、指纹或 user-agent。公开报告会隐藏初始化次数少于五次的客户端类别。
• 按 IP 限制速率（默认 120 次请求/分钟，通过 Apache 设置的 X-Forwarded-For）。
• Apache 反向代理：LimitRequestBody 与 1 MB 限制一致，响应带有安全标头， 应用超时为 30 秒，并在此端点禁用代理 keepalive。
• systemd 加固：DynamicUser、TimeoutStartSec=45、TimeoutStopSec=15、UMask=0077、 PrivateIPC、LimitCORE=0、ProtectSystem=strict、清空 capabilities、ReadOnlyPaths、 MemoryMax、系统调用过滤器。

原子部署（Debian，服务器“zen”）

假设：Apache 已通过 HTTPS 提供 l0g.fr，站点部署在 /var/www/html/l0g/current。需要 Node 22+。

1. 为 MCP 服务安装 Node 24 LTS

sudo deploy/install-node24-runtime.sh

脚本会在 /opt 下安装官方 Node.js 24.18.1 二进制文件，校验固定的 SHA-256， 不会替换 Debian 软件包，并且只通过 systemd drop-in 切换 MCP 服务。脚本会保留当前活动守护进程的身份；如果健康检查失败，则恢复先前的配置。

2. 一次性安装经过证明的版本发布轮询器

完整运行手册、包含备份的迁移步骤和版本发布流程见 docs/MCP-RELEASE.md。 完成此迁移后，服务器不再运行 git pull 或 npm ci：它会轮询公开的 GitHub Releases，校验 SHA-256 和 GitHub/Sigstore 证明，测试候选版本，然后通过原子方式切换符号链接，并自动回滚。

其他前提条件：GitHub CLI 必须提供 gh attestation verify。计时器和守护进程不会开放任何入站部署端口，也不会使用任何永久 GitHub token。

3. 对本地来源进行空跑测试

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. 检查服务和计时器

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. 配置 Apache（反向代理）

sudo a2enmod proxy proxy_http headers

仓库中维护的完整虚拟主机配置位于 ../deploy/l0g.fr.apache.conf。在生产环境中，应先备份当前启用的文件，再以事务方式将其安装到 /etc/apache2/sites-available/l0g.fr-hardened.conf。deploy/apache-l0g-mcp.conf 片段仅作为两个 MCP 路由的独立参考，并非生产环境虚拟主机的来源。然后：

sudo apache2ctl configtest        # Syntax OK
sudo systemctl reload apache2

重新加载后：

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. 从外部验证

在推荐的精简门面上，通过原始 JSON-RPC 执行最简 MCP 流程：

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

或者，让兼容的客户端（通过 mcp-remote 使用的 Claude Desktop、MCP 检查器等）连接到 https://l0g.fr/api/mcp/compact。只有在完整功能面使用专用工具时，才将 URL 替换为 https://l0g.fr/api/mcp。

收集七天后，运营人员可以查看仍归入 other 的标准化标签。该路径不会经 Apache 代理，并且会拒绝所有非本地请求：

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

更新

• 数据（新文章、线索）：自动更新。网站会重新部署，原子切换到新目录后，服务缓存会立即失效。
• 服务器代码：在创建 mcp-vX.Y.Z 标签后自动更新。工作流会构建带有 SBOM 的版本化归档，通过 OIDC 进行证明，将其发布为 GitHub Release，等待 zen 完成原子部署，然后通过 OIDC 将清单发布到 MCP Registry。
• Registry：处于预览阶段的发现渠道，主要面向下游聚合器。发布后会进行验证，但它不能替代实时测试或采用策略。

环境变量

变量	默认值	作用
MCP_HOST	127.0.0.1	监听接口
MCP_PORT	8848	本地端口
MCP_PATH	/mcp	endpoint 路径
MCP_USAGE_PATH	未设置	聚合计数器的私有文件；生产环境中为 /var/lib/l0g-mcp/usage.json
L0G_DATA_DIR	/var/www/html/l0g/current	已部署网站的根目录（只读）
L0G_SITE	https://l0g.fr	返回 URL 的基址
MCP_ALLOWED_HOSTS	l0g.fr,127.0.0.1,localhost	允许的 Host 标头
MCP_ALLOWED_ORIGINS	https://l0g.fr	允许的 Origin 标头
MCP_MAX_BODY_BYTES	1048576	每个请求的负载限制（1 MB）
MCP_RATE_MAX	120	请求数/分钟/IP
MCP_HEADER_TIMEOUT	10000	HTTP 标头超时时间（ms）
MCP_REQUEST_TIMEOUT	15000	完整 HTTP 请求超时时间（ms）
MCP_KEEP_ALIVE_TIMEOUT	5000	TCP keep-alive 超时时间（ms）
MCP_MAX_HEADERS_COUNT	64	可解析标头的最大数量
MCP_RELEASE_ATTESTED	未设置	仅在轮询器已验证来源的归档中设为 1