comind-mcp

仓库：https://github.com/comind-pro/comind-mcp

MCP 网关 — 连接各种 MCP 服务器和 REST API，允许你策划和组合工具，将它们组织成组（每个组 = 一个独立的虚拟 MCP 服务器，具有单一端点）并分发给代理。代理只能看到分配给它的那组狭窄工具，并且可以通过 MCP 安排自己的定时任务。

自托管：单个 Node 服务 + Postgres。多用户，每个账户隔离。

Source (mcp │ openapi │ http) ──import──▶ Tool (native │ composite, curated)
                                              │
Group = virtual MCP ◀──toolset[]──────────────┘   + built-in self-cron tools
   └─▶  /g/:groupId/mcp   (Streamable HTTP, single endpoint)
            └─▶ Agent (Bearer key) — only granted V-MCPs, schedules itself
Vault (${secret.X}) · Scheduler · CallLog / Metrics

快速开始

前提条件：Node 20+、pnpm 9（corepack enable）、Docker（本地 Postgres）。

make setup        # install deps, start Postgres, apply migrations
make dev          # Postgres + server :8787 + web :5173

• Web UI — http://localhost:5173（注册账户，然后登录）

• 网关 + 控制 API — http://localhost:8787（GET /healthz）

• Postgres — 在 Docker 中运行（docker compose）；仓库 .env 映射主机端口 5434

查看 make help 获取所有目标。底层的 pnpm 脚本（pnpm dev、pnpm dev:server、pnpm dev:web）仍然有效，但不会管理 Postgres 容器。

数据库模式

存储由 DATABASE_URL 方案选择 — 相同的模式，相同的迁移：

PGlite 就是 Postgres（WASM），因此所有内容（jsonb、percentile_cont、迁移）无需外部数据库进程即可运行。持久化： file: 目录是一个真正的 Postgres 数据目录；将其挂载为卷（例如 /data）以在版本之间保留数据。迁移是增量的且幂等的，因此升级永远不会清除现有数据。嵌入式模式是单节点（无多实例 — 一个写入者）。

# zero-infra: no Docker/Postgres needed
DATABASE_URL=file:/data/comind SERVER_ENV=dev pnpm --filter comind-server start

Related MCP server: Figma MCP Server

端到端场景

1. 源 → 添加一个源（MCP 代理、OpenAPI 或 HTTP）→ 测试 → 导入工具。

2. 工具 → 重命名 / 隐藏不必要的 / 组装一个复合工具（一个由多次调用组成的意图工具）。

3. 组 → 创建一个组 → 标记工具集（复选框）→ （可选）添加一个计划。

4. 代理 → 在组中创建一个代理 → 获取一个 API 密钥（一次性） + MCP 端点。

5. 将任何 MCP 客户端连接到 http://localhost:8787/g/<groupId>/mcp，并带有 Authorization: Bearer <key>。客户端只能看到该组的工具集（+ 自定时任务工具）。

6. 日志 → 调用、指标、错误。

概念

API（控制平面，REST 在 :8787）

GET  /healthz
# sources
POST/GET /sources          GET/PATCH/DELETE /sources/:id
POST /sources/:id/test     POST /sources/:id/import
# tools
GET /tools  (?sourceId&kind&visible)   GET/PATCH/DELETE /tools/:id
# composites
POST/GET /composite-tools  GET/DELETE /composite-tools/:id   POST /composite-tools/:id/run
# python tools (gated — see "Python tools")
POST /python-tools         GET/PATCH/DELETE /python-tools/:id
POST /python-tools/test    POST /python-tools/:id/run
GET  /features
# groups
POST/GET /groups           GET/PATCH/DELETE /groups/:id
GET/PUT /groups/:id/tools
# agents
POST/GET /agents           GET/DELETE /agents/:id            POST /agents/:id/rotate-key
# schedules
POST/GET /groups/:id/schedules    DELETE /schedules/:id
POST /schedules/:id/run           GET /schedules/:id/runs
# secrets (metadata only; value/ciphertext is NEVER returned)
POST/GET /secrets          DELETE /secrets/:id
# observability
GET /logs (?groupId&agentId&toolName&status&limit)   GET /metrics
GET /agents/:id/inspect    POST /agents/:id/invoke

网关（用于代理，MCP）

POST /a/mcp            — agent-wide endpoint: union of tools across the agent's groups
POST /g/:groupId/mcp   — Streamable HTTP endpoint (Authorization: Bearer <agent-key>)

SSE 传输 — 计划中。

从 Claude / ChatGPT（网页版）连接： 带截图的分步指南 — docs/connect.md。

Python 工具

一个代码体为 Python 的工具。在复合引擎无法满足需求时很有用：循环、算术、解析、将多次调用折叠成一个表格。

