monorepo —— MCPP 聚合 server 示例

演示 MCPP 3.7 的 monorepo 拓扑：单一 HTTP 出口，路径路由到 sub server。

形态

                    ┌─────────────────────────────────────────────┐
  客户端             │ monorepo（单一 HTTP server，端口 8787）      │
                    │                                             │
  /openspec/mcp   ──► OpenSpec skills sub server                  │
  /mattpocock/mcp ──► Matt Pocock skills sub server               │
  其他路径         ──► 404                                         │
                    └─────────────────────────────────────────────┘

每个路径是独立的 MCP endpoint；skills 和 resources 相互隔离。
本地 Bun 与 Cloudflare Worker 均使用 @peri-code/mcpp@0.2 的严格 2026-07-28 无状态 Streamable HTTP，不依赖内存 session。
src/registry.ts 是本地入口、Cloudflare Worker 和测试共用的唯一路由注册表。
stdio 没有 URL/路径概念，不适用该聚合形态。

初始化

bun run init

该命令安装依赖、按 skills.lock.json 复现第三方 skills，并生成 Worker 可打包的静态 registry。

常用命令

bun dev                     # 构建 skills 后启动 http://127.0.0.1:8787/
bun run demo                # 端到端 smoke 测试
bun run skills:sync         # 按 lock 同步第三方 skills
bun run skills:update       # 更新第三方 commit 并重新生成 registry
bun run deploy:dry-run      # 验证 Cloudflare Worker bundle
bun run deploy              # 部署 Cloudflare Worker

目录结构

├── src/
│   ├── index.ts                 # 本地网关和纯 fetch handler
│   ├── registry.ts              # 唯一 sub server 注册表
│   └── static-skills.ts         # 静态 skills resource 挂载器
├── servers/
│   ├── openspec/
│   │   ├── server.ts
│   │   ├── skills/              # 生成、Git ignored
│   │   └── skills.generated.ts  # 生成、Git ignored
│   └── mattpocock/
│       ├── server.ts
│       ├── skills/              # 生成、Git ignored
│       └── skills.generated.ts  # 生成、Git ignored
├── install-skills.js            # manifest + lock 同步器
├── generate-skills-registry.js  # 静态 registry 生成器
├── skills.json                  # source 声明
├── skills.lock.json             # 锁定 commit，提交进 Git
├── test/smoke.ts
├── worker.ts
└── wrangler.jsonc

可复现 Skills 构建

skills.json + skills.lock.json
            │
            ▼
     install-skills.js
            │ copy 锁定 commit
            ▼
 servers/<id>/skills/
            │
            ▼
generate-skills-registry.js
            │
            ▼
servers/<id>/skills.generated.ts
            │ static import
            ▼
      Bun / Worker bundle

生成目录和生成 registry 都不提交；新 clone 通过 bun run init 完整恢复。sub server 不在运行时读取 node:fs，因此 Worker bundle 会包含 SKILL.md 正文与全部附件（skill://<name>/<path>）。

Docker 部署

本地构建并启动：

docker compose up --build -d
docker compose ps

默认监听 http://127.0.0.1:8787。可覆盖宿主机端口和镜像：

MCP_SKILLS_PORT=8080 \
MCP_SKILLS_IMAGE=ghcr.io/konghayao/mcp-skills-registry:latest \
docker compose up -d

Docker builder 按 skills.lock.json 下载并生成静态 registry；runtime 镜像直接运行 bun src/index.ts，启动时不访问 GitHub。镜像内服务监听 0.0.0.0:8787，并带有 /nope 404 健康检查。

直接拉取 GHCR 镜像：

docker pull ghcr.io/konghayao/mcp-skills-registry:latest
docker run -d --name mcp-skills-registry \
  --restart unless-stopped \
  -p 8787:8787 \
  ghcr.io/konghayao/mcp-skills-registry:latest

GHCR 自动发布

.github/workflows/publish-ghcr.yaml 在以下场景构建并推送 linux/amd64、linux/arm64 镜像：

push 到 main：发布 latest、main 和 sha-*；
push v* tag：发布 tag、semver 和 sha-*；
GitHub Actions 手动触发。

Workflow 使用仓库自带的 GITHUB_TOKEN，需要仓库 Actions 具备 packages: write 权限，不需要额外配置 GHCR token。首次发布后可在 GitHub Packages 中调整镜像可见性。

Cloudflare 部署

bun run deploy:dry-run
bun run deploy

Worker 使用无状态 Streamable HTTP：响应不返回 Mcp-Session-Id，每个请求独立创建 server 与 transport，适合 Cloudflare 多 isolate 路由，无需 Durable Objects。

mcp-skills-registry