comind-mcp

Репозиторий: https://github.com/comind-pro/comind-mcp

MCP-шлюз — соединяет различные MCP-серверы и REST API, позволяет курировать и комбинировать инструменты, организовывать их в группы (каждая = отдельный виртуальный MCP-сервер с единой конечной точкой) и раздавать их агентам. Агент видит только узкий набор инструментов, назначенных ему, и может планировать свои собственные cron-задачи через 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

• Веб-интерфейс — http://localhost:5173 (зарегистрируйте аккаунт, затем войдите)

• Шлюз + Control 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 (Control Plane, 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. Полезен там, где возможностей composite-движка не хватает: циклы, арифметика, парсинг, свёртка множества вызовов в одну таблицу.

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, когда код является шагом внутри composite ({"id": "x", "python": "..."}).

• Результат — это то, что вы присваиваете output. Если скрипт определяет main, вызывается main(args) (синхронно или асинхронно). Ни то, ни другое → явная ошибка, никогда не тихий пустой результат.

• return на верхнем уровне — это SyntaxError в Python и убивает весь скрипт — присваивайте output или оборачивайте логику в def main(args).

• print() перехватывается и показывается в редакторе инструмента.

Песочница. Pyodide (CPython → WASM) в рабочем потоке: без сети, без файловой системы, без process. Модули сети Node блокируются в рабочем потоке до загрузки Pyodide, поэтому сокеты Python тоже не работают — единственный выход из скрипта — call(...), который проходит через обычную среду выполнения инструментов (аутентификация, защита SSRF, журнал вызовов). Вышедший из-под контроля скрипт убивается завершением рабочего потока.

Стоимость. Один рабочий поток на уровень вложенности, запускается лениво и держится тёплым: первый запуск после старта ≈ 1 с, последующие ≈ 10 мс. Запуски на одном уровне сериализуются, поэтому длинный скрипт задерживает другие 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-сервера, импорт REST API из OpenAPI 3.x (собственный парсер → инструменты) или подключение HTTP-сервиса с явными конечными точками.

• ✅ Реестр инструментов и курирование — импорт инструментов, переименование, редактирование описаний, переключение видимости, уникальные имена на владельца.

• ✅ Composite-движок — инструменты-намерения, выполняющие несколько вызовов последовательно; условный when; шаблонизация ($.input.*, $.steps.ID.text); шаблон вывода; пошаговая трассировка для настройки.

• ✅ Общая среда выполнения (invokeTool) — один диспетчер для шлюза, композитов и планировщика; native→коннектор, composite→рекурсия (с ограничением глубины); изоляция ошибок (плохой вышестоящий сервис никогда не крашит вызывающего).

• ✅ Группы = виртуальный MCP — объединение курируемых инструментов в единую MCP-конечную точку /g/:groupId/mcp (Streamable HTTP).

• ✅ Агенты — идентификаторы потребителей с одним API-ключом (sha256-хеширован, показывается один раз) + ротация ключей.

• ✅ Разрешения агент ↔ V-MCP (M2M) — предоставление/отзыв доступа по группам; один агент может достигать многих конечных точек групп; ключ работает только для предоставленных групп.

Планирование

• ✅ Scheduler — cron registry (node-cron), JobRun log, run-now, loaded on boot.

• ✅ Self-cron over MCP — built-in schedule_task / list_schedules / cancel_schedule tools inside a group; a connected agent schedules itself.

Secrets & auth-to-upstreams

• ✅ Vault — credentials encrypted at rest (AES-256-GCM); injected at runtime via ${secret.NAME}; agents/config never see the value.

• ✅ Source-scoped secrets — same name can exist per source; scoped overrides global.

• ✅ Static auth — bearer/api-key/custom headers, basic (username/password).

• ✅ Dynamic token flows — oauth2_client_credentials, token_request (login→JSON-path), oauth2_refresh (cached + auto-refresh).

• ✅ User OAuth — oauth2_authorization_code (Connect flow) and MCP-native OAuth (mcp_oauth: SDK discovery + DCR + PKCE + refresh, with optional pre-registered clientId).

Accounts & isolation

• ✅ Auth — email/password (scrypt) + HS256 session JWTs; register / login / me.

• ✅ Multi-user isolation — every resource is owned by a user; all routes scoped by owner; tools resolve only within the owner's namespace. No cross-account access.

Observability

• ✅ Call logs — who/which tool/status/duration/token estimate per invocation.

• ✅ Metrics — totals + by-tool + by-agent.

• ✅ Inspector & test-invoke — see what an agent sees per granted V-MCP; run any tool to view the raw response.

Web UI (Vite + React)

• ✅ Auth — login / register, token gating, logout.

• ✅ Form ⟷ JSON builders for sources and composites (edit a form or the raw JSON, two-way).

• ✅ Inline secrets in the source wizard (scoped to the source).

• ✅ Grouped, collapsible, searchable tool picker & registry (scales to large imported APIs).

• ✅ Connect snippets per V-MCP (claude mcp add …, curl) with copy buttons.

• ✅ Tabs: Sources · Tools · V-MCP · Agents · Secrets · Logs.

Infrastructure

• ✅ Postgres via Drizzle (migrations auto-applied on boot).

• ✅ Docker Compose for local Postgres + Makefile (make setup / make dev / make db-*).

• ✅ .env loading, generated dev secrets.

Not yet (optional next)

• ⬜ Org / project layer (teams, sharing).

• ⬜ SSE transport on the gateway (Streamable HTTP only today).

• ⬜ Hot-reload tools/changed notifications.

• ⬜ OpenAPI endpoint for a toolset; traces.

Roadmap

• Rate-limit /auth (password brute-force), the gateway, and per-agent quotas.

• Make the scheduler multi-replica safe (Postgres advisory lock or a dedicated worker) — today in-memory cron fires N times with N instances.

• Move migrations to a separate deploy step (they run on every instance boot → race with multiple replicas).

• JWT revocation — short-lived access + refresh tokens (a leaked 7-day token can't be invalidated; logout is local-only).

• Secret management — KMS + rotation for VAULT_KEY / JWT_SECRET; tighten CORS (defaults to *); document the TLS reverse proxy.

• Serve the web UI for production (build & serve dist behind a CDN/proxy; Vite dev only today).

• Pagination on list endpoints (tools, logs).

• Scheduler retry / backoff / alerting.

• OpenAPI parser — handle complex specs (allOf, deep $ref).

• Password reset / email verification; user audit log.

Distribution

Packaged as an OCI image (ghcr.io/comind-pro/comind-mcp) and listed in the official MCP Registry (registry.modelcontextprotocol.io) — the canonical source that downstream catalogs (PulseMCP, Smithery, Docker Hub, …) consume. The metadata lives in server.json under the GitHub-verified namespace io.github.comind-pro/comind-mcp.

Run the image (zero-infra, embedded 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

Releasing is automated — push a version tag and CI (release.yml) builds & pushes the image to GHCR, then publishes server.json to the registry via GitHub OIDC (no tokens):

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

Note: ComindMCP is a multi-tenant gateway (HTTP MCP at /g/:slug/mcp, agent-key auth), not a single stdio server — registry clients self-deploy it and connect their own agents.

Contributing

comind-mcp is open source (MIT) and contributions are welcome — bug reports, features, docs, tests.

1. Fork & branch from main (feat/..., fix/...).

2. Set up locally — see DEVELOPMENT.md. TL;DR: corepack enable && pnpm install, then pnpm dev.

3. Before opening a PR: pnpm typecheck and pnpm -r test must pass.

4. Use Conventional Commits for messages (feat:, fix:, docs:, chore:).

5. Open a PR against comind-pro/comind-mcp with a clear description; link any related issue.

Questions or ideas? Open an issue. See CONTRIBUTING.md for details.

License

MIT © comind — open source, free to use, modify, and distribute anywhere, including commercially.

Repository: https://github.com/comind-pro/comind-mcp