MCP TypeScript SDK

개요

MCP(Model Context Protocol)를 사용하면 애플리케이션이 LLM에 컨텍스트를 표준화된 방식으로 제공할 수 있으며, 컨텍스트 제공과 실제 LLM 상호작용의 관심사를 분리합니다.

이 저장소는 MCP 사양의 TypeScript SDK 구현을 포함합니다. Node.js, Bun, Deno에서 실행되며 다음을 제공합니다:

• MCP 서버 라이브러리 (도구/리소스/프롬프트, Streamable HTTP, stdio, 인증 도우미)

• MCP 클라이언트 라이브러리 (전송, 고수준 도우미, OAuth 도우미)

• 특정 런타임/프레임워크를 위한 선택적 미들웨어 패키지 (Express, Fastify, Hono, Node.js HTTP)

• 실행 가능한 예제 (examples/ 아래)

패키지

이 모노레포는 분할 패키지를 게시합니다:

• @modelcontextprotocol/server: MCP 서버 구축

• @modelcontextprotocol/client: MCP 클라이언트 구축

도구 및 프롬프트 스키마는 Standard Schema를 사용합니다 — Zod v4, Valibot, ArkType 또는 호환되는 라이브러리를 가져오세요.

이들은 의도적으로 얇은 어댑터입니다: 새로운 MCP 기능이나 비즈니스 로직을 도입하지 않아야 합니다. 자세한 내용은 packages/middleware/README.md를 참조하세요.

• @modelcontextprotocol/node: IncomingMessage / ServerResponse를 위한 Node.js Streamable HTTP 전송 래퍼

• @modelcontextprotocol/express: Express 도우미 (앱 기본값 + Host 헤더 검증)

• @modelcontextprotocol/fastify: Fastify 도우미 (앱 기본값 + Host 헤더 검증)

• @modelcontextprotocol/hono: Hono 도우미 (앱 기본값 + JSON 본문 파싱 훅 + Host 헤더 검증)

설치

서버

npm install @modelcontextprotocol/server
# or
bun add @modelcontextprotocol/server
# or
deno add npm:@modelcontextprotocol/server

클라이언트

npm install @modelcontextprotocol/client
# or
bun add @modelcontextprotocol/client
# or
deno add npm:@modelcontextprotocol/client

선택적 미들웨어 패키지

SDK는 또한 특정 런타임 또는 웹 프레임워크(예: Express, Fastify, Hono, Node.js http)에 MCP를 연결하는 데 도움이 되는 선택적 "미들웨어" 패키지를 게시합니다.

이 패키지는 의도적으로 얇은 어댑터이며 추가 MCP 기능이나 비즈니스 로직을 도입하지 않아야 합니다. 자세한 내용은 packages/middleware/README.md를 참조하세요.

# Node.js HTTP (IncomingMessage/ServerResponse) Streamable HTTP transport:
npm install @modelcontextprotocol/node

# Express integration:
npm install @modelcontextprotocol/express express

# Fastify integration:
npm install @modelcontextprotocol/fastify fastify

# Hono integration:
npm install @modelcontextprotocol/hono hono

시작하기

MCP 서버의 모습은 다음과 같습니다. 이 최소 예제는 stdio를 통해 단일 greet 도구를 노출합니다:

import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

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

server.registerTool(
    'greet',
    {
        description: 'Greet someone by name',
        inputSchema: z.object({ name: z.string() })
    },
    async ({ name }) => ({
        content: [{ type: 'text', text: `Hello, ${name}!` }]
    })
);

async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
}

main();

실제 무언가를 구축할 준비가 되셨나요? 단계별 튜토리얼을 따라해보세요:

• 첫 번째 서버 구축 — npm init부터 도구 호출까지의 stdio 날씨 알림 서버

• 첫 번째 클라이언트 구축 — 해당 서버에 연결하고, 도구를 나열하고, 호출하기

튜토리얼 외에 실행 가능한 종단간 예제는 다음을 참조하세요:

• examples/README.md — 실행 가능하고 자체 검증하는 클라이언트/서버 예제 쌍 (디렉토리당 하나의 스토리)

문서

• 서버 구축 — 첫 번째 MCP 서버를 단계별로

• 클라이언트 구축 — 첫 번째 MCP 클라이언트를 단계별로

• 문서 사이트 — 전체 가이드: 도구, 리소스, 프롬프트, HTTP 및 stdio를 통한 서빙, 클라이언트, OAuth, 마이그레이션

• 문제 해결 — 일반적인 오류 및 해결 방법

• API 참조

• MCP 문서

• MCP 사양

로컬에서 문서 빌드

로컬에서 문서 사이트를 작업하려면:

pnpm docs:api      # Generate the API reference markdown (output: docs/api/)
pnpm docs:dev      # Start the VitePress dev server for the V2 site
pnpm docs:build    # Build the V2 site (output: docs/.vitepress/dist/)
pnpm docs:multi    # Build the combined V1 + V2 site (output: tmp/docs-combined/)