ComposioHQ/mcp-builder

MCP 서버 개발 가이드

개요

고품질 MCP(Model Context Protocol) 서버를 만들어 LLM이 외부 서비스와 효과적으로 상호작용할 수 있도록 하려면 이 스킬을 사용하세요. MCP 서버는 LLM이 외부 서비스와 API에 액세스할 수 있는 도구를 제공합니다. MCP 서버의 품질은 제공된 도구를 사용하여 LLM이 실제 작업을 얼마나 잘 수행할 수 있는지로 측정됩니다.

---

프로세스

🚀 상위 수준 워크플로우

고품질 MCP 서버를 만드는 과정은 네 가지 주요 단계로 구성됩니다.

1단계: 심층 연구 및 계획

1.1 에이전트 중심 설계 원칙 이해

구현에 들어가기 전에, 다음 원칙을 검토하여 AI 에이전트를 위한 도구 설계 방법을 이해하세요.

워크플로우를 위한 구축, 단순한 API 엔드포인트가 아닌:

• 기존 API 엔드포인트를 단순히 래핑하지 말고, 사려 깊고 영향력 있는 워크플로우 도구를 구축하세요.
• 관련 작업을 통합하세요(예: schedule_event는 가용성을 확인하고 이벤트를 생성).
• 에이전트가 실제로 완료해야 하는 워크플로우에 초점을 맞추세요.

제한된 컨텍스트에 최적화:

• 에이전트는 제한된 컨텍스트 창을 가지고 있습니다. 모든 토큰이 중요합니다.
• 정보를 과도하게 제공하지 말고, 핵심 정보를 반환하세요.
• "간결" 및 "상세" 응답 형식 옵션을 제공하세요.
• 기술 코드(ID)보다는 사람이 읽을 수 있는 식별자(이름)를 기본값으로 사용하세요.

실행 가능한 오류 메시지 설계:

• 오류 메시지는 에이전트를 올바른 사용 패턴으로 안내해야 합니다.
• 구체적인 다음 단계를 제안하세요: "결과를 줄이려면 filter='active_only'를 사용해보세요."
• 오류는 진단적일 뿐만 아니라 교육적이어야 합니다.

자연스러운 작업 세분화 따르기:

• 도구 이름은 사용자가 작업에 대해 생각하는 방식을 반영해야 합니다.
• 검색 가능성을 높이기 위해 일관된 접두사로 관련 도구를 그룹화하세요.

평가 기반 개발 사용:

• 초기 단계에서 현실적인 평가 시나리오를 만드세요.
• 에이전트의 피드백을 통해 도구를 개선하세요.

1.3 MCP 프로토콜 문서 학습

최신 MCP 프로토콜 문서를 가져오세요:

WebFetch를 사용하여 로드: https://modelcontextprotocol.io/llms-full.txt

이 포괄적인 문서에는 완전한 MCP 사양 및 지침이 포함되어 있습니다.

1.4 프레임워크 문서 학습

다음 참조 파일을 로드하여 읽으세요:

• MCP 모범 사례: 📋 모범 사례 보기 - 모든 MCP 서버를 위한 핵심 지침

Python 구현의 경우 다음도 로드하세요:

• Python SDK 문서: WebFetch를 사용하여 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md 로드
• 🐍 Python 구현 가이드 - Python 관련 모범 사례 및 예제

Node/TypeScript 구현의 경우 다음도 로드하세요:

• TypeScript SDK 문서: WebFetch를 사용하여 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md 로드
• ⚡ TypeScript 구현 가이드 - Node/TypeScript 관련 모범 사례 및 예제

1.5 API 문서 철저히 연구

서비스를 통합하려면 사용 가능한 모든 API 문서를 읽으세요.

• 공식 API 참조 문서
• 인증 및 권한 부여 요구 사항
• 속도 제한 및 페이지 매김 패턴
• 오류 응답 및 상태 코드
• 사용 가능한 엔드포인트 및 매개변수
• 데이터 모델 및 스키마

포괄적인 정보를 수집하려면 필요에 따라 웹 검색 및 WebFetch 도구를 사용하세요.

1.6 포괄적인 구현 계획 수립

연구를 바탕으로 다음을 포함하는 세부 계획을 수립하세요.

도구 선택:

• 구현할 가장 가치 있는 엔드포인트/작업 목록
• 가장 일반적이고 중요한 사용 사례를 가능하게 하는 도구 우선 순위 지정
• 복잡한 워크플로우를 가능하게 하기 위해 함께 작동하는 도구 고려

공유 유틸리티 및 헬퍼:

• 공통 API 요청 패턴 식별
• 페이지 매김 헬퍼 계획
• 필터링 및 형식 지정 유틸리티 설계
• 오류 처리 전략 계획

입력/출력 설계:

