comind-mcp

リポジトリ: https://github.com/comind-pro/comind-mcp

MCP ゲートウェイ — さまざまな MCP サーバーや REST API を接続し、ツールをキュレーション・組み合わせてグループ（各グループは単一エンドポイントを持つ独立した仮想 MCP サーバー）に整理し、エージェントに提供できます。エージェントは割り当てられた狭いツールセットのみを認識し、MCP 経由で独自の cron をスケジュールできます。

セルフホスト: 単一の 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、マイグレーション）が変更なしで動作します — 外部 DB プロセスは不要です。永続性: file: ディレクトリは実際の Postgres データディレクトリです。ボリュームとしてマウント（例: /data）することで、リリース間でデータを保持できます。マイグレーションは追加的かつ冪等なので、アップグレードで既存データが消えることはありません。組み込みモードはシングルノードです（マルチインスタンス不可 — ライターは1つ）。

# 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> を設定。クライアントはグループのツールセット（+ セルフ cron ツール）のみを認識します。

6. ログ → 呼び出し、メトリクス、エラー。

概念

API（コントロールプレーン、REST on :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（Web）から接続: スクリーンショット付きのステップバイステップガイド — docs/connect.md。

Python ツール

本体が Python であるツール。コンポジットエンジンでは対応できない場合に便利: ループ、算術、パース、複数の呼び出しを1つのテーブルにまとめるなど。

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 ガード、呼び出しログ）を経由します。暴走したスクリプトはワーカーを終了させることで強制終了されます。

コスト。 ネストレベルごとに1つのワーカーが遅延起動され、ウォーム状態を維持: 起動後の初回実行 ≈ 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 ハッシュとして保存され、トークンは一度だけ表示されます。

• 1つの上流の障害がエンドポイント全体をダウンさせることはありません（ランタイムの障害分離）。

モジュールと機能

モジュールごとに反復的に構築されています。以下はすべて実装済みで動作しています。

コアゲートウェイ

• ✅ コネクタ — 既存の MCP サーバーのプロキシ、OpenAPI 3.x からの REST API インポート（独自パーサー → ツール）、または明示的なエンドポイントを持つ HTTP サービスの配線。

• ✅ ツールレジストリとキュレーション — ツールのインポート、リネーム、説明の編集、可視性の切り替え、所有者ごとの一意の名前。

• ✅ コンポジットエンジン — 複数の呼び出しを順次実行するインテントツール; 条件付き when; テンプレート（$.input.*、$.steps.ID.text）; 出力テンプレート; ステップごとのトレースで調整可能。

• ✅ 共有ランタイム（invokeTool） — ゲートウェイ、コンポジット、スケジューラーに共通のディスパッチャー; ネイティブ→コネクタ、コンポジット→再帰（深さ制限）; 障害分離（悪い上流が呼び出し元をクラッシュさせることはありません）。

• ✅ グループ = 仮想 MCP — キュレーションされたツールを単一の MCP エンドポイント /g/:groupId/mcp（Streamable HTTP）にバンドル。

• ✅ エージェント — 1つの API キー（sha256 ハッシュ、一度だけ表示）を持つコンシューマ ID + キーローテーション。

• ✅ エージェント ↔ V-MCP 許可（M2M） — グループごとにアクセスを許可/取り消し; 1つのエージェントが複数のグループエンドポイントにアクセス可能; キーは許可されたグループに対してのみ機能します。

スケジューリング

• ✅ スケジューラ — cronレジストリ (node-cron)、JobRunログ、即時実行、起動時にロード。

• ✅ MCP経由のセルフcron — グループ内に組み込みの schedule_task / list_schedules / cancel_schedule ツール。接続されたエージェントが自身をスケジュール。

シークレットと上流への認証

• ✅ Vault — 保存時に暗号化された認証情報 (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 via 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など）が消費する正規のソース。メタデータはGitHub検証済み名前空間 io.github.comind-pro/comind-mcp の下の server.json に存在。

イメージを実行（ゼロインフラ、組み込み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 at /g/:slug/mcp、エージェントキー認証）であり、単一のstdioサーバーではありません — レジストリクライアントはそれを自己デプロイし、自身のエージェントを接続します。

コントリビューション

comind-mcpはオープンソース（MIT）であり、コントリビューションを歓迎します — バグ報告、機能追加、ドキュメント、テスト。

1. 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