mcp-server-patterns

name	mcp-server-patterns
description	Node/TypeScript SDK로 MCP 서버 빌드 — 도구, 리소스, 프롬프트, Zod 검증, stdio vs Streamable HTTP. 최신 API는 Context7이나 공식 MCP 문서를 참고하세요.
origin	ECC

MCP 서버 패턴

Model Context Protocol(MCP)을 사용하면 AI 어시스턴트가 서버의 도구를 호출하고, 리소스를 읽고, 프롬프트를 사용할 수 있습니다. MCP 서버를 구축하거나 유지관리할 때 이 스킬을 사용하세요. SDK API는 계속 진화하므로, 현재 메서드 이름과 시그니처는 Context7("MCP" 문서 쿼리)이나 공식 MCP 문서를 확인하세요.

기능을 규칙, 스킬, MCP 또는 일반 CLI/API 워크플로 중 어디에 둘지에 대한 더 넓은 라우팅 결정은 docs/capability-surface-selection.md를 참고하세요.

사용 시점

다음 경우에 사용하세요: 새 MCP 서버 구현, 도구 또는 리소스 추가, stdio vs HTTP 선택, SDK 업그레이드, 또는 MCP 등록 및 전송 문제 디버깅.

동작 방식

핵심 개념

• 도구(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 버전에 따라 다릅니다(예: 생성자 vs 팩토리). 현재 패턴은 공식 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). 최신 등록 및 전송 패턴은 Context7에서 라이브러리 이름 "MCP"로 확인하세요.
• Go: GitHub의 공식 Go SDK (modelcontextprotocol/go-sdk).
• C#: .NET용 공식 C# SDK.