13FLOW

13FLOW MCP 服务

此目录包含 13FLOW 的生产环境 MCP 接口。

它与 Flask 应用刻意分开：

• Flask 提供公开网站、公开 API 和 Pro API。
• 此 Node 服务通过 Streamable HTTP 提供 Model Context Protocol 端点。
• Apache 将此服务发布到 https://13flow.eu/api/mcp。
• 此服务调用本地 Flask API http://127.0.0.1:8000，不会接触 EDGAR。

此设计采用与 l0g.fr MCP 架构相同的模式：无状态传输、每个请求创建一个 MCP 服务、限制 JSON 请求体大小、验证 Host/Origin、按 IP 限流、提供运行状况检查、结构化工具输出和只读注解。

能力边界

公开工具免费且只读：

• get_live_status
• get_product_status
• get_research_readiness
• list_funds
• get_fund
• get_stock
• preview_watchlist
• discover_watchlist
• get_confluence_signals
• get_signal_history
• get_confluence_methodology
• get_data_quality
• get_agent_stats

公开资源包括 13flow://product-status、13flow://research-readiness 和 13flow://agent-stats。 它们展示当前的验证、数据质量和运营人员审核边界，不会将已停用的公开商业服务转变为面向 Agent 的服务契约。

get_agent_stats、该资源和 GET /stats 会公开与 /agents、/fr/agents 和 /api/agent-stats 相同的隐私安全计数器。它们仅存储 UTC 每日聚合数据： 固定的客户端类别、已注册的工具名称、处理程序结果和耗时计数器。遥测存储绝不保留 IP 地址、User-Agent、客户端版本、原始客户端名称、参数、提示词、响应或密钥。初始化是一次握手，不代表唯一用户。

默认情况下，上下文密集型工具均受限。list_funds 返回精简的分页行数据；基金和股票代码工具会明确提供结果窗口计数；观察列表工具会限制变动证据，同时在结构化输出中保留规范的网址和 API URL。

可选 Pro 工具为只读，但只有在运营人员主动设置 MCP_PRO_TOOLS_ENABLED=1 后才会注册或公开：

• pro.list_funds
• pro.get_fund
• pro.get_data_quality

启用此独立配置后，只有满足以下任一条件时才接受调用：

1. 请求在 X-13FLOW-Key 中包含有效的现有 13FLOW Pro API 密钥。
2. 请求包含 x402 v2 PAYMENT-SIGNATURE，且该签名已通过配置的 facilitator 验证并结算。

MCP Pro 凭据不接受客户端的 Authorization 标头，也不会将其转发到下游。这可以防止 MCP OAuth 令牌被传递给不同的 API 受众。

如果两个条件都不满足，服务将返回 HTTP 402 Payment Required，并附带 PAYMENT-REQUIRED 标头。响应正文仍采用 JSON-RPC 格式，以便 MCP 客户端显示清晰的失败信息。

x402 策略

13FLOW 可将 x402 用作机器到机器支付门槛，用于单次 Pro MCP 工具调用。 默认情况下，此功能处于禁用状态，不包含在 Registry 配置文件中，也不属于当前的公开服务。 启用此功能还需要明确指定 Pro 配置文件，并重新进行安全运营审查。 服务会为每个付费工具公布一个可接受的支付选项：

• scheme：默认为 exact
• network：默认为 eip155:8453
• price：MCP_X402_PRICE
• destination：MCP_X402_PAY_TO
• resource：https://13flow.eu/api/mcp#<tool>

该服务采用失败时默认拒绝策略：

• 如果未设置 MCP_X402_ENABLED=1，则不授予 x402 付费访问权限；
• 如果未设置 MCP_X402_PAY_TO，则不授予 x402 付费访问权限；
• 如果未设置 MCP_X402_FACILITATOR_URL，则不授予 x402 付费访问权限；
• 如果未设置 MCP_13FLOW_INTERNAL_PRO_TOKEN_FILE，则不授予 x402 付费访问权限；
• MCP 工具运行前，支付必须通过 facilitator 的 /verify 和 /settle。

此实现遵循 x402 v2 HTTP 标头：

