mcp-suite

AI 에이전트(Claude Desktop, Cursor, Windsurf, 커스텀 에이전트)에게 금융 시장, Web3/DeFi, 개발자 도구, 의료(FHIR) 등 4개 도메인 전반의 실제 데이터에 대한 구조화된 액세스를 제공하는 프로덕션급 TypeScript MCP 서버입니다.

인증 우선 — 기본적으로 JWT 유효성 검사 활성화
도메인 격리 — API 키가 없으면 전체 서버가 아닌 해당 도메인만 비활성화
도메인별 응답 캐시(LRU + TTL) 및 토큰 버킷 속도 제한
모든 도구 입력 및 출력에 대한 타입 지정 스키마(Zod)
두 가지 전송 방식: stdio(로컬) 및 HTTP + SSE(원격/호스팅)

빠른 시작

# Run directly (no global install required)
npx mcp-suite

# Or install globally
npm install -g mcp-suite
mcp-suite

요구 사항: Node.js ≥ 20, npm ≥ 10

설치

1. 환경 변수 설정

.env.example을 .env로 복사하고 활성화하려는 도메인의 키를 입력하세요:

cp .env.example .env

# Authentication (required in production)
MCP_JWT_SECRET=your-secret-here

# Financial Markets (Alpha Vantage + CoinGecko)
ALPHA_VANTAGE_API_KEY=

# Web3 / DeFi (Alchemy + OpenSea + Blur)
ALCHEMY_API_KEY=
OPENSEA_API_KEY=

# Developer Tools (GitHub)
GITHUB_TOKEN=

# Healthcare / FHIR (optional — defaults to public HAPI sandbox)
FHIR_BASE_URL=https://hapi.fhir.org/baseR4

# Server
LOG_LEVEL=info         # debug | info | warn | error
MCP_PORT=3000          # HTTP transport only
AUTH_DISABLED=false    # set true for local dev only

사용하는 도메인에 대한 키만 있으면 됩니다. 키가 없는 도메인은 시작 시 자동으로 비활성화됩니다.

2. 개발용 토큰 생성

npx mcp-suite gen-token
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Claude Desktop에 추가

~/Library/Application Support/Claude/claude_desktop_config.json(macOS)에 추가하세요:

{
  "mcpServers": {
    "mcp-suite": {
      "command": "npx",
      "args": ["mcp-suite"],
      "env": {
        "MCP_JWT_SECRET": "your-secret-here",
        "ALPHA_VANTAGE_API_KEY": "...",
        "ALCHEMY_API_KEY": "...",
        "OPENSEA_API_KEY": "...",
        "GITHUB_TOKEN": "..."
      }
    }
  }
}

4. HTTP 서버로 시작(원격/호스팅 배포)

npx mcp-suite --transport http --port 3000

이 명령은 원격 MCP 클라이언트를 위해 GET /health, GET /tools 및 SSE 엔드포인트를 노출합니다.

CLI 명령어

명령어	설명
`npx mcp-suite`	서버 시작(stdio 전송, 기본값)
`npx mcp-suite --transport http`	HTTP + SSE 서버 시작
`npx mcp-suite gen-token`	개발용 JWT 생성
`npx mcp-suite list-tools`	도메인별로 그룹화된 모든 활성 도구 출력

사용 가능한 도구

금융 시장

Alpha Vantage 및 CoinGecko 기반. 필수: ALPHA_VANTAGE_API_KEY

도구	설명
`get_stock_quote`	미국 주식 가격, 거래량, 변동 %
`get_forex_rate`	통화 쌍 환율(ISO 4217)
`get_crypto_price`	암호화폐 가격, 시가 총액, 24시간 변동
`get_market_news`	감정 점수가 포함된 금융 헤드라인

예시:

{ "tool": "get_stock_quote", "arguments": { "ticker": "NVDA" } }

Web3 / DeFi

Alchemy, OpenSea, Blur 기반. 필수: ALCHEMY_API_KEY, OPENSEA_API_KEY

도구	설명
`get_nft_floor`	OpenSea + Blur 전체 최저가(ETH, Base, Arbitrum)
`get_nft_recent_sales`	특성 및 마켓플레이스가 포함된 최근 N건의 판매 내역
`get_wallet_balances`	멀티체인 토큰 + NFT 보유량, ENS 확인
`get_amm_reserves`	Uniswap V2/V3 풀 예치금 및 가격 비율
`get_dex_liquidity`	규모별 거래 슬리피지 추정치

예시:

{ "tool": "get_nft_floor", "arguments": { "collection_slug": "boredapeyachtclub" } }

개발자 도구

GitHub API 기반. 필수: GITHUB_TOKEN

도구	설명
`get_repo_stats`	스타, 포크, 이슈, 언어, 마지막 커밋
`summarize_pr`	PR diff 요약, 리뷰어, CI 확인, 병합 상태
`get_pipeline_status`	브랜치별 최신 GitHub Actions 실행 내역
`get_deployment_health`	활성 배포 URL 및 상태

예시:

{ "tool": "get_pipeline_status", "arguments": { "repo": "vercel/next.js", "branch": "canary" } }

의료 (FHIR)

HAPI FHIR R4 기반. 필수: 없음(기본적으로 공개 샌드박스 사용) 또는 커스텀 엔드포인트용 FHIR_BASE_URL.

