GenPDM MCP Server

고정 비즈니스 GraphQL API를 안전하고 타입이 지정된 MCP 도구로 노출하기 위한 TypeScript/Express MCP 서버 스켈레톤입니다.

기능

• ALL /mcp의 MCP SDK v2 Streamable HTTP 엔드포인트

• HS256 Bearer JWT 검증 및 범위(scope) 검사

• IP별 및 주체별 인메모리 속도 제한

• 제한된 Undici keep-alive 풀을 기반으로 하는 GraphQL 클라이언트

• 쿼리 전용 재시도, 뮤테이션 멱등성, 동시성 및 응답 크기 제한

• 재현 가능한 모의(mock) GraphQL 업스트림

• Liveness/readiness 엔드포인트 및 graceful shutdown

현재 속도 제한 저장소는 의도적으로 프로세스 로컬입니다. src/rate-limit.ts에는 향후 Redis 기반 저장소를 위한 어댑터 경계가 포함되어 있습니다. 여러 복제본을 실행할 때 현재 카운터를 전역으로 취급하지 마십시오.

Related MCP server: gqai

문서

• 시스템 아키텍처

• 구현 가이드

• 개발 가이드

• 테스트 가이드

• 로컬 실행 및 수동 테스트

• AI 에이전트 통합

• 에이전트 사용자 승인 테스트

저장소 자동화:

• AGENTS.md는 항상 적용되는 아키텍처 및 명명 규칙을 정의합니다.

• genpdm-mcp-development는 GraphQL 작업 및 MCP 도구 변경 시 Codex를 안내합니다.

실행 가능한 예시:

• 격리된 GenPDM 샘플 에이전트

로컬 실행

Node.js 20 이상이 필요합니다.

Copy-Item .env.example .env
npm install
npm run dev:mock

두 번째 터미널에서:

npm run dev
$token = npm.cmd run --silent token

엔드포인트 http://127.0.0.1:3000/mcp와 헤더 Authorization: Bearer <token>로 MCP 클라이언트를 구성하십시오.

사용 가능한 도구:

• get_customer: { "id": "cust-001" }, customers:read 권한 필요

• create_order: { "customerId": "cust-001", "items": [{ "sku": "SKU-1", "quantity": 2 }] }, orders:write 권한 필요

헬스 엔드포인트는 인증이 필요 없습니다:

• GET /health/live

• GET /health/ready

검증

npm run typecheck
npm run build
npm test

프로덕션 참고 사항

• HS256 검증을 회사 IdP의 JWKS 검증기로 교체하십시오.

• 수평 확장으로 엄격한 글로벌 제한이 필요해지기 전에 인메모리 속도 제한 저장소를 Redis로 교체하십시오.

• JWT 및 GraphQL 자격 증명을 시크릿 매니저에서 주입하십시오.

• 배포 토폴로지에 맞게 ALLOWED_HOSTS, CORS_ORIGINS 및 신뢰할 수 있는 프록시 설정을 제한하십시오.