Magic-API MCP Server

# Magic-API 工具用户指南 本指南面向日常使用 Magic-API 工具链的工程师，介绍环境准备、常用命令与排障建议。所有命令默认在仓库根目录 `magic-api-mcp-server/` 内执行。 ## 环境准备 1. **基础环境** - Python ≥ 3.10（建议 3.11/3.12） - [uv](https://github.com/astral-sh/uv)（推荐的依赖与命令执行工具） 2. **安装依赖** ```bash uv pip install -r requirements.txt ``` 3. **环境变量（按需配置）** ```bash export MAGIC_API_BASE_URL="http://127.0.0.1:10712" export MAGIC_API_WS_URL="ws://127.0.0.1:10712/magic/web/console" export MAGIC_API_AUTH_ENABLED=false # 需要认证时改为 true，并提供账号口令 export MAGIC_API_USERNAME=admin export MAGIC_API_PASSWORD=123456 ``` > 新的 `magicapi_tools` 包会自动读取上述变量，为 CLI 和 MCP 服务提供统一配置。 ## 常用命令速查 ### 1. 资源树提取 (`extract_api_paths.py`) - **列出接口列表（默认 CSV）** ```bash python3 extract_api_paths.py --url ``` - **查询“POST + 名称含 数据”接口** ```bash python3 extract_api_paths.py --url --method POST --query '数据' ``` - **根据路径直接查看接口详情**（等价 `--path-to-detail` 功能） ```bash python3 extract_api_paths.py --url --path-to-detail '/db/module/list' ``` - **获取接口 ID** ```bash python3 extract_api_paths.py --url --path-to-id 'test00/test0001' ``` ### 2. 资源管理 (`magic_api_resource_manager.py`) > 提供分组、资源、锁操作，自动读取环境变量。 ```bash # 查看资源树（默认全量） python3 magic_api_resource_manager.py --list-tree # 创建分组 python3 magic_api_resource_manager.py --create-group "测试分组" --path "/demo" # 复制分组 python3 magic_api_resource_manager.py --copy-group <源ID> --target <目标父ID> # 保存接口脚本（脚本 JSON 可通过 extract_api_paths 输出） python3 magic_api_resource_manager.py --save-file payload.json --group-id <分组ID> ``` ### 3. WebSocket 客户端 (`magic_api_client.py`) - **监听日志** ```bash python3 magic_api_client.py --listen-only ``` - **发起一次接口调用** ```bash python3 magic_api_client.py --call 'GET /test00/test0001' --params 'k=v' ``` - **结合 WebSocket 监听实时日志**（等同 `MagicAPIWebSocketClient` 中 `enable_websocket=True` 行为） ```bash python3 magic_api_client.py --call 'POST /api/create' --data '{"name":"demo"}' ``` ### 4. 断点调试客户端 (`magic_api_debug_client.py`) ```bash python3 magic_api_debug_client.py ``` 交互命令示例： - `test /api/demo 5,12`：调用接口并在第 5、12 行打断点 - `breakpoint 20` / `remove_bp 20`：增删断点 - `step`、`resume`：单步或恢复执行 - `call GET /api/status`：直接调用接口（不进断点） > CLI 自动加载环境变量，可在匿名模式下使用；设置 `MAGIC_API_AUTH_ENABLED=true` 后会携带账号信息登录。 ## 使用 `magicapi_tools` 作为库 若希望在 Python 中复用工具逻辑，可直接导入 `magicapi_tools` 包： ```python from magicapi_tools import MagicAPISettings, MagicAPIHTTPClient settings = MagicAPISettings.from_env() client = MagicAPIHTTPClient(settings) ok, detail = client.api_detail("<file_id>") ``` 常用导出： - `MagicAPISettings`：统一解析环境变量 - `MagicAPIHTTPClient`：HTTP 封装（资源树、详情、接口调用） - `load_resource_tree` / `find_api_id_by_path` / `find_api_detail_by_path` - `MagicAPIWebSocketClient`、`MagicAPIDebugClient`（低层 WebSocket 客户端） ## 常见问题 | 问题 | 说明与解决思路 | | --- | --- | | `uv run fastmcp ...` 提示 `No such file or directory` | 首次运行需执行 `uv tool run fastmcp --help` 拉取工具；或使用 `uv tool run fastmcp run ...`。 | | `uv pip install` 报 `.venv` 失效 | 仓库默认无虚拟环境，若存在残留 `.venv` 可删除后重新执行 `uv pip install ...`。 | | `--path-to-detail` 找不到接口 | 确认 `--url` 指向实际 Magic-API 服务；路径支持带/不带前导 `/`，默认模糊匹配。 | | WebSocket 客户端提示未连接 | 需要先启动 Magic-API 的调试端口（通常为控制台 10712），或检查防火墙策略。 | | 调试客户端日志过多 | 可在 CLI 内使用 `help` 查看命令；`test` 命令支持指定断点行，避免长时间等待。 | ## 建议工作流 1. 通过 `extract_api_paths.py --url --path-to-detail` 获取历史脚本，对齐项目风格。 2. 使用 `magic_api_resource_manager.py` 创建或更新分组与接口元数据。 3. 借助 `magic_api_client.py` 验证接口输出，必要时切换到 `magic_api_debug_client.py` 设置断点调试。 4. 最终在 MCP 服务里调用 `path_detail`、`call` 等工具，形成端到端自动化流程。 --- 如遇本文未覆盖的问题，可阅读 `MCP-MagicAPI-Assistant-设计与提示词.md` 中的架构说明，或直接查阅 `magicapi_tools` 包源码获取更多细节。