HIPAA 주의사항: 모든 의료 도구는 합성 데이터만 포함된 공개 샌드박스에 연결됩니다. 실제 환자 건강 정보(PHI)에는 액세스하지 않습니다. 프로덕션 환경에서 사용하려면 FHIR_BASE_URL을 HIPAA 준수 EHR 엔드포인트로 교체하고 적절한 SMART on FHIR OAuth 2.0 자격 증명을 구성하십시오.

도구	설명
`lookup_patient`	인구 통계학적 환자 검색
`get_observations`	환자별 활력 징후 및 검사 결과
`get_medications`	환자별 활성 약물 목록

예시:

{ "tool": "lookup_patient", "arguments": { "name": "Smith", "birth_date": "1980-01-15" } }

인증

인증은 기본적으로 활성화되어 있습니다. 모든 도구 호출에는 유효한 JWT가 포함되어야 합니다.

프로덕션

MCP_JWT_SECRET을 강력한 비밀 키로 설정하세요. 프로덕션 모드에서는 이 키 없이는 서버가 시작되지 않습니다.

개발

옵션 A — 인증 완전히 비활성화(로컬 전용):

AUTH_DISABLED=true

옵션 B — 개발용 JWT 사용:

npx mcp-suite gen-token

생성된 토큰을 MCP 요청의 _meta 필드(stdio) 또는 Authorization: Bearer 헤더(HTTP)에 전달하세요.

JWT 구조

{
  "sub": "your-client-id",
  "scope": "mcp:tools",
  "iat": 1713484800,
  "exp": 1716076800
}

아키텍처

MCP Clients (Claude Desktop · Cursor · Windsurf · Custom Agents)
        │  MCP Protocol
┌───────▼────────────────────────────────────────┐
│  Transport Layer  (stdio  |  HTTP + SSE)        │
├────────────────────────────────────────────────┤
│  Auth Middleware  (JWT validation / bypass)     │
├────────────────────────────────────────────────┤
│  Tool Registry    (register · list · route)     │
├──────────┬──────────┬──────────┬───────────────┤
│Financial │  Web3    │ DevTools │  Healthcare   │
├──────────┴──────────┴──────────┴───────────────┤
│  Shared: Rate Limiter · Cache · Logger · Errors │
└─────────────────────────────────────────────────┘
         │           │          │          │
   Alpha Vantage  Alchemy   GitHub API  HAPI FHIR
   CoinGecko      OpenSea
                  Blur

캐싱: 프로세스 내 LRU + TTL 캐시(node-cache). TTL은 도메인에 적합하게 설정됨(암호화폐 15초, GitHub 저장소 통계 300초).
속도 제한: 도메인별 토큰 버킷으로 무료 티어 API 할당량 보호.
오류 유형: AuthError, ValidationError, DomainUnavailableError, UpstreamError, RateLimitError — 모두 구조화된 MCP 오류 응답을 생성.
로깅: 모든 도구 호출에 대한 구조화된 JSON: 도메인, 도구 이름, 지연 시간, 캐시 적중 여부, 상태.

도메인 추가

각 도메인은 동일한 패턴을 따릅니다. 새 도메인을 추가하려면:

src/domains/[name]/에 index.ts, schemas.ts, client.ts 및 tools/를 생성합니다.
Domain 객체를 내보냅니다:

export const myDomain: Domain = {
  name: 'my-domain',
  isAvailable: () => !!config.MY_API_KEY,
  registerTools: (server) => { /* server.tool(...) calls */ }
}

src/server.ts에 등록합니다.
docs/API.md에 도구를 문서화합니다.

전체 패턴은 docs/TDD.md §5 및 docs/CODING_STANDARDS.md를 참조하세요.

개발

git clone https://github.com/ayenisholah/mcp-suite.git
cd mcp-suite
npm install
cp .env.example .env   # fill in your API keys

npm run build          # compile TypeScript → dist/
npm run dev            # watch mode
npm run typecheck      # type check without emit
npm run lint           # ESLint
npm test               # unit tests (Vitest)
npm run test:coverage  # tests + coverage report

# Integration tests — hits real APIs, requires .env keys
RUN_INTEGRATION=true npm test

HTTP 전송 엔드포인트

--transport http로 실행할 때:

엔드포인트	인증	설명
`GET /health`	아니오	도메인별 가용성 상태
`GET /tools`	예	도메인별로 그룹화된 모든 등록된 도구
`POST /mcp`	예	MCP 프로토콜 엔드포인트(SSE)

오류 참조

코드	설명
`AUTH_ERROR`	JWT 누락, 만료 또는 잘못된 서명
`VALIDATION_ERROR`	입력값이 Zod 스키마 유효성 검사 실패
`DOMAIN_UNAVAILABLE`	시작 시 도메인 API 키가 구성되지 않음
`RATE_LIMITED`	도메인별 속도 제한 초과
`UPSTREAM_ERROR`	외부 API가 오류를 반환하거나 시간 초과 발생

라이선스

MIT — LICENSE 참조

기여

이슈 및 PR을 환영합니다. 제출하기 전에 docs/CODING_STANDARDS.md를 읽어주세요.

mcp-suite

mcp-suite

빠른 시작

설치

1. 환경 변수 설정

2. 개발용 토큰 생성

3. Claude Desktop에 추가

4. HTTP 서버로 시작(원격/호스팅 배포)

CLI 명령어

사용 가능한 도구

금융 시장

Web3 / DeFi

개발자 도구

의료 (FHIR)

인증

프로덕션

개발

JWT 구조

아키텍처

도메인 추가

개발

HTTP 전송 엔드포인트

오류 참조

라이선스

기여

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API