# TeamAPI-MCP

用 **Markdown 接口描述** 作为唯一真相源，提供：

1. **远程 MCP 服务**（`http://<IP>:<PORT>/mcp`）—— Agent 查询请求/响应结构  
2. **管理 REST API + Web 管理台**—— 上传/编辑/预览/删除 `.md` 文档  
3. **Cursor / Claude Code skill & command**—— 引导 Agent 先查文档再写联调代码  

## 快速开始

```bash
# 安装后端
uv sync --extra dev

# 启动（默认 127.0.0.1:8765）
uv run python -m api_mcp

# 开发前端（代理到 8765）
cd frontend && npm install && npm run dev
```

生产可先构建前端，再由后端托管 `frontend/dist`：

```bash
cd frontend && npm install && npm run build
API_MCP_HOST=0.0.0.0 API_MCP_PORT=8765 uv run python -m api_mcp
```

浏览器打开 `http://<host>:8765/` 进入管理台。

## 环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `API_MCP_HOST` | `127.0.0.1` | 监听地址；局域网访问用 `0.0.0.0` |
| `API_MCP_PORT` | `8765` | 端口 |
| `API_MCP_PATH` | `/mcp` | MCP 挂载路径 |
| `API_MCP_DOCS_DIR` | `data/apis` | Markdown 文档目录 |
| `API_MCP_TEMPLATE_PATH` | `data/templates/api-doc.template.md` | 写作样例模板路径（不在 catalog 列表中） |
| `API_MCP_CATEGORIES_PATH` | `data/categories.json` | 分类注册表 |
| `API_MCP_TOKEN` | _(空)_ | 可选共享 Bearer Token；**留空 = 不鉴权**（内网/防火墙控访问即可） |
| `API_MCP_PUBLIC_HOST` | _(空)_ | 管理台展示用对外主机名/IP；**启用 Token 时**还需把该 Host 加入 MCP 允许列表 |

未设置 `API_MCP_TOKEN` 时：管理 API 与 MCP 均无鉴权，并关闭 MCP 的 Host（DNS rebinding）校验，便于用 `http://<局域网IP>:8765/mcp/` 直连。访问范围请用防火墙限制。

## Markdown 约定

每个接口一个 `.md` 文件，需含 YAML frontmatter 与固定章节：

```markdown
---
id: user-login
method: POST
path: /api/v1/auth/login
title: 用户登录
summary: 使用账号密码换取 token
---

## Description
...

## Request
...

## Response
...
```

示例见 `data/apis/`。

## MCP Tools

| Tool | 作用 |
|------|------|
| `list_apis` | 列出接口摘要；可选 `category`（空/不传=全部）、`limit` |
| `search_apis` | 按 keyword / method / path_contains / category 检索（category 空或不传=全部） |
| `get_api_detail` | 返回请求与响应章节 |
| `get_api_doc_template` | 获取写作样例（写入/修改前先调用） |
| `overwrite_api_doc` | 用完整 Markdown **全文覆盖**创建或替换某接口文档 |
| `create_api_doc` | 新建接口文档（id 已存在则报错）；可选 `category`（不存在则新建，空/不传=`未分类`） |
| `list_categories` | 列出分类及接口数量（含保留分类 `未分类` / `样例`） |
| `create_category` | 新建分类 |
| `delete_category` | 删除空自定义分类（保留/非空不可删） |
| `set_api_category` | 将接口移动到已有分类 |

新建工作流：`get_api_doc_template` → 改编全文（替换占位 `id`）→ `create_api_doc(content, category?)` → `get_api_detail` 校验。  
更新工作流：改编全文 → `overwrite_api_doc(content)` → `get_api_detail` 校验。

管理台左侧按分类分组；`样例` 下展示写作样例（只读）；业务接口可拖拽到其他分类。

## Cursor 配置示例

`~/.cursor/mcp.json`（或项目级 MCP 配置）：

```json
{
  "mcpServers": {
    "TeamAPI-MCP": {
      "url": "http://192.168.1.10:8765/mcp/"
    }
  }
}
```

启用鉴权时增加 headers（以你使用的 Cursor MCP 字段为准）：

```json
{
  "mcpServers": {
    "TeamAPI-MCP": {
      "url": "http://192.168.1.10:8765/mcp/",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}
```

项目内已提供：

- Skill：`.cursor/skills/api-docs-lookup/SKILL.md`
- Command：`.cursor/commands/api-docs.md`（`/api-docs`）

## Claude Code 配置示例

```json
{
  "mcpServers": {
    "TeamAPI-MCP": {
      "type": "http",
      "url": "http://192.168.1.10:8765/mcp/",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}
```

Skill：`.claude/skills/api-docs-lookup/SKILL.md`

## 管理 API（摘要）

- `GET /api/apis` — 列表  
- `GET /api/apis/{id}/raw` — 原文  
- `POST /api/apis` — 创建/覆盖（JSON `{content}`）  
- `PUT /api/apis/{id}` — 更新  
- `DELETE /api/apis/{id}` — 删除  
- `POST /api/apis/upload` — 上传 `.md`  
- `GET /api/connection` — MCP 连接信息（不回显完整 token）  
- `GET /health` — 健康检查（无需鉴权）  

## 安全说明

面向内网联调。未设置 `API_MCP_TOKEN` 时服务无鉴权；绑定 `0.0.0.0` 前请确认网络可信或启用 token。

## 测试

```bash
uv run pytest
```