MCP OpenAPI 스키마 탐색기
MCP 리소스를 통해 OpenAPI(v3.0) 및 Swagger(v2.0) 사양에 대한 토큰 효율적인 액세스를 제공하는 MCP(Model Context Protocol) 서버입니다.
프로젝트 목표
이 프로젝트의 주요 목표는 MCP 클라이언트(예: Cline 또는 Claude Desktop)가 전체 파일을 LLM 컨텍스트 창에 로드하지 않고도 대규모 OpenAPI 사양의 구조와 세부 정보를 탐색할 수 있도록 하는 것입니다. 읽기 전용 데이터 탐색에 적합한 MCP 리소스를 통해 사양의 일부를 공개함으로써 이를 달성합니다.
이 서버는 로컬 파일 경로와 원격 HTTP/HTTPS URL 모두에서 사양 로딩을 지원합니다. Swagger v2.0 사양은 로딩 시 OpenAPI v3.0으로 자동 변환됩니다.
Related MCP server: Swagger MCP Server
왜 MCP Resources인가요?
모델 컨텍스트 프로토콜은 리소스 와 도구를 모두 정의합니다.
리소스: 데이터 소스(파일, API 응답 등)를 나타냅니다. MCP 클라이언트의 읽기 전용 액세스 및 탐색(예: Claude Desktop에서 API 경로 탐색)에 적합합니다.
도구: LLM이 작업을 수행하거나 외부 시스템과 상호 작용하는 데 자주 사용되는 실행 가능한 동작이나 기능을 나타냅니다.
Tools를 통해 OpenAPI 사양에 대한 액세스를 제공하는 다른 MCP 서버도 있지만, 이 프로젝트는 Resources를 통해 액세스를 제공하는 데 중점을 둡니다. 따라서 MCP 클라이언트 애플리케이션 내에서 직접 탐색하는 데 특히 유용합니다.
MCP 클라이언트와 해당 기능에 대한 자세한 내용은 MCP 클라이언트 설명서를 참조하세요.
설치
권장 사용 방법(아래에 설명된 npx 및 Docker)의 경우 별도의 설치 단계가 필요하지 않습니다 . MCP 클라이언트는 사용자가 제공한 구성에 따라 자동으로 패키지를 다운로드하거나 Docker 이미지를 가져옵니다.
하지만 서버를 명시적으로 설치해야 하거나 선호한다면 두 가지 옵션이 있습니다.
글로벌 설치: npm을 사용하여 패키지를 글로벌하게 설치할 수 있습니다.
지엑스피1
글로벌하게 설치된 서버를 사용하도록 MCP 클라이언트를 구성하는 방법은 아래의 방법 3을 참조하세요.
로컬 개발/설치: 저장소를 복제하여 로컬로 빌드할 수 있습니다.
git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git cd mcp-openapi-schema-explorer npm install npm run build로컬 빌드에서
node사용하여 서버를 실행하도록 MCP 클라이언트를 구성하는 방법은 아래의 방법 4를 참조하세요.
MCP 클라이언트에 서버 추가
이 서버는 MCP 클라이언트(예: Claude Desktop, Windsurf, Cline 등)에서 실행되도록 설계되었습니다. 사용하려면 클라이언트 설정 파일(주로 JSON 파일)에 구성 항목을 추가해야 합니다. 이 항목은 클라이언트에게 서버 프로세스를 실행하는 방법(예: npx , docker 또는 node 사용)을 알려줍니다. 서버 자체는 클라이언트 설정 항목에 지정된 명령줄 인수 외에 별도의 구성이 필요하지 않습니다.
클라이언트 구성에 서버 항목을 추가하는 일반적인 방법은 다음과 같습니다.
방법 1: npx (권장)
npx 사용하면 글로벌/로컬 설치가 필요 없고 클라이언트가 최신 게시 버전을 사용하게 되므로 권장됩니다.
예제 클라이언트 구성 항목(npx 방법):
MCP 클라이언트 구성 파일의 mcpServers 섹션에 다음 JSON 객체를 추가하세요. 이 항목은 클라이언트에게 npx 사용하여 서버를 실행하는 방법을 알려줍니다.
구성 참고 사항:
클라이언트에서
"My API Spec (npx)"이 서버 인스턴스의 고유한 이름으로 바꾸세요.<path-or-url-to-spec>사양의 절대 로컬 파일 경로 또는 전체 원격 URL로 바꾸세요.--output-format선택 사항(json,yaml,json-minified)이며, 기본값은json입니다.여러 사양을 탐색하려면
mcpServers에 각각 고유한 이름을 지정하고 다른 사양을 가리키는 별도 항목을 추가합니다.
방법 2: Docker
공식 Docker 이미지인 kadykov/mcp-openapi-schema-explorer 사용하여 MCP 클라이언트가 서버를 실행하도록 지시할 수 있습니다.
클라이언트 구성 항목 예시(Docker 방법):
MCP 클라이언트 구성 파일의 mcpServers 섹션에 다음 JSON 객체 중 하나를 추가하세요. 이 항목들은 클라이언트에게 docker run 사용하여 서버를 실행하는 방법을 알려줍니다.
원격 URL:
docker run에 URL을 직접 전달합니다.원격 URL 사용:
{ "mcpServers": { "My API Spec (Docker Remote)": { "command": "docker", "args": [ "run", "--rm", "-i", "kadykov/mcp-openapi-schema-explorer:latest", "<remote-url-to-spec>" ], "env": {} } } }로컬 파일 사용: (컨테이너에 파일을 마운트해야 함)
{ "mcpServers": { "My API Spec (Docker Local)": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/full/host/path/to/spec.yaml:/spec/api.yaml", "kadykov/mcp-openapi-schema-explorer:latest", "/spec/api.yaml", "--output-format", "yaml" ], "env": {} } } }중요:
/full/host/path/to/spec.yaml호스트 머신의 올바른 절대 경로로 바꾸세요./spec/api.yaml경로는 컨테이너 내부의 해당 경로입니다.
방법 3: 글로벌 설치(덜 일반적)
npm install -g 사용하여 패키지를 전역으로 설치한 경우 클라이언트를 구성하여 해당 패키지를 직접 실행할 수 있습니다.
클라이언트 구성 항목 예(전역 설치 방법):
MCP 클라이언트 구성 파일에 다음 항목을 추가하세요. 이는 mcp-openapi-schema-explorer 명령이 클라이언트 실행 환경 PATH에서 접근 가능하다는 것을 전제로 합니다.
MCP 클라이언트에서 사용하는 PATH 환경 변수에서
command(mcp-openapi-schema-explorer)에 액세스할 수 있는지 확인하세요.
방법 4: 로컬 개발/설치
이 방법은 개발을 위해 로컬로 저장소를 복제한 경우나 수정된 버전을 실행하려는 경우에 유용합니다.
설정 단계(터미널에서 한 번 실행):
저장소를 복제합니다:
git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git디렉토리로 이동합니다:
cd mcp-openapi-schema-explorer종속성 설치:
npm install프로젝트 빌드:
npm run build(또는just build)
클라이언트 구성 항목 예시(로컬 개발 방법):
MCP 클라이언트 구성 파일에 다음 항목을 추가하세요. 이 항목은 클라이언트가 node 사용하여 로컬로 빌드한 서버를 실행하도록 지시합니다.
중요: /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js 복제된 저장소에 있는 빌드된 index.js 파일의 올바른 절대 경로로 바꾸세요.
특징
MCP 리소스 액세스: 직관적인 URI(
openapi://info,openapi://paths/...,openapi://components/...)를 통해 OpenAPI 사양을 살펴보세요.OpenAPI v3.0 및 Swagger v2.0 지원: 두 형식을 모두 로드하고 v2.0을 v3.0으로 자동 변환합니다.
로컬 및 원격 파일: 로컬 파일 경로 또는 HTTP/HTTPS URL에서 사양을 로드합니다.
토큰 효율성: 구조화된 액세스를 제공하여 LLM의 토큰 사용을 최소화하도록 설계되었습니다.
다양한 출력 형식: JSON(기본값), YAML 또는 축소된 JSON(
--output-format) 형식으로 자세한 보기를 가져옵니다.동적 서버 이름: MCP 클라이언트의 서버 이름은 로드된 사양의
info.title반영합니다.참조 변환: 내부
$ref(#/components/...)는 클릭 가능한 MCP URI로 변환됩니다.
사용 가능한 MCP 리소스
이 서버는 OpenAPI 사양을 탐색하기 위한 다음 MCP 리소스 템플릿을 제공합니다.
다중 값 매개변수 이해(
일부 리소스 템플릿에는 {method*} 또는 {name*} 처럼 별표( * )로 끝나는 매개변수가 포함되어 있습니다. 이는 매개변수가 쉼표로 구분된 여러 값을 허용함을 나타냅니다. 예를 들어, 경로의 GET 및 POST 메서드에 대한 세부 정보를 모두 요청하려면 openapi://paths/users/get,post 와 같은 URI를 사용합니다. 이렇게 하면 단일 요청으로 여러 항목에 대한 세부 정보를 가져올 수 있습니다.
리소스 템플릿:
openapi://{field}설명: OpenAPI 문서의 최상위 필드(예:
info,servers,tags)에 접근하거나paths또는components의 내용을 나열합니다. 사용 가능한 필드는 로드된 사양에 따라 달라집니다.예:
openapi://info출력:
paths및components에 대한text/plain목록, 기타 필드에 대한 구성된 형식(JSON/YAML/최소화된 JSON).완성: 로드된 사양에서 발견된 실제 최상위 키를 기반으로
{field}에 대한 동적 제안을 제공합니다.
openapi://paths/{path}설명: 특정 API 경로에 대해 사용 가능한 HTTP 메서드(작업)를 나열합니다.
매개변수:
{path}- API 경로 문자열입니다. URL로 인코딩되어야 합니다 (예:/users/{id}``users%2F%7Bid%7D가 됩니다).예:
openapi://paths/users%2F%7Bid%7D출력: 메서드의
text/plain목록입니다.완성: 로드된 사양(URL 인코딩)에서 발견된 경로를 기반으로
{path}에 대한 동적 제안을 제공합니다.
openapi://paths/{path}/{method*}설명: 특정 API 경로에 대한 하나 이상의 작업(HTTP 메서드)에 대한 자세한 사양을 가져옵니다.
매개변수:
{path}- API 경로 문자열입니다. URL로 인코딩되어야 합니다 .{method*}- 하나 이상의 HTTP 메서드(예:get,post,get,post). 대소문자를 구분하지 않습니다.
예(단일):
openapi://paths/users%2F%7Bid%7D/get예(다중):
openapi://paths/users%2F%7Bid%7D/get,post출력: 구성된 형식(JSON/YAML/최소화된 JSON).
완성:
{path}에 대한 동적 제안을 제공합니다.{method*}(GET, POST, PUT, DELETE 등 일반적인 HTTP 동사)에 대한 정적 제안을 제공합니다.
openapi://components/{type}설명: 특정 유형의 정의된 모든 구성 요소(예:
schemas,responses,parameters)의 이름을 나열합니다. 사용 가능한 구체적인 유형은 로드된 사양에 따라 달라집니다. 또한 나열된 각 유형에 대한 간략한 설명을 제공합니다.예:
openapi://components/schemas출력: 설명이 포함된 구성 요소 이름의
text/plain목록입니다.완성: 로드된 사양에서 발견된 구성 요소 유형을 기반으로
{type}에 대한 동적 제안을 제공합니다.
openapi://components/{type}/{name*}설명: 특정 유형의 하나 이상의 명명된 구성 요소에 대한 자세한 사양을 가져옵니다.
매개변수:
{type}- 구성 요소 유형입니다.{name*}- 하나 이상의 구성 요소 이름(예:User,Order,User,Order). 대소문자를 구분합니다.
예(단일):
openapi://components/schemas/User예(다중):
openapi://components/schemas/User,Order출력: 구성된 형식(JSON/YAML/최소화된 JSON).
완성:
{type}에 대한 동적 제안을 제공합니다. 로드된 사양에 전체적으로 단 하나의 구성 요소 유형(예:schemas만)만 포함된 경우에만{name*}에 대한 동적 제안을 제공합니다. 이러한 제한은 MCP SDK가 현재 선택된{type}에 대한 완성 제공을 지원하지 않기 때문에 발생합니다. 모든 유형의 모든 이름을 제공하면 오해의 소지가 있을 수 있습니다.
기여하다
기여를 환영합니다! 개발 환경 설정, 테스트 실행, 변경 사항 제출에 대한 지침은 CONTRIBUTING.md 파일을 참조하세요.
출시
이 프로젝트에서는 Conventional Commit을 기반으로 한 자동화된 버전 관리 및 패키지 게시를 위해 semantic-release 사용합니다.
미래 계획
(향후 계획은 추후 결정)