• PAYMENT-REQUIRED：从服务端发送到客户端，包含 base64 JSON 支付要求；
• PAYMENT-SIGNATURE：从客户端发送到服务端，包含 base64 JSON 支付载荷；
• PAYMENT-RESPONSE：从服务端发送到客户端，包含 base64 JSON 结算响应。

此实现接受可选的 payment-identifier 扩展。存在该扩展时，服务端会存储与指纹绑定的短期结算缓存，以确保对完全相同请求的重试不会作为不同的付费操作执行。在负载均衡器后运行多个 MCP 副本前，请使用 Redis 或其他共享存储。

环境

MCP_HOST=127.0.0.1
MCP_PORT=8849
MCP_PATH=/mcp
MCP_PUBLIC_SITE=https://13flow.eu
MCP_13FLOW_API_BASE=http://127.0.0.1:8000
# Required only for an explicitly enabled isolated Pro profile.
MCP_13FLOW_PRO_API_BASE=http://127.0.0.1:8001
MCP_ALLOWED_HOSTS=13flow.eu,www.13flow.eu,127.0.0.1,localhost
MCP_ALLOWED_ORIGINS=https://13flow.eu,https://www.13flow.eu
MCP_RATE_MAX=120
MCP_MAX_RATE_BUCKETS=10000
MCP_MAX_BODY=1048576
MCP_MAX_UPSTREAM_BODY=8388608
MCP_MAX_IN_FLIGHT=32
MCP_MAX_CONNECTIONS=128
MCP_MAX_PAYMENT_CACHE=500
MCP_STATS_RETENTION_DAYS=30
# Production is pinned to this systemd StateDirectory path.
MCP_STATS_FILE=/var/lib/13flow-mcp/agent-stats.json
MCP_API_TIMEOUT_MS=10000
MCP_REQUEST_TIMEOUT_MS=15000
MCP_GIT_SHA=<deploy sha>

# Keep this disabled on the public Registry daemon.
MCP_PRO_TOOLS_ENABLED=0

# Optional isolated profile only (do not uncomment on the Registry daemon):
# MCP_PRO_TOOLS_ENABLED=1
# MCP_X402_ENABLED=1
# MCP_X402_SCHEME=exact
# MCP_X402_NETWORK=eip155:8453
# MCP_X402_PRICE=$0.05
# MCP_X402_PAY_TO=0x...
# MCP_X402_ASSET=<optional asset identifier>
# MCP_X402_FACILITATOR_URL=https://...
# Production secrets must use root-owned files, never inline environment values.
# MCP_X402_FACILITATOR_AUTH_FILE=/etc/13flow/mcp-facilitator-auth

# Server-side Pro credential used only after a verified x402 settlement.
# Prefer the _FILE form with a root-readable/flowmcp-readable 0640 secret.
# MCP_13FLOW_INTERNAL_PRO_TOKEN_FILE=/etc/13flow/mcp-internal-pro-token

MCP_X402_TEST_MODE=1 仅供本地测试使用。不得在生产环境中启用。

本地运行

cd mcp-server
npm ci
npm run check
MCP_13FLOW_API_BASE=https://13flow.eu npm start

在另一个终端中：

cd mcp-server
URL=http://127.0.0.1:8849/mcp npm test

测试客户端会验证传输标头、Host/Origin 拒绝、JSON-RPC 批处理拒绝、协议版本处理、请求正文大小限制、工具/资源发现、只读注释、结果大小限制、规范来源链接，以及默认情况下不存在 Pro 工具。运行 npm run test:config 和 npm run test:security，测试失败时默认拒绝的配置、上游响应过大和并发上限回归。npm run test:telemetry 会验证持久化、保留期限、指标协调，以及不包含原始客户端/工具数据。仅当通过有意将 /healthz 设为私有的公共代理进行测试时，才设置 SKIP_HEALTH=1。生产环境的 ModSecurity 边缘层可能会在 MCP 后端收到请求前拒绝不受支持的请求内容类型。在 Debian 12 上，打包的 ModSecurity 2.x JSON 处理器也受上游问题 #2807影响：在第 2 阶段规则可读取 REQBODY_ERROR 之前，截断的 JSON 可能会被拒绝，并返回通用 HTTP 500。设置 EXPECT_WAF_REJECTIONS=1，即可接受这些有限且失败时默认拒绝的边缘层差异（不受支持的内容类型返回 403 或 415；截断的 JSON 返回 400 或 500）。直接后端测试仍采用严格要求，分别要求返回 415 和 400。不要禁用 SecRequestBodyAccess 或 JSON 处理器来统一这些状态码：这会降低请求正文检查能力。

