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（阶段协议）。

环境变量

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

Related MCP server: Log MCP Server

本地运行

# 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