IBM/mcp-context-forgePlease refer to the latest official releases for information GitHub Homepage
기능이 풍부한 모델 컨텍스트 프로토콜(MCP) 게이트웨이 및 등록 센터로, 도구, 리소스 및 프롬프트의 통합 관리를 제공하며, REST API를 MCP 프로토콜로 변환하는 것을 지원하고, 보안 및 관측 가능성을 갖추고 있습니다.
Apache-2.0Python 0.6kIBMmcp-context-forge Last Updated: 2025-06-24
MCP Context Forge 프로젝트 상세 소개
프로젝트 개요
MCP Context Forge는 IBM에서 오픈 소스로 제공하는 기능이 풍부한 FastAPI 기반 모델 컨텍스트 프로토콜(MCP) 게이트웨이입니다. 이 게이트웨이는 도구, 리소스, 프롬프트, 서버 및 피어 게이트웨이를 통합하고 연합하여 모든 REST API를 MCP 표준을 준수하는 도구 또는 가상 서버로 래핑합니다. 이 프로젝트는 HTTP/JSON-RPC, WebSocket, 서버 전송 이벤트(SSE) 및 stdio 전송 프로토콜을 통해 모든 기능을 공개하고, 풍부한 대화형 관리 UI를 제공하며, 컨테이너 형태로 패키징되어 모든 SQLAlchemy 지원 데이터베이스를 지원합니다.
핵심 기능
1. 프로토콜 게이트웨이 기능
- 진정한 게이트웨이 아키텍처: 도구, 리소스 및 프롬프트 등록 센터를 중앙 집중화하면서 공식 MCP 2025-03-26 프로토콜 표준을 유지합니다.
- 다중 서버 연합: 여러 MCP 서버를 하나의 엔드포인트로 통합합니다. 피어 노드 자동 검색(mDNS 또는 명시적 구성), 상태 확인 및 기능 병합을 수행합니다.
- 가상화 서비스: 비 MCP 서비스를 "가상 서버"로 가상화하여 모든 REST API 또는 함수 엔드포인트를 등록하고 MCP 의미 체계 하에서 공개할 수 있습니다.
2. API 어댑터 기능
- REST to MCP 어댑터: 임의의 REST/HTTP API를 MCP 도구로 어댑터합니다. JSON-Schema 입력 유효성 검사, 재시도/속도 제한 정책 및 투명한 JSON-RPC 호출을 지원합니다.
- 프로토콜 변환: 다양한 전송 프로토콜 간의 변환(stdio, SSE, 스트리밍 가능한 HTTP)을 지원합니다.
3. 배포 및 관리
- 완전한 관리 UI: 풍부한 전송 프로토콜, 사전 구축된 개발 경험 파이프라인 및 프로덕션 수준의 관찰 가능성을 제공합니다.
- 엔터프라이즈급 기능: 인증, 권한 부여, 캐싱, 상태 확인, 지표 수집 등 완전한 기능을 포함합니다.
시스템 아키텍처
이 프로젝트는 모듈식 아키텍처 설계를 채택했습니다.
┌─────────────────┐ ┌──────────────────┐
│ 🖥️ Admin UI │ │ 🔐 인증 권한 부여 │
│ 관리 인터페이스 │ │ JWT + Basic │
└─────────────────┘ └──────────────────┘
│ │
└────────┬─────────────────┘
│
┌─────────────▼─────────────────┐
│ 🚪 MCP 게이트웨이 코어 │
│ 프로토콜 초기화 Ping 완료 │
│ 연합 관리자 │
│ 전송 프로토콜 HTTP WS SSE Stdio │
└─────────────┬─────────────────┘
│
┌─────────────▼─────────────────┐
│ 서비스 계층 │
│ 🧰 도구 서비스 📁 리소스 서비스 │
│ 📝 프롬프트 서비스 🧩 서버 서비스 │
└─────────────┬─────────────────┘
│
┌─────────────▼─────────────────┐
│ 영구 저장 계층 │
│ 💾 데이터베이스 SQLAlchemy │
│ ⚡ 캐시 Redis/Memory │
└───────────────────────────────┘
기술 특성
지원되는 프로토콜 및 전송
- 완전한 MCP 2025-03-26 지원: initialize, ping, notify, completion, sampling (SSE) 및 JSON-RPC 폴백
- 다중 전송 프로토콜: HTTP/JSON-RPC, WebSocket(ping/pong), SSE(단방향 + 콜백 채널), stdio
- 프로토콜 변환: 서로 다른 전송 프로토콜 간의 원활한 변환 지원
연합 및 검색
- 자동 검색: mDNS 또는 명시적으로 구성된 피어 게이트웨이 검색 지원
- 상태 확인: 정기적인 상태 확인, 장애 조치 지원
- 투명한 병합: 원격 레지스트리를 통합 디렉터리에 투명하게 병합
리소스 관리
- 템플릿 URI: 매개변수화된 리소스 URI 지원
- 스마트 캐시: LRU+TTL 캐시 메커니즘, MIME 유형 감지
- 실시간 구독: SSE 실시간 리소스 변경 구독 지원
프롬프트 관리
- Jinja2 템플릿: 강력한 템플릿 엔진 지원
- 스키마 유효성 검사: JSON-Schema 강제 유효성 검사
- 다중 모달 지원: 다중 모달 콘텐츠 블록 지원
- 버전 관리: 버전 관리 및 롤백 기능
도구 관리
- 다양한 유형 지원: 기본 MCP 또는 REST 기반 도구
- 입력 유효성 검사: 완전한 입력 유효성 검사 메커니즘
- 재시도 로직: 스마트 재시도 및 속도 제한/동시성 제어
관리 및 모니터링 기능
웹 관리 인터페이스
- 기술 스택: HTMX + Alpine.js + Tailwind CSS
- 완전한 CRUD: 서버, 도구, 리소스, 프롬프트, 게이트웨이, 루트 디렉터리 및 지표의 완전한 관리
- 실시간 모니터링: 실시간 상태 모니터링 및 로그 보기
인증 및 권한 부여
- 다양한 인증 방식: Basic 인증, JWT Bearer, 사용자 정의 헤더 인증
- 세분화된 제어: 각 엔드포인트의 종속성 주입 제어
- 보안 암호화: 도구 인증 헤더의 AES 암호화 저장
영구 저장 및 마이그레이션
- ORM 지원: 비동기 SQLAlchemy ORM(SQLite, PostgreSQL, MySQL 등)
- 자동 마이그레이션: Alembic 자동 데이터베이스 마이그레이션
- 연결 풀: 완전한 데이터베이스 연결 풀 구성
이벤트 시스템 및 관찰 가능성
- 통합 이벤트: WS/SSE 팬아웃의 통합 이벤트 래핑
- 서버 측 필터링: 서버 측 이벤트 필터링 및 콜백 후크
- 구조화된 로그: 구조화된 JSON 로깅
- 상태 확인:
/health엔드포인트 및 지연 지표 데코레이터 - 완전한 지표: 각 처리기의 지표 수집
개발 경험
개발 도구
- Makefile 대상: 100개 이상의 사전 정의된 개발 대상
- 코드 품질: pre-commit hooks(ruff, black, mypy, isort)
- 실시간 재로드: 개발 서버는 실시간 재로드를 지원합니다.
- 테스트 커버리지: 400개 이상의 테스트 케이스
- CI/CD: 완전한 CI 배지 및 자동화된 프로세스
배포 옵션
- 컨테이너화된 배포: Docker/Podman 지원
- 클라우드 네이티브: IBM Cloud Code Engine 배포 지원
- 다중 환경: 개발, 테스트, 프로덕션 환경 구성
- SSL/TLS: 완전한 HTTPS 지원
구성 옵션
기본 구성
# 애플리케이션 기본 구성
APP_NAME=MCP Gateway
HOST=0.0.0.0
PORT=4444
DATABASE_URL=sqlite:///./mcp.db
APP_ROOT_PATH=/gateway # 선택적 하위 경로 접두사
인증 구성
# Basic 인증(관리 인터페이스 및 API)
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme
# JWT 구성
JWT_SECRET_KEY=my-test-key
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=10080 # 분
# 인증 제어
AUTH_REQUIRED=true
AUTH_ENCRYPTION_SECRET=my-test-salt
연합 구성
# 연합 기능
FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=false
FEDERATION_PEERS=["http://peer1:4444","http://peer2:4444"]
FEDERATION_TIMEOUT=30
FEDERATION_SYNC_INTERVAL=300
빠른 시작
Docker를 사용하여 실행
docker run -d --name mcpgateway \
-p 4444:4444 \
-e HOST=0.0.0.0 \
-e JWT_SECRET_KEY=my-secret-key \
-e BASIC_AUTH_USER=admin \
-e BASIC_AUTH_PASSWORD=changeme \
-e AUTH_REQUIRED=true \
-e DATABASE_URL=sqlite:///./mcp.db \
ghcr.io/ibm/mcp-context-forge:latest
로컬 개발
# 가상 환경을 만들고 종속성을 설치합니다.
make venv install serve
# 또는 수동으로 설치합니다.
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444
인증 토큰 생성
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)
API 사용 예시
프로토콜 초기화
curl -X POST -u admin:changeme \
-H "Content-Type: application/json" \
-d '{
"protocol_version":"2025-03-26",
"capabilities":{},
"client_info":{"name":"MyClient","version":"1.0.0"}
}' \
http://localhost:4444/protocol/initialize
도구 등록
curl -X POST -u admin:changeme \
-H "Content-Type: application/json" \
-d '{
"name":"clock_tool",
"url":"http://localhost:9000/rpc",
"description":"Returns current time",
"input_schema":{
"type":"object",
"properties":{"timezone":{"type":"string"}},
"required":[]
}
}' \
http://localhost:4444/tools
프롬프트 템플릿 생성
curl -X POST -u admin:changeme \
-H "Content-Type: application/json" \
-d '{
"name":"greet",
"template":"Hello, {{ user }}!",
"argument_schema":{
"type":"object",
"properties":{"user":{"type":"string"}},
"required":["user"]
}
}' \
http://localhost:4444/prompts
IBM Cloud Code Engine에 배포
이 프로젝트는 완전한 IBM Cloud Code Engine 배포를 지원합니다.
환경 구성
IBMCLOUD_REGION=us-south
IBMCLOUD_RESOURCE_GROUP=default
IBMCLOUD_PROJECT=my-codeengine-project
IBMCLOUD_CODE_ENGINE_APP=mcpgateway
IBMCLOUD_IMAGE_NAME=us.icr.io/myspace/mcpgateway:latest
IBMCLOUD_API_KEY=your_api_key_here
배포 명령
make ibmcloud-check-env # 환경 변수 확인
make ibmcloud-cli-install # IBM Cloud CLI 설치
make ibmcloud-login # IBM Cloud 로그인
make ibmcloud-ce-login # Code Engine 프로젝트 선택
make ibmcloud-tag # 컨테이너 이미지 태그 지정
make ibmcloud-push # IBM Container Registry에 푸시
make ibmcloud-deploy # Code Engine에 배포
프로젝트 구조
mcpgateway/
├── admin.py # FastAPI 라우트 및 관리 UI 컨트롤러
├── cache/
│ └── resource_cache.py # 리소스의 메모리 LRU+TTL 캐시
├── config.py # Pydantic 설정 로더
├── db.py # SQLAlchemy ORM 모델 및 데이터베이스 설정
├── federation/
│ ├── discovery.py # 피어 게이트웨이 검색
│ ├── forward.py # RPC 전달 로직
│ └── manager.py # 연합 조정 및 상태 확인
├── handlers/
│ └── sampling.py # MCP 스트리밍 샘플링 요청 처리기
├── services/
│ ├── completion_service.py # 프롬프트 및 리소스 매개변수 완료 로직
│ ├── gateway_service.py # 피어 게이트웨이 등록 및 관리
│ ├── prompt_service.py # 프롬프트 템플릿 CRUD 및 렌더링
│ ├── resource_service.py # 리소스 등록, 검색, 구독
│ ├── server_service.py # 서버 등록 및 상태 모니터링
│ └── tool_service.py # 도구 등록, 호출, 지표
├── transports/
│ ├── sse_transport.py # 서버 전송 이벤트 전송
│ ├── stdio_transport.py # stdio 전송
│ └── websocket_transport.py # WebSocket 전송
└── utils/
├── create_jwt_token.py # JWT 생성 및 검사 도구
└── verify_credentials.py # FastAPI 인증 종속성
개발 및 기여
개발 환경 설정
# 개발 종속성 설치
make install-dev
# 코드 검사 실행
make lint
# 테스트 실행
make test
# 커버리지 테스트 실행
make coverage
코드 품질 도구
이 프로젝트는 다양한 코드 품질 도구를 통합합니다.
- 포맷: black, isort, autoflake
- 정적 분석: mypy, pylint, pyright, pyre
- 보안 스캔: bandit, pip-audit
- 복잡도 분석: radon, wily
- 종속성 검사: fawltydeps, pip-licenses
요약
MCP Context Forge는 완전한 기능을 갖춘 프로덕션 준비 모델 컨텍스트 프로토콜 게이트웨이 솔루션으로, 특히 엔터프라이즈급 LLM 애플리케이션의 도구 통합 및 관리 요구 사항에 적합합니다. MCP 프로토콜의 완전한 기능을 구현했을 뿐만 아니라 연합 검색, 프로토콜 변환, 가상화 서비스 등과 같은 풍부한 확장 기능을 제공하여 복잡한 AI 애플리케이션 생태계를 구축하기 위한 이상적인 인프라 구성 요소입니다.