MCP 데이터 게이트웨이

상태: 초기 개발 단계. 프로젝트 스캐폴딩(설정, 의존성, 문서)이 마련되어 있습니다. src/ 하위의 소스 코드는 아직 구현되지 않았습니다. 현재 진행 상황은 개발 로드맵을 참조하세요. 구현 계획은 docs/plan.md에 있습니다.

통합 데이터 게이트웨이 역할을 하는 Python 기반 MCP(Model Context Protocol) 서버로, Claude(및 기타 MCP 클라이언트)가 단일 보안 인터페이스를 통해 여러 외부 API와 데이터를 주고받을 수 있게 합니다.

개요

이 MCP 서버는 다음을 제공합니다:

• 다양한 데이터 유형을 위한 일반 데이터 처리

• 모든 REST 또는 GraphQL 엔드포인트를 지원하는 일반 API 게이트웨이

• 자동 브라우저 기반 로그인 흐름을 포함한 OAuth 2.0 인증

• 시스템 키링을 사용한 보안 자격 증명 저장

• 향후 MCP 앱 발전을 위한 기반

기능

아키텍처

MCP/
├── src/
│   ├── server.py              # MCP server entry point
│   ├── auth/
│   │   ├── __init__.py
│   │   ├── oauth.py           # OAuth 2.0 flow handler with popup
│   │   └── credentials.py     # Secure credential storage (keyring)
│   ├── gateway/
│   │   ├── __init__.py
│   │   ├── api_client.py      # Generic REST/GraphQL HTTP client
│   │   └── handlers.py        # Request/response transformation
│   ├── models/
│   │   ├── __init__.py
│   │   └── data_models.py     # Generic Pydantic data models
│   └── tools/
│       ├── __init__.py
│       └── mcp_tools.py       # MCP tool definitions for Claude
├── config/
│   └── api_configs.json       # API service configurations
├── tests/                     # Unit and integration tests
├── .env.example               # Environment variables template
├── .gitignore                 # Excludes secrets and build artifacts
├── requirements.txt           # Python dependencies
└── README.md                  # This file

모듈 책임

핵심 MCP 서버 (src/server.py)

• Python mcp SDK를 사용하여 MCP 서버 초기화

• 도구(fetch_data, send_data, execute_graphql 등) 등록

• 도구 실행 수명 주기 및 오류 응답 처리

인증 (src/auth/)

• oauth.py: 자동 브라우저 팝업을 포함한 OAuth 2.0 인증 코드 흐름. 인증 코드를 수신하기 위해 로컬 HTTP 콜백 서버를 실행합니다. 여러 공급자(Google, GitHub, 사용자 지정)를 지원합니다.

• credentials.py: 시스템 키링을 통한 액세스/갱신 토큰의 보안 저장. 토큰 유효성 검사 및 만료 처리.

API 게이트웨이 (src/gateway/)

• api_client.py: REST(GET/POST/PUT/DELETE) 및 GraphQL(쿼리/뮤테이션)을 지원하는 일반 비동기 HTTP 클라이언트. Bearer 토큰, API 키, 기본 인증을 처리합니다.

• handlers.py: 서로 다른 API 간의 응답을 정규화하고 HTTP 오류와 별도로 GraphQL 오류를 파싱합니다.

MCP 도구 (src/tools/mcp_tools.py)

인증 흐름

Claude가 인증이 필요한 도구를 호출할 때:

1. Claude invokes tool (e.g., fetch_data)
        ↓
2. MCP checks credentials in keyring
        ↓
3a. Valid token  →  Proceed with API call
3b. Missing/Expired  →  Open browser popup for OAuth
        ↓
4. User logs in via browser
        ↓
5. Local callback server receives auth code
        ↓
6. Exchange auth code for access token
        ↓
7. Store token in keyring
        ↓
8. Resume original tool call

기술 스택

• Python 3.10+

• mcp — Model Context Protocol Python SDK

• httpx — 비동기 HTTP 클라이언트 (REST + GraphQL)

• keyring — 크로스 플랫폼 보안 자격 증명 저장소

• pydantic — 데이터 유효성 검사 및 모델링

• python-dotenv — 환경 변수 관리

설정

사전 요구 사항

• Python 3.10 이상

• pip 또는 uv (권장)

설치

# Clone the repository
cd /Users/chawengwit/Documents/MCP

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env
# Edit .env with your OAuth credentials and API settings

구성

1. 환경 변수 (.env)

# OAuth credentials (per provider)
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret
OAUTH_REDIRECT_URI=http://localhost:8765/callback

# Server settings
MCP_LOG_LEVEL=INFO              # DEBUG | INFO | WARN | ERROR
MCP_LOG_FILE=                   # Optional path to log file (default: stderr only)
MCP_DEBUG=false                 # Enable verbose request tracing
MCP_MAX_RESPONSE_BYTES=1048576  # Response size cap (1 MB default)
OAUTH_CALLBACK_PORT=8765

2. API 구성 (config/api_configs.json)

{
  "apis": {
    "example_api": {
      "base_url": "https://api.example.com",
      "type": "rest",
      "auth": {
        "method": "oauth2",
        "provider": "custom",
        "authorize_url": "https://auth.example.com/oauth/authorize",
        "token_url": "https://auth.example.com/oauth/token",
        "scopes": ["read", "write"]
      },
      "endpoints": {
        "get_users": {"method": "GET", "path": "/users"},
        "create_user": {"method": "POST", "path": "/users"}
      }
    }
  }
}

사용법

MCP 서버 실행

python -m src.server

Claude Code에 연결