rows = []
for tok in args["tokens"]:
    book = await call("market.get_order_book", {"token_id": tok})   # any tool you own
    if book["is_error"]:
        continue
    rows.append(book["structured"])

output = {"count": len(rows), "rows": rows}

• 作用域内：args（工具的输入）、await call(name, args) → {"text", "structured", "is_error"}、以及当代码是复合工具中的一步时的 steps（{"id": "x", "python": "..."}）。

• 结果是你赋值给 output 的任何内容。如果脚本定义了 main，则调用 main(args)（同步或异步）。两者都没有 → 显式错误，永远不会静默返回空结果。

• 顶层的 return 是 Python 的 SyntaxError，会终止整个脚本 — 赋值给 output，或将逻辑包装在 def main(args) 中。

• print() 会被捕获并显示在工具编辑器中。

沙盒。 Pyodide（CPython → WASM）在工作线程中：无网络，无文件系统，无 process。Node 的网络模块在 Pyodide 加载之前就在工作线程中被阻止，因此 Python 套接字也会失败 — 脚本的唯一出路是 call(...)，它通过正常的工具运行时（认证、SSRF 防护、调用日志）。失控的脚本通过终止工作线程来杀死。

成本。 每个嵌套级别一个工作线程，延迟启动并保持热状态：启动后首次运行 ≈ 1s，后续运行 ≈ 10ms。同一级别的运行是串行的，因此长时间运行的脚本会延迟其他 Python 工具（原生/虚拟工具不受影响）。Python 工具调用 Python 工具再调用 Python 工具是限制 — 更深的嵌套会被拒绝。

默认关闭。 设置 PYTHON_TOOLS=1（为实例上的每个账户开放该功能 — 本地开发 / 单用户自托管），或按用户授予：

INSERT INTO user_features (id, user_id, feature, enabled)
VALUES (gen_random_uuid()::text, '<user-id>', 'python_tools', true);

撤销该行也会停止现有工具 — ACL 在每次调用时重新检查，而不仅仅在创作时。调优：PYTHON_TOOL_TIMEOUT_MS（30000）、PYTHON_TOOL_MAX_CALLS（100）、PYTHON_TOOL_MAX_CODE_BYTES（65536）。

结构

开发详情 — DEVELOPMENT.md。

安全性

• 密钥在静态时加密（AES-256-GCM）；代理/配置只能看到 ${secret.NAME} 占位符，值在运行时替换。

• 代理只能获得其组的工具集；每次调用都通过工具集进行门控。

• API 密钥以 sha256 哈希存储，令牌仅显示一次。

• 一个上游的故障不会导致端点崩溃（运行时中的故障隔离）。

模块与功能

迭代构建，模块化。以下所有内容均已实现并正常工作。

核心网关

• ✅ 连接器 — 代理现有 MCP 服务器，从 OpenAPI 3.x 导入 REST API（自有解析器 → 工具），或连接具有显式端点的 HTTP 服务。

• ✅ 工具注册表与策划 — 导入工具、重命名、编辑描述、切换可见性、每个所有者唯一名称。

• ✅ 复合引擎 — 按顺序运行多个调用的意图工具；条件 when；模板（$.input.*、$.steps.ID.text）；输出模板；每步跟踪用于调优。

• ✅ 共享运行时（invokeTool）— 一个调度器用于网关、复合工具和调度器；原生→连接器、复合工具→递归（深度限制）；故障隔离（坏的上游永远不会使调用者崩溃）。

• ✅ 组 = 虚拟 MCP — 将策划的工具捆绑到单个 MCP 端点 /g/:groupId/mcp（Streamable HTTP）。

• ✅ 代理 — 消费者身份，带有一个 API 密钥（sha256 哈希，仅显示一次）+ 密钥轮换。

• ✅ 代理 ↔ V-MCP 授权（M2M） — 按组授予/撤销访问权限；一个代理可以访问多个组端点；密钥仅对已授权的组有效。

调度

• ✅ 调度器 — cron注册表 (node-cron), JobRun日志, 立即运行, 启动时加载。

• ✅ 通过MCP的自我调度 — 内置 schedule_task / list_schedules / cancel_schedule 工具在一个组内；连接的智能体自行调度。

机密与上游认证

• ✅ 保险库 — 凭证静态加密 (AES-256-GCM)；通过 ${secret.NAME} 在运行时注入；智能体/配置永远看不到值。

• ✅ 源级机密 — 同一名称可在每个源中存在；作用域覆盖全局。

• ✅ 静态认证 — Bearer/API密钥/自定义标头, Basic (用户名/密码)。

• ✅ 动态令牌流 — oauth2_client_credentials, token_request (登录→JSON路径), oauth2_refresh (缓存+自动刷新)。

• ✅ 用户OAuth — oauth2_authorization_code (Connect流) 和 MCP原生OAuth (mcp_oauth: SDK发现 + DCR + PKCE + 刷新，附带可选的预注册 clientId)。

