Skip to content

About

πŸ“¬ Swagger/OpenAPI MCP server for natural-language API search and code generation in Claude Code

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Swagger MCP Server

Backend API의 Swagger λ¬Έμ„œλ₯Ό MCP μ„œλ²„λ‘œ μ œκ³΅ν•˜μ—¬, ν΄λΌμ΄μ–ΈνŠΈ κ°œλ°œμžκ°€ Claude Codeμ—μ„œ μžμ—°μ–΄λ‘œ APIλ₯Ό κ²€μƒ‰ν•˜κ³  μ™„μ „ν•œ λ„€νŠΈμ›Œν‚Ή μ½”λ“œλ₯Ό μžλ™ 생성할 수 μžˆλ„λ‘ ν•˜λŠ” μ‹œμŠ€ν…œμž…λ‹ˆλ‹€.

기쑴에 Swagger UIλ₯Ό 직접 νƒμƒ‰ν•˜λ©° μ—”λ“œν¬μΈνŠΈ, μš”μ²­/응닡 ꡬ쑰λ₯Ό ν™•μΈν•˜λ˜ 과정을 LLM 기반 쑰회둜 λŒ€μ²΄ν•΄ λ‹¨μΆ•ν•©λ‹ˆλ‹€.

🎯 핡심 μ‹œλ‚˜λ¦¬μ˜€

개발자: "둜그인 API μ°Ύμ•„μ„œ DTO λ§Œλ“€μ–΄μ€˜"
    ↓
Claudeκ°€ μžλ™μœΌλ‘œ:
1. searchApiByKeyword("둜그인") 호좜 β†’ API μ°ΎκΈ°
2. getApiDetail(apiId) 호좜 β†’ Request/Response μŠ€ν‚€λ§ˆ 쑰회
3. μ¦‰μ‹œ Front-end DTO μ½”λ“œ 생성 + λ„€νŠΈμ›Œν¬ 호좜 μ½”λ“œ μž‘μ„±

✨ μ£Όμš” κΈ°λŠ₯

1. Swagger νŒŒμ‹± 및 DB μ €μž₯

  • Backend μ„œλ²„μ˜ OpenAPI 3.0 JSON λ‹€μš΄λ‘œλ“œ 및 νŒŒμ‹±
  • $ref Resolution: #/components/schemas/LoginRequest β†’ μ‹€μ œ schema ꡬ쑰둜 λ³€ν™˜
  • API μ—”λ“œν¬μΈνŠΈ, Request/Response/Error μŠ€ν‚€λ§ˆλ₯Ό MySQL에 ꡬ쑰화 μ €μž₯
  • μ—λŸ¬ μ½”λ“œ ν˜•μ‹ νŒŒμ‹±: DOMAIN-CATEGORY-DETAIL

2. MCP Tools 제곡 (Spring AI MCP)

  • searchApiByKeyword: ν‚€μ›Œλ“œλ‘œ API 검색 (path, summary, description, operationId)
  • getApiDetail: API 상세 정보 쑰회 (Request, Response, Error 포함)
  • getRequestFormat: Request DTO μŠ€ν‚€λ§ˆ λ°˜ν™˜
  • getResponseFormat: Success Response DTO μŠ€ν‚€λ§ˆ λ°˜ν™˜
  • getErrorFormats: Error Response λͺ©λ‘ λ°˜ν™˜

3. AI μΉœν™”μ  응닡 포맷

  • DB μ €μž₯ 포맷 β†’ AIκ°€ μ΄ν•΄ν•˜κΈ° μ‰¬μš΄ ꡬ쑰둜 λ³€ν™˜ (SchemaSupporter)
  • 쀑첩 객체, λ°°μ—΄ νƒ€μž…, Required/Optional ν•„λ“œ λͺ…ν™•ν•˜κ²Œ ꡬ뢄
  • Example κ°’ 제곡으둜 μ¦‰μ‹œ μ½”λ“œ 생성 κ°€λŠ₯

πŸ—οΈ μ•„ν‚€ν…μ²˜

4-Layer Architecture

Controller β†’ Facade(UseCase) β†’ Service β†’ Repository
  • Controller: HTTP μš”μ²­/응닡 처리, UseCase만 의쑴
  • UseCase(Facade): μ—¬λŸ¬ Service μ‘°ν•© (orchestration)
  • Service: 단일 μ±…μž„ 원칙에 λ”°λ₯Έ μ„ΈλΆ„ν™”λœ λΉ„μ¦ˆλ‹ˆμŠ€ 둜직
  • Repository: Spring Data JPA 기반 데이터 μ ‘κ·Ό

