secureFlows MCP 服务器

可云部署的 MCP 服务器，封装了标记为 ai-safe 和 ai-optional 的 secureFlows OpenAPI 接口。

此仓库是公开镜像，定期从实际开发的私有 secureFlows 单仓库发布。欢迎提交 Issue 和 PR；较大的更改可能需要一个发布周期才能先合并到上游。

什么是 MCP 服务器？

MCP 服务器是一种小型 HTTP 服务，以标准方式暴露一组 AI 客户端可以调用的“工具”。

在此仓库中：

• secureFlows MCP 服务器暴露从你的 OpenAPI YAML 规范自动生成的工具。

• 当客户端调用工具时，MCP 服务器将调用转发到你的真实 secureFlows 后端（connection.host），并以规范化的工具结果返回响应。

这使得 AI 客户端可以：

• 通过 listTools 发现可用的 secureFlows 操作

• 通过 callTool 调用它们

• 而无需硬编码 API 表面或手动进行认证/头部接线

它的功能

两种工具，一起注册在 src/server.ts 中：

生成的工具（src/tools/build-tools.ts）——每个 OpenAPI 操作一个：

• 加载：

  • docs/openapi/session/secure-flows-session-api.yaml

  • docs/openapi/user/secure-flows-user-api.yaml

  • docs/openapi/docs/secure-flows-docs-api.yaml

• 仅将标记为 ai-safe 或 ai-optional 的操作暴露为 MCP 工具

• 将请求转发到调用方提供的 secureFlows 主机——一个轻量、通用的 HTTP 包装器，没有 secureFlows 特定的判断。这些操作都需要有效的 auth.* 令牌，因此只有在会话已经存在时才有用（参见下面的运行时模型）。

• 从 MCP 工具输入映射 secureFlows 认证头：

  • auth.firebaseToken

  • auth.sessionToken

  • auth.userToken

静态工具（src/tools/static-tools.ts）——手写的，不是从规范生成的：

• secureflows_build_login_url / secureflows_build_logout_url — 通过构造正确构建托管登录和重定向注销 URL（始终使用 /app/sessions/login，绝不使用旧的 /app/login；拒绝指向 /callback 或泄露 session_token 的注销后 redirect_uri）。不需要 secureFlows 令牌。

• secureflows_lint_integration — 根据集成规则检查生成的应用程序源代码，并报告结构化发现，而不是将它们留作代理必须自我监督的散文。不需要 secureFlows 令牌。两种发现：

  • scope: "file" — 禁止的构造存在，在精确的 file:line 处：环境变量配置常量、localStorage 中的令牌、旧的 /app/login、fetch/XHR 注销、客户端 JWT 解码、注销时撤销、空的 catch {}、在非认证错误时恢复 setSession(null)、基于 session === null 的 Continue CTA，……

  • scope: "project" — 在传入的每个文件中缺少必需的处理：检测到 401/410 但从未清除令牌，从未处理 403，或处理 403 而没有 BILLING_GRACE_LOCK 例外。

存在性检查之所以存在，是因为模式规则在结构上无法捕获主导真实生成应用的缺陷类别。实测：在一个真实试用版应用上，评估框架的 LLM 评判员给出了 4/10 的评分——引用了“登出后陈旧令牌从未清除”、“403 变体未处理”、“无错误处理”——仅模式规则产生了零个发现，因为每一个这些错误都是缺失，而正则表达式只能看到存在的内容。有了存在性检查，它产生了 3 个发现，包括 error 严重级别的令牌清除问题。两种检查都针对规范的 templates/web-app-secureflows 起始模板进行了验证，该模板必须保持零发现。

仍然是启发式文本分析，不是解析器或类型检查器：它会遗漏没有规则的内容，项目检查可能被错误位置的正确关键字满足，并且无法覆盖需要运行中应用的检查（认证守卫挂载竞争、全新重新加载检查）。这是一个快速的初步检查——不能替代 SKILL.md 中的 Agent 实现清单。

这些静态工具的存在是因为生成的工具无法帮助处理会话存在之前发生的集成部分——搭建重定向/回调/令牌生命周期代码——而这正是大多数 secureFlows 集成错误发生的地方。

使用无状态的 HTTP MCP 传输，因此服务器不会持久化租户配置或机密。

运行时模型

每次工具调用接收：

• connection.host：secureFlows 基础 URL

• connection.workspaceName：可选的默认工作区

• connection.appId：可选的默认应用程序 ID