• 입력 유효성 검사 모델 정의(Python의 경우 Pydantic, TypeScript의 경우 Zod)
• 일관된 응답 형식(예: JSON 또는 Markdown) 및 구성 가능한 세부 수준(예: 상세 또는 간결) 설계
• 대규모 사용(수천 명의 사용자/리소스) 계획
• 문자 제한 및 잘림 전략 구현(예: 25,000토큰)

오류 처리 전략:

• 정상적인 실패 모드 계획
• 명확하고, 실행 가능하며, LLM에 친화적이고, 추가 조치를 유도하는 자연어 오류 메시지 설계
• 속도 제한 및 시간 초과 시나리오 고려
• 인증 및 권한 부여 오류 처리

---

2단계: 구현

이제 포괄적인 계획이 있으므로 언어별 모범 사례에 따라 구현을 시작하세요.

2.1 프로젝트 구조 설정

Python의 경우:

• 단일 .py 파일 생성 또는 복잡한 경우 모듈로 구성(🐍 Python 가이드 참조)
• MCP Python SDK를 사용하여 도구 등록
• 입력 유효성 검사를 위해 Pydantic 모델 정의

Node/TypeScript의 경우:

• 적절한 프로젝트 구조 생성(⚡ TypeScript 가이드 참조)
• package.json 및 tsconfig.json 설정
• MCP TypeScript SDK 사용
• 입력 유효성 검사를 위해 Zod 스키마 정의

2.2 핵심 인프라를 먼저 구현

구현을 시작하려면 도구를 구현하기 전에 공유 유틸리티를 만드세요.

• API 요청 헬퍼 함수
• 오류 처리 유틸리티
• 응답 형식 지정 함수(JSON 및 Markdown)
• 페이지 매김 헬퍼
• 인증/토큰 관리

2.3 도구를 체계적으로 구현

계획의 각 도구에 대해:

입력 스키마 정의:

• 유효성 검사를 위해 Pydantic(Python) 또는 Zod(TypeScript) 사용
• 적절한 제약 조건 포함(최소/최대 길이, 정규식 패턴, 최소/최대 값, 범위)
• 명확하고 설명적인 필드 설명 제공
• 필드 설명에 다양한 예제 포함

포괄적인 독스트링/설명 작성:

• 도구가 수행하는 작업에 대한 한 줄 요약
• 목적과 기능에 대한 자세한 설명
• 예제가 포함된 명시적 매개변수 유형
• 완전한 반환 유형 스키마
• 사용 예제(사용 시기, 사용하지 않아야 할 시기)
• 특정 오류가 발생했을 때 진행 방법을 설명하는 오류 처리 문서

도구 로직 구현:

• 코드 중복을 피하기 위해 공유 유틸리티 사용
• 모든 I/O에 대해 async/await 패턴 따르기
• 적절한 오류 처리 구현
• 여러 응답 형식(JSON 및 Markdown) 지원
• 페이지 매김 매개변수 준수
• 문자 제한 확인 및 적절히 잘림

도구 주석 추가:

• readOnlyHint: true(읽기 전용 작업의 경우)
• destructiveHint: false(비파괴 작업의 경우)
• idempotentHint: true(반복 호출이 동일한 효과를 갖는 경우)
• openWorldHint: true(외부 시스템과 상호작용하는 경우)

2.4 언어별 모범 사례 따르기

이 시점에서 적절한 언어 가이드를 로드하세요.

Python의 경우: 🐍 Python 구현 가이드를 로드하고 다음을 확인하세요.

• 적절한 도구 등록과 함께 MCP Python SDK 사용
• model_config가 포함된 Pydantic v2 모델
• 모든 곳에 타입 힌트 사용
• 모든 I/O 작업에 async/await 사용
• 적절한 imports 구성
• 모듈 수준 상수(CHARACTER_LIMIT, API_BASE_URL)

Node/TypeScript의 경우: ⚡ TypeScript 구현 가이드를 로드하고 다음을 확인하세요.

• server.registerTool을 올바르게 사용
• .strict()가 포함된 Zod 스키마
• TypeScript 엄격 모드 활성화
• any 타입 없음 - 적절한 타입 사용
• 명시적인 Promise 반환 타입
• 빌드 프로세스 구성(npm run build)

---

3단계: 검토 및 개선

초기 구현 후:

3.1 코드 품질 검토

품질을 보장하려면 다음 사항을 확인하세요.

• DRY 원칙: 도구 간 중복 코드 없음
• 구성 가능성: 공유 로직이 함수로 추출됨
• 일관성: 유사한 작업이 유사한 형식을 반환
• 오류 처리: 모든 외부 호출에 오류 처리 포함
• 타입 안전성: 완전한 타입 커버리지(Python 타입 힌트, TypeScript 타입)
• 문서화: 모든 도구에 포괄적인 독스트링/설명 포함

3.2 테스트 및 빌드

중요: MCP 서버는 stdio/stdin 또는 sse/http를 통해 요청을 기다리는 장기 실행 프로세스입니다. 메인 프로세스에서 직접 실행하면(예: python server.py 또는 node dist/index.js) 프로세스가 무기한 중단됩니다.

