first-mcp-server

프로젝트 요약

• 두 숫자를 합결과를 텍스트로 반환하는 add 도구 하나를 노출하는 최소형 MCP (Model Context Protocol) 서버입니다.

• @modelcontextprotocol 패키지와 zod를 사용하여 입력 검증을 수행합니다.

주요 파일

• index.js — add 도구를 등록하고 서버를 시지하는 메인 서버 파일입니다.

요구 사항

• Node.js 14+ (LTS 권장)

• npm 또는 yarn

설치

1. 저장소를 클론하고 프로젝트 디렉터리로 이동합니다:

   git clone && cd /Users/sagar/Documents/Learning/MCP-Server

2. 의존성을 설치합니다 (npm 예시):

   npm install

이 프로젝트에서 사용된 의존성 (코드에서 가져온 예):

• @modelcontextprotocol/server

• @modelcontextprotocol/server/stdout (STDIO 전송)

• @modelcontextprotocol/express (express 헬퍼)

• @modelcontextprotocol/node (Node HTTP 전송)

• zod (검증)

실행

• 기본 전송 (현재 프로젝트는 이 방식으로 시도합니다):

  node index.js

  서버는 포트 3001에서 수신하며 MCP 엔드포인트를 /mcp에 마운트합니다 (index.js 참조).

• STDIO 전송 (로컬 CLI 스타일 연동에 유용):

  index.js에서 runServeronSTDIOTransport() 호출의 주석을 해제하고 실행합니다:

  node index.js

사용 예제

1. HTTP 예제 (curl)

• 요청 페이로드 (JSON):

  { "tool": "add", "input": { "num1": 10, "num2": 20 } }

• 예제 curl 호출 (필요하면 호스트명/포트 조정):

  curl -X POST http://localhost:3001/mcp
  -H "Content-Type: application/json"
  -d '{"tool":"add","input":{"num1":10,"num2":20}}'

• 예상 응답 (서버의 도구는 텍스트 블록의 content 배열을 반환합니다):

  { "content": [ { "type": "text", "text": "30" } ] }

  참고: index.js는 NodeStreamableHTTPServerTransport를 사용하여 HTTP 전송을 연걀하며 transport.handleRequest(req, res, req.body)를 호출합니다 (index.js 참조). 전송이 기대하는 정확한 봉투 모단은 @modelcontextprotocol/node 전송 구현에 의존합니다. 위 예는 이 프로젝트에서 사☁하는 단순한 모단 (tool + input)을 따르는 것입니다.

2. STDIO 예제 (로컬 CLI 연동)

   이 프로젝트에는 StdioServerTransport를 사☁하여 서버를 STDIO로 실행하는 헬퍼가 포함되어 있습니다. STDIO 모드로 시각하면 서버는 stdin에서 JSON 요청을 기대하고 stdout에 응답합니다. [index.js]에 등록된 도구는 zod로 입력을 검증하고 합계를 텍스트로 반환합니다.

도구 번들 (코드에서)

• 도구 이: "add"

• 설명: "Add two numbers"

• 입력 스키마 (zod):

  • num1: number

  • num2: number

[구현 스니펫 ([index.js]):

server.registerTool(
  "add",
  {
    title: "add",
    description: "Add two numbers",
    inputSchema: z.object({ num1: z.number(), num2: z.number() }),
  },
  async (ctx) => ({
    content: [{ type: "text", text: `${ctx.num1 + ctx.num2}` }],
  }),
);

참고 사항:

• 검증: zod가 이미 입력을 검증합니다. 호출자가 숫자 값을 보내도록 하고, 검증 오류를 적절히 처도하세요.

• 오류 처리: transport.handleRequest와 도구 핸들러에 주강 try/catch를 추가하고 일관된 오류 페이로드와 HTTP 상태 코드 (걸라이언트 오류 4xx, 서버 오류 5xx)를 반환하세요.

• 로깅 및 모니터: 구조화 로깅, 요청 ID, 기본 미트자를 추가하여 사☁ 현황과 오류를 모니터하세요.

• 보안: 공개는 /mcp 엔드포인트 (인증 및 요청 제한) 와 리버스 프록시 뒤에서 실행하세요.

• 테스트: 도구 핸들러에 대한 단위 테스트와 전송(HTTP, STDIO)에 대한 통합 테스트를 추가하세요.

기여

• 기능 요청이나 수정 사항은 이슈오 및 PR로 열어 주세요.