Magic-API MCP Server

# Magic-API 工具开发者指南 本文档面向维护者与扩展开发者，介绍代码结构、模块职责、运行调试方式与贡献规范。 ## 代码结构概览 ``` magic-api-mcp-server/ ├── docs/ # 用户 & 开发者文档 ├── magicapi_tools/ # 核心可复用模块 │ ├── __init__.py # 导出统一 API │ ├── settings.py # MagicAPISettings 环境解析 │ ├── http_client.py # HTTP 调用封装 │ ├── extractor.py # 资源树遍历、路径匹配工具 │ ├── resource_manager.py # 资源管理类（增删改、锁定） │ ├── ws.py # WebSocket 客户端与调试器实现 │ └── mcp/ # MCP 工具实现（ApiTools、ResourceTools 等） ├── mcp/ # 兼容包，转发至 magicapi_mcp │ ├── __init__.py # 兼容导出 │ ├── config.py # 指向 magicapi_mcp.config │ ├── knowledge_base.py # 指向 magicapi_tools.knowledge_base │ └── magicapi_assistant.py # 指向 magicapi_mcp.magicapi_assistant ├── extract_api_paths.py # CLI：资源树提取（调用 magicapi_tools） ├── magic_api_client.py # CLI：WebSocket 日志 / API 调用 ├── magic_api_debug_client.py # CLI：断点调试入口 ├── magic_api_resource_manager.py # CLI：资源管理操作 └── test/ # 针对工具模块的单元测试 ``` ## 模块职责说明 ### `magicapi_tools.settings` - `MagicAPISettings.from_env()`：统一解析 `MAGIC_API_*` 环境变量。 - `inject_auth()` / `to_requests_kwargs()`：在需要认证时自动注入 Header。 ### `magicapi_tools.http_client` - `MagicAPIHTTPClient`：封装 `/magic/web/resource` 系列请求。 - `resource_tree()` 返回完整资源树 JSON。 - `api_detail(file_id)` 获取脚本详情。 - `call_api(method, path, ...)` 直接访问业务接口。 - CLI 与 MCP 服务均通过该类访问 Magic-API。 ### `magicapi_tools.extractor` - `load_resource_tree()`：支持本地 JSON、HTTP 两种加载方式。 - `extract_api_endpoints()`：扁平化生成 `method path [name]` 列表。 - `find_api_id_by_path()` / `find_api_detail_by_path()`：提供 `--path-to-id/--path-to-detail` 核心逻辑。 - `filter_endpoints()`：统一的正则/方法/关键字过滤。 - `format_file_detail()`：格式化详情输出，供 CLI/MCP 复用。 ### `magicapi_tools.ws` - `MagicAPIWebSocketClient`：基础日志监听 + API 调用。 - `MagicAPIDebugClient`：断点调试核心，配合 `DebugCompleter` 和 `setup_readline()`。 - `run_custom_api_call()`：可选择是否建立 WebSocket 监听。 - 所有 CLI 均从此处导入清晰的接口，避免冗余实现。 ### `magicapi_tools.resource_manager` - `MagicAPIResourceManager`：封装分组增删改、资源锁定/解锁、保存脚本等操作。 - 仍保留原脚本输出日志行为，便于排查请求结果。 ### `magicapi_tools.mcp` - `common.py`：`error_response`、`path_to_id_impl`、`find_api_details_by_path_impl` 等通用逻辑。 - `ApiTools` / `ResourceManagementTools` / `QueryTools` / `DocumentationTools` / `DebugTools` / `SystemTools`：统一注册 FastMCP 工具，直接复用上述客户端与资源管理组件。 - `__init__.py`：聚合导出供 `magicapi_mcp` 与兼容包 `mcp` 调用。 ## MCP 服务工具 `magicapi_mcp/magicapi_assistant.py` 负责组合工具并暴露 `create_app()`，其内部逻辑全部来自 `magicapi_tools.mcp`；`mcp/` 目录仅用于兼容旧引用路径。 - `path_to_id` / `path_detail`：调用 `magicapi_tools.mcp.common` 的路径解析实现。 - `resource_tree`：`MagicAPIResourceTools` 负责资源树遍历与 CSV 导出。 - `call`、`api_detail`、`workflow`：共用 `MagicAPIHTTPClient`、知识库与工作流模板。 运行方法（建议使用 uv）： ```bash # 查看 fastmcp 使用文档 uv tool run fastmcp --help # 启动 MCP 服务（默认 stdio） uv tool run fastmcp run magicapi_mcp/magicapi_assistant.py:tools --no-banner ``` > 若所在系统限制 `uv` 写入缓存，可提前执行 `uv tool run fastmcp --help` 拉取工具。 ## 测试与质量保障 - **单元测试**： ```bash python3 -m unittest discover -s test -p 'test_magicapi_*.py' ``` 覆盖配置解析、资源过滤、CSV 导出逻辑。 - **场景脚本**：`python3 test_step_commands.py` 验证断点消息格式。 - **开发建议**： 1. 修改 CLI 前优先更新 `magicapi_tools` 中的对应模块；CLI 层仅负责参数解析与打印。 2. 新增工具时请补充测试或示例，保持 `test/` 目录命名规范（`test_*.py`）。 3. 引入第三方库需更新 `requirements.txt` 并给出用途注释。 ## 扩展指引 1. **新增 MCP 工具**：在 `magicapi_assistant.py` 中调用 `magicapi_tools` 或自定义模块，并更新 `MCP-MagicAPI-Assistant-设计与提示词.md`。 2. **CLI 扩展**：使用 `argparse`，解析完成后调用 `magicapi_tools` 对应方法，保持入口简洁；示例可参考新的 `extract_api_paths.py`。 3. **自定义脚本/自动化**： ```python from magicapi_tools import MagicAPISettings, MagicAPIHTTPClient, find_api_detail_by_path settings = MagicAPISettings.from_env() client = MagicAPIHTTPClient(settings) details = find_api_detail_by_path('/demo/path', client=client) ``` 4. **调试 WebSocket**：可直接使用 `MagicAPIDebugClient`，或在 CLI 基础上替换输入来源，实现自动脚本。 ## 发布流程建议 1. 运行单元测试与关键脚本： ```bash python3 -m unittest discover -s test -p 'test_magicapi_*.py' python3 test_step_commands.py ``` 2. 通过 `uv tool run fastmcp run ...` 验证 MCP 服务最小可运行。 3. 更新文档：`docs/用户指南.md`、`docs/开发者指南.md`、`README.md` 梳理兼容性变更。 4. 提交信息建议：`refactor(magicapi_tools): ...` 或 `feat(mcp): ...`。 ## 常见维护问题 | 问题 | 处理建议 | | --- | --- | | 需要访问历史脚本范例 | 使用 `path_detail`（MCP 或 CLI）获取数据库最新版本，避免依赖过期示例。 | | `uv tool run fastmcp` 报权限错误 | 首次拉取会写入 `~/.cache/uv`，若目录受限可指定 `UV_CACHE_DIR` 或手动执行 `uv tool` 命令时开启权限。 | | 调试客户端阻塞 | `MagicAPIDebugClient` 已在内部启用线程 + `asyncio` 事件循环，保持 CLI 代码简洁；若要脚本化调用，建议直接复用类而非 CLI。 | | 需要新增测试类型 | 可在 `test/` 下增加 `test_magicapi_xxx.py`，使用标准 `unittest`。 | ## 参考文档 - `MCP-MagicAPI-Assistant-设计与提示词.md`：整体架构与 MCP 工具说明 - `docs/用户指南.md`：终端用户操作手册 - 官方参考： - [FastMCP Quickstart](https://gofastmcp.com/getting-started/quickstart) - [Magic-API 脚本文档](https://www.ssssssss.org/magic-api/pages/base/script/) --- 如需进一步讨论架构或新增功能规范，可在提交 PR 前补充设计说明，确保所有 CLI/MCP 均通过 `magicapi_tools` 模块共用逻辑。