109 lines
2.9 KiB
Markdown
109 lines
2.9 KiB
Markdown
# Agent Fox
|
||
|
||
API Documentation MCP Service — 让 LLM 高效检索 API 文档，而非一次性灌入全部内容。
|
||
|
||
## 它是什么
|
||
|
||
Agent Fox 是一个面向开发者的 SaaS 产品。导入 OpenAPI / Swagger 文档后，它会生成一个 MCP 服务端点，供 Claude、GPT 等大模型通过多级检索按需获取接口信息，最小化 token 消耗。
|
||
|
||
**一次典型检索仅需 ~1,300 tokens，而非全量文档的 10,000+ tokens。**
|
||
|
||
## 核心功能
|
||
|
||
- **导入 OpenAPI 文档** — 支持 OpenAPI 3.x 和 Swagger 2.0，URL 或文件上传
|
||
- **自动分组** — 按 tags 或 URL 路径前缀自动归类为模块，支持手动调整
|
||
- **MCP 多级检索** — 5 个工具逐层深入：概览 → 模块 → 接口列表 → 接口详情 → 搜索
|
||
- **项目管理** — 多项目、独立 API Key、配置一键复制
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 前端 | React 19, Vite, TailwindCSS |
|
||
| 后端 | Express 5, TypeScript, Zod |
|
||
| MCP | @modelcontextprotocol/sdk, Streamable HTTP |
|
||
| 数据库 | PostgreSQL 16, Prisma ORM |
|
||
| 部署 | Docker Compose |
|
||
|
||
## 快速开始
|
||
|
||
### 前置条件
|
||
|
||
- Node.js >= 20
|
||
- pnpm
|
||
- Docker & Docker Compose
|
||
|
||
### 启动
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone <repo-url> agent-fox
|
||
cd agent-fox
|
||
|
||
# 复制环境变量
|
||
cp .env.example .env
|
||
|
||
# 一键启动（开发模式）
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
|
||
|
||
# 首次运行需要执行数据库迁移
|
||
DATABASE_URL=postgresql://agentfox:agentfox@localhost:5432/agentfox \
|
||
npx prisma migrate deploy --schema=prisma/schema.prisma
|
||
```
|
||
|
||
访问 `http://localhost:5173` 使用前端。
|
||
|
||
### 生产模式
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
生产模式下 server 容器会自动执行数据库迁移，前端通过 Nginx 在 80 端口提供服务。
|
||
|
||
## MCP 接入
|
||
|
||
在 Agent Fox 中导入 API 文档后，将生成的配置添加到你的 MCP 客户端：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"my-api": {
|
||
"type": "http",
|
||
"url": "http://localhost:3001/mcp/<project-id>",
|
||
"headers": {
|
||
"Authorization": "Bearer <api-key>"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
LLM 即可通过以下工具按需检索文档：
|
||
|
||
| 工具 | 说明 | ~Tokens |
|
||
|------|------|---------|
|
||
| `get_project_overview` | 项目概览 + 模块统计 | 200 |
|
||
| `list_modules` | 模块列表含描述 | 100-300 |
|
||
| `list_endpoints` | 模块内接口摘要 | 200-500 |
|
||
| `get_endpoint_detail` | 完整接口详情 | 500-2000 |
|
||
| `search_endpoints` | 关键字搜索 | 200-500 |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
agent-fox/
|
||
├── packages/
|
||
│ ├── web/ # React 前端
|
||
│ ├── server/ # Express 后端 API (端口 3000)
|
||
│ ├── mcp/ # MCP 服务 (端口 3001)
|
||
│ └── shared/ # Prisma Client + 共享类型
|
||
├── prisma/ # 数据库 Schema + 迁移
|
||
├── docker-compose.yml
|
||
└── docker-compose.dev.yml
|
||
```
|
||
|
||
## License
|
||
|
||
MIT
|