배포 전 MCP 서버를 린트(Lint)하세요 (MCP를 위한 eslint)

만약 당신이 Model Context Protocol 서버를 출시했다면, 아마 이런 상황을 겪어봤을 것입니다: 서버가 에디터에서는 잘 작동하는데, 막상 배포하고 나면 에이전트들이 도구(tools)를 잘못 호출하거나, 더 심하게는 클라이언트가 이를 안전하지 않다고 표시하여 ChatGPT나 Claude 앱 디렉토리에 등록되지 못하는 상황 말입니다.

이를 위한 eslint가 없습니다. 그래서 제가 하나 만들었습니다: mcp-conform — 배포 전에 실행하는 결정론적(deterministic)인 개발자 측면의 준수성(conformance) 및 안전성 린터(linter)입니다.

npx github:fernforge/mcp-conform --cmd "node dist/index.js"

mcp-conform — 7 tool(s) checked

delete_record
...

왜 개발자 측면(author-side)의 린터인가요?

MCP 개발자들에게 세 가지 변화가 생겼으며, 이들은 모두 배포 시점에 문제를 일으킵니다:

1. 도구 어노테이션(tool annotations) 누락은 서버가 앱 디렉토리에서 거절되는 가장 큰 이유입니다. 명세(spec)에 따르면, 힌트가 없을 때 클라이언트는 최악의 상황(worst case) — 즉, 파괴적이고 개방된 환경(open-world) — 을 가정해야 합니다. 따라서 readOnlyHint / destructiveHint / openWorldHint / title을 설정하지 않으면, 당신의 무해한 읽기 도구는 위험한 것으로 취급되고, 당신의 파괴적인 도구는 아무런 경고 없이 배포됩니다.

2. 도구 설명(Tool descriptions)은 인젝션 공격 표면(injection surface)입니다. 설명은 에이전트의 컨텍스트(context)로 직접 전달됩니다. 설명 안에 들어있는 "이전 지침을 무시하세요..."라는 문구 — 또는 보이지 않는 유니코드(Unicode) 페이로드 — 는 실제적인 도구 오염(tool-poisoning) 벡터가 됩니다. 당신은 이것이 패키지에 대한 보안 보고서가 아닌, CI(지속적 통합) 단계에서 포착되기를 원할 것입니다.

3. 공식 레지스트리는 이제 네임스페이스 검증 배포(namespace-verified publishing)를 수행합니다. 역도메인 네임(Reverse-DNS names), server.json 매니페스트(manifest), 그리고 깨끗한 패키지 메타데이터는 이제 선택 사항이 아니라 배포 가능하고 발견 가능하기 위한 필수 요소입니다.

기존의 대부분의 MCP 보안 도구는 **사용자 측면(consumer-side)**입니다 — 즉, 당신이 설치하려는 서버를 스캔합니다. mcp-conform은 개발자 측면(author-side)이며 시프트 레프트(shift-left) 방식입니다: 누군가 설치하기 전에 당신의 서버가 규격에 맞도록 만듭니다.

검사 항목

• Annotations (어노테이션) — 누락되거나 잘못된 readOnlyHint, destructiveHint, openWorldHint, title.
• Schema hygiene (스키마 위생) — 빈약하거나 모호한 입력 스키마, 설명(description) 누락, 제약 조건(constraints) 부재.
• Safety / tool-poisoning (안전성 / 도구 오염) — 설명 내의 지시문 오버라이드(instruction-override) 문구 및 숨겨진 유니코드 페이로드(hidden-Unicode payloads).
• Distribution & registry metadata (배포 및 레지스트리 메타데이터) — 레지스트리 등록을 위한 package.json / server.json 준비 상태.
• 모든 발견 사항은 **한 줄의 수정 방법(one-line fix)**을 함께 제공하며, 0~100 사이의 단일 준수 점수(conformance score)로 합산됩니다.

실제로 배포되는 것을 린트합니다

흥미로운 점은, 이 도구를 서버의 **실행 명령(launch command)**으로 지정하면 stdio를 통해 서버를 시작하고, tools/list를 호출하여 사용자가 실제로 받게 될 실제 스키마를 검사한다는 것입니다. 소스 코드에서 파싱한 추측값이 아닙니다. 이를 통해 코드가 보이는 모습과 서버가 실제로 제공하는 내용 사이의 간극을 잡아낼 수 있습니다.

# 실행 중인 라이브 서버를 린트합니다
npx github:fernforge/mcp-conform --cmd "node dist/server.js"

...

LLM 키 불필요. 네트워크 불필요. 완전히 결정론적(deterministic).

이것은 모델이 아니라 린터(linter)입니다. CI에서 실행하기 안전하며, 하루에 수천 번을 실행해도 비용이 들지 않고, 그 판정 결과가 변하지 않습니다. 모든 PR(Pull Request)을 점수화하고 작업 요약(job summary)을 작성하는 GitHub Action이 바로 적용 가능한 형태로 제공되므로, 도구 메타데이터의 회귀(regression)가 발생하면 다른 린트 에러와 마찬가지로 빌드를 실패하게 만듭니다.

사용해 보기

npx github:fernforge/mcp-conform --cmd "<당신의 서버 실행 명령>"

리포지토리, 규칙 및 GitHub Action: https://github.com/fernforge/mcp-conform (MIT).

아직 초기 단계입니다. 만약 MCP 서버를 배포하신다면, 어떤 검사 항목이 실제 문제를 잡아내는지, 그리고 다음에 어떤 규칙을 원하는지 진심으로 알고 싶습니다. 이슈(issue)를 생성하거나 댓글을 남겨주세요.