MCP 서버 개발 5단계

  1. 도메인 정의 — MCP가 다루는 철학/기술 도메인 경계 설정
  2. 인터페이스 설계 — Tool 목록 + 입출력 스키마 + 리소스 URI
  3. 서버 구현 — Python FastMCP 또는 Node.js SDK
  4. 로컬 검증 — subprocess 호출 + 응답 파싱 테스트
  5. 레포 등록 — .mcp.json + GitHub Pages 문서 + MCP 갤러리 등록

표준 서버 구조

{mcp-name}/
├── server.py          ← FastMCP 서버 (모든 도구 구현)
├── requirements.txt   ← 의존성
├── README.md          ← 사용법
├── index.html         ← GitHub Pages 문서
└── tests/
    └── test_server.py ← 단위 테스트

표준과 실제의 차이

이 표준은 서버마다 개별 tests/ 디렉토리를 두라고 명시하지만, 실제로 2026-07-09 시점 12개 MCP는 각자 테스트가 아니라 레포 루트의 tests/test_mcp_smoke.py 하나가 12개를 순회하며 initialize+tools/list 핸드셰이크만 검증한다. 이건 표준 미달이 아니라 의도적 절충이다 — 서버 12개 각각에 전용 단위 테스트를 짜는 건 비용이 크고, 지금 필요한 건 "로직이 완벽한가"가 아니라 "프로토콜이 살아있는가"였다. 표준 문서가 이상형을 남겨두고, 실제 구현이 지금 수준에 맞는 최소 버전을 택한 것 — 이 간극 자체를 지우지 않고 남겨두는 게 정직하다.

5단계 중 가장 늦게 채워진 게 4단계였다

도메인 정의(1)와 서버 구현(3)은 빠르게 진행됐지만, 로컬 검증(4)은 12개 서버 중 상당수가 __pycache__조차 없는(=실행된 적 없는) 상태로 한동안 방치돼 있었다. 감사에서 이 사실이 드러난 뒤에야 4단계가 실제로 이행됐다. 방법론 문서에 단계가 적혀 있다고 그 단계가 실제로 지켜지는 건 아니라는 걸 이 레포 자신이 보여준 사례다.

PHL-Engineering#MCP방법론#개발표준