# 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