secureflows-mcp

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——根据集成规则检查生成的应用源代码，并报告结构化问题，而不是 将其留作需要 Agent 自行遵守的说明文字。无需 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 集成错误大多恰恰发生在这里。

提示词（src/prompts/security-review.ts）——一个 MCP 提示词：security-review。它会要求 Agent 检查当前项目如何管理用户账号，列出安全漏洞，按 secureFlows 标准逐项评级，并编写迁移计划。只读，无需 secureFlows 令牌。相同文本也以 Claude Code 插件技能 skills/security-review 的形式发布（通过 /secureflows:security-review 运行），并作为可复制粘贴的提示词发布在 https://www.secure-flows.com/docs/getting-started/security-review/。TypeScript 常量是源文件；如果任一副本与其不一致，test/security-review-prompt.test.ts 就会报错。

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

运行时模型

每次工具调用都会收到：

• connection.host：secureFlows 基础 URL
• connection.workspaceName：可选的默认工作区
• connection.appId：可选的默认应用 ID
• auth.*：所选端点所需的令牌

workspaceName 和 appId 会被视为稳定的应用配置。调用方未提供这些值时，服务会将其注入已知的 secureFlows 请求结构。

面向 Agent（唯一受支持的客户端接入方式）

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

环境	MCP URL
生产环境	https://www.secure-flows.com/mcp
预发布环境	https://secure-flows-staging.onrender.com/mcp
健康检查	…/mcp/health → {"ok":true}

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

不要让 Agent 运行 npx 或使用 localhost——那会造成混乱，让从未启动本地进程的用户无法使用。该服务已接入 Web Docker 镜像（Node 运行于 127.0.0.1:8787，nginx 使用 location = /mcp；参见 docs/ROUTING.md）。Node 进程会安装 uncaughtException／unhandledRejection 防护，确保单个错误请求不会导致进程退出；若进程仍然退出，docker/entrypoint.sh 也会重启 MCP。

Claude Code 插件

此仓库也是一个 Claude Code 插件。它会连接上文的托管 MCP 服务（.mcp.json），并添加两项技能：secureflows-integration 和 security-review。在 Claude Code 中：

/plugin marketplace add michal-lefler/secureflows-mcp
/plugin install secureflows@secureflows-marketplace

然后在任意项目中运行 /secureflows:security-review，即可对其用户管理进行只读检查。

本地开发（本软件包的维护者）

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

服务默认在 http://0.0.0.0:8787 启动（POST /mcp、GET /health）。此方式用于修改 MCP 服务本身，不是产品 Agent 应配置的接入方式。

环境变量

• 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 Streamable 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 直接集成，而不是通过此服务。这里的生成式工具面向已有令牌的 Agent/自动化（用于测试、脚本化验证）。静态工具（secureflows_build_login_url、secureflows_build_logout_url、secureflows_lint_integration）无需令牌，适合编码 Agent 在搭建集成过程中调用——请参阅上文的功能说明。

测试此 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. 可选：使用 connection.host + auth.*，通过 POST /mcp 连接 MCP 客户端，以使用生成式工具。

插件分发也由 npm test 覆盖（离线运行；仅限 monorepo 的检查在公开镜像中会自行跳过）：

• test/plugin-distribution.test.ts — 清单、托管的 .mcp.json 目标位置、文档页面和 README 中的安装命令，以及 sync-public-mirrors CI 任务（仅限标签触发，等待 npm 发布完成，secrets: inherit，令牌仅存在于步骤环境中）。
• test/mirror-sync.test.ts — 针对本地裸 git 仓库运行真实的 scripts/sync-public-mirrors.mjs --commit --push，并检查外部用户会收到的内容：插件、市场、技能、托管的 .mcp.json、注册表 server.json、幂等的再次运行，以及删除操作的同步传播。
• npm run test:live（选择性运行，SECUREFLOWS_LIVE_MCP=1）— 连接 .mcp.json 中的 URL 并列出工具；添加 SECUREFLOWS_LIVE_MCP_PROMPTS=1 还会要求存在 security-review 提示词。请在部署后运行（或使用 SECUREFLOWS_LIVE_MCP_URL 测试暂存环境）。此测试不属于 npm test，因此 CI 可保持离线。

上述检查都无法覆盖：使用 MIRRORS_PUSH_TOKEN 进行的真实推送（工作流在 GitHub 上首次运行时），以及从全新安装的 Claude Code 中执行真正的 /plugin marketplace add。

部署

已打包在 Web Docker 镜像中，并通过代理部署在 www.secure-flows.com / 暂存环境的 /mcp 路径上（见上文的面向 Agent）。无需单独的子域名。

npm 包 secureflows 用于让 CI 发布带版本号的制品（也可用于从 mcp-server/Dockerfile 构建独立容器）；它不是面向 Agent 的设置方式。通过 .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