Swagger 동기화 ν”Œλ‘œμš°

SyncController
    ↓
SyncSwaggerUseCase (Facade)
    β”œβ”€β†’ SwaggerFetchService     (Swagger JSON λ‹€μš΄λ‘œλ“œ)
    β”œβ”€β†’ SwaggerExtractorService (메타데이터 μΆ”μΆœ)
    β”œβ”€β†’ SwaggerParserService    (νŒŒμ‹± μ˜€μΌ€μŠ€νŠΈλ ˆμ΄μ…˜)
    β”‚       β”œβ”€ EndpointBasicInfoParser
    β”‚       β”œβ”€ RequestSchemaParser  ($ref resolution)
    β”‚       β”œβ”€ ResponseSchemaParser ($ref resolution)
    β”‚       └─ ErrorResponseParser  ($ref resolution, μ—λŸ¬ μ½”λ“œ νŒŒμ‹±)
    └─→ SwaggerSyncService      (DB μ €μž₯)

MCP 쑰회 ν”Œλ‘œμš°

Claude Code
    ↓
SwaggerMcpTools (@McpTool)
    ↓
ApiSearchService
    β”œβ”€β†’ Repository (DB 쑰회)
    └─→ SchemaSupporter (DB 포맷 β†’ AI μΉœν™”μ  포맷)

πŸ› οΈ 기술 μŠ€νƒ

μΉ΄ν…Œκ³ λ¦¬ 기술
Framework Spring Boot 3.5.9
Language Java 21
Database MySQL 8.0
ORM Spring Data JPA
MCP Spring AI MCP 1.1.2
Parser Jackson, Swagger Parser 2.1.40
Utility Lombok
Deploy Docker, GitHub Actions

πŸ“ ν”„λ‘œμ νŠΈ ꡬ쑰

src/main/java/com/kimjiwon/apispecmcp/
β”œβ”€β”€ sync/                          # Swagger 동기화 도메인
β”‚   β”œβ”€β”€ presentation/http/
β”‚   β”‚   └── SyncController
β”‚   β”œβ”€β”€ application/
β”‚   β”‚   β”œβ”€β”€ usecase/
β”‚   β”‚   β”‚   └── SyncSwaggerUseCase  (Facade)
β”‚   β”‚   β”œβ”€β”€ service/
β”‚   β”‚   β”‚   β”œβ”€β”€ SwaggerFetchService
β”‚   β”‚   β”‚   β”œβ”€β”€ SwaggerParserService
β”‚   β”‚   β”‚   β”œβ”€β”€ SwaggerExtractorService
β”‚   β”‚   β”‚   └── SwaggerSyncService
β”‚   β”‚   └── parser/
β”‚   β”‚       β”œβ”€β”€ EndpointBasicInfoParser
β”‚   β”‚       β”œβ”€β”€ RequestSchemaParser
β”‚   β”‚       β”œβ”€β”€ ResponseSchemaParser
β”‚   β”‚       β”œβ”€β”€ ErrorResponseParser
β”‚   β”œβ”€β”€ utils/
β”‚   β”‚   └── JsonSchemaParsingUtil  ($ref 해석, Example μΆ”μΆœ)
β”‚   └── dto/
β”‚       β”œβ”€β”€ ParsedApiEndpoint
β”‚       β”œβ”€β”€ ParsedRequestBody
β”‚       β”œβ”€β”€ ParsedParameter
β”‚       β”œβ”€β”€ ParsedResponseSchema
β”‚       └── ParsedErrorResponse
β”‚
β”œβ”€β”€ ai/                            # MCP μ„œλ²„ 도메인
β”‚   β”œβ”€β”€ presentation/mcp/
β”‚   β”‚   └── SwaggerMcpTools        (MCP Tool κ΅¬ν˜„)
β”‚   β”œβ”€β”€ service/
β”‚   β”‚   └── ApiSearchService
β”‚   β”œβ”€β”€ support/
β”‚   β”‚   └── SchemaSupporter        (DB 포맷 β†’ AI μΉœν™”μ  포맷)
β”‚   └── dto/
β”‚       β”œβ”€β”€ ApiDetailForAI
β”‚       β”œβ”€β”€ RequestForAI
β”‚       β”œβ”€β”€ ResponseForAI
β”‚       β”œβ”€β”€ ErrorForAI
β”‚       β”œβ”€β”€ FieldInfo
β”‚       β”œβ”€β”€ ParameterInfo
β”‚       └── ApiSummary
β”‚
β”œβ”€β”€ persistence/                   # 데이터 μ ‘κ·Ό 계측
β”‚   β”œβ”€β”€ entity/
β”‚   β”‚   β”œβ”€β”€ ApiEndpoint
β”‚   β”‚   β”œβ”€β”€ RequestSchema
β”‚   β”‚   β”œβ”€β”€ Parameter
β”‚   β”‚   β”œβ”€β”€ ResponseSchema
β”‚   β”‚   β”œβ”€β”€ ErrorResponse
β”‚   β”‚   └── SwaggerMetadata
β”‚   └── repository/
β”‚
└── common/
    β”œβ”€β”€ config/
    β”‚   β”œβ”€β”€ JpaConfig
    β”‚   β”œβ”€β”€ JacksonConfig    
    β”‚   └── RestClientConfig
    └── filter/
        └── ApiKeyAuthFilter       (MCP 인증)