• auth.*：所选端点需要的任何令牌

workspaceName 和 appId 被视为稳定的应用配置。当调用方省略时，服务器会将它们注入到已知的 secureFlows 请求形状中。

对于代理（唯一支持的客户端路径）

将 MCP 客户端指向托管 URL——与产品相同的主机，路径 /mcp（不是子域）：

{
  "mcpServers": {
    "secureflows": {
      "url": "https://www.secure-flows.com/mcp"
    }
  }
}

不要告诉代理运行 npx 或使用 localhost——那会割裂故事，并破坏任何从不启动本地进程的人。已接入 Web Docker 镜像（Node 在 127.0.0.1:8787，nginx location = /mcp；参见 docs/ROUTING.md）。Node 进程安装了 uncaughtException / unhandledRejection 保护，因此单个错误请求不会导致进程退出；docker/entrypoint.sh 也会在进程仍然退出时重启 MCP。

本地开发（此包的维护者）

cd mcp-server
npm install
npm run build
npm test
npm run dev

服务器默认在 http://0.0.0.0:8787 上启动（POST /mcp，GET /health）。这是用于更改 MCP 服务器本身——而不是产品代理应配置的路径。

环境变量

• PORT：HTTP 端口，默认 8787（在 Web 容器中，入口点仅为 MCP 子进程设置 PORT=8787，以便 nginx 保留 Render 的公共 $PORT）

• HOST：绑定主机，默认 0.0.0.0（Web 容器使用 127.0.0.1）

• ALLOWED_HOSTS：可选的逗号分隔的主机允许列表，用于 MCP 主机头验证

• MCP_ALLOWED_HOSTS：启动镜像内进程时对 ALLOWED_HOSTS 的入口点覆盖

端点

• POST /mcp：MCP 可流式 HTTP 端点

• GET /health：健康检查（通过 nginx 公开为 GET /mcp/health）

在应用程序中嵌入 secureFlows

产品应用直接与 secureFlows HTTP API 和托管登录集成。从以下开始：

• docs/integration/quickstart.md — 配置（工作区 + 应用程序）和运行时托管登录

• docs/integration/CONCEPT.md — 基线顺序：在高级功能之前登录 → 创建工作区

• docs/openapi/integration-auth.yaml — /app/sessions/login（会话应用）与 /app/login（旧版/控制台）

产品应用仍然直接与上述 HTTP API 集成，而不是通过此服务器。这里的生成工具适用于已经拥有令牌的代理/自动化（测试、脚本化验证）。静态工具（secureflows_build_login_url、secureflows_build_logout_url、secureflows_lint_integration）不需要令牌，旨在供编码代理在仍在搭建集成时调用——参见上面的它的功能。

测试此 MCP 服务器

1. 在 mcp-server/ 中运行 npm test — 单元测试加上 HTTP 冒烟测试（test/http-smoke.test.ts）：在临时端口上启动 Express 应用，检查 GET /health、GET /mcp → 405，以及真实的 Streamable-HTTP 客户端 listTools + callTool(secureflows_build_login_url)。

2. 部署后：Playwright tests/smoke/mcp-health.spec.ts 在目标主机上访问公共 GET /mcp/health 和 GET /mcp（生产冒烟任务）。

3. 本地维护者循环：npm run dev，然后 curl -sS http://127.0.0.1:8787/health。

4. 可选：针对 POST /mcp 使用 connection.host + auth.* 的 MCP 客户端，用于生成的工具。

部署

随 Web Docker 镜像一起发布，并在 www.secure-flows.com / 暂存环境上通过 /mcp 代理（参见上面的对于代理）。没有单独的子域。

npm 包 secureflows-mcp-server 是 CI 发布版本化工件的方式（以及如何从 mcp-server/Dockerfile 构建独立容器）；它不是面向代理的设置路径。通过 .github/workflows/publish-secureflows-mcp-server.yml 在 v*.*.* 标签上发布。

docker build -f mcp-server/Dockerfile -t secureflows-mcp-server .
docker run --rm -p 8787:8787 secureflows-mcp-server

备注

• 托管登录/重定向端点仅在 OpenAPI 规范中标记为 ai-safe 或 ai-optional 时才暴露。

• 文档搜索（get_docs_search）是 ai-safe，不需要 auth.* — 只需要 connection.host 和查询 q。

• 仅限人工的管理控制台 API 被有意排除。

• 每个工具返回的响应负载包括：

  • status

  • ok

  • url

  • headers

  • data