mcp-server-patterns

name	mcp-server-patterns
description	Node/TypeScript SDK를 사용한 MCP 서버 구축 — 도구, 리소스, 프롬프트, Zod 유효성 검사, stdio 대 Streamable HTTP. 최신 API는 Context7이나 공식 MCP 문서를 참조하세요.
origin	ECC

MCP 서버 패턴 (MCP Server Patterns)

모델 컨텍스트 프로토콜(MCP)을 사용하면 AI 어시스턴트가 서버의 도구를 호출하고, 리소스를 읽고, 프롬프트를 사용할 수 있습니다. MCP 서버를 구축하거나 유지보수할 때 이 스킬을 사용하세요. SDK API는 계속 진화하므로, 현재 메서드 이름과 시그니처는 Context7("MCP"로 query-docs 실행) 또는 공식 MCP 문서를 확인하세요.

특정 기능이 규칙, 기술, MCP 또는 일반 CLI/API 워크플로우 중 어디에 위치해야 하는지에 대한 더 넓은 라우팅 결정은 docs/capability-surface-selection.md를 참조하세요.

사용 시점

사용 시기: 새로운 MCP 서버 구현, 도구 또는 리소스 추가, stdio 대 HTTP 선택, SDK 업그레이드, 또는 MCP 등록 및 전송(transport) 문제 디버깅 시.

작동 방식

핵심 개념

• 도구 (Tools): 모델이 호출할 수 있는 동작 (예: 검색, 명령어 실행). SDK 버전에 따라 registerTool() 또는 tool()로 등록합니다.
• 리소스 (Resources): 모델이 가져올 수 있는 읽기 전용 데이터 (예: 파일 내용, API 응답). registerResource() 또는 resource()로 등록합니다. 핸들러는 보통 uri 인자를 받습니다.
• 프롬프트 (Prompts): 클라이언트(예: Claude Desktop)가 표시할 수 있는 재사용 가능하고 매개변수화된 프롬프트 템플릿. registerPrompt() 등으로 등록합니다.
• 전송 (Transport): 로컬 클라이언트(예: Claude Desktop)의 경우 stdio를 사용합니다. 원격(Cursor, 클라우드)의 경우 Streamable HTTP를 선호합니다. 레거시 HTTP/SSE는 하위 호환성을 위해 사용됩니다.

Node/TypeScript SDK는 tool() / resource() 또는 registerTool() / registerResource()를 노출할 수 있습니다. 공식 SDK는 시간에 따라 변경되었습니다. 항상 최신 MCP 문서 또는 Context7을 통해 확인하세요.

stdio로 연결하기

로컬 클라이언트의 경우, stdio 전송을 생성하여 서버의 connect 메서드에 전달합니다. 정확한 API는 SDK 버전에 따라 다릅니다 (예: 생성자 대 팩토리). 현재 패턴은 공식 MCP 문서나 Context7에서 "MCP stdio server"를 검색하여 확인하세요.

도구와 리소스를 포함한 서버 로직은 엔트리포인트에서 stdio나 HTTP를 갈아 끼울 수 있도록 전송 방식과 독립적으로 유지하세요.

원격 (Streamable HTTP)

Cursor, 클라우드 또는 기타 원격 클라이언트의 경우 Streamable HTTP(현재 사양에 따른 단일 MCP HTTP 엔드포인트)를 사용하세요. 하위 호환성이 필요한 경우에만 레거시 HTTP/SSE를 지원하세요.

예시

설치 및 서버 설정

npm install @modelcontextprotocol/sdk zod

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

사용 중인 SDK 버전이 제공하는 API를 사용하여 도구와 리소스를 등록하세요: 어떤 버전은 server.tool(name, description, schema, handler)(위치 기반 인자)을 사용하고, 다른 버전은 server.tool({ name, description, inputSchema }, handler) 또는 registerTool()을 사용합니다. 리소스도 마찬가지로, API에서 제공하는 경우 핸들러에 uri를 포함하세요. 복사-붙여넣기 오류를 피하기 위해 공식 MCP 문서나 Context7에서 현재 @modelcontextprotocol/sdk 시그니처를 확인하세요.

입력 유효성 검사에는 Zod(또는 SDK가 선호하는 스키마 형식)를 사용하세요.

모범 사례

• 스키마 우선: 모든 도구에 대해 입력 스키마를 정의하고, 매개변수와 반환 형식을 문서화하세요.
• 에러 처리: 모델이 해석할 수 있는 구조화된 에러나 메시지를 반환하세요. 원시 스택 트레이스는 피하세요.
• 멱등성: 재시도가 안전하도록 가능한 경우 멱등성이 있는 도구를 선호하세요.
• 속도 및 비용: 외부 API를 호출하는 도구의 경우 속도 제한과 비용을 고려하고 도구 설명에 명시하세요.
• 버전 관리: package.json에 SDK 버전을 고정하고, 업그레이드 시 릴리스 노트를 확인하세요.

공식 SDK 및 문서

• JavaScript/TypeScript: @modelcontextprotocol/sdk (npm). 현재 등록 및 전송 패턴은 라이브러리 이름 "MCP"로 Context7을 사용하세요.
• Go: GitHub의 공식 Go SDK (modelcontextprotocol/go-sdk).
• C#: .NET용 공식 C# SDK.