swagger-mcp-server

seeeeeeong/swagger-mcp-server

3.2

If you are the rightful owner of swagger-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This server provides Swagger API documentation to LLMs using the Model Context Protocol (MCP).

Tools
6
Resources
0
Prompts
0

Swagger MCP Server

Swagger API 문서를 LLM에 제공하는 MCP 서버입니다.

아키텍처

┌─────────────────┐         ┌──────────────────┐         ┌──────────────┐
│   blog-api      │         │  swagger-mcp     │         │     LLM      │
│  (Spring Boot)  │◄────────│     -server      │◄────────│ (Claude/GPT) │
│                 │ Swagger │  (MCP Protocol)  │  HTTP   │              │
│ :8080           │  JSON   │  :8081           │ Request │              │
└─────────────────┘         └──────────────────┘         └──────────────┘

기능

MCP(Model Context Protocol)를 통해 LLM이 Swagger API 문서를 자동으로 조회하고 활용할 수 있습니다.

제공하는 Tools

  1. getApiTags: 사용 가능한 API 태그 목록 조회
  2. getApisByTag: 특정 태그의 모든 API 목록 조회
  3. getApiDetail: 특정 API의 상세 정보 (파라미터, 요청 본문, 응답)
  4. getComponentSchema: 컴포넌트 스키마 정의 조회 (DTO 구조)
  5. getFullSwaggerJson: 전체 Swagger JSON 문서 조회
  6. refreshSwaggerCache: Swagger 캐시 새로고침

API 사용 예시

1. Tool 목록 조회

curl http://localhost:8081/mcp/tools

응답:

{
  "tools": [
    {
      "name": "getApiTags",
      "description": "Get all available API tags (service categories)",
      "parameters": {}
    },
    ...
  ]
}

2. API 태그 목록 조회

curl -X POST http://localhost:8081/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "toolName": "getApiTags"
  }'

응답:

{
  "success": true,
  "result": "=== Available API Tags ===\n- Post: 블로그 게시글 API\n- User: 사용자 인증 및 관리 API\n- Category: 카테고리 API"
}

3. 특정 태그의 API 목록 조회

curl -X POST http://localhost:8081/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "toolName": "getApisByTag",
    "parameters": {
      "tagName": "Post"
    }
  }'

응답:

{
  "success": true,
  "result": "=== APIs for tag: Post ===\n\n[POST] /api/posts\n  Summary: 게시글 작성\n  Description: 새로운 블로그 게시글을 작성합니다.\n\n[GET] /api/posts/{postId}\n  Summary: 게시글 상세 조회\n..."
}

4. API 상세 정보 조회

curl -X POST http://localhost:8081/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "toolName": "getApiDetail",
    "parameters": {
      "path": "/api/posts",
      "method": "GET"
    }
  }'

응답:

{
  "success": true,
  "result": "=== API Detail ===\nPath: /api/posts\nMethod: GET\nSummary: 게시글 목록 조회\n...\nParameters:\n  - page (query)\n    Description: 페이지 번호\n    Required: false\n    Schema: {\"type\":\"integer\"}"
}

5. 컴포넌트 스키마 조회

curl -X POST http://localhost:8081/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "toolName": "getComponentSchema",
    "parameters": {
      "schemaName": "CreatePostRequest"
    }
  }'

LLM 통합 시나리오

시나리오 1: "게시글 작성 API 알려줘"

  1. LLM이 getApiTags를 호출하여 "Post" 태그 확인
  2. getApisByTag("Post")를 호출하여 게시글 관련 API 목록 확인
  3. getApiDetail("/api/posts", "POST")를 호출하여 상세 정보 확인
  4. 사용자에게 완전한 API 정보 제공

시나리오 2: "카테고리별 게시글 조회 API 사용법"

  1. LLM이 getApisByTag("Post")에서 관련 엔드포인트 찾기
  2. getApiDetail("/api/posts/categories/{categoryId}", "GET") 호출
  3. 파라미터, 응답 형식 등 상세 정보 제공

기술 스택

  • Spring Boot 3.5.7: 웹 애플리케이션 프레임워크
  • Spring-AI 1.0.0-M5: MCP Tools 구현
  • Kotlin 1.9.25: 프로그래밍 언어
  • Jackson: JSON 파싱
  • RestTemplate: HTTP 클라이언트

설정

src/main/resources/application.yml:

blog:
  api:
    url: http://localhost:8080
    swagger-json-path: /v3/api-docs

server:
  port: 8081

참고 자료