# Swagger/OpenAPI MCP Server (Streamable HTTP)

这是一个基于 **MCP (Model Context Protocol)** 的服务端应用，专为 AI 辅助开发设计。

它采用 **Streamable HTTP** 协议运行，能够扫描您本地的 OpenAPI/Swagger 文档目录，使 AI (如 Claude, Cursor) 能够理解您的后端接口结构、查询详细定义，甚至为您生成前端 TypeScript 类型代码。

## 🌟 核心特性

- **智能文档索引**：AI 可以扫描指定文件夹下的所有 `.yaml` / `.json` 文件并自动聚合。
- **基于 Tag 分组**：支持按业务 Tag (如 `Auth`, `Users`) 查看接口，跨文件聚合，更符合业务逻辑。
- **TypeScript 类型生成**：集成 `openapi-typescript`，直接为特定接口生成精简的 TypeScript `interface` (Query/Body/Response)。
- **缓存热更新**：支持手动刷新缓存，即时同步文档变更。

## 📥 下载与运行

### 1. 下载项目

```bash
git clone https://github.com/dreamhuan/swagger-openapi-mcp.git
cd swagger-openapi-mcp
```

### 2. 安装依赖

```bash
pnpm install
```

### 3. 环境配置

复制 `.env.sample` 为 `.env`，并修改 `OPENAPI_DIR_PATH` 为你本地 Swagger/OpenAPI 文件所在的**绝对路径**。

```bash
cp .env.sample .env
```

`.env` 示例：

```ini
OPENAPI_DIR_PATH=/Users/username/my-project/docs
PORT=3030
```

注意这是一个文件夹的路径，里面存放所有的xxx.yaml，有一个api.yaml作为入口

### 4. 启动服务

```bash
pnpm dev
```

服务启动后，Endpoint 地址为: `http://localhost:3030/mcp`

## ⚙️ MCP 客户端配置

```json
{
  "mcpServers": {
    "openapi-tools": {
      "transport": "http",
      "url": "http://localhost:3030/mcp"
    }
  }
}
```

## 🤖 可用工具 (Tools)

### 1. `list_api_group`

- **功能**：列出当前所有可用的 API Tags (业务分组)。
- **示例输出**：`["auth", "billing", "users"]`

### 2. `list_api_structure`

- **功能**：列出 API 路径概览。支持按 Tag 过滤。
- **参数**：
  - `tags` (可选, string[]): 指定 Tag 列表。建议先调用 `list_api_group` 获取 Tag，然后指定此参数以减少输出量。
  - 示例: `{"tags": ["auth", "files"]}`

### 3. `get_endpoint_types`

- **功能**：精准提取特定接口的 TypeScript 类型定义 (Query Params, Request Body, Response)。
- **参数**：
  - `path` (如 `/users/{id}`)
  - `method` (如 `POST`)

### 4. `refresh_api_cache`

- **功能**：清除内存缓存并重新解析 OpenAPI 文件。当您修改了 YAML 文件后调用此工具。

## 📦 推荐的 AI 工作流

1.  **AI**: "先看看有哪些 API 业务分组。" -> 调用 `list_api_group`。
2.  **AI**: "我看有 `auth` 模块，列出里面的接口。" -> 调用 `list_api_structure(tags=["auth"])`。
3.  **AI**: "需要 `/auth/login` 接口的类型定义。" -> 调用 `get_endpoint_types(path="/auth/login", method="POST")`。