账户与隔离

• ✅ 认证 — 邮箱/密码 (scrypt) + HS256会话JWT；注册/登录/我。

• ✅ 多用户隔离 — 每个资源归用户所有；所有路由按所有者限定范围；工具仅在所有者命名空间内解析。无跨账户访问。

可观测性

• ✅ 调用日志 — 谁/哪个工具/状态/持续时间/每次调用的令牌估算。

• ✅ 指标 — 总量 + 按工具 + 按智能体。

• ✅ 检查器与测试调用 — 查看智能体在每个授权的V-MCP中看到的内容；运行任何工具以查看原始响应。

Web UI (Vite + React)

• ✅ 认证 — 登录/注册, 令牌门控, 注销。

• ✅ 表单⟷JSON构建器 用于源和组合体 (编辑表单或原始JSON，双向)。

• ✅ 源向导中的内联机密 (作用域限定于该源)。

• ✅ 分组、可折叠、可搜索 的工具选择器与注册表 (可扩展至大型导入API)。

• ✅ 每个V-MCP的连接片段 (claude mcp add …, curl) 带复制按钮。

• ✅ 标签页: 源 · 工具 · V-MCP · 智能体 · 机密 · 日志。

基础设施

• ✅ Postgres 通过 Drizzle (迁移在启动时自动应用)。

• ✅ Docker Compose 用于本地Postgres + Makefile (make setup / make dev / make db-*)。

• ✅ .env 加载，生成的开发机密。

尚未实现 (可选的下一步)

• ⬜ 组织/项目层 (团队，共享)。

• ⬜ 网关上的SSE传输 (目前仅Streamable HTTP)。

• ⬜ 热重载 tools/changed 通知。

• ⬜ 工具集的OpenAPI端点；追踪。

路线图

• 对 /auth (密码暴力破解)、网关以及每个智能体的配额进行速率限制。

• 使调度器多副本安全 (Postgres咨询锁或专用工作进程) — 目前内存中的cron在N个实例上触发N次。

• 将迁移移至单独的部署步骤 (它们在每个实例启动时运行 → 与多个副本竞争)。

• JWT撤销 — 短寿命访问 + 刷新令牌 (泄露的7天令牌无法失效；注销仅本地有效)。

• 机密管理 — KMS + 轮换 VAULT_KEY / JWT_SECRET；收紧CORS (默认 *)；记录TLS反向代理。

• 为生产环境提供Web UI (构建并发布 dist 在CDN/代理后；目前仅Vite开发)。

• 列表端点分页 (工具，日志)。

• 调度器重试/退避/告警。

• OpenAPI解析器 — 处理复杂规范 (allOf, 深层 $ref)。

• 密码重置/邮箱验证；用户审计日志。

分发

打包为 OCI镜像 (ghcr.io/comind-pro/comind-mcp) 并列入 官方MCP注册表 (registry.modelcontextprotocol.io) — 下游目录 (PulseMCP, Smithery, Docker Hub, …) 消费的权威来源。 元数据位于 server.json 中，在GitHub验证的命名空间 io.github.comind-pro/comind-mcp 下。

运行镜像 (零基础设施，嵌入式Postgres):

docker run -p 8787:8787 -v comind-data:/data \
  -e SERVER_ENV=dev ghcr.io/comind-pro/comind-mcp:latest
# prod: drop SERVER_ENV=dev and set VAULT_KEY + JWT_SECRET

发布是自动化的 — 推送版本标签，CI (release.yml) 构建并推送镜像到GHCR，然后通过GitHub OIDC (无需令牌) 将 server.json 发布到注册表:

git tag v0.2.0 && git push origin v0.2.0

注意: ComindMCP 是一个多租户 网关 (HTTP MCP 位于 /g/:slug/mcp，智能体密钥认证)， 不是单个stdio服务器 — 注册表客户端自行部署它并连接自己的智能体。

贡献

comind-mcp 是开源的 (MIT) 欢迎贡献 — 错误报告、功能、文档、测试。

1. Fork 并从 main 分支 (feat/..., fix/...)。

2. 本地设置 — 见 DEVELOPMENT.md。简而言之: corepack enable && pnpm install, 然后 pnpm dev。

3. 在打开PR之前: pnpm typecheck 和 pnpm -r test 必须通过。

4. 使用 Conventional Commits 编写消息 (feat:, fix:, docs:, chore:)。

5. 向 comind-pro/comind-mcp 提交PR，附上清晰描述；链接相关issue。

有问题或想法？请打开 issue。详情见 CONTRIBUTING.md。

许可证

MIT © comind — 开源，可自由使用、修改和分发，包括商业用途。

仓库: https://github.com/comind-pro/comind-mcp