스웨거 MCP

Swagger 사양에 연결하고 AI가 해당 서비스에 대한 MCP 서버를 생성하는 데 필요한 모든 모델을 구축하는 데 도움이 되는 MCP 서버입니다.

특징

Swagger 사양을 다운로드하여 더 빠르게 참조할 수 있도록 로컬에 저장합니다.
모든 엔드포인트와 해당 HTTP 메서드 및 설명의 목록을 반환합니다.
모든 모델의 목록을 반환합니다.
모델을 반환합니다
종단점에 연결하기 위한 서비스 반환
MCP 함수 정의를 반환합니다.
전체 스키마 정보를 사용하여 완전한 MCP 도구 정의를 생성합니다.
도구 설명에 AI 관련 지침이 포함되어 있습니다.

필수 조건

Node.js(v14 이상)
npm 또는 yarn

설치

저장소를 복제합니다.

지엑스피1

종속성 설치:

npm install

.env.example 파일을 기반으로 .env 파일을 만듭니다.

cp .env.example .env

.env 파일을 업데이트합니다.

구성

.env 파일을 편집하여 애플리케이션을 구성합니다.

PORT : 서버가 실행될 포트(기본값: 3000)
NODE_ENV : 환경(개발, 프로덕션, 테스트)
LOG_LEVEL : 로깅 레벨(정보, 오류, 디버그)

용법

애플리케이션 구축

애플리케이션을 빌드하세요:

npm run build

이렇게 하면 MCP 서버로 사용할 준비가 된 TypeScript 코드가 컴파일됩니다.

MCP 서버로 실행

Cursor 및 기타 애플리케이션과 통합하기 위해 MCP 서버로 실행하려면:

node build/index.js

MCP 검사기 사용

디버깅을 위해 MCP 검사기를 실행하려면:

npm run inspector

커서에 추가

이 MCP 서버를 Cursor에 추가하려면:

커서 설정 > 기능 > MCP 열기
"+ 새 MCP 서버 추가"를 클릭하세요
서버 이름을 입력하세요(예: "Swagger MCP")
전송 유형으로 "stdio"를 선택하세요
서버를 실행하려면 다음 명령을 입력하세요: node path/to/swagger-mcp/build/index.js 그리고 필요한 경우 위에서 언급한 대로 명령줄 인수를 추가합니다.
"추가"를 클릭하세요

이제 Composer의 커서 에이전트에서 Swagger MCP 도구를 사용할 수 있습니다.

사용 가능한 Swagger MCP 도구

다음 도구는 MCP 서버를 통해 사용할 수 있습니다.

getSwaggerDefinition : URL에서 Swagger 정의를 다운로드합니다.
listEndpoints : Swagger 정의의 모든 엔드포인트를 나열합니다.
listEndpointModels : 특정 엔드포인트에서 사용되는 모든 모델을 나열합니다.
generateModelCode : 모델에 대한 TypeScript 코드를 생성합니다.
generateEndpointToolCode : MCP 도구 정의에 대한 TypeScript 코드를 생성합니다.

사용 가능한 Swagger MCP 프롬프트

이 서버는 또한 AI 어시스턴트를 일반적인 워크플로로 안내하는 MCP 프롬프트를 제공합니다.

add-endpoint : Swagger MCP 도구를 사용하여 새 엔드포인트를 추가하기 위한 단계별 가이드

프롬프트를 사용하려면 클라이언트가 프롬프트 이름과 선택적 인수를 사용하여 prompts/get 요청을 만들 수 있습니다.

{
  "method": "prompts/get",
  "params": {
    "name": "add-endpoint",
    "arguments": {
      "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
      "endpointPath": "/pets/{id}",
      "httpMethod": "GET"
    }
  }
}

프롬프트는 AI 어시스턴트가 새로운 엔드포인트를 추가하는 데 필요한 정확한 프로세스를 안내하는 일련의 메시지를 반환합니다.

