모델 컨텍스트 프로토콜(MCP) 서버
여러 AI 모델 공급자를 위한 통합 API를 제공하는 모델 컨텍스트 프로토콜을 위한 간단한 서버 구현입니다.
특징
- 여러 AI 공급자(Anthropic, OpenAI)를 위한 통합 API
- 채팅 완성 및 레거시 완성 지원
- 도구 호출 지원
- 컨텍스트/시스템 메시지 처리
- 환경 기반 구성
- 지속성 및 상태 관리를 위한 MongoDB 데이터베이스
- 도구 실행 기록 및 분석
설치
지엑스피1
설정 스크립트는 필요한 API 키를 구성하는 방법을 안내합니다.
ANTHROPIC_API_KEY - Claude 모델용OPENAI_API_KEY - GPT 모델 및 DALL-E 이미지 생성용STABILITY_API_KEY - 안정적인 확산 이미지 생성을 위해GOOGLE_CSE_API_KEY 및 GOOGLE_CSE_ID - 웹 검색 기능용BING_SEARCH_API_KEY - 대체 웹 검색용
원하는 경우 .env 파일을 수동으로 편집할 수도 있습니다.
몽고DB 설정
MCP 서버는 데이터 지속성을 위해 MongoDB를 사용합니다. MongoDB를 설정하는 데는 여러 가지 옵션이 있습니다.
옵션 1: 자동 설정(권장)
MongoDB 설치 스크립트를 실행하면 설치 과정을 안내해 줍니다.
# Run the MongoDB setup script
npm run setup-mongodb
이 스크립트는 다음을 수행합니다.
- Docker를 사용할 수 있는지 확인하세요
- Docker Compose를 사용하여 MongoDB 시작(사용 가능한 경우)
- .env 파일에서 연결을 구성하세요
- MongoDB 연결 확인
옵션 2: 수동 Docker 설정
MongoDB를 시작하는 가장 쉬운 방법은 포함된 Docker Compose 구성을 사용하는 것입니다.
# Start MongoDB and Mongo Express in Docker
docker compose up -d
# Update your .env file with the connection string
echo "MONGODB_URI=mongodb://mcpuser:mcppassword@localhost:27017/mcp-server" >> .env
MongoDB는 mongodb://mcpuser:mcppassword@localhost:27017/mcp-server 에서 사용할 수 있습니다.
Mongo Express(웹 관리자)는 http://localhost:8081 에서 사용할 수 있습니다.
옵션 3: 로컬 MongoDB 설치
MongoDB를 로컬에 설치하려면 다음을 수행하세요.
- https://www.mongodb.com/try/download/community 에서 MongoDB를 설치하세요
- MongoDB 서비스 시작
- 다음으로
.env 파일을 업데이트하세요.MONGODB_URI=mongodb://localhost:27017/mcp-server
옵션 4: MongoDB Atlas(클라우드)
프로덕션 용도로는 MongoDB Atlas를 권장합니다.
- https://www.mongodb.com/cloud/atlas 에서 계정을 만드세요
- 새 클러스터를 만듭니다
- 데이터베이스 사용자를 설정하고 IP 주소를 허용 목록에 추가하세요
- 연결 문자열을 가져와서
.env 파일을 업데이트하세요.MONGODB_URI=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/mcp-server?retryWrites=true&w=majority
데이터베이스 마이그레이션
기존 데이터를 MongoDB로 마이그레이션하려면:
# Run the migration script
npm run migrate-mongodb
이 스크립트는 다음을 수행합니다.
- 도구 정의를 MongoDB로 마이그레이션
- 구성(API 키 등)을 MongoDB로 마이그레이션
- 사용 가능한 경우 백업 데이터를 가져옵니다.
용법
서버를 시작합니다
# Interactive startup (checks for API keys)
npm start
# Development mode with auto-reload
npm run dev
# Quick start (skips environment checks)
npm run quick-start
# Start server with PM2 process manager
npm run pm2:start
# Start server with PM2 in production mode
npm run pm2:start:prod
서버는 http://localhost:3000 (또는 .env에서 지정한 포트)에서 실행됩니다.
시작 옵션
- 표준 시작 (
npm start ):- API 키가 구성되었는지 확인합니다.
- 키가 발견되지 않으면 설정을 요청합니다.
- 처음 사용하는 사용자에게 권장
- 개발 모드 (
npm run dev ):- 코드 변경 시 자동 재로드를 위해 nodemon을 사용합니다.
- 여전히 환경 검사를 수행합니다.
- 개발에 가장 적합
- 빠른 시작 (
npm run quick-start ):- 모든 환경 검사를 우회합니다
- 서버를 즉시 시작합니다
- 구성이 올바른지 알고 있을 때 유용합니다.
- PM2 프로덕션 모드 (
npm run pm2:start:prod ):- PM2 프로세스 관리자를 사용하여 서버를 실행합니다.
- 서버가 충돌하면 자동으로 다시 시작됩니다.
- 프로덕션 환경에 최적화됨
- 환경 검사를 우회합니다
PM2 프로세스 관리자 사용
이 서버는 Node.js 애플리케이션용 프로덕션 프로세스 관리자인 PM2와 함께 실행될 수 있습니다. PM2는 다음과 같은 기능을 제공합니다.
- 프로세스 관리(충돌 시 재시작)
- 로그 관리
- 성능 모니터링
- 부하 분산(여러 인스턴스에 대해)
PM2 명령
# Start the server with PM2
npm run pm2:start
# Start in production mode
npm run pm2:start:prod
# View logs
npm run pm2:logs
# Monitor performance
npm run pm2:monit
# Restart the server
npm run pm2:restart
# Stop the server
npm run pm2:stop
# Remove the server from PM2
npm run pm2:delete
PM2 구성은 ecosystem.config.js 에 저장되어 있습니다. 이 파일을 수정하여 다음을 변경할 수 있습니다.
- 프로세스 이름
- 환경 변수
- 메모리 제한
- 배포 구성
- 인스턴스 수(로드 밸런싱용)
API 엔드포인트
POST /mcp/:provider
통합 API를 통해 AI 모델에 요청을 보냅니다.
URL 매개변수:
provider : 사용할 AI 제공자( anthropic 또는 openai )
요청 본문:
{
"messages": [
{ "role": "user", "content": "Your prompt here" }
],
"model": "claude-3-opus-20240229", // Optional, provider-specific model name
"tools": [...], // Optional, tools for function calling
"context": "System message or context" // Optional
}
또는 (레거시 형식):
{
"prompt": "Your prompt here",
"model": "claude-3-opus-20240229", // Optional
"context": "System message or context" // Optional
}
응답: 제공자의 API에서 원시 응답을 반환합니다.
자세한 정보와 함께 사용 가능한 모든 도구의 포괄적인 목록을 받아보세요.
쿼리 매개변수:
format - 응답 형식: json (기본값), yaml , table 또는 htmlcategory - 카테고리별 필터 도구(선택 사항)enabled - 활성화 상태별 필터링: true (기본값) 또는 falsesearch - 이름, 설명 또는 태그로 도구 검색provider - 제공자별 필터 도구(예: openai , google )limit - 반환할 도구의 최대 개수(페이지 매김용)offset - 페이지 매김을 위한 오프셋(기본값: 0)
응답(JSON 형식):
{
"success": true,
"count": 10,
"metadata": {
"categories": ["web", "image", "utility"],
"providers": ["openai", "anthropic", "internal"],
"totalCount": 24,
"offset": 0,
"limit": 10
},
"tools": [
{
"name": "web_search",
"description": "Search the web for information",
"category": "web",
"version": "1.0.0",
"provider": "google",
"enabled": true,
"parameters": {
"query": {
"type": "string",
"description": "The search query",
"required": true
},
"limit": {
"type": "number",
"description": "Maximum number of results",
"required": false,
"default": 5
}
},
"usage": {
"endpoint": "/tools/web/search",
"method": "POST",
"parameters": { /* same as above */ }
},
"metadata": {
"createdAt": "2023-10-15T12:00:00Z",
"updatedAt": "2024-04-20T09:30:00Z",
"usageCount": 1245
}
}
// ... more tools
]
}
GET /health
서버가 실행 중인 경우 상태 200을 반환하는 상태 검사 엔드포인트입니다.
데이터 관리
데이터베이스 백업
데이터베이스 백업을 생성하고 관리할 수 있습니다.
# Create a full backup
npm run backup-mongodb
# Create a backup with execution history
npm run backup-mongodb -- --with-executions
# List existing backups
npm run backup-mongodb -- --list
데이터베이스 연결 테스트
MongoDB 설정을 확인하려면:
# Run the database test script
npm run test-mongodb
예시 클라이언트
명령줄 클라이언트
테스트 클라이언트는 src/client.js 에 포함되어 있습니다. 실행하려면 다음을 실행하세요.
웹 클라이언트
서버가 실행 중일 때 http://localhost:3000 에서 간단한 웹 인터페이스를 이용할 수 있습니다. 이를 통해 브라우저에서 직접 API를 테스트할 수 있습니다.
사용 가능한 도구
MCP 서버는 사용자와 AI 에이전트가 사용 가능한 모든 도구를 프로그래밍 방식으로 나열할 수 있는 도구 검색 엔드포인트를 제공합니다.
도구 검색
GET /tools/available - 자세한 정보와 함께 사용 가능한 모든 도구를 나열합니다.
- JSON, YAML, HTML, ASCII 테이블 등 다양한 형식을 지원합니다.
- 카테고리, 제공자 및 검색어별 필터링 제공
- 각 도구에 대한 자세한 메타데이터와 사용 예가 포함되어 있습니다.
사용 예:
# Get all tools in JSON format
curl http://localhost:3000/tools/available
# Get tools in a specific category
curl http://localhost:3000/tools/available?category=web
# Search for image-related tools
curl http://localhost:3000/tools/available?search=image
# Get a formatted HTML page of all tools
curl http://localhost:3000/tools/available?format=html > tools.html
웹 검색 도구
서버에는 웹 검색 및 검색 도구가 내장되어 있습니다.
- 웹 검색 (
/tools/web/search )- 주어진 쿼리에 대한 정보를 웹에서 검색합니다.
- 매개변수:
query (필수), limit (선택 사항) - 필요 사항:
GOOGLE_CSE_API_KEY 및 GOOGLE_CSE_ID 환경 변수 - Google 검색에 실패하면
BING_SEARCH_API_KEY 로 돌아갑니다.
- 웹 콘텐츠 (
/tools/web/content )- 특정 URL에서 콘텐츠 검색 및 추출
- 매개변수:
url (필수), useCache (선택 사항)
- 웹 배치 (
/tools/web/batch )- 여러 URL에서 병렬로 콘텐츠 검색
- 매개변수:
urls (필수 배열), useCache (선택 사항)
이미지 생성 도구
서버에는 이미지 생성, 편집 및 변형 도구도 포함되어 있습니다.
- 이미지 생성 (
/tools/image/generate )- 텍스트 프롬프트를 기반으로 이미지 생성
- 매개변수:
prompt (필수): 이미지에 대한 자세한 설명provider (선택 사항): openai 또는 stability (기본값은 openai )options (선택 사항): 공급자별 옵션
- 이미지 편집 (
/tools/image/edit )- 텍스트 프롬프트로 기존 이미지 편집
- 매개변수:
imagePath (필수): 편집할 이미지의 경로prompt (필수): 편집할 내용에 대한 설명maskPath (선택 사항): 마스크 이미지 경로
- 이미지 변형 만들기 (
/tools/image/variation )- 기존 이미지의 변형을 만듭니다
- 매개변수:
imagePath (필수): 변형을 생성할 이미지 경로
참고: 이러한 도구를 사용하려면 .env 파일에 API 키를 설정해야 합니다.
- OpenAI 이미지의 경우:
OPENAI_API_KEY - Stability AI 이미지의 경우:
STABILITY_API_KEY - 웹 검색의 경우:
GOOGLE_CSE_API_KEY 및 GOOGLE_CSE_ID
AI 모델과 도구 통합
MCP 서버는 AI 모델에서 도구 호출 및 실행을 자동으로 처리합니다. 모델이 도구를 사용하기로 결정하면 서버는 다음을 수행합니다.
- 제공된 매개변수로 요청된 도구를 실행합니다.
- 모델에 대한 도구의 응답을 반환합니다.
- 그러면 모델은 도구의 응답을 최종 답변에 통합할 수 있습니다.
AI 모델을 위한 도구 검색
AI 모델은 /tools/available 엔드포인트를 사용하여 사용 가능한 도구와 사용 방법을 파악할 수 있습니다. 이는 특히 다음과 같은 경우에 유용합니다.
- 런타임 중 동적 도구 검색
- AI 에이전트를 위한 자체 문서화
- AI 시스템이 사용 가능한 기능에 적응할 수 있도록 지원
AI 모델을 위한 시스템 프롬프트 예시:
You have access to external tools through the MCP server.
Before using any tools, you should check what tools are available by calling:
GET /tools/available
This will return a list of all available tools with their parameters and usage instructions.
You can then use these tools by following the provided usage patterns.
도구 사용 예시
도구 사용법을 보여주는 샘플 코드는 /examples 디렉토리를 참조하세요.
새로운 공급자 또는 도구 추가
새로운 AI 공급자 추가
새로운 AI 공급자를 추가하려면:
- 프로젝트에 공급자의 SDK를 추가합니다.
server.js 에 새로운 핸들러 함수를 만듭니다.- 메인 경로 핸들러에 새로운 케이스를 추가합니다.
새로운 도구 추가
서버에 새로운 도구를 추가하려면:
/src/tools 디렉토리에 새로운 도구 구현을 만듭니다.tool-definitions.js 에 도구 정의를 추가합니다.server.js 에서 도구 실행 기능을 업데이트합니다.- 필요한 경우 직접 도구 사용을 위한 새로운 API 엔드포인트 추가
특허
아이에스씨