MCP 서버 개발 가이드
개요
LLM이 외부 서비스와 상호작용할 수 있도록 설계된 잘 만들어진 도구를 제공하는 MCP(Model Context Protocol) 서버를 생성합니다. MCP 서버의 품질은 LLM이 실제 작업을 얼마나 잘 수행할 수 있게 하는지로 측정됩니다.
프로세스
🚀 상위 수준 워크플로우
고품질 MCP 서버를 만들기 위한 네 가지 주요 단계:
1단계: 심층 조사 및 계획
1.1 현대 MCP 디자인 이해
API 커버리지 vs. 워크플로 도구: 포괄적인 API 엔드포인트 커버리지와 특수 워크플로 도구 간의 균형을 유지하세요. 워크플로 도구는 특정 작업에 더 편리할 수 있지만, 포괄적인 커버리지는 에이전트에게 작업을 조합할 수 있는 유연성을 제공합니다. 성능은 클라이언트에 따라 다릅니다. 일부 클라이언트는 기본 도구를 결합하는 코드 실행의 이점을 보는 반면, 다른 클라이언트는 더 높은 수준의 워크플로와 더 잘 작동합니다. 확실하지 않은 경우 포괄적인 API 커버리지를 우선시하세요.
도구 이름 지정 및 검색 가능성:
명확하고 설명적인 도구 이름은 에이전트가 올바른 도구를 빠르게 찾는 데 도움이 됩니다. 일관된 접두사(예: github_create_issue, github_list_repos)와 동작 중심의 이름 지정을 사용하세요.
컨텍스트 관리: 에이전트는 간결한 도구 설명과 결과를 필터링/페이징할 수 있는 기능의 이점을 누립니다. 집중되고 관련성 높은 데이터를 반환하는 도구를 설계하세요. 일부 클라이언트는 코드 실행을 지원하여 에이전트가 데이터를 효율적으로 필터링하고 처리하는 데 도움이 될 수 있습니다.
실행 가능한 오류 메시지: 오류 메시지는 구체적인 제안과 다음 단계를 통해 에이전트를 솔루션으로 안내해야 합니다.
1.2 MCP 프로토콜 문서 연구
MCP 사양 탐색:
사이트맵에서 관련 페이지를 찾는 것으로 시작하세요: https://modelcontextprotocol.io/sitemap.xml
그런 다음 마크다운 형식을 위해 .md 접미사를 사용하여 특정 페이지를 가져옵니다(예: https://modelcontextprotocol.io/specification/draft.md).
검토할 주요 페이지:
- 사양 개요 및 아키텍처
- 전송 메커니즘(Streamable HTTP, stdio)
- 도구, 리소스 및 프롬프트 정의
1.3 프레임워크 문서 연구
권장 스택:
- 언어: TypeScript(고품질 SDK 지원 및 다양한 실행 환경(MCPB)에서의 우수한 호환성. 또한 AI 모델은 TypeScript 코드 생성에 능숙하며, 광범위한 사용, 정적 타이핑 및 우수한 린팅 도구의 이점을 누립니다)
- 전송: 원격 서버의 경우 Streamable HTTP, 상태 비저장 JSON 사용(상태 저장 세션 및 스트리밍 응답에 비해 확장 및 유지 관리가 더 간단함). 로컬 서버의 경우 stdio.
프레임워크 문서 로드:
- MCP 모범 사례: 📋 모범 사례 보기 - 핵심 지침
TypeScript(권장)의 경우:
TypeScript SDK에는 두 가지 주요 버전이 있습니다. 코드를 작성하기 전에 하나를 선택하세요:
- v2 (
@modelcontextprotocol/server): 현재 안정적인 릴리스입니다. 새 서버에 사용하세요. - v1 (
@modelcontextprotocol/sdk): 버그 및 보안 수정만 받습니다. 프로젝트의package.json에 이미@modelcontextprotocol/sdk가 종속되어 있거나npx @modelcontextprotocol/codemod@latest v1-to-v2 .로 해당 프로젝트를 마이그레이션하는 경우에만 사용하세요.
프로젝트가 이미 v1을 사용하는 경우, 한두 문장으로 v2(@modelcontextprotocol/server)가 현재 안정적인 릴리스이고 v1은 버그 및 보안 수정만 받으며 npx @modelcontextprotocol/codemod@latest v1-to-v2 .가 프로젝트를 마이그레이션한다는 것을 사용자에게 한 번 알려주세요. 그런 다음 사용자가 마이그레이션을 요청하지 않는 한 v1을 계속 사용하세요.
하나의 프로젝트에서 두 버전을 혼합하지 마세요: v1 코드 샘플(@modelcontextprotocol/sdk/...에서 가져오기)은 v2에 적용되지 않습니다.
- TypeScript SDK (v2): WebFetch를 사용하여
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md를 로드하세요. 전체 문서 색인은https://ts.sdk.modelcontextprotocol.io/v2/llms.txt입니다. - ⚡ TypeScript 가이드 (v2) - TypeScript 패턴 및 예제
- v1 프로젝트 전용:
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.md및 TypeScript 가이드 (v1)
Python의 경우:
- Python SDK: WebFetch를 사용하여
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md를 로드하세요. - 🐍 Python 가이드 - Python 패턴 및 예제
1.4 구현 계획 수립
API 이해: 서비스의 API 문서를 검토하여 주요 엔드포인트, 인증 요구 사항 및 데이터 모델을 식별하세요. 필요에 따라 웹 검색 및 WebFetch를 사용하세요.
도구 선택: 포괄적인 API 커버리지를 우선시하세요. 가장 일반적인 작업부터 시작하여 구현할 엔드포인트를 나열하세요.
2단계: 구현
2.1 프로젝트 구조 설정
프로젝트 설정에 대한 언어별 가이드를 참조하세요:
- ⚡ TypeScript 가이드 (v2) - 프로젝트 구조, package.json, tsconfig.json (v1 기존 v1 프로젝트용)
- 🐍 Python 가이드 - 모듈 구성, 종속성
2.2 핵심 인프라 구현
공유 유틸리티 생성:
- 인증이 포함된 API 클라이언트
- 오류 처리 도우미
- 응답 형식 지정(JSON/Markdown)
- 페이징 지원
2.3 도구 구현
각 도구에 대해:
입력 스키마:
- Zod(TypeScript) 또는 Pydantic(Python) 사용
- 제약 조건 및 명확한 설명 포함
- 필드 설명에 예제 추가
출력 스키마:
- 구조화된 데이터를 위해 가능한 경우
outputSchema정의 - 도구 응답에
structuredContent사용(TypeScript SDK 기능) - 클라이언트가 도구 출력을 이해하고 처리하는 데 도움
도구 설명:
- 기능에 대한 간결한 요약
- 매개변수 설명
- 반환 유형 스키마
구현:
- I/O 작업에 Async/await 사용
- 실행 가능한 메시지가 포함된 적절한 오류 처리
- 해당되는 경우 페이징 지원
- 최신 SDK 사용 시 텍스트 콘텐츠와 구조화된 데이터 모두 반환
어노테이션:
readOnlyHint: true/falsedestructiveHint: true/falseidempotentHint: true/falseopenWorldHint: true/false
3단계: 리뷰 및 테스트
3.1 코드 품질
다음 사항을 검토하세요:
- 중복 코드 없음(DRY 원칙)
- 일관된 오류 처리
- 전체 유형 커버리지
- 명확한 도구 설명
3.2 빌드 및 테스트
TypeScript:
npm run build실행하여 컴파일 확인- v2 프로젝트: v2 가이드의 셀프 체크 스크립트를 빌드된 서버에 대해 실행
- MCP Inspector로 테스트:
npx @modelcontextprotocol/inspector
Python:
- 구문 확인:
python -m py_compile your_server.py - MCP Inspector로 테스트
자세한 테스트 접근 방식 및 품질 체크리스트는 언어별 가이드를 참조하세요.
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/sitemap.xml의 사이트맵으로 시작한 다음.md접미사를 사용하여 특정 페이지를 가져오세요. - 📋 MCP 모범 사례 - 다음을 포함한 범용 MCP 지침:
- 서버 및 도구 이름 지정 규칙
- 응답 형식 지침(JSON vs Markdown)
- 페이징 모범 사례
- 전송 선택(Streamable HTTP vs stdio)
- 보안 및 오류 처리 표준
SDK 문서 (1/2단계에서 로드)
- Python SDK:
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md에서 가져오기 - TypeScript SDK (v2):
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md에서 가져오기; 전체 문서 색인:https://ts.sdk.modelcontextprotocol.io/v2/llms.txt - TypeScript SDK (v1, 기존 v1 프로젝트만):
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.md에서 가져오기
언어별 구현 가이드 (2단계에서 로드)
-
🐍 Python 구현 가이드 - 다음을 포함한 완전한 Python/FastMCP 가이드:
- 서버 초기화 패턴
- Pydantic 모델 예제
@mcp.tool을 사용한 도구 등록- 완전한 작동 예제
- 품질 체크리스트
-
⚡ TypeScript 구현 가이드 (SDK v2) -
@modelcontextprotocol/server에 대한 완전한 TypeScript 가이드:- 프로젝트 설정 및 서버 팩토리
- 도구 설계: Zod 4 스키마, 출력 형식, 페이징, 오류
- stdio 및 Streamable HTTP를 제공하고 Bearer 인증을 포함하는 완전한 예제
- 리소스, 프롬프트 및 알림
- 빌드된 서버를 확인하기 위한 셀프 체크 스크립트
- 고급 기능을 위한 SDK 예제 링크
- v1 → v2 변환 테이블, 마이그레이션 단계 및 품질 체크리스트
-
⚡ TypeScript 구현 가이드 (SDK v1) - 기존
@modelcontextprotocol/sdk프로젝트에 대한 동등한 가이드
평가 가이드 (4단계에서 로드)
- ✅ 평가 가이드 - 다음을 포함한 완전한 평가 생성 가이드:
- 질문 생성 지침
- 답변 확인 전략
- XML 형식 사양
- 예제 질문 및 답변
- 제공된 스크립트로 평가 실행