# API MCP 서버

Swagger/OpenAPI 스펙 기반의 Model Context Protocol (MCP) 서버입니다. OpenAPI 문서를 통해 API 목록과 상세 정보를 조회할 수 있는 도구를 제공합니다.

## 기능

### 도구 (Tools)

- **`getApiList`** - API 목록 조회

  - OpenAPI 스펙에서 모든 API 엔드포인트 목록을 조회합니다.
  - 반환 형식: 각 경로별 HTTP 메서드와 `tags`, `operationId`, `summary` 정보

- **`getApiDetail`** - API 상세 조회
  - 특정 API의 상세 정보를 조회합니다.
  - 파라미터: `requestUrl` (string), `httpMethod` (get|post|put|delete|patch)
  - 반환 형식: `parameters`, `requestBody`, `responses` 정보

### 리소스 (Resources)

- **`greeting://{name}`** - 동적 인사말 생성 리소스

## 설치

### NPM 패키지로 설치

```bash
npm install @koseha/api-mcp
```

또는

```bash
npm install @koseha/api-mcp@latest
```

## 사용 방법

### 방법 1: Cursor IDE 에서 사용

Cursor 설정 파일에 추가:

```
{
  "mcpServers": {
    "api-mcp": {
      "command": "node",
      "args": ["./node_modules/@koseha/api-mcp/dist/index.js"],
      "env": {
        "OPENAPI_URL": <your swagger.json url ex.'https://petstore3.swagger.io/api/v3/openapi.json'>
      }
    }
  }
}

```

### 방법 2: Claude Desktop에서 사용

Claude Desktop 설정 파일에 추가:

**macOS:**

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**

```
%APPDATA%\Claude\claude_desktop_config.json
```

설정 예시:

```json
{
  "mcpServers": {
    "api-mcp": {
      "command": "npx",
      "args": ["-y", "@koseha/api-mcp"],
      "env": {
        "OPENAPI_URL": "https://api.example.com/openapi.json"
      }
    }
  }
}
```

또는 로컬 경로 사용:

```json
{
  "mcpServers": {
    "api-mcp": {
      "command": "node",
      "args": ["/path/to/api-mcp/dist/index.js"],
      "env": {
        "OPENAPI_URL": "https://api.example.com/openapi.json"
      }
    }
  }
}
```

### 방법 3: Node.js 프로젝트에서 직접 사용

```javascript
import { spawn } from "child_process";

const mcpServer = spawn("npx", ["-y", "@koseha/api-mcp"], {
  stdio: ["pipe", "pipe", "pipe"],
});

// JSON-RPC 요청 보내기
function sendRequest(method, params) {
  const request = {
    jsonrpc: "2.0",
    id: Date.now(),
    method,
    params: params || {},
  };
  mcpServer.stdin?.write(JSON.stringify(request) + "\n");
}

// API 목록 조회
sendRequest("tools/call", {
  name: "getApiList",
  arguments: {},
});

// API 상세 조회
sendRequest("tools/call", {
  name: "getApiDetail",
  arguments: {
    requestUrl: "/pet/{petId}/uploadImage",
    httpMethod: "post",
  },
});
```

### 방법 4: 로컬 개발 중 사용

#### npm link 사용

현재 프로젝트에서:

```bash
npm link
```

다른 프로젝트에서:

```bash
npm link @koseha/api-mcp
```

#### 상대 경로 사용

다른 프로젝트의 `package.json`에 추가:

```json
{
  "dependencies": {
    "@koseha/api-mcp": "file:../api-mcp"
  }
}
```

## 개발

### 사전 요구사항

- Node.js 18 이상
- npm 또는 yarn

### 설치

```bash
npm install
```

### 빌드

```bash
npm run build
```

### 실행

```bash
npm start
```

또는 개발 모드:

```bash
npm run dev
```

## 프로젝트 구조

```
api-mcp/
├── src/
│   ├── index.ts              # MCP 서버 엔트리포인트
│   ├── server.ts             # 서버 생성 로직
│   ├── tools/                # 도구 모듈
│   │   ├── index.ts
│   │   ├── getApiList.tool.ts    # API 목록 조회 도구
│   │   └── getApiDetail.tool.ts  # API 상세 조회 도구
│   ├── resources/            # 리소스 모듈
│   │   ├── index.ts
│   │   └── greeting.resource.ts
│   └── swagger/              # Swagger 로더 및 변환기
│       ├── swaggerLoader.ts
│       ├── apiTransformer.ts
│       ├── schemaResolver.ts
│       └── types.ts
├── dist/                     # 빌드된 파일
├── openapi.json             # OpenAPI 스펙 파일
├── package.json
├── tsconfig.json
└── README.md
```

## OpenAPI 스펙 설정

`OPENAPI_URL` 환경 변수를 통해 OpenAPI 문서의 URL을 설정해야 합니다. 서버 시작 시 이 환경 변수가 설정되지 않으면 서버가 시작되지 않습니다.

예시:

```bash
export OPENAPI_URL=https://api.example.com/openapi.json
```

## 의존성

### 프로덕션 의존성

- `@modelcontextprotocol/sdk`: MCP SDK (^1.25.1)
- `zod`: 스키마 검증 (^4.2.1)

### 개발 의존성

- `typescript`: 타입스크립트 컴파일러 (^5.9.3)
- `@types/node`: Node.js 타입 정의 (^25.0.3)
- `ts-node`: TypeScript 실행 도구 (^10.9.2)

## 버전

현재 버전: **0.0.10**

## History

| 버전   | 날짜           | 변경사항                                                                                                                                                |
| ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0.0.10 | KST 2025.12.31 | - OpenAPI 문서를 HTTP 요청으로 로드하도록 변경 <br/> - OPENAPI_URL 환경 변수 필수 검증 추가 <br/> - API 상세 조회 로직 리팩토링 (apiTransformer 모듈화) |
| 0.0.7  | KST 2025.12.31 | - tool 요청 시 openapi.json 문서의 특정 부분만 추출하여 사용하도록 변경 <br/> >> 전체 openapi.json 문서 내용이 사용되지 않도록 함. token 절약           |

## 라이선스

ISC

## 참고 자료

- [MCP 공식 문서](https://modelcontextprotocol.io)
- [MCP SDK GitHub](https://github.com/modelcontextprotocol/typescript-sdk)
- [OpenAPI 스펙](https://swagger.io/specification/)

## 기여

이슈나 풀 리퀘스트는 [GitHub 저장소](https://github.com/koseha/api-mcp)에서 환영합니다.