새 프로젝트 설정

먼저 에이전트에게 Swagger 파일을 가져오라고 요청하고, Swagger 파일의 URL을 알려주거나 적어도 파일을 찾을 수 있는 방법을 알려주세요. 이렇게 하면 파일이 다운로드되어 해시된 파일 이름으로 로컬에 저장됩니다. 이 파일 이름은 현재 솔루션의 루트에 있는 .swagger-mcp 설정 파일에 자동으로 추가됩니다.

자동 생성된 .swagger-mcp 구성 파일

SWAGGER_FILENAME = TheFilenameOfTheLocallyStoredSwaggerFile

이 간단한 구성 파일은 현재 프로젝트를 특정 Swagger API와 연결하며, 나중에 더 자세한 내용을 저장하는 데 사용할 수 있습니다.

MCP를 구성하면 Swagger 정의를 찾아 현재 솔루션과 연결할 수 있으며, 작업 중인 솔루션과 관련된 프로젝트 및 작업을 가져오는 데 필요한 API 호출 수가 줄어듭니다.

개선된 MCP 도구 코드 생성기

MCP 도구 코드 생성기가 더욱 완전하고 사용 가능한 도구 정의를 제공하도록 향상되었습니다.

주요 개선 사항

완전한 스키마 정보 : 생성기는 이제 중첩된 객체를 포함한 모든 모델에 대한 완전한 스키마 정보를 inputSchema에 직접 포함합니다.
더 나은 매개변수 명명 : 매개변수 이름이 이제 더 의미론적으로 바뀌었고 마침표와 같은 문제가 있는 문자가 사용되지 않습니다(예: taskRequest 대신 task.Request ).
의미적 도구 이름 : 도구 이름이 이제 더 설명적이며 HTTP 메서드와 리소스 경로를 기반으로 일관된 명명 규칙을 따릅니다.
YAML Swagger 파일 지원 : 생성기는 이제 JSON과 YAML Swagger 정의 파일을 모두 지원합니다.
개선된 문서화 : 생성된 도구 정의에는 모든 매개변수와 속성에 대한 포괄적인 설명이 포함됩니다.
외부 종속성 없음 : 생성된 코드는 외부 모델 파일을 가져올 필요가 없으므로 더욱 독립적이고 사용하기 쉽습니다.
AI 전용 지침 : 도구 설명에 이제 AI 에이전트를 위한 특별 지침이 포함되어 도구를 효과적으로 사용하는 방법을 이해하는 데 도움이 됩니다.

사용 예

엔드포인트에 대한 MCP 도구 정의를 생성하려면 다음을 수행합니다.

import generateEndpointToolCode from './services/generateEndpointToolCode.js';

const toolCode = await generateEndpointToolCode({
  path: '/pets',
  method: 'POST',
  swaggerFilePath: './petstore.json',
  singularizeResourceNames: true
});

console.log(toolCode);

이렇게 하면 POST /pets 엔드포인트에 대한 전체 스키마 정보가 포함된 완전한 MCP 도구 정의가 생성됩니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

AI 어시스턴트를 위한 MCP 프롬프트

AI 어시스턴트가 Swagger MCP 도구를 효과적으로 사용할 수 있도록, 일반적인 작업을 안내하는 프롬프트 모음을 만들었습니다. 이 프롬프트는 새 엔드포인트 추가, 생성된 모델 사용 등의 프로세스에 대한 단계별 지침을 제공합니다.

전체 프롬프트 컬렉션은 PROMPTS.md 파일에서 확인하세요.

예시 사용 사례: AI 어시스턴트에게 프로젝트에 새로운 엔드포인트를 추가하도록 요청할 때 "새로운 엔드포인트 추가" 프롬프트를 참조하여 어시스턴트가 올바른 순서대로 올바른 프로세스를 따르도록 할 수 있습니다.

Integrations