ai-log-mcp-server

把「AI 日志分析平台」的 REST 能力封装成 MCP tools，供 Claude Desktop / Cursor 等 MCP 客户端调用。

• 语言：Python 3.10+ · MCP：官方 mcp SDK · 传输：stdio · HTTP：httpx
• 设计原则：所有 tool 只转调平台 REST，不重写平台逻辑；schema 以平台 /openapi.json 为唯一来源。
• 详见 CLAUDE.md（工程契约）、DESIGN.md（工具设计）、WORKFLOW.md（阶段协议）。

⚠️ 前置依赖：业务平台必须在运行

本 MCP server 是薄壳——它只把请求转发给「AI 日志分析平台」的 REST API。平台不跑，14 个 tool 全部失败。所以使用前先把平台起起来。

前置条件

• Docker Desktop（含 compose v2）—— 跑平台
• Python 3.10+ —— 跑本 MCP server
• Git
• 一个 MCP 客户端：Claude Code / Claude Desktop / Cursor
• DeepSeek API key（无则平台用 --profile mock 起一个 mock LLM）

起一份自己的平台

git clone https://github.com/jeff-dev-1/vibecoding2026.git
cd vibecoding2026
cp .env.example .env          # 填 DEEPSEEK_API_KEY（没有就跳过，改用下方 mock）
docker compose up -d          # 平台 → http://localhost:8000

想更快？ 若该仓含 docker-compose.dist.yml（直接拉预构建镜像，不本地编译），优先用它： docker compose -f docker-compose.dist.yml up -d 没有 DeepSeek key 时：docker compose --profile mock up -d（平台用内置 mock LLM）。

连上 MCP

export APP_BASE_URL=http://localhost:8000
python -m ai_log_mcp.check     # 确认 /openapi.json 可达
# 再按下文「在 Claude Desktop / Cursor 注册」接入

平台跑起来、check 通过后，再回到本文档其余部分。

环境变量

backend REST 是开放的（登录门只在前端），无需鉴权 token。

本地运行

# 1. 安装（含测试依赖用 .[dev]）
pip install -e .

# 2. 指定平台地址（不指定则用默认 demo 地址）
export APP_BASE_URL="http://localhost:8000"

# 3. 以 stdio 方式启动 MCP server
python -m ai_log_mcp.server

调试推荐用 MCP Inspector：npx @modelcontextprotocol/inspector python -m ai_log_mcp.server 连通自检：python -m ai_log_mcp.check（拉到 ${APP_BASE_URL}/openapi.json 即通）

可用工具（本轮 MVP）

所有 tool 的入参/出参 schema 以 ${APP_BASE_URL}/openapi.json 为唯一来源（见 DESIGN.md §3.1），只转调 REST、原样透传响应；非 2xx 返回 {error, status, body}。

网关安全（只读，面向安全工程师）

均为无入参 GET；openapi 无输出 schema，下表「返回内容」即选 tool 依据（见 DESIGN.md §3.2）。

上传（写操作）

file_path 首选（本地路径，server 读盘上传）；content 兜底（内联文本，不依赖文件系统）。大小上限默认 5 MB，可经 UPLOAD_MAX_BYTES 调整。详见 DESIGN.md §6。

网关动作（写/查询）

语义为裁定/查询，不写业务数据（仅令 gateway observability 计数+1）。 3 个 *-report 的 POST（写回扫描报告）为 CI-only，不暴露为 tool——读取用对应 GET（见 DESIGN.md §5）。

在 Claude Desktop 注册

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ai-log": {
      "command": "python",
      "args": ["-m", "ai_log_mcp.server"],
      "env": {
        "APP_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

重启 Claude Desktop 后，工具会出现在工具列表中。

在 Cursor 注册

编辑 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）：

{
  "mcpServers": {
    "ai-log": {
      "command": "python",
      "args": ["-m", "ai_log_mcp.server"],
      "env": {
        "APP_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

如何验收

# 1. 单元测试（mock REST，不依赖平台在线）
pip install -e '.[dev]'
python -m pytest -q                       # 期望: 41 passed, 2 deselected

# 2. 集成测试（需可达 ${APP_BASE_URL}）。⚠️ 含真上传，有副作用：会在平台创建真任务、污染数据
python -m pytest -m integration -q        # 期望: 2 passed（连通性 + 真上传）
#   只跑连通性、不触发上传：pytest -m integration -k "not upload"

# 3. stdio 协议级冒烟（真实 MCP client over stdio 驱动本 server）
python scripts/smoke_stdio.py             # 期望: 列出 14 个 tool + health 返回, SMOKE OK

完整逐条验收（PRD §4 A1–A7）记录见 WORKFLOW.md 阶段 3。

参考链接

• demo UI：http://localhost:3000/ （登录 admin / <由讲师提供>，仅前端）
• REST 文档（人读）：http://localhost:8000/docs
• 机读契约（唯一权威）：http://localhost:8000/openapi.json