URL=https://13flow.eu/api/mcp \
STATS_URL=https://13flow.eu/api/agent-stats \
SKIP_HEALTH=1 EXPECT_WAF_REJECTIONS=1 npm test

官方 MCP Registry

根目录中的 server.json 将公开的 Streamable HTTP 端点声明为 io.github.bluetouff/13flow。发布前请验证清单：

cd /opt/13flow
mcp-publisher validate

部署对应版本的服务并通过公开冒烟测试后，尽可能延后身份验证，发布一次，然后验证确切的版本和远程 URL：

mcp-publisher login github
mcp-publisher publish
cd mcp-server
npm run registry:verify -- --version 1.0.0

Registry 发布的是元数据，不会部署 MCP 守护进程，因此必须分别验证在线端点和 Registry 条目。

证明默认的 Registry 配置文件不会执行私有工具：

curl -i http://127.0.0.1:8849/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pro.list_funds","arguments":{}}}'

预期结果：JSON-RPC 未知工具错误。pro.list_funds 也必须不存在于 tools/list 中。

隔离且明确启用的 Pro 配置文件仅接受专用密钥标头：

printf "API token: "
read -r -s TOKEN
printf "\n"

curl -fsS http://127.0.0.1:8849/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-13FLOW-Key: $TOKEN" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pro.list_funds","arguments":{}}}'

unset TOKEN

生产环境部署

安装一次依赖：

sudo useradd --system --no-create-home --shell /usr/sbin/nologin flowmcp
cd /opt/13flow/mcp-server
sudo npm ci --omit=dev
sudo chown -R root:flowmcp /opt/13flow/mcp-server
sudo chmod o+x /opt/13flow

从 deploy/13flow-mcp.service 安装 systemd 单元，在 /etc/13flow/13flow-mcp.env 中设置环境变量，然后：

sudo systemctl daemon-reload
sudo systemctl enable --now 13flow-mcp
curl -fsS http://127.0.0.1:8849/healthz | python3 -m json.tool
curl -fsS http://127.0.0.1:8849/stats | python3 -m json.tool

该单元会将 /var/lib/13flow-mcp 创建为模式为 0700 的 systemd StateDirectory，且不会授予守护进程其他持久写入路径。agent-stats.json 通过有界临时文件和重命名操作，以模式 0600 写入；生产环境禁止使用其他遥测路径。

Apache 必须仅允许在 /api/mcp 上使用 POST，并将该路径代理到 Node 服务。保留主站的请求方法允许列表，以确保其他公共端点保持只读。提供的 vhost 将请求大小限制为 1 MiB，并在代理前移除客户端提供的转发标头。提供的 systemd 单元会禁止非回环网络连接；因此，启用外部 x402 协调器需要有意覆盖网络策略并进行新一轮审查。该单元还会在读取环境文件后移除所有 Pro/x402 激活变量和机密变量，因此，不能通过意外修改环境变量将此公共单元转换为私有配置。

方法论约定

MCP 服务仅是一种传输协议，不会重新定义投资信号。

Confluence v1 仍是冻结的公共研究约定：

• 评分是序数启发式排名，并非概率或预期收益；
• 在发布实时历史验证之前，默认权重均为启发式权重；
• 实时状态、数据质量、申报数量和覆盖范围保持公开；
• 仅追加的信号历史记录是信号修订的审计轨迹；
• Pro 输出必须保留足够的元数据，以便重现所选申报文件、基准日期、持仓、变动及数据质量注意事项。

MCP 工具不会直接调用 EDGAR。数据新鲜度和 13F 覆盖范围来自已发布的市场数据库和缓存文件。