서버를 안전하게 테스트하는 방법:

• 평가 도구 사용(4단계 참조) - 권장 접근 방식
• tmux에서 서버를 실행하여 메인 프로세스 외부 유지
• 테스트 시 시간 제한 사용: timeout 5s python server.py

Python의 경우:

• Python 구문 확인: python -m py_compile your_server.py
• 파일을 검토하여 imports가 올바르게 작동하는지 확인
• 수동 테스트: tmux에서 서버 실행 후 메인 프로세스에서 평가 도구로 테스트
• 또는 평가 도구를 직접 사용(stdio 전송을 위해 서버 관리)

Node/TypeScript의 경우:

• npm run build 실행 후 오류 없이 완료되는지 확인
• dist/index.js가 생성되었는지 확인
• 수동 테스트: tmux에서 서버 실행 후 메인 프로세스에서 평가 도구로 테스트
• 또는 평가 도구를 직접 사용(stdio 전송을 위해 서버 관리)

3.3 품질 체크리스트 사용

구현 품질을 확인하려면 언어별 가이드에서 적절한 체크리스트를 로드하세요.

• Python: 🐍 Python 가이드의 "품질 체크리스트" 참조
• Node/TypeScript: ⚡ TypeScript 가이드의 "품질 체크리스트" 참조

---

4단계: 평가 만들기

MCP 서버를 구현한 후에는 포괄적인 평가를 만들어 효과를 테스트하세요.

전체 평가 지침은 ✅ 평가 가이드를 로드하세요.

4.1 평가 목적 이해

평가는 LLM이 MCP 서버를 사용하여 현실적이고 복잡한 질문에 효과적으로 답변할 수 있는지 테스트합니다.

4.2 10개의 평가 질문 만들기

효과적인 평가를 만들려면 평가 가이드에 설명된 프로세스를 따르세요.

1. 도구 검사: 사용 가능한 도구를 나열하고 기능 이해
2. 콘텐츠 탐색: 읽기 전용 작업을 사용하여 사용 가능한 데이터 탐색
3. 질문 생성: 10개의 복잡하고 현실적인 질문 생성
4. 답변 확인: 각 질문을 직접 해결하여 답변 확인

4.3 평가 요구 사항

각 질문은 다음 조건을 충족해야 합니다.

• 독립적: 다른 질문에 의존하지 않음
• 읽기 전용: 비파괴 작업만 필요
• 복잡: 여러 도구 호출 및 심층 탐색 필요
• 현실적: 사람들이 관심을 가질 실제 사용 사례 기반
• 검증 가능: 문자열 비교로 검증할 수 있는 단일하고 명확한 답변
• 안정적: 시간이 지나도 답변이 변경되지 않음

4.4 출력 형식

다음 구조로 XML 파일을 만드세요.

<evaluation>
  <qa_pair>
    <question>동물 코드명을 가진 AI 모델 출시에 대한 토론을 찾으세요. 한 모델은 ASL-X 형식을 사용하는 특정 안전 지정이 필요했습니다. 점박이 야생 고양이의 이름을 딴 모델에 대해 결정된 숫자 X는 무엇입니까?</question>
    <answer>3</answer>
  </qa_pair>
<!-- 추가 qa_pair... -->
</evaluation>

---

참조 파일

📚 문서 라이브러리

개발 중 필요에 따라 다음 리소스를 로드하세요.

핵심 MCP 문서(먼저 로드)

• MCP 프로토콜: https://modelcontextprotocol.io/llms-full.txt에서 가져오기 - 전체 MCP 사양
• 📋 MCP 모범 사례 - 보편적인 MCP 지침 포함:
  • 서버 및 도구 명명 규칙
  • 응답 형식 지침(JSON 대 Markdown)
  • 페이지 매김 모범 사례
  • 문자 제한 및 잘림 전략
  • 도구 개발 지침
  • 보안 및 오류 처리 표준

SDK 문서(1/2단계에서 로드)

• Python SDK: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md에서 가져오기
• TypeScript SDK: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md에서 가져오기

언어별 구현 가이드(2단계에서 로드)

• 🐍 Python 구현 가이드 - 완전한 Python/FastMCP 가이드 포함:

  • 서버 초기화 패턴
  • Pydantic 모델 예제
  • @mcp.tool을 사용한 도구 등록
  • 완전한 작동 예제
  • 품질 체크리스트

• ⚡ TypeScript 구현 가이드 - 완전한 TypeScript 가이드 포함:

  • 프로젝트 구조
  • Zod 스키마 패턴
  • server.registerTool을 사용한 도구 등록
  • 완전한 작동 예제
  • 품질 체크리스트

평가 가이드(4단계에서 로드)

• ✅ 평가 가이드 - 완전한 평가 생성 가이드 포함:
  • 질문 생성 지침
  • 답변 확인 전략
  • XML 형식 사양
  • 예제 질문 및 답변
  • 제공된 스크립트로 평가 실행