제가 흔히 접하는 대부분의 MCP 서버들은 간단한 스크립트로 시작해서 그대로 방치되곤 합니다. 검증(validation)도 없고, 구조화된 로깅(structured logging)도 없으며, 테스트도 없고, 배포 방식 또한 node_modules를 통째로 옮겨야 하는 수준이죠.

클라이언트 프로젝트에서 Model Context Protocol (MCP) 서버가 필요할 때마다 매번 동일한 스캐폴딩(scaffolding)을 다시 만드는 것에 지쳐서, 제가 모든 프로젝트를 시작할 때 사용하는 템플릿을 오픈 소스로 공개했습니다: 🚀 mcp-server-template

이것은 Claude Desktop 및 Cursor와 같은 AI 에이전트를 여러분의 도구, 데이터, 워크플로에 연결하는 MCP 서버를 구축하기 위한 프로덕션 준비 완료(production-ready)된 TypeScript/Node.js 기반입니다.

시작하는 데는 네 가지 명령어가 필요합니다:

git clone https://github.com/qmmughal/mcp-server-template.git
cd mcp-server-template && npm install
cp .env.example .env
...

이렇게 하면 watch 모드로 작동하는 서버가 실행됩니다. npm test는 Vitest 스위트를 실행하며, npm run build는 esbuild를 사용하여 모든 것을 단일 dist/index.js 파일로 번들링합니다. 즉, 배포할 때 node_modules가 필요 없습니다.

실제 도구가 어떻게 생겼는지:

모든 도구는 Zod 스키마(schema), 정의(definition), 그리고 핸들러(handler)를 가집니다. 따라서 잘못된 형식의 AI 페이로드(payload)가 들어오더라도 프로세스가 충돌하는 대신 깔끔한 에러와 함께 거부됩니다:

const schema = z.object({
  text: z.string().describe("The text to process"),
  repeat: z.number().int().min(1).max(10).optional()
...

자신만의 도구로 확장하기:

1. src/tools/ 폴더에 동일한 schema → definition → handler 구조를 따르는 새 파일을 넣으세요.
2. src/tools/index.ts에 등록하세요 — tools 목록에 정의를 추가하고, CallToolRequest를 여러분의 핸들러로 라우팅하는 switch 문에 case를 추가하세요.
3. 실제 로직은 src/services/에 두세요. 그래야 프로토콜 계층(protocol layer)은 가볍게 유지되고, 비즈니스 로직은 독립적으로 단위 테스트(unit-testable)가 가능합니다.
4. 리소스(AI가 읽을 수 있는 데이터)와 프롬프트(Prompts, 재사용 가능한 템플릿)는 각각의 폴더에서 정확히 동일한 패턴을 따릅니다 — 예시를 복사하고, 이름을 바꾸고, 스키마를 조정하세요.

구조화된 pino 로깅은 전체 과정에서 안전하게 stderr로 라우팅되므로, 무엇을 추가하더라도 MCP stdio 전송(transport)을 절대 손상시키지 않습니다.

배포할 준비가 되면, 릴리스(release) 태그를 지정하세요. 그러면 GitHub Actions 워크플로(workflow)가 npm과 MCP Registry 양쪽 모두에 자동으로 게시합니다:

git tag v1.0.0 && git push origin v1.0.0

목표는 간단합니다. 로깅(logging), 검증(validation), 번들링(bundling) 문제를 다섯 번째 다시 해결하는 데 시간을 쓰는 것이 아니라, 여러분의 MCP 서버를 유용하게 만드는 로직(logic)에 시간을 집중하는 것입니다.

이 프로젝트는 MIT 라이선스이며 현재 GitHub에서 확인하실 수 있습니다. 에이전트형 AI (agentic AI) 통합 기능을 구축하고 계신다면, 피드백이나 스타(star)를 부탁드립니다:

🔗 github.com/qmmughal/mcp-server-template

MCP #ModelContextProtocol #AgenticAI #TypeScript #OpenSource #AIEngineering #ClaudeAI