MCP 서버 개발 가이드
개요
고품질 MCP(Model Context Protocol) 서버를 만들어 LLM이 외부 서비스와 효과적으로 상호작용할 수 있도록 하려면 이 스킬을 사용하세요. MCP 서버는 LLM이 외부 서비스와 API에 접근할 수 있는 도구를 제공합니다. MCP 서버의 품질은 제공된 도구를 사용하여 LLM이 실제 작업을 얼마나 잘 수행할 수 있는지로 측정됩니다.
프로세스
🚀 상위 수준 워크플로우
고품질 MCP 서버를 만드는 과정은 네 가지 주요 단계로 구성됩니다:
1단계: 심층 조사 및 계획
1.1 에이전트 중심 설계 원칙 이해
구현에 들어가기 전에, 다음 원칙을 검토하여 AI 에이전트를 위한 도구 설계 방법을 이해하세요:
워크플로우를 위해 구축하라, 단순한 API 엔드포인트가 아닌:
- 기존 API 엔드포인트를 단순히 래핑하지 말고, 신중하고 영향력 있는 워크플로우 도구를 구축하세요.
- 관련 작업을 통합하세요(예:
schedule_event는 가용성 확인과 이벤트 생성을 모두 수행합니다). - 개별 API 호출이 아닌, 완전한 작업을 가능하게 하는 도구에 집중하세요.
- 에이전트가 실제로 완료해야 하는 워크플로우가 무엇인지 고려하세요.
제한된 컨텍스트에 최적화하라:
- 에이전트는 제한된 컨텍스트 창을 가지고 있습니다. 모든 토큰이 중요합니다.
- 포괄적인 데이터 덤프가 아닌, 고신호 정보를 반환하세요.
- '간결한' vs '상세한' 응답 형식 옵션을 제공하세요.
- 기술 코드(ID)보다 사람이 읽을 수 있는 식별자(이름)를 기본값으로 사용하세요.
- 에이전트의 컨텍스트 예산을 희소한 자원으로 고려하세요.
실행 가능한 오류 메시지를 설계하라:
- 오류 메시지는 에이전트를 올바른 사용 패턴으로 안내해야 합니다.
- 구체적인 다음 단계를 제안하세요: "결과를 줄이려면 'filter='active_only''를 사용해 보세요."
- 오류를 단순한 진단이 아닌 교육적으로 만드세요.
- 명확한 피드백을 통해 에이전트가 적절한 도구 사용법을 배우도록 도우세요.
자연스러운 작업 하위 분할을 따르라:
- 도구 이름은 사람이 작업에 대해 생각하는 방식을 반영해야 합니다.
- 검색 가능성을 위해 일관된 접두사를 사용하여 관련 도구를 그룹화하세요.
- API 구조가 아닌 자연스러운 워크플로우를 중심으로 도구를 설계하세요.
평가 기반 개발을 사용하라:
- 초기에 현실적인 평가 시나리오를 만드세요.
- 에이전트 피드백이 도구 개선을 주도하도록 하세요.
- 빠르게 프로토타입을 만들고 실제 에이전트 성능을 기반으로 반복하세요.
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
- 적절한 임포트 구성
- 모듈 수준 상수(CHARACTER_LIMIT, API_BASE_URL)
Node/TypeScript의 경우: ⚡ TypeScript 구현 가이드를 로드하고 다음을 확인하세요:
server.registerTool을 올바르게 사용.strict()를 사용한 Zod 스키마- TypeScript strict 모드 활성화
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 - 파일을 검토하여 임포트가 올바르게 작동하는지 확인
- 수동 테스트: 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개의 평가 질문 생성
효과적인 평가를 만들려면 평가 가이드에 설명된 프로세스를 따르세요:
- 도구 검사: 사용 가능한 도구를 나열하고 그 기능을 이해합니다.
- 콘텐츠 탐색: 읽기 전용 작업을 사용하여 사용 가능한 데이터를 탐색합니다.
- 질문 생성: 10개의 복잡하고 현실적인 질문을 만듭니다.
- 답변 확인: 각 질문을 직접 풀어서 답변을 확인합니다.
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을 사용한 도구 등록- 완전한 작동 예제
- 품질 체크리스트