모델 컨텍스트 프로토콜(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 설치 스크립트를 실행하면 설치 과정을 안내해 줍니다.

이 스크립트는 다음을 수행합니다.

1. Docker를 사용할 수 있는지 확인하세요

2. Docker Compose를 사용하여 MongoDB 시작(사용 가능한 경우)

3. .env 파일에서 연결을 구성하세요

4. MongoDB 연결 확인

옵션 2: 수동 Docker 설정

MongoDB를 시작하는 가장 쉬운 방법은 포함된 Docker Compose 구성을 사용하는 것입니다.

MongoDB는 mongodb://mcpuser:mcppassword@localhost:27017/mcp-server 에서 사용할 수 있습니다.
Mongo Express(웹 관리자)는 http://localhost:8081 에서 사용할 수 있습니다.

옵션 3: 로컬 MongoDB 설치

MongoDB를 로컬에 설치하려면 다음을 수행하세요.

1. https://www.mongodb.com/try/download/community 에서 MongoDB를 설치하세요

2. MongoDB 서비스 시작

3. 다음으로 .env 파일을 업데이트하세요.

   MONGODB_URI=mongodb://localhost:27017/mcp-server

옵션 4: MongoDB Atlas(클라우드)

프로덕션 용도로는 MongoDB Atlas를 권장합니다.

1. https://www.mongodb.com/cloud/atlas 에서 계정을 만드세요

2. 새 클러스터를 만듭니다

3. 데이터베이스 사용자를 설정하고 IP 주소를 허용 목록에 추가하세요

4. 연결 문자열을 가져와서 .env 파일을 업데이트하세요.

   MONGODB_URI=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/mcp-server?retryWrites=true&w=majority

데이터베이스 마이그레이션

기존 데이터를 MongoDB로 마이그레이션하려면:

이 스크립트는 다음을 수행합니다.

1. 도구 정의를 MongoDB로 마이그레이션

2. 구성(API 키 등)을 MongoDB로 마이그레이션

3. 사용 가능한 경우 백업 데이터를 가져옵니다.

용법

서버를 시작합니다

서버는 http://localhost:3000 (또는 .env에서 지정한 포트)에서 실행됩니다.

시작 옵션

1. 표준 시작 ( npm start ):

   • API 키가 구성되었는지 확인합니다.

   • 키가 발견되지 않으면 설정을 요청합니다.

   • 처음 사용하는 사용자에게 권장

2. 개발 모드 ( npm run dev ):

   • 코드 변경 시 자동 재로드를 위해 nodemon을 사용합니다.

   • 여전히 환경 검사를 수행합니다.

   • 개발에 가장 적합

3. 빠른 시작 ( npm run quick-start ):

   • 모든 환경 검사를 우회합니다

   • 서버를 즉시 시작합니다

   • 구성이 올바른지 알고 있을 때 유용합니다.

4. PM2 프로덕션 모드 ( npm run pm2:start:prod ):

   • PM2 프로세스 관리자를 사용하여 서버를 실행합니다.

   • 서버가 충돌하면 자동으로 다시 시작됩니다.

   • 프로덕션 환경에 최적화됨

   • 환경 검사를 우회합니다

PM2 프로세스 관리자 사용

이 서버는 Node.js 애플리케이션용 프로덕션 프로세스 관리자인 PM2와 함께 실행될 수 있습니다. PM2는 다음과 같은 기능을 제공합니다.

• 프로세스 관리(충돌 시 재시작)

• 로그 관리

• 성능 모니터링

• 부하 분산(여러 인스턴스에 대해)

PM2 명령

PM2 구성은 ecosystem.config.js 에 저장되어 있습니다. 이 파일을 수정하여 다음을 변경할 수 있습니다.

• 프로세스 이름

• 환경 변수

• 메모리 제한

• 배포 구성

• 인스턴스 수(로드 밸런싱용)

API 엔드포인트

POST /mcp/:provider

통합 API를 통해 AI 모델에 요청을 보냅니다.

URL 매개변수:

• provider : 사용할 AI 제공자( anthropic 또는 openai )

요청 본문:

또는 (레거시 형식):

응답: 제공자의 API에서 원시 응답을 반환합니다.

GET /tools/available

자세한 정보와 함께 사용 가능한 모든 도구의 포괄적인 목록을 받아보세요.

쿼리 매개변수:

• format - 응답 형식: json (기본값), yaml , table 또는 html

• category - 카테고리별 필터 도구(선택 사항)

• enabled - 활성화 상태별 필터링: true (기본값) 또는 false

• search - 이름, 설명 또는 태그로 도구 검색

• provider - 제공자별 필터 도구(예: openai , google )

• limit - 반환할 도구의 최대 개수(페이지 매김용)

• offset - 페이지 매김을 위한 오프셋(기본값: 0)

응답(JSON 형식):

GET /health

서버가 실행 중인 경우 상태 200을 반환하는 상태 검사 엔드포인트입니다.

데이터 관리

데이터베이스 백업

데이터베이스 백업을 생성하고 관리할 수 있습니다.

데이터베이스 연결 테스트

MongoDB 설정을 확인하려면:

예시 클라이언트

명령줄 클라이언트

테스트 클라이언트는 src/client.js 에 포함되어 있습니다. 실행하려면 다음을 실행하세요.

웹 클라이언트

서버가 실행 중일 때 http://localhost:3000 에서 간단한 웹 인터페이스를 이용할 수 있습니다. 이를 통해 브라우저에서 직접 API를 테스트할 수 있습니다.

사용 가능한 도구

MCP 서버는 사용자와 AI 에이전트가 사용 가능한 모든 도구를 프로그래밍 방식으로 나열할 수 있는 도구 검색 엔드포인트를 제공합니다.

도구 검색

GET /tools/available - 자세한 정보와 함께 사용 가능한 모든 도구를 나열합니다.

• JSON, YAML, HTML, ASCII 테이블 등 다양한 형식을 지원합니다.

• 카테고리, 제공자 및 검색어별 필터링 제공

• 각 도구에 대한 자세한 메타데이터와 사용 예가 포함되어 있습니다.

사용 예:

웹 검색 도구

서버에는 웹 검색 및 검색 도구가 내장되어 있습니다.

1. 웹 검색 ( /tools/web/search )

   • 주어진 쿼리에 대한 정보를 웹에서 검색합니다.

   • 매개변수: query (필수), limit (선택 사항)

   • 필요 사항: GOOGLE_CSE_API_KEY 및 GOOGLE_CSE_ID 환경 변수

   • Google 검색에 실패하면 BING_SEARCH_API_KEY 로 돌아갑니다.

2. 웹 콘텐츠 ( /tools/web/content )

   • 특정 URL에서 콘텐츠 검색 및 추출

   • 매개변수: url (필수), useCache (선택 사항)

3. 웹 배치 ( /tools/web/batch )

   • 여러 URL에서 병렬로 콘텐츠 검색

   • 매개변수: urls (필수 배열), useCache (선택 사항)

이미지 생성 도구

서버에는 이미지 생성, 편집 및 변형 도구도 포함되어 있습니다.

1. 이미지 생성 ( /tools/image/generate )

   • 텍스트 프롬프트를 기반으로 이미지 생성

   • 매개변수:

     • prompt (필수): 이미지에 대한 자세한 설명

     • provider (선택 사항): openai 또는 stability (기본값은 openai )

     • options (선택 사항): 공급자별 옵션

2. 이미지 편집 ( /tools/image/edit )

   • 텍스트 프롬프트로 기존 이미지 편집

   • 매개변수:

     • imagePath (필수): 편집할 이미지의 경로

     • prompt (필수): 편집할 내용에 대한 설명

     • maskPath (선택 사항): 마스크 이미지 경로

3. 이미지 변형 만들기 ( /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 모델에서 도구 호출 및 실행을 자동으로 처리합니다. 모델이 도구를 사용하기로 결정하면 서버는 다음을 수행합니다.

1. 제공된 매개변수로 요청된 도구를 실행합니다.

2. 모델에 대한 도구의 응답을 반환합니다.

3. 그러면 모델은 도구의 응답을 최종 답변에 통합할 수 있습니다.

AI 모델을 위한 도구 검색

AI 모델은 /tools/available 엔드포인트를 사용하여 사용 가능한 도구와 사용 방법을 파악할 수 있습니다. 이는 특히 다음과 같은 경우에 유용합니다.

• 런타임 중 동적 도구 검색

• AI 에이전트를 위한 자체 문서화

• AI 시스템이 사용 가능한 기능에 적응할 수 있도록 지원

AI 모델을 위한 시스템 프롬프트 예시:

도구 사용 예시

도구 사용법을 보여주는 샘플 코드는 /examples 디렉토리를 참조하세요.

새로운 공급자 또는 도구 추가

새로운 AI 공급자 추가

새로운 AI 공급자를 추가하려면:

1. 프로젝트에 공급자의 SDK를 추가합니다.

2. server.js 에 새로운 핸들러 함수를 만듭니다.

3. 메인 경로 핸들러에 새로운 케이스를 추가합니다.

새로운 도구 추가

서버에 새로운 도구를 추가하려면:

1. /src/tools 디렉토리에 새로운 도구 구현을 만듭니다.

2. tool-definitions.js 에 도구 정의를 추가합니다.

3. server.js 에서 도구 실행 기능을 업데이트합니다.

4. 필요한 경우 직접 도구 사용을 위한 새로운 API 엔드포인트 추가

특허

아이에스씨