openapi-md-mcp

OpenAPI spec을 점진적 공개（progressive disclosure）하여 markdown으로 제공하는 MCP 서버.

왜

• Swagger UI（/docs）는 JS 셸이라 AI가 내용을 가져올 수 없음

• /openapi.json 전체는 흔히 수십 K tokens에 달해 통째로 컨텍스트에 넣기에는 너무 비쌈

• 이 도구는 AI 상주 컨텍스트를 「키 + 요약」 엔드포인트 표（~1k tokens）로 유지하고, 키로 드릴다운하여 단일 엔드포인트 / 단일 schema의 markdown 상세를 가져온다. 실측 ~90% 컨텍스트 절약

Related MCP server: OpenAPI MCP Server

도구 구성（점진적 공개, 출력은 모두 markdown）

드릴다운 키 = METHOD /path 또는 schema 이름이며, 상위 출력에서 바로 얻는다.

배치 모드（select + get_batch）

• select(patterns=["GET /v1/auth/*", "* /v1/scoring/*"], security="X-Service-Token", tag="scoring", schema_glob="Credit*")

  • patterns 요소는 "METHOD /path/glob" 형태: 메서드는 *（대소문자 구분 안 함）; 경로 glob은 대소문자 구분

  • security는 scheme 이름; patterns 끼리는 OR, security/tag와는 AND

  • 매칭 0건은 성공 텍스트를 반환（사용 가능한 scheme / tag + 조건 완화 제안）, 오류가 아님

• get_batch(["POST /v1/scoring/credit", "CreditBatchRequest"])

  • 키는 중복 제거하면서 순서를 유지, 상한 40개; 렌더링 총 문자 수 상한 100k, 초과 시 include_refs=False 또는 분할 요청 권장

  • include_refs=True는 렌더링 중 참조되는 $ref를 자동으로 통합해「공유 schema 부록」을 만든다（이름마다 한 번만 렌더링）

설정（env）

• spec은 JSON과 YAML 지원; 로드 후 프로세스 내 60s 캐시

• 요청은 직접 연결（trust_env=False）: 대상이 localhost / 내부망 spec이므로 시스템 프록시를 거치지 않음（macOS 시스템 프록시가 localhost를 502로 만들 수 있음）

• 읽기 전용이며 API 호출 기능을 제공하지 않음（인증 헤더는 MCP 계층으로 들어가지 않음）

어떤 저장소든 연동

Claude Code 사용자 수준 등록（한 번 등록하면 모든 저장소에서 사용 가능）:

claude mcp add openapi-md -s user -- \
  uv run --directory /path/to/openapi-md-mcp openapi-md-mcp

다른 데이터 소스가 필요한 저장소는 각자 프로젝트 수준 .mcp.json에서 env를 덮어쓰면 된다.

프로토콜 준수（MCP 2026-07-28, 일명 2.0）

• 도구 이름 / 설명 / inputSchema가 규격 §Tools를 충족（이름 문자셋과 길이, 결정적 tools/list 순서）

• 다섯 도구 모두 annotations.readOnlyHint: true를 선언（읽기 전용）

• 오류 의미는 규격 §Tools Error Handling을 따른다: spec 로드 실패, 알 수 없는 키（유사 키 제안 포함）, 잘못된 필터 패턴과 일괄 상한 초과는 Tool Execution Error로 ToolError를 던짐 → 실제로는 CallToolResult(isError=true)로 나타나며, 클라이언트는 제안을 모델에 되먹여 자가 수정하게 한다. 매칭 0건은 성공 텍스트; call（API 호출）기능은 제공하지 않음

• 버전 협상: stdio는 initialize 핸드셰이크 에포크를 사용（최대 2025-11-25）; 2026-07-28의 무상태 봉투 에포크는 SDK가 HTTP 전송 계층에서 처리（server/discover）, stdio 시나리오에는 해당하지 않음

개발

uv sync                 # 安装依赖
uv run pytest --cov=openapi_md_mcp   # 测试（fixture 为真实 OpenAPI 3.1 快照）