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

• 웹 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)으로 마운트하여 릴리스 간 데이터를 유지하세요. 마이그레이션은 추가적이고 멱등적이므로 업그레이드 시 기존 데이터가 지워지지 않습니다. 임베디드 모드는 단일 노드입니다 (다중 인스턴스 불가 — 하나의 작성자만 가능).

# 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 (제어 평면, :8787에서 REST)

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 보호, 호출 로그)을 거칩니다. 실행이 중단된 스크립트는 워커를 종료하여 처리됩니다.

비용. 중첩 수준당 하나의 워커, 지연 부팅 및 워밍 상태 유지: 시작 후 첫 실행 ≈ 1초, 이후 실행 ≈ 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 해시, 한 번만 표시) + 키 교체를 통한 소비자 ID.

• ✅ 에이전트 ↔ V-MCP 권한 부여 (M2M) — 그룹별로 액세스 부여/취소; 하나의 에이전트가 여러 그룹 엔드포인트에 도달 가능; 키는 권한이 부여된 그룹에만 작동.

스케줄링

• ✅ 스케줄러 — cron 레지스트리 (node-cron), JobRun 로그, 즉시 실행, 부팅 시 로드됨.

• ✅ MCP를 통한 자체 cron — 그룹 내 내장 schedule_task / list_schedules / cancel_schedule 도구; 연결된 에이전트가 스스로를 스케줄링합니다.

비밀 및 업스트림 인증

• ✅ 볼트 — 저장 시 암호화된 자격 증명 (AES-256-GCM); ${secret.NAME}을 통해 런타임에 주입; 에이전트/구성은 값을 볼 수 없습니다.

• ✅ 소스 범위 비밀 — 동일한 이름이 소스별로 존재 가능; 범위가 전역을 재정의합니다.

• ✅ 정적 인증 — bearer/API 키/사용자 정의 헤더, 기본 (사용자 이름/비밀번호).

• ✅ 동적 토큰 흐름 — 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별로 보는 내용 확인; 모든 도구를 실행하여 원시 응답 보기.

웹 UI (Vite + React)

• ✅ 인증 — 로그인 / 등록, 토큰 게이팅, 로그아웃.

• ✅ 소스 및 복합체를 위한 폼 ⟷ JSON 빌더 (폼 또는 원시 JSON 편집, 양방향).

• ✅ 소스 마법사의 인라인 비밀 (소스 범위).

• ✅ 그룹화, 접기 가능, 검색 가능 도구 선택기 및 레지스트리 (대규모 가져온 API로 확장 가능).

• ✅ V-MCP별 연결 스니펫 (claude mcp add …, curl) 복사 버튼 포함.

• ✅ 탭: 소스 · 도구 · V-MCP · 에이전트 · 비밀 · 로그.

인프라

• ✅ Postgres (Drizzle 사용, 부팅 시 마이그레이션 자동 적용).

• ✅ 로컬 Postgres를 위한 Docker Compose + Makefile (make setup / make dev / make db-*).

• ✅ .env 로딩, 생성된 개발 비밀.

아직 미구현 (선택적 다음 단계)

• ⬜ 조직/프로젝트 계층 (팀, 공유).

• ⬜ 게이트웨이의 SSE 전송 (현재는 Streamable HTTP만).

• ⬜ 핫 리로드 tools/changed 알림.

• ⬜ 도구 세트를 위한 OpenAPI 엔드포인트; 트레이스.

로드맵

• /auth (비밀번호 무차별 대입), 게이트웨이, 에이전트별 할당량에 대한 속도 제한.

• 스케줄러를 다중 복제본 안전하게 만들기 (Postgres 어드바이저리 락 또는 전용 워커) — 현재 인메모리 cron은 N개 인스턴스에서 N번 실행됨.

• 마이그레이션을 별도의 배포 단계로 이동 (모든 인스턴스 부팅 시 실행 → 여러 복제본과 경합).

• JWT 폐기 — 수명이 짧은 액세스 + 리프레시 토큰 (유출된 7일 토큰은 무효화 불가; 로그아웃은 로컬 전용).

• 비밀 관리 — VAULT_KEY / JWT_SECRET에 대한 KMS + 순환; CORS 강화 (기본값 *); TLS 리버스 프록시 문서화.

• 프로덕션용 웹 UI 제공 (CDN/프록시 뒤에서 dist 빌드 및 제공; 현재는 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는 단일 stdio 서버가 아닌 다중 테넌트 게이트웨이 (/g/:slug/mcp의 HTTP MCP, 에이전트 키 인증)입니다 — 레지스트리 클라이언트가 자체 배포하고 자체 에이전트를 연결합니다.

기여하기

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을 열고 관련 이슈를 링크하세요.

질문이나 아이디어가 있으신가요? 이슈를 열어주세요. 자세한 내용은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT © comind — 오픈 소스, 상업적 용도를 포함하여 어디서든 자유롭게 사용, 수정, 배포 가능.

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