mcp-builder

# MCP Server Development Guide

## 개요 (Overview)

LLM이 잘 설계된 도구를 통해 외부 서비스와 상호작용할 수 있게 해주는 MCP (Model Context Protocol) 서버를 생성하세요. MCP 서버의 품질은 LLM이 실제 작업을 얼마나 잘 수행할 수 있게 하는지에 따라 결정됩니다.

---

# 프로세스 (Process)

## 🚀 워크플로우 개요 (High-Level Workflow)

고품질 MCP 서버를 만드는 과정은 크게 네 단계로 나뉩니다:

### Phase 1: 심층 조사 및 계획 (Deep Research and Planning)

#### 1.1 최신 MCP 설계 이해

**API 커버리지 vs. 워크플로우 도구:**
포괄적인 API 엔드포인트 커버리지와 특화된 워크플로우 도구 사이의 균형을 맞추세요. 워크플로우 도구는 특정 작업에 더 편리할 수 있으며, 포괄적인 커버리지는 에이전트(agent)가 작업을 자유롭게 구성할 수 있는 유연성을 제공합니다. 성능은 클라이언트에 따라 다릅니다—일부 클라이언트는 기본 도구들을 조합하는 코드 실행 방식이 효율적이며, 다른 클라이언트는 상위 수준의 워크플로우 도구가 더 잘 작동합니다. 확실하지 않을 때는 포괄적인 API 커버리지를 우선시하세요.

**도구 명명 및 발견 가능성 (Tool Naming and Discoverability):**
명확하고 설명적인 도구 이름은 에이전트가 적절한 도구를 빠르게 찾는 데 도움이 됩니다. 일관된 접두사(예: `github_create_issue`, `github_list_repos`)를 사용하고 동작 중심의 이름을 지으세요.

**컨텍스트 관리 (Context Management):**
에이전트는 간결한 도구 설명과 결과 필터링/페이지네이션 기능이 있을 때 더 효율적으로 작동합니다. 집중적이고 관련성 높은 데이터를 반환하도록 도구를 설계하세요. 일부 클라이언트는 코드 실행을 지원하며, 이는 에이전트가 데이터를 효율적으로 필터링하고 처리하는 데 도움이 됩니다.

**실행 가능한 에러 메시지 (Actionable Error Messages):**
에러 메시지는 구체적인 제안과 다음 단계를 제시하여 에이전트가 해결책을 찾을 수 있도록 안내해야 합니다.

#### 1.2 MCP 프로토콜 문서 학습

**MCP 사양 탐색:**

먼저 사이트맵에서 관련 페이지를 찾으세요: `https://modelcontextprotocol.io/sitemap.xml`

그 다음, 마크다운 형식을 위해 `.md` 접미사가 붙은 특정 페이지를 가져오세요 (예: `https://modelcontextprotocol.io/specification/draft.md`).

검토해야 할 주요 페이지:
- 사양 개요 및 아키텍처
- 전송 메커니즘 (streamable HTTP, stdio)
- 도구(Tool), 리소스(Resource), 프롬프트(Prompt) 정의

#### 1.3 프레임워크 문서 학습

**권장 스택:**
- **언어**: TypeScript (고품질 SDK 지원 및 MCPB 등 다양한 실행 환경에서 좋은 호환성 제공. 또한 AI 모델들이 광범위한 사용량, 정적 타이핑 및 우수한 린팅 도구 덕분에 TypeScript 코드를 생성하는 데 능숙함)
- **전송(Transport)**: 원격 서버의 경우 상태 비저장(stateless) JSON을 사용하는 Streamable HTTP (상태 저장 세션 및 스트리밍 응답에 비해 확장 및 유지보수가 간단함). 로컬 서버의 경우 stdio 사용.

**프레임워크 문서 로드:**

- **MCP Best Practices**: [📋 Best Practices 보기](./reference/mcp_best_practices.md) - 핵심 가이드라인

**TypeScript용 (권장):**
- **TypeScript SDK**: WebFetch를 사용하여 `https://raw.githubusercontent.com/modelcontextprotocol/typ