# SummitFlow MCP

[![protocol tests](https://github.com/zrzqbr/summitflow-mcp-demo/actions/workflows/test.yml/badge.svg)](https://github.com/zrzqbr/summitflow-mcp-demo/actions/workflows/test.yml)
![Node.js](https://img.shields.io/badge/Node.js-22%2B-3c873a)
![MCP SDK](https://img.shields.io/badge/MCP%20SDK-2.0-6f42c1)
![default access](https://img.shields.io/badge/default-read--only-0969da)

SummitFlow MCP 是“2026 腾讯云粤港澳大湾区架构师峰会”官网的业务研发控制面。它把报名运营、代码质量和正式发布规则封装为有限、可审计的 MCP 工具，让 Cursor、Claude Code、Codex 或企业内部 Agent 能理解并操作真实峰会工作流。

> 一句话定位：让 AI 不只“看懂代码”，还能在最小权限和人工审批下理解峰会业务、执行质量检查并协助完成研发交付。

它不是另一个通用 GitHub MCP，也不向模型暴露任意 Shell 或任意 SQL：

- SummitFlow MCP：峰会业务统计、站点健康、发布规则与受控研发动作。
- GitHub 官方 MCP：仓库、Issue、Pull Request、Actions 与代码安全。
- Playwright MCP：官网和报名后台的浏览器验收。
- Sentry MCP（后续接入）：错误、性能与发布后异常诊断。

```mermaid
flowchart LR
  A[研发人员 / AI Agent] --> B[SummitFlow MCP]
  A --> G[GitHub MCP]
  A --> P[Playwright MCP]
  B --> C[峰会聚合数据 API]
  B --> D[本地 Git 工作区]
  B --> E[固定质量门禁]
  B --> F[原子发布脚本]
  C --> H[(MariaDB)]
  F --> I[正式站 + EdgeOne CDN]
```

## 为什么值得做成 MCP

普通 Coding Agent 看到的通常只有文件；SummitFlow 额外提供稳定的业务语义和操作边界：

| 研发问题 | SummitFlow 提供的上下文 |
|---|---|
| “今天报名增长怎么样？” | 累计、今日、最近一小时、主论坛与数据质量聚合指标 |
| “哪个分论坛最热？” | 六大平行论坛和特色专场的统一统计口径 |
| “这个渠道改动会漏掉哪里？” | 前端埋点、后端映射、后台筛选与测试的完整任务模板 |
| “代码可以发布了吗？” | Git 状态、风险扫描、固定质量门禁、commit SHA 与正式站健康检查 |
| “AI 会不会越权？” | 无任意 SQL/Shell、默认只读、敏感字段脱敏、写操作双重确认 |

## AI 阅读这个仓库后能理解什么

AI 可以从源码和测试中还原：

- 峰会官网、报名后台、数据层、Git 与发布系统之间的边界；
- 11 个工具的输入、输出、权限等级和失败方式；
- 报名、论坛、渠道、行业分布等聚合口径；
- Git 代码审查、质量门禁和原子发布的控制思路；
- 为什么业务 MCP 应与 GitHub MCP、Playwright MCP、Sentry MCP 组合，而不是重复实现通用能力。

AI 无法从公开仓库获得真实报名明细、数据库凭证、短信密钥、SSH 权限、后台令牌或私有官网代码。没有系统所有者提供的令牌，受保护的业务工具会直接拒绝访问。

## 已实现能力

| 工具 | 作用 | 默认权限 |
|---|---|---|
| `summit_get_project_context` | 技术栈、Git 状态、正式域名与发布约束 | 只读 |
| `summit_get_registration_summary` | 累计、今日、主论坛和数据质量汇总 | 只读、仅聚合 |
| `summit_get_forum_distribution` | 六大平行论坛与特色专场热度 | 只读、仅聚合 |
| `summit_get_channel_distribution` | 推广渠道人数与占比 | 只读、仅聚合 |
| `summit_get_forum_industry_distribution` | 各论坛行业分布 | 只读、仅聚合 |
| `summit_get_site_health` | 首页、主 KV、讲师图、后台和 RELEASE 健康检查 | 只读 |
| `summit_review_changes` | 变更文件、疑似密钥、数据库和发布风险扫描 | 只读 |
| `summit_run_quality_gate` | 运行固定的类型检查与测试，不接受任意命令 | 受控执行 |
| `summit_prepare_release` | 生成可发布性报告 | 只读 |
| `summit_create_commit` | 只提交明确文件清单，不自动推送 | 默认关闭、双重确认 |
| `summit_deploy_release` | 通过仓库原子发布脚本部署指定 SHA | 默认关闭、双重确认 |

同时提供两个资源：`summit://project/architecture`、`summit://runbooks/release`；以及“新增推广渠道”“排查报名转化异常”两个可复用 Prompt。

## 快速运行

要求 Node.js 22.13+、pnpm，并在仓库根目录执行：

```bash
pnpm install
pnpm run mcp:test
SUMMITFLOW_ADMIN_TOKEN='<后台只读令牌>' pnpm run mcp:start
```

只进行代码与协议评审时不需要真实令牌：测试使用的是虚构聚合数据。连接真实峰会统计时，令牌必须由系统所有者通过 MCP 宿主的安全配置注入。

客户端配置示例：

```json
{
  "mcpServers": {
    "summitflow": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/summitflow-mcp-demo", "run", "mcp:start"],
      "env": {
        "SUMMITFLOW_ADMIN_TOKEN": "SET_IN_YOUR_MCP_HOST_SECRET_STORE"
      }
    }
  }
}
```

连接后可以直接向 Agent 提问：

```text
查看今天的峰会报名增量、主论坛人数、六大平行论坛热度和推广渠道占比，只返回聚合结果。

审查当前代码改动，告诉我是否包含密钥风险、数据库风险或发布风险，然后执行 quick 质量门禁。
```

不要把后台令牌写进源码、配置样例或 Git。对于 Codex/Claude Desktop 等宿主，可参考 [`client-config.example.json`](./client-config.example.json)，把绝对路径和令牌改成宿主本地的安全配置。

可选 HTTP 模式默认只监听 `127.0.0.1:8787`：

```bash
SUMMITFLOW_ADMIN_TOKEN='<后台只读令牌>' \
SUMMITFLOW_HTTP_BEARER_TOKEN='<独立的MCP访问令牌>' \
pnpm run mcp:http
```

健康检查为 `GET /healthz`，MCP 入口为 `POST /mcp`。若改变监听地址为非本机地址，程序会强制要求 Bearer Token；正式企业接入仍建议置于 HTTPS 网关、SSO/OAuth 和网络访问控制之后。

## 配置项

| 环境变量 | 默认值 | 说明 |
|---|---|---|
| `SUMMITFLOW_SITE_URL` | `https://ruitcarch.cloud` | 正式官网地址 |
| `SUMMITFLOW_ADMIN_TOKEN` | 空 | 访问报名聚合 API 的服务端令牌 |
| `SUMMITFLOW_REPO_ROOT` | 当前目录 | Git 仓库根目录 |
| `SUMMITFLOW_REQUEST_TIMEOUT_MS` | `15000` | 官网 API 请求超时 |
| `SUMMITFLOW_ENABLE_QUALITY_GATE` | `true` | 是否允许运行固定质量门禁 |
| `SUMMITFLOW_ENABLE_GIT_WRITES` | `false` | 是否开放受控 Git 提交 |
| `SUMMITFLOW_ENABLE_PRODUCTION_DEPLOY` | `false` | 是否开放正式部署 |
| `SUMMITFLOW_AUDIT_LOG` | `.summitflow/audit.jsonl` | 脱敏审计日志位置 |
| `SUMMITFLOW_HTTP_HOST` | `127.0.0.1` | HTTP 模式监听地址 |
| `SUMMITFLOW_HTTP_PORT` | `8787` | HTTP 模式监听端口 |
| `SUMMITFLOW_HTTP_BEARER_TOKEN` | 空 | HTTP 模式独立访问令牌 |

## 安全边界

1. 报名工具只返回聚合结果，API 适配层会主动丢弃报名人员明细。
2. 不提供任意 SQL、任意 Shell、删除数据、群发短信或查看验证码的工具。
3. Git 提交必须由服务端开关授权，同时要求调用方传入 `CREATE_COMMIT`；仅允许显式文件列表。
4. 正式部署必须由另一开关授权，要求完整 40 位 SHA 和 `DEPLOY_PRODUCTION`，且只能部署干净的 `main` 当前提交。
5. 所有工具调用写入本地 JSONL 审计日志；手机号、邮箱、微信、令牌、密码和密钥字段会自动脱敏。
6. 提交前扫描密钥文件路径、疑似凭证和空白错误；正式部署只调用仓库已有的原子发布与回滚流程。

### 权限模型

```text
默认状态                 聚合查询 + 仓库只读审查
开启质量门禁             仅执行预定义检查，不接受任意命令
开启 Git 写入 + 确认词   仅提交显式文件清单，不自动推送
开启生产发布 + 完整 SHA  仅允许干净 main 的当前提交进入既有原子发布流程
```

## 项目结构

```text
server.ts                  11 个工具、2 个资源和 2 个 Prompt
summit-api.ts              峰会后台聚合 API 适配与隐私裁剪
repository.ts              Git 审查、质量门禁、受控提交和发布
audit.ts                   JSONL 审计与敏感字段脱敏
stdio.ts / http.ts         stdio 与 Streamable HTTP 入口
tests/server.test.ts       MCP 协议、安全边界与隐私测试
client-config.example.json 客户端接入样例
DEMO.md                    5—8 分钟技术演示脚本
SECURITY.md                公开版本的安全策略
```

## 与知名开源 MCP 的组合方式

本项目采用“业务自研、通用能力复用”的方式，不复制社区成熟轮子：

- [GitHub MCP Server](https://github.com/github/github-mcp-server)：负责 PR、Issue、Actions、代码搜索与代码安全。
- [Playwright MCP](https://github.com/microsoft/playwright-mcp)：负责报名链路、移动端、后台页面的真实浏览器验收。
- [Sentry MCP](https://github.com/getsentry/sentry-mcp)：后续用于发布后错误与性能诊断。
- MCP 官方 TypeScript SDK 2.0：SummitFlow 的协议实现基础。

推荐的企业权限分层是：开发环境启用质量门禁；评审环境只读；发布账号单独配置短时 Git/生产权限。不要在一个长期令牌上同时开放数据、提交和部署。

## 五分钟演示

完整演示脚本见 [`DEMO.md`](./DEMO.md)。推荐依次展示：

1. 查询今日报名、论坛热度与渠道分布。
2. 修改一个渠道映射后做代码审查，展示风险扫描。
3. 运行固定质量门禁。
4. 展示未授权提交/部署会被拒绝。
5. 由 GitHub MCP 创建 PR，再由 Playwright MCP 完成页面验收。

## 公开演示版说明

这个仓库是从私有峰会官网中抽离出的安全公开版本，只包含 MCP 实现、协议测试和技术文档。它不包含官网前端、报名人员、数据库、生产环境变量、短信服务密钥、SSH 配置或私有 Git 历史。

未提供 `SUMMITFLOW_ADMIN_TOKEN` 时，任何受保护的业务统计工具都会拒绝访问；Git 写入与正式部署也保持默认关闭。公开仓库主要用于代码审查、架构讨论和本地协议式演示，连接真实系统必须由系统所有者另行授予最小权限凭证。

## 当前成熟度

当前版本定位为“可运行的工程原型”，不是一键接管生产系统的超级管理员工具。已经具备协议实现、双传输、测试、聚合隐私裁剪、审计与写操作门禁；进入企业生产前仍建议增加 SSO/OAuth、角色权限、集中审计、指标告警与短时凭证。