TeamAPI-MCP

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

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

快速开始

# 安装后端
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：

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 与固定章节：

---
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 配置）：

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

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

{
  "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 配置示例

{
  "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。

测试

uv run pytest