MCP 서버 템플릿

TypeScript에서 모델 컨텍스트 프로토콜(MCP) 서버를 생성하기 위한 템플릿입니다. 이 템플릿은 적절한 도구, 타입 안전성 및 모범 사례를 통해 MCP 호환 서버를 구축하기 위한 탄탄한 기반을 제공합니다.

특징

🚀 전체 TypeScript 지원
🏗️ 컨테이너 기반 종속성 주입
📦 DataProcessor 인터페이스를 갖춘 서비스 기반 아키텍처
🛠️ 테스트를 통한 도구 구현 예시
🧪 Vitest 테스트 프레임워크
📝 유형 정의
🔌 MCP SDK 통합

Related MCP server: MCP Server Template

시작하기

개발

종속성 설치:
지엑스피1
핫 리로드로 개발 서버를 시작합니다.
npm run dev
프로젝트를 빌드하세요:
npm run build
테스트 실행:
npm test
프로덕션 서버를 시작합니다.
npm start

프로젝트 구조

src/ ├── index.ts # Entry point ├── interfaces/ # Interface definitions │ └── tool.ts # DataProcessor interface └── tools/ # Tool implementations └── example.ts # Example tool

도구 만들기

src/tools/example.ts 의 예제에 따라 도구와 핸들러를 내보내세요.
// In your-tool.ts export const YOUR_TOOLS = [ { name: "your-tool-name", description: "Your tool description", parameters: { // Your tool parameters schema }, }, ]; export const YOUR_HANDLERS = { "your-tool-name": async (request) => { // Your tool handler implementation return { toolResult: { content: [{ type: "text", text: "Result" }], }, }; }, };
src/index.ts 의 ALL_TOOLS 및 ALL_HANDLERS 상수에 도구를 등록합니다.
// In src/index.ts import { YOUR_TOOLS, YOUR_HANDLERS } from "./tools/your-tool.js"; // Combine all tools const ALL_TOOLS = [...EXAMPLE_TOOLS, ...YOUR_TOOLS]; const ALL_HANDLERS = { ...EXAMPLE_HANDLERS, ...YOUR_HANDLERS };

서버는 자동으로 다음을 수행합니다.

사용 가능한 도구에 도구를 나열하세요
입력 검증 처리
도구에 대한 프로세스 요청
MCP 프로토콜에 따라 응답 형식 지정

테스트

템플릿에는 로컬 테스트를 위한 내장 TestClient와 시각적 디버깅을 위한 MCP Inspector가 포함되어 있습니다.

TestClient 사용

TestClient는 도구를 테스트하는 간단한 방법을 제공합니다.

import { TestClient } from "./utils/TestClient"; describe("YourTool", () => { const client = new TestClient(); it("should process data correctly", async () => { await client.assertToolCall( "your-tool-name", { input: "test" }, (result) => { expect(result.toolResult.content).toBeDefined(); } ); }); });

MCP Inspector 사용

템플릿에는 도구의 시각적 디버깅을 위한 MCP 검사기가 포함되어 있습니다.

검사기를 시작합니다.
npx @modelcontextprotocol/inspector node dist/index.js
http://localhost:5173 에서 검사기 UI를 엽니다.

검사관은 다음을 제공합니다.

테스트 도구를 위한 시각적 인터페이스
실시간 요청/응답 모니터링
도구 메타데이터 검사
대화형 테스트 환경

커서를 사용한 로컬 테스트

Cursor를 사용하여 로컬로 MCP 서버를 테스트하려면:

패키지를 빌드하고 연결하세요.
npm run build npm run link
바이너리가 작동하는지 확인하세요.
npx example-mcp-tool
커서에 서버를 추가합니다.
- 커서 설정 열기
- 기능 탭으로 이동
- MCP 서버 섹션으로 스크롤하세요
- "서버 추가"를 클릭하세요
- "명령" 유형을 선택하세요
- 이름을 지정합니다(예: "로컬 예제 도구")
- 명령을 입력하세요: npx example-mcp-tool
- 확인을 클릭하세요
MCP 서버 섹션에 서버가 실행 중으로 표시되는지 확인하여 Cursor에서 서버가 올바르게 시작되는지 확인하세요.