πŸ“‹ MCP Tools λͺ…μ„Έ

1. searchApiByKeyword(keyword: String)

μ„€λͺ…: ν‚€μ›Œλ“œλ‘œ API 검색 검색 λŒ€μƒ: path, summary, description, operationId λ°˜ν™˜: List<ApiSummary> (id, method, path, summary, tags)

μ˜ˆμ‹œ:

searchApiByKeyword("둜그인")
β†’ [
    {
      "id": 1,
      "method": "POST",
      "path": "/api/v1/auth/login",
      "summary": "μ‚¬μš©μž 둜그인",
      "tags": ["인증"]
    }
  ]

2. getApiDetail(apiId: Long)

μ„€λͺ…: API 상세 정보 쑰회 (Request, Response, Error 포함) λ°˜ν™˜: ApiDetailForAI

응닡 ꡬ쑰:

{
  "id": 1,
  "method": "POST",
  "path": "/api/v1/auth/login",
  "summary": "μ‚¬μš©μž 둜그인",
  "request": {
    "body": {
      "email": {"type": "string", "required": true, "example": "user@example.com"},
      "password": {"type": "string", "required": true, "example": "password123"}
    },
    "parameters": []
  },
  "responses": {
    "200": {"fields": {"accessToken": {"type": "string"}, "refreshToken": {"type": "string"}}}
  },
  "errors": {
    "401": {"code": "AUTH-LOGIN-INVALID_CREDENTIALS", "message": "인증 μ‹€νŒ¨"}
  }
}

3. getRequestFormat(apiId: Long)

μ„€λͺ…: Request Body + Parameters 쑰회 / λ°˜ν™˜: RequestForAI

4. getResponseFormat(apiId: Long)

μ„€λͺ…: μƒνƒœ μ½”λ“œλ³„ Success Response 쑰회 / λ°˜ν™˜: Map<Integer, ResponseForAI>

5. getErrorFormats(apiId: Long)

μ„€λͺ…: μƒνƒœ μ½”λ“œλ³„ Error Response 쑰회 / λ°˜ν™˜: Map<Integer, ErrorForAI>

πŸš€ λΉŒλ“œ 및 μ‹€ν–‰

사전 μš”κ΅¬μ‚¬ν•­

  • Java 21+
  • Docker

둜컬 μ‹€ν–‰

# 1. .env 파일 생성
cp .env.example .env  # κ°’ μ±„μ›Œλ„£κΈ°

# 2. μ»¨ν…Œμ΄λ„ˆ μ‹€ν–‰ (MySQL + App)
docker compose up -d

# 3. λ˜λŠ” 둜컬 직접 μ‹€ν–‰
./gradlew bootRun

.env μ„€μ •κ°’

MYSQL_ROOT_PASSWORD=
MYSQL_DATABASE=
MYSQL_USER=
MYSQL_PASSWORD=
MCP_ACCESS_TOKEN=
APP_IMAGE=

MCP μ—”λ“œν¬μΈνŠΈ

GET /mcp
Authorization: Bearer {MCP_ACCESS_TOKEN}

πŸ”— Claude Code μ—°κ²°

claude mcp add --transport http swagger-mcp http://{SERVER_IP}:{SERVER_PORT}/mcp \
  --header "Authorization: Bearer {MCP_ACCESS_TOKEN}" --scope project

About

πŸ“¬ Swagger/OpenAPI MCP server for natural-language API search and code generation in Claude Code

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages