Chat MCP Farm

聊天MCP农场

用于构建OAuth保护的模型上下文协议服务器的可重用工作区。它打包了一个参考服务、共享的TypeScript身份验证助手、Keycloak的自动化脚本和模板化文档，因此可以快速构建新的MCP服务。

里面是什么

• services/mcp-test-server/ –确定性MCP诊断服务连接到身份验证工具包和组合工具。
• packages/mcp-auth-kit/ –表示加载基于环境的配置、强制OAuth受众和公开清单/PRM处理程序的实用程序（请参阅 AUTH_ENV_VARS).
• scripts/kc/ –Keycloak的客户端凭据自动化（不需要本地容器）。
• templates/service/ –新MCP服务的脚手架（Dockerfile、env模板、compose片段）。
• scripts/compose.sh –发现每个 services/*/compose.yml 并调用 docker compose 与组合堆栈。
• docs/ –引导和OAuth集成指南（通过模板 npm run docs:render).
• PROJECT_SPLIT_PLAN.md –强化工作空间的路线图和开放任务。

入门指南

1. 安装依赖项

   npm install

1. 配置环境

- 复制 .env.example 到 .env 用于工作区范围的覆盖（可选）。 - 复制 .keycloak-env.example 到 .keycloak-env 并提供 KC_CLIENT_ID / KC_CLIENT_SECRET 加上发行人URL。 - 对于每项服务，请复制 services//.env.example 到 services//.env 并填写： - PORT （集装箱+Traefik港） - MCP_PUBLIC_HOST （Traefik主机规则） - MCP_SERVICE_NAME （编写服务密钥） - MCP_BUILD_CONTEXT （服务源的路径，例如。 ./services/) - MCP_NETWORK_EXTERNAL （Traefik使用的现有Docker网络） - OAuth URL(MCP_PUBLIC_BASE_URL, PRM_RESOURCE_URL, OIDC_ISSUER, OIDC_AUDIENCE)

1. 运行服务

   scripts/compose.sh up --build

scripts/compose.sh 自动包括每个 services/*/compose.yml，因此添加新的服务文件夹会将其注册到堆栈中，而无需编辑根组合文件。

1. Bootstrap钥匙斗篷

- scripts/kc/create_mcp_scope.sh --resource 确保作用域、映射器和受信任的主机存在。 - scripts/kc/status.sh --resource 验证领域默认值和客户端分配。 - scripts/kc/trusted_hosts.sh --add 维护受信任的主机策略。

1. 冒烟测试

   npm run build --workspace 
   npm run smoke --workspace 
   npm run smoke:sse --workspace    # when ENABLE_SSE=true

护栏

在推动之前或作为CI的一部分运行护栏束，以确保组合配置文件保持可选状态，并正确获取机密：

npm run guard

这将执行 scripts/check-inline-secrets.mjs （阻止内联机密/弃用标志），然后 scripts/check-compose-profile.sh （跑步 COMPOSE_PROFILES=mcp-test-server scripts/compose.sh --profile mcp-test-server config). npm test 在工作区测试之前自动调用相同的护栏。

碰撞后回归辅助工具

在依赖升级后运行工作区范围的回归帮助程序，以确保每个包仍然构建并且其测试通过：

npm run postbump:test

该助手需要Node.js 20.19+（工作区标准为Node 22 LTS），因为 jose@6 Express 5依赖于原生 require(esm) 支持。传递额外的旗帜将它们转发给 npm run test --workspaces --if-present （例如， npm run postbump:test -- --workspace packages/mcp-auth-kit).

添加新的MCP服务

1. scripts/bootstrap.sh –将模板骨架复制到 services/.
2. 填写 services//.env 以该示例为指导。
3. 更新Taurus文档(docs/bootstrap-checklist.md)或根据需要提供README服务。
4. 重新运行 scripts/compose.sh up --build 包括新服务。

文档

• docs/config.sample.json 枚举模板变量。
• 使用生成特定于环境的文档 npm run docs:render 在放置覆盖后 docs/local/config.local.json （被git忽略）。
• 承诺文档保留 {{VARIABLE}} 占位符，因此公共仓库与环境无关。

存储库卫生

• 秘密和特定环境的价值观属于当地 .env 文件（被git忽略）。
• 跑 scripts/compose.sh 和 npm run build --workspaces 在打开PR之前。
• 使用 codex-review 或在进行更改后使用您首选的审核工具；它与上次提交进行比较，因此确保存在基线。

路线图

1. 扩展模板服务中的测试覆盖率。
2. 发布 mcp-auth-kit 提交至内部或公共注册机构。
3. 添加CI工作流（lint、test、docs-render）。
4. 在切割初始版本之前，加强文档和自动化。