Metadata-Version: 2.4
Name: yonglelaoren-openapi-mcp
Version: 0.4.0
Summary: OpenAPI MCP Server - 基于 Model Context Protocol 的 OpenAPI 规范解析服务器
Author-email: yongle <yonglelaoren@163.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.25.0
Requires-Dist: prance>=23.6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: openapi-spec-validator>=0.7.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# OpenAPI MCP Server

基于 Model Context Protocol 的 OpenAPI 规范解析服务器。

## 功能特性

- 解析 OpenAPI 3.0 规范（支持本地文件和远程 URL）
- 列出规范中的所有接口
- 获取接口的详细信息（参数、请求体、响应等）
- 自动展开 `$ref` 引用
- 支持循环引用处理
- 支持深层嵌套结构解析
- 可选的 server URL 拼接功能

## 安装

使用 uvx：

```bash
uvx yonglelaoren-openapi-mcp
```

或使用 pip：

```bash
pip install yonglelaoren-openapi-mcp
```

## MCP 工具

### list_endpoints

列出 OpenAPI 规范中的所有接口。

**参数：**
- `spec_source`: OpenAPI 规范来源（文件路径或 URL）

**返回：**
- 接口列表，包含路径、方法、摘要和描述

### get_endpoint_details

获取指定接口的详细信息，包括参数、请求体、响应等，所有 `$ref` 引用已展开为具体字段结构。

**参数：**
- `spec_source`: OpenAPI 规范来源（文件路径或 URL）
- `path`: 接口路径（例如：/users/{id}）
- `method`: HTTP 方法（GET, POST, PUT, DELETE 等）

**返回：**
- 接口详细信息，包含参数、请求体、响应、解析后的 schemas 等

## 环境变量

### INCLUDE_SERVER_URL

控制是否在返回的接口路径中包含 server URL 前缀。

**默认值：** `false`

**作用：**
- 当设置为 `true` 时，如果 OpenAPI 规范中定义了 `servers` 字段，返回的接口路径会包含第一个 server 的 URL 前缀
- 当设置为 `false` 或未设置时，返回原始的接口路径

**支持的值（启用）：**
- `true`
- `True`
- `1`
- `yes`

**支持的值（禁用）：**
- `false`
- `False`
- `0`
- `no`

**示例：**

假设 OpenAPI 规范中定义：
```yaml
servers:
  - url: /video-service

paths:
  /mvc/test/hello:
    get:
      summary: 测试接口
```

- **默认行为（INCLUDE_SERVER_URL=false）**：
  ```json
  {
    "path": "/mvc/test/hello"
  }
  ```

- **启用 server URL（INCLUDE_SERVER_URL=true）**：
  ```json
  {
    "path": "/video-service/mvc/test/hello"
  }
  ```

**使用场景：**
在微服务架构中，不同的服务可能有不同的 URL 前缀。启用此功能可以在返回的接口路径中自动包含服务前缀，便于区分不同服务的接口地址。

## 配置示例

### 在 Claude Desktop 中配置

编辑 Claude Desktop 的配置文件（通常位于 `~/Library/Application Support/Claude/claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "openapi-extraction": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/openapi-mcp",
        "yonglelaoren-openapi-mcp"
      ],
      "env": {
        "INCLUDE_SERVER_URL": "true"
      }
    }
  }
}
```

### 使用 uvx

```bash
uvx -e INCLUDE_SERVER_URL=true yonglelaoren-openapi-mcp
```

### 使用环境变量

```bash
export INCLUDE_SERVER_URL=true
uvx yonglelaoren-openapi-mcp
```

### 不启用 server URL（默认行为）

```bash
uvx yonglelaoren-openapi-mcp
```

或显式禁用：

```bash
uvx -e INCLUDE_SERVER_URL=false yonglelaoren-openapi-mcp
```

## 开发

### 安装依赖

```bash
uv sync
```

### 运行测试

```bash
# 运行所有测试
uv run pytest

# 运行测试并查看覆盖率
uv run pytest --cov

# 运行特定测试文件
uv run pytest tests/test_parsers/test_openapi_parser.py
```

### 代码质量检查

```bash
# 代码格式化
uv run ruff format src/

# 代码检查
uv run ruff check src/

# 类型检查
uv run mypy src/
```

### 构建

```bash
uv build
```

## 技术栈

- Python 3.11+
- MCP/FastMCP - Model Context Protocol 框架
- Prance - OpenAPI 规范解析器
- Pydantic - 数据验证
- httpx - HTTP 客户端

## 许可证

MIT License

## 作者

yongle <yonglelaoren@163.com>

## 版本历史

- 0.4.0 - 新增 server URL 拼接功能（INCLUDE_SERVER_URL 环境变量）
- 0.3.0 - 修复循环引用处理和 schema 递归解析
- 0.2.1 - 新增循环引用处理和 schema 递归解析功能
- 0.2.0 - 初始版本
