OpenAPI Schema Explorer

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으로 자동 변환됩니다.

왜 MCP Resources인가요?

모델 컨텍스트 프로토콜은 리소스 와 도구를 모두 정의합니다.

• 리소스: 데이터 소스(파일, API 응답 등)를 나타냅니다. MCP 클라이언트의 읽기 전용 액세스 및 탐색(예: Claude Desktop에서 API 경로 탐색)에 적합합니다.
• 도구: LLM이 작업을 수행하거나 외부 시스템과 상호 작용하는 데 자주 사용되는 실행 가능한 동작이나 기능을 나타냅니다.

Tools를 통해 OpenAPI 사양에 대한 액세스를 제공하는 다른 MCP 서버도 있지만, 이 프로젝트는 Resources를 통해 액세스를 제공하는 데 중점을 둡니다. 따라서 MCP 클라이언트 애플리케이션 내에서 직접 탐색하는 데 특히 유용합니다.

MCP 클라이언트와 해당 기능에 대한 자세한 내용은 MCP 클라이언트 설명서를 참조하세요.

설치

권장 사용 방법(아래에 설명된 npx 및 Docker)의 경우 별도의 설치 단계가 필요하지 않습니다 . MCP 클라이언트는 사용자가 제공한 구성에 따라 자동으로 패키지를 다운로드하거나 Docker 이미지를 가져옵니다.

하지만 서버를 명시적으로 설치해야 하거나 선호한다면 두 가지 옵션이 있습니다.

1. 글로벌 설치: npm을 사용하여 패키지를 글로벌하게 설치할 수 있습니다.지엑스피1글로벌하게 설치된 서버를 사용하도록 MCP 클라이언트를 구성하는 방법은 아래의 방법 3을 참조하세요.
2. 로컬 개발/설치: 저장소를 복제하여 로컬로 빌드할 수 있습니다.
   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: 로컬 개발/설치

이 방법은 개발을 위해 로컬로 저장소를 복제한 경우나 수정된 버전을 실행하려는 경우에 유용합니다.

설정 단계(터미널에서 한 번 실행):

1. 저장소를 복제합니다: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
2. 디렉토리로 이동합니다: cd mcp-openapi-schema-explorer
3. 종속성 설치: npm install
4. 프로젝트 빌드: 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/{id} 가 됩니다).
  • 예: openapi://paths/users/{id}
  • 출력: 메서드의 text/plain 목록입니다.
  • 완성: 로드된 사양(URL 인코딩)에서 발견된 경로를 기반으로 {path} 에 대한 동적 제안을 제공합니다.
• openapi://paths/{path}/{method*}
  • 설명: 특정 API 경로에 대한 하나 이상의 작업(HTTP 메서드)에 대한 자세한 사양을 가져옵니다.
  • 매개변수:
    • {path} - API 경로 문자열입니다. URL로 인코딩되어야 합니다 .
    • {method*} - 하나 이상의 HTTP 메서드(예: get , post , get,post ). 대소문자를 구분하지 않습니다.
  • 예(단일): openapi://paths/users/{id}/get
  • 예(다중): openapi://paths/users/{id}/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 사용합니다.

미래 계획

(향후 계획은 추후 결정)