MCP 서버 템플릿

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

특징

• 🚀 전체 TypeScript 지원

• 🏗️ 컨테이너 기반 종속성 주입

• 📦 DataProcessor 인터페이스를 갖춘 서비스 기반 아키텍처

• 🛠️ 테스트를 통한 도구 구현 예시

• 🧪 Vitest 테스트 프레임워크

• 📝 유형 정의

• 🔌 MCP SDK 통합

Related MCP server: MCP Server Template

시작하기

개발

1. 종속성 설치:

   지엑스피1

2. 핫 리로드로 개발 서버를 시작합니다.

   npm run dev

3. 프로젝트를 빌드하세요:

   npm run build

4. 테스트 실행:

   npm test

5. 프로덕션 서버를 시작합니다.

   npm start

프로젝트 구조

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

도구 만들기

1. 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" }],
         },
       };
     },
   };

2. 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 검사기가 포함되어 있습니다.

1. 검사기를 시작합니다.

   npx @modelcontextprotocol/inspector node dist/index.js

2. http://localhost:5173 에서 검사기 UI를 엽니다.

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

• 테스트 도구를 위한 시각적 인터페이스

• 실시간 요청/응답 모니터링

• 도구 메타데이터 검사

• 대화형 테스트 환경

커서를 사용한 로컬 테스트

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

1. 패키지를 빌드하고 연결하세요.

   npm run build
   npm run link

2. 바이너리가 작동하는지 확인하세요.

   npx example-mcp-tool

3. 커서에 서버를 추가합니다.

   • 커서 설정 열기

   • 기능 탭으로 이동

   • MCP 서버 섹션으로 스크롤하세요

   • "서버 추가"를 클릭하세요

   • "명령" 유형을 선택하세요

   • 이름을 지정합니다(예: "로컬 예제 도구")

   • 명령을 입력하세요: npx example-mcp-tool

   • 확인을 클릭하세요

4. MCP 서버 섹션에 서버가 실행 중으로 표시되는지 확인하여 Cursor에서 서버가 올바르게 시작되는지 확인하세요.

참고: 코드를 변경한 경우 다시 빌드하고 다시 링크하는 것을 잊지 마세요.

npm run build
npm run link

테스트가 끝나면 패키지의 연결을 해제할 수 있습니다.

npm run unlink

이렇게 하면 개발 중에 생성된 글로벌 심볼릭 링크가 제거됩니다.