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/ 进入管理台。

Related MCP server: swagger-api-mcp-server

环境变量

未设置 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

新建工作流：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