内容
# MCPer
**MCPer** 是一款开发者工具，可将 OpenAPI 3.x 规范转换为功能齐全的 [FastMCP](https://github.com/jlowin/fastmcp) 服务器。只需指向任何 API，它就会生成一个可立即运行的 Python MCP 服务器，将每个端点暴露为原生工具 — 无需样板代码。
---
## 概述
MCPer 连接了传统的 REST API 和 AI 代理框架。与其手动编写 MCP 服务器代码，MCPer：
- 从 URL、本地文件或通过从基础 API URL 自动发现中获取 OpenAPI 规范
- 解析所有端点、参数、请求正文和身份验证方案
- 使用 Jinja2 模板渲染完整的、类型注释的 FastMCP 服务器
- 输出一个服务器，可以立即在 Claude Desktop、Codex CLI 或 MCP Inspector 中挂载
---
## 架构
```
用户输入（URL / 文件）
|
v
摄入层 app/ingest/loader.py
|
v
分析引擎 app/analyze/parser.py
|
v
代码生成器 app/generate/codegen.py + templates/
|
v
生成的 MCP 服务器 generated/<name>/server.py
```
### 前端（Next.js）
一个 Web 界面包含在 `frontend/` 下。它通过 Next.js API 代理路由与运行在端口 8000 上的本地 FastAPI 后端（`api.py`）进行通信。
```
浏览器
|
v
Next.js（端口 3000） -- /api/build 代理 --> FastAPI（端口 8000） --> main.py CLI
```
---
## 项目结构
```
MCPer/
├── app/
│ ├── ingest/ # 规范加载：URL、文件、自动发现
│ ├── analyze/ # OpenAPI 解析、端点提取、身份验证检测
│ ├── generate/ # 通过 Jinja2 的 FastMCP 代码生成
│ └── runtime/ # CLI 输出格式化和运行说明
├── templates/
│ ├── server.py.j2 # 主服务器脚手架
│ └── tool.py.j2 # 每个端点的工具函数
├── frontend/ # Next.js + Tailwind + TypeScript Web 界面
├── generated/ # 生成的 MCP 服务器输出目录
├── main.py # CLI 入口点
├── api.py # FastAPI 后端（用于 Web 界面）
└── pyproject.toml
```
---
## 要求
- Python 3.12+
- [uv](https://github.com/astral-sh/uv) （包和环境管理器）
- Node.js 18+（用于 Web 前端）
---
## 入门指南
### 克隆仓库
```bash
git clone https://github.com/openshaf/MCPer.git
cd MCPer
```
### 安装 Python 依赖项
```bash
git clone https://github.com/openshaf/MCPer.git
cd custom-mcp-builder
```
### 通过 CLI 运行
```bash
# 从基础 API URL 自动发现规范（推荐）
uv run main.py --api https://petstore3.swagger.io/api/v3
# 直接指向规范文件 URL
uv run main.py --url https://petstore3.swagger.io/api/v3/openapi.json
# 使用本地规范文件
uv run main.py --file ./openapi.json
```
生成的服务器将被写入 `generated/<api-name>/server.py`。
### 运行生成的服务器
```bash
uv run generated/<api-name>/server.py
```
---
## Web 界面
前端提供了一种视觉方式来提交 API URL 并检索生成的服务器配置。
### 启动 FastAPI 后端
```bash
uv run api.py
```
### 启动 Next.js 前端
```bash
cd frontend
npm install
npm run dev
```
在浏览器中打开 [http://localhost:3000](http://localhost:3000)。
---
## 连接到 MCP 客户端
### Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"my-api": {
"command": "uv",
"args": [
"run",
"-q",
"--directory",
"/absolute/path/to/generated/my-api",
"/absolute/path/to/generated/my-api/server.py"
]
}
}
}
```
### Codex CLI
```bash
codex mcp add my-api -- uv run -q --directory "/path/to/generated/my-api" "/path/to/generated/my-api/server.py"
```
### MCP Inspector
```bash
npx @modelcontextprotocol/inspector uv run -q --directory "/path/to/generated/my-api" "server.py"
```
---
## 功能
| 功能 | 详情 |
| --------------------- | ---------------------------------------------------------------------------------- |
| 自动发现 | 从基础 URL 探测公共规范路径（`/openapi.json`、`/swagger.json`等） |
| 身份验证检测 | 检测 Bearer、API 密钥和基本身份验证；将凭证映射到环境变量 |
| 重定向处理 | 生成的 `httpx` 调用包括 `follow_redirects=True` |
| 类型注释输出 | 所有工具函数都是完全类型化的，与 FastMCP 兼容 |
| 相对服务器 URL | 从使用 `servers` 数组中的相对路径的规范构造绝对 URL |
---
## 已知限制
- **每个服务器一个 API**：每个生成的服务器对应一个 API。计划将多个 API 合并到一个服务器中，但尚未实现。
- **仅 OpenAPI 3.x**：Swagger 2.0（OpenAPI 2）不受支持。
- **仅 REST**：GraphQL、gRPC 和其他协议不在范围之内。
---
## 贡献
1. 分叉仓库
2. 创建一个功能分支（`git checkout -b feature/my-feature`）
3. 提交您的更改
4. 打开一个拉取请求
---
## 许可证
MIT