Claude Code MCP 설정에 다음 구성을 추가하세요:

{
  "mcpServers": {
    "data-gateway": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/Users/chawengwit/Documents/MCP"
    }
  }
}

예시 상호 작용

연결되면 Claude는 다음을 수행할 수 있습니다:

• 구성된 API 나열: "사용 가능한 API 서비스를 보여줘"

• 데이터 가져오기: "example_api에서 사용자 목록을 가져와"

• 데이터 전송: "이 데이터로 example_api에 새 레코드를 생성해..."

• GraphQL 실행: "내 API에 대해 이 GraphQL 쿼리를 실행해..."

인증이 필요한 도구를 Claude가 처음 사용할 때, OAuth 로그인을 위해 브라우저가 자동으로 열립니다.

응답 형식

모든 MCP 도구는 일관된 파싱을 위해 구조화된 JSON을 반환합니다.

성공:

{
  "data": <api response>,
  "metadata": { "source": "...", "endpoint": "...", "timestamp": "...", "duration_ms": 142 }
}

오류:

{
  "error": { "code": "AUTH_REQUIRED", "message": "...", "details": { ... } }
}

표준 오류 코드: AUTH_REQUIRED, AUTH_FAILED, API_NOT_CONFIGURED, ENDPOINT_NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, VALIDATION_ERROR, RESPONSE_TOO_LARGE.

MCP_MAX_RESPONSE_BYTES보다 큰 JSON/텍스트 응답은 잘리고 성공으로 반환되며 metadata.truncated: true와 페이지네이션 커서가 포함됩니다. 바이너리 또는 스트리밍 페이로드만 RESPONSE_TOO_LARGE를 발생시킵니다(안전하게 자를 수 없음). 바이너리 데이터는 content_type 메타데이터와 함께 base64로 인코딩됩니다. GraphQL 응답은 data와 errors를 모두 노출하므로 부분적인 성공은 계속 사용할 수 있습니다.

자세한 내용은 CLAUDE.md를 참조하세요.

디버깅

빠른 진단

디버그 모드 활성화

MCP_DEBUG=true MCP_LOG_LEVEL=DEBUG python -m src.server

이 설정은 전체 HTTP 교환(비밀 정보는 마스킹됨)을 stderr로 덤프합니다. 절대 stdout으로 출력하지 마세요 — stdout은 MCP JSON-RPC 프로토콜 스트림을 전달합니다.

로깅 참고 사항

• 모든 로그는 stderr(또는 선택적 MCP_LOG_FILE)로 이동합니다.

• 토큰, API 키, Authorization 헤더 및 자격 증명은 로깅 전에 자동으로 마스킹됩니다.

• 로그는 jq로 쉽게 파싱할 수 있도록 구조화된 JSON(줄당 하나의 이벤트) 형식입니다.

디버깅 전략에 대한 자세한 내용은 CLAUDE.md를 참조하세요.

개발 로드맵

1단계: 프로젝트 설정

• [x] 의존성이 고정된 requirements.txt

• [x] 비밀 정보 및 캐시를 위한 .gitignore

• [x] 환경 변수를 문서화한 .env.example

• [ ] src/ 패키지 구조 초기화

• [ ] 초기 config/api_configs.json 템플릿

2단계: 핵심 MCP 서버

• [ ] MCP 서버 초기화

• [ ] 도구 스키마 정의

• [ ] 로깅 및 오류 처리

3단계: 인증

• [ ] OAuth 2.0 인증 코드 흐름

• [ ] 로컬 콜백 HTTP 서버

• [ ] 키링 기반 토큰 저장소

• [ ] 토큰 갱신 로직

4단계: API 게이트웨이

• [ ] 일반 REST 클라이언트

• [ ] GraphQL 쿼리/뮤테이션 지원

• [ ] 다중 인증 방식 지원

• [ ] 요청/응답 핸들러

5단계: 도구 및 통합

• [ ] fetch_data 도구 구현

• [ ] send_data 도구 구현

• [ ] execute_graphql 도구 구현

• [ ] list_apis 및 get_status 도구 구현

6단계: 테스트 및 마무리

• [ ] 모듈별 단위 테스트

• [ ] 모의 API를 사용한 통합 테스트

• [ ] 구성 예시

• [ ] 사용자 문서

향후 개선 사항

• MCP 앱: 이 게이트웨이 위에 프론트엔드로 제공되는 독립형 웹 인터페이스

• 영구 저장소: 데이터 기록 및 감사 로그를 위한 SQLite/PostgreSQL

• 속도 제한: API별 속도 제한 및 요청 대기열

• 캐싱: 구성 가능한 TTL을 사용한 응답 캐싱

• 멀티 테넌트: 별도의 자격 증명 저장소를 가진 여러 사용자 지원

• 웹훅: 수신 웹훅을 통해 데이터 수신

• 데이터 변환 파이프라인: API 간 변환 체인 연결

보안

• 모든 자격 증명은 OS 수준의 보안 키링(macOS의 Keychain, Windows의 Credential Manager, Linux의 Secret Service)에 저장됨

• .env 파일은 .gitignore를 통해 버전 관리에서 제외됨

• OAuth는 표준 인증 코드 흐름을 사용함(암시적 승인 없음)

• 토큰은 절대 로깅되거나 오류 메시지에 노출되지 않음

• 로컬 콜백 서버는 localhost에서만 수신하며 OAuth 흐름 중에만 활성화됨

라이선스

미정

기여

이 프로젝트는 초기 개발 단계입니다. 핵심 구현이 안정화되면 기여 가이드라인이 추가될 예정입니다.