# Magic-API MCP Server 使用指南
## 🚀 快速开始
本项目集成了 Model Context Protocol (MCP) 功能，为 Magic-API 开发提供高级交互能力。
### 1. 安装与测试
```bash
# 如果尚未安装 uv (推荐方式)
pip install uv
# 安装项目依赖
uv sync
# 或者安装 fastmcp
uv add fastmcp
```
### 2. MCP 配置
#### 基础配置（适用于大多数用户）：
```json
{
"mcpServers": {
"magic-api-mcp-server": {
"command": "uvx",
"args": ["magic-api-mcp-server@latest", "--transport", "stdio"],
"timeout": 600
}
}
}
```
#### 高级配置（需要自定义环境）：
```json
{
"mcpServers": {
"magic-api-mcp-server": {
"command": "uvx",
"args": ["magic-api-mcp-server@latest", "--transport", "stdio"],
"timeout": 600,
"env": {
"MAGIC_API_BASE_URL": "http://127.0.0.1:10712",
"MAGIC_API_WS_URL": "ws://127.0.0.1:10712/magic/web/console",
"MAGIC_API_TIMEOUT_SECONDS": "30.0",
"LOG_LEVEL": "INFO"
}
}
}
}
```
#### MCP 提示词 （非常重要）
##### 提示词概述
当使用支持 MCP 的 AI 助手（如 Claude Desktop、Cursor 等）时，请务必使用以下提示词让助手了解 Magic-API MCP Server 的功能和用途。
##### 核心提示词
```
你现在是一个专业的 Magic-API 开发者助手，具备强大的 MCP (Model Context Protocol) 工具（Magic-API MCP Server）支持。
## 🎯 你的核心职能
- 提供 Magic-API 脚本语法指导和最佳实践
- 帮助用户编写高效的数据库查询和业务逻辑
- 解答 Magic-API 配置和部署相关问题
- 提供代码示例和调试建议
## ⚠️ 强制要求：代码编写前语法规则获取
**重要：** 在编写任何 Magic-Script 代码前，你必须首先调用 `get_full_magic_script_syntax` 工具获取完整的语法规则。
Magic-Script 是一种小众语言，具有独特的语法规则，不遵循标准 JavaScript 或 Java 语法。
不获取完整语法规则而直接编写代码将导致严重的语法错误。
**重要：** 在API脚本开发（create/edit API scripts）编写编辑脚本前，你必须：
1. 调用 `get_full_magic_script_syntax` 获取完整的 Magic-Script 语法规则
2. 调用 `get_development_workflow` 获取开发工作流指南
3. 遵循标准化的开发流程：准备→信息采集→执行→校验→总结
## 🧭 MagicAPI MCP Agent 核心工作流
> 流转需按顺序推进，用户可随时指令跳转。
按照以下流程调用 MCP 工具，确保每一步都有依据：
- **[需求洞察]** → `search_knowledge`、`get_development_workflow`，识别目标场景与约束
- **语法对齐** → `get_full_magic_script_syntax`、`get_script_syntax`，确认Magic-Script写法
- **[资源定位]** → `get_resource_tree`、`get_api_details_by_path`、`search_api_endpoints`，查阅现有资产
- **[实现与调试]** → `create_api_resource`、`replace_api_script`、`call_magic_api`、`call_api_with_debug`、`set_breakpoint`，落实代码并验证
- **[结果反馈]** → `get_practices_guide`、`get_common_pitfalls`、`list_backups`，输出结论并保证可回溯
## 🛠️ 可用工具能力
在本文档第 3 节中详细介绍了所有可用工具，包括：
- **文档工具** (DocumentationTools): 语法、文档、示例、最佳实践等
- **API 工具** (ApiTools): 接口调用和测试
- **资源管理工具** (ResourceManagementTools): 资源的CRUD操作
- **查询工具** (QueryTools): 资源检索
- **调试工具** (DebugTools): 断点管理
- **搜索工具** (SearchTools): 内容搜索
- **备份工具** (BackupTools): 数据备份管理
- **类方法工具** (ClassMethodTools): Java类和方法查询
- **系统工具** (SystemTools): 系统元信息查询
详情请参见下方第 3 节 "本项目 MCP 工具功能"。
## 📋 使用指南
##### 问题分析
首先理解用户的需求和上下文，再选择合适的工具。
##### 知识搜索策略
🔍 **当你不确定某个功能或语法时，优先使用搜索工具：**
- 调用 `search_knowledge` 进行全文搜索，关键词可以是功能名称、语法关键词等
- 例如：搜索"数据库连接"、"缓存使用"、"文件上传"等
- 可以限定搜索分类：syntax(语法)、modules(模块)、functions(函数)、web_docs(文档)等
##### 最佳实践
- 🔍 **遇到不确定的问题时，先搜索知识库**
- 📚 优先使用文档查询工具了解功能
- 🔍 开发时先用查询工具了解现有资源
- 🐛 调试时设置断点逐步排查问题
- 💾 重要的变更操作前先备份
##### 错误处理
- 🔍 遇到未知错误时，使用 `search_knowledge` 搜索相关解决方案
- 🌐 网络错误时检查 Magic-API 服务状态
- 🔐 权限错误时确认用户认证配置
- 📁 资源不存在时先用查询工具确认路径
## ⚠️ 注意事项
- 所有工具都支持中文和英文参数
- API 调用支持自定义请求头和参数
记住：你现在具备了完整的 Magic-API 开发工具链，可以为用户提供专业、高效的开发支持！
```
##### 简短提示词 (适用于快速配置)
```
你是一个专业的 Magic-API 开发者助手，拥有以下 MCP 工具：
⚠️ 强制要求：
- 编写任何 Magic-Script 代码前必须先调用 get_full_magic_script_syntax 获取完整语法规则！
- API脚本开发（create/edit API scripts）编写编辑脚本前必须调用 get_development_workflow 获取工作流指南！
📚 文档查询: get_full_magic_script_syntax[强制], get_development_workflow[强制], search_knowledge[推荐], get_script_syntax, get_module_api, get_best_practices, get_examples
🔧 API 调用: call_magic_api
📁 资源管理: get_resource_tree, create_api_resource, delete_resource
🔍 查询工具: get_api_details_by_path, get_api_details_by_id, search_api_endpoints
🐛 调试工具: set_breakpoint, resume_breakpoint_execution, call_api_with_debug
🔎 搜索工具: search_api_scripts, search_todo_comments
💾 备份工具: list_backups, create_full_backup, rollback_backup
⚙️ 系统工具: get_assistant_metadata
🔍 不确定时优先使用 search_knowledge 搜索知识库，代码编写前必须获取完整语法规则。
🧭 按核心工作流顺序完成需求洞察→语法对齐→资源定位→实现调试→结果反馈。
```
##### 配置提示词 (Cursor/VS Code 等编辑器)
```json
{
"mcpServers": {
"magic-api-mcp-server": {
"command": "uvx",
"args": ["magic-api-mcp-server@latest", "--transport", "stdio"],
"timeout": 600,
"env": {
"MAGIC_API_BASE_URL": "http://127.0.0.1:10712",
"MAGIC_API_WS_URL": "ws://127.0.0.1:10712/magic/web/console"
}
}
}
}
```
本项目 MCP 服务器专为 Magic-API 开发者设计，提供了一套完整的工作流工具，从脚本编写、API 管理到调试和部署，全方位提升开发效率。
## 🧠 Prompts (提示词模板)
Magic-API MCP Server 提供了可复用的提示词模板，帮助您快速配置专业的 Magic-API 开发者助手。
### 可用 Prompts
#### magic_api_developer_guide
生成专业的 Magic-API 开发者助手提示词，包含：
- 完整的工具能力介绍
- 使用指南和最佳实践
- 错误处理建议
- 工具选择策略
**使用方法：**
```python
# 通过 MCP 客户端调用
prompt = await client.get_prompt("magic_api_developer_guide")
content = prompt.messages[0].content.text
```
**适用场景：**
- 配置新的 AI 助手
- 标准化开发工作流
- 培训新团队成员
- 创建一致的开发环境
#### 工具组合配置
本项目支持多种工具组合，可根据需要选择：
- `full`: 完整工具集 - 适用于完整开发环境 (默认)
- `minimal`: 最小工具集 - 适用于资源受限环境
- `development`: 开发工具集 - 专注于开发调试
- `production`: 生产工具集 - 生产环境稳定运行
- `documentation_only`: 仅文档工具 - 文档查询和学习
- `api_only`: 仅API工具 - 接口测试和调用
- `backup_only`: 仅备份工具 - 数据备份和管理
- `class_method_only`: 仅类方法工具 - Java类和方法查询
- `search_only`: 仅搜索工具 - 快速搜索定位
**工具组合使用场景**：
| 场景 | 组合模式 | 适用环境 | 特点 |
|------|----------|----------|------|
| **新手学习** | `documentation_only` | 学习阶段 | 专注文档查询和语法学习 |
| **API开发** | `development` | 开发环境 | 接口开发、测试和调试 |
| **生产运维** | `production` | 生产环境 | 系统运维和资源管理 |
| **问题调试** | `minimal` | 调试场景 | 问题排查，启用DEBUG日志 |
**基础配置模板**：
```json
{
"mcpServers": {
"magic-api-server": {
"command": "uvx",
"args": ["magic-api-mcp-server@latest", "--composition", "{组合模式}", "--transport", "stdio"],
"timeout": 600
}
}
}
```
### 3. 本项目 MCP 工具功能
Magic-API MCP 服务器为 Magic-API 开发提供以下专业工具：
#### 3.1 系统工具 (SystemTools)
系统信息和元数据工具
- **get_assistant_metadata**: 获取Magic-API MCP Server的完整元信息，包括版本、功能列表和配置
#### 3.2 文档工具 (DocumentationTools)
文档查询与知识库工具，覆盖语法、实践、示例与流程
- **get_full_magic_script_syntax** ⚠️ **[强制]**: 获取完整的Magic-Script语法规则 - 大模型编写代码前必须调用此工具
- **search_knowledge** 🔍 **[推荐]**: 在Magic-API知识库中进行全文搜索 - 不确定时优先使用此工具
- **get_magic_script_syntax**: 查询 Magic-Script 语法规则与示例
- **get_magic_script_examples**: 获取脚本示例，支持关键词过滤
- **get_magic_api_docs**: 查看官方文档索引或详细内容
- **get_best_practices**: 查阅最佳实践列表
- **get_common_pitfalls**: 查阅常见问题与规避建议
- **get_development_workflow**: 获取标准化开发流程指南
- **get_module_api_docs**: 查询内置模块 API 文档
- **list_available_modules**: 查看可用模块与自动导入模块
- **get_function_docs**: 获取内置函数库文档
- **get_extension_docs**: 获取类型扩展文档（默认禁用，启用后可用）
- **get_config_docs**: 获取配置项文档（默认禁用）
- **get_plugin_docs**: 获取插件系统文档（默认禁用）
- **get_examples** / **list_examples**: 统一查询示例分类与代码片段
- **get_docs**: 获取 Magic-API 官方站点索引
#### 3.3 API 工具 (ApiTools)
API调用和测试工具，支持灵活的接口调用和测试
- **call_magic_api**: 调用Magic-API接口并返回请求结果，支持GET、POST、PUT、DELETE等HTTP方法
##### 🔍 API响应智能检查
Magic-API MCP Server 支持多种API响应格式的智能成功/失败判断：
**优先级顺序**：
1. 🚀 **`message="success"`** - 最高优先级，直接匹配message字段是否等于"success"
2. 🔢 **Code字段检查** - 检查code字段是否等于配置的成功码（默认1，可配置）
3. 📊 **Status字段检查** - 检查status字段（某些自定义响应格式）
4. ❌ **错误字段检查** - 检查是否存在error、exception、failure等错误字段
5. ✅ **默认成功** - 兼容模式，对没有明确标识的响应默认视为成功
**支持的响应格式示例**：
```json
// 标准格式
{"code": 1, "message": "success", "data": {...}}
// 自定义状态码
{"code": 200, "message": "ok", "data": {...}}
// Message优先（最高优先级）
{"code": 500, "message": "success", "data": {...}} // 仍然成功！
{"code": 1, "message": "operation failed", "data": {...}} // 失败！
// 自定义格式
{"status": 1, "msg": "success", "body": {...}}
// 错误响应
{"code": 500, "message": "Internal Error", "data": {...}}
{"error": "something went wrong"}
```
**配置方式**：
```bash
# 通过环境变量配置成功状态码和消息
MAGIC_API_SUCCESS_CODE=200
MAGIC_API_SUCCESS_MESSAGE=ok
MAGIC_API_INVALID_CODE=400
MAGIC_API_EXCEPTION_CODE=500
```
#### 3.4 资源管理工具 (ResourceManagementTools)
完整的资源管理系统，支持资源树查询与批量操作
- **get_resource_tree**: 获取资源树，支持过滤、导出多种格式（JSON/CSV/树形），向后兼容CSV参数
- **save_group**: 保存分组，支持单个分组创建或更新，包含完整的分组配置选项
- **create_api_resource** / **create_api_endpoint**: 创建单个或批量 API
- **replace_api_script**: 按接口 ID 替换 Magic-Script 片段，支持一次或全量替换
- **copy_resource**: 复制资源
- **move_resource**: 移动资源
- **delete_resource**: 删除单个或批量资源
- **lock_resource** / **unlock_resource**: 批量锁定或解锁资源
- **list_resource_groups**: 列出与搜索资源分组
- **get_resource_stats**: 统计资源数量与类型分布
#### 3.5 查询工具 (QueryTools)
高效的资源查询和检索工具
- **get_api_details_by_path**: 根据API路径直接获取接口的详细信息，支持模糊匹配
- **get_api_details_by_id**: 根据接口ID获取完整的接口详细信息和配置
- **search_api_endpoints**: 搜索和过滤Magic-API接口端点，返回包含ID的完整信息列表
#### 3.6 调试工具 (DebugTools)
强大的调试功能，支持断点管理和调试会话
- **set_breakpoint**: 在指定API脚本中设置断点
- **remove_breakpoint**: 移除指定的断点
- **resume_breakpoint_execution**: 恢复断点执行，继续运行调试脚本
- **step_over_breakpoint**: 单步执行，越过当前断点继续执行
- **list_breakpoints**: 列出所有当前设置的断点
- **call_api_with_debug**: 调用指定接口并在命中断点处暂停
- **execute_debug_session**: 执行完整的调试会话
- **get_debug_status**: 获取当前调试状态
- **clear_all_breakpoints**: 清除所有断点
- **get_websocket_status**: 获取WebSocket连接状态
#### 3.7 搜索工具 (SearchTools)
内容搜索与定位
- **search_api_scripts**: 在所有 API 脚本中检索关键词
- **search_todo_comments**: 搜索脚本中的 TODO 注释（默认禁用）
#### 3.8 备份工具 (BackupTools)
完整的备份管理功能
- **list_backups**: 查询备份列表，支持时间戳过滤和名称过滤
- **get_backup_history**: 获取备份历史记录
- **get_backup_content**: 获取指定备份的内容
- **rollback_backup**: 回滚到指定的备份版本
- **create_full_backup**: 创建完整的系统备份
#### 3.9 类方法工具 (ClassMethodTools)
Java类和方法检索工具
- **list_magic_api_classes**: 列出所有Magic-API可用的类、扩展和函数，支持翻页浏览
- **get_class_details**: 获取指定类的详细信息，包括方法、属性和继承关系
- **get_method_details**: 获取指定方法的详细信息，包括参数类型和返回值
#### 3.10 代码生成工具 (CodeGenerationTools) - 当前禁用
智能代码生成功能（需启用后使用）
- **generate_crud_api**: 生成完整的CRUD API接口代码
- **generate_database_query**: 生成数据库查询代码
- **generate_api_test**: 生成API接口测试代码
- **generate_workflow_code**: 生成工作流模板代码
#### 3.11 提示词工具 (PromptTools)
提供可复用的提示词模板，确保助手严格遵循 MCP 工具化流程
- **magic_api_developer_guide**: 输出最新版“Magic-API 开发者助手”系统提示词，强调“仅依赖 MCP 工具”工作守则、六步工具工作流以及结构化输出要求
#### 3.12 工作流知识库亮点
`magicapi_tools/utils/kb_practices.py` 新增 "mcp_tool_driven" 等工作流，调用 `get_development_workflow` 或 `get_practices_guide` 时可获取：
- 🔍 **智能搜索驱动**：遇到不确定的问题时，优先调用 `search_knowledge` 工具进行知识库全文搜索，确保获取最新和准确的信息。
- MCP 工具优先的通用流程：覆盖准备、信息采集、执行、校验、总结全链路，并针对每一步给出对应工具提示。
- api_script_development / diagnose / optimize / refactor 等场景化流程：提供原则说明、步骤拆解以及工具列表，确保在接口开发、故障排查、性能优化与重构中全程依赖 MCP 工具完成。
- 结合 `magic_api_developer_guide` 提示词，可让大模型在对话中主动引用工具证据，输出可验证的结论。
### 4. 环境变量
| 变量 | 用途 | 值 | 默认值 |
|------|------|----|--------|
| MAGIC_API_BASE_URL | Magic-API 服务基础 URL | URL 地址 | http://127.0.0.1:10712 |
| MAGIC_API_WS_URL | Magic-API WebSocket URL | WebSocket 地址 | ws://127.0.0.1:10712/magic/web/console |
| MAGIC_API_USERNAME | Magic-API 认证用户名 | 字符串 | 无 |
| MAGIC_API_PASSWORD | Magic-API 认证密码 | 字符串 | 无 |
| MAGIC_API_TOKEN | Magic-API 认证令牌 | 字符串 | 无 |
| MAGIC_API_AUTH_ENABLED | 是否启用认证 | true/false | false |
| MAGIC_API_TIMEOUT_SECONDS | 请求超时时间（秒） | 数字 | 30.0 |
| MAGIC_API_SUCCESS_CODE | API成功状态码 | 数字 | 1 |
| MAGIC_API_SUCCESS_MESSAGE | API成功消息文本 | 字符串 | success |
| MAGIC_API_INVALID_CODE | 参数验证失败状态码 | 数字 | 0 |
| MAGIC_API_EXCEPTION_CODE | 系统异常状态码 | 数字 | -1 |
| LOG_LEVEL | 日志级别 | DEBUG/INFO/WARNING/ERROR | INFO |
| FASTMCP_TRANSPORT | FastMCP 传输协议 | stdio/http | stdio |
### 5. 本地运行方式
```bash
# 推荐方式：使用 uvx 运行最新版本（适用于已发布到 pip 的包）
uvx magic-api-mcp-server@latest
# 或安装后使用本地命令
magic-api-mcp-server
# 或者直接运行 Python 脚本（开发时）
uv run fastmcp run run_mcp.py:mcp --transport http --port 8000
# 指定工具组合运行
uvx magic-api-mcp-server@latest --composition development
# 使用特定配置运行
MAGIC_API_BASE_URL=http://localhost:8080 uvx magic-api-mcp-server@latest
```
### 6. Docker 运行方式
#### 使用 Docker Compose (推荐)
```bash
# 使用 Makefile 命令 (推荐，简化操作)
make quick-start # 快速启动开发环境
make deploy # 生产环境部署
make logs # 查看日志
make status # 查看状态
make shell # 进入容器
make test # 运行测试
# 或直接使用 docker-compose 命令
# 1. 构建并启动服务
docker-compose up -d
# 2. 查看日志
docker-compose logs -f magic-api-mcp-server
# 3. 停止服务
docker-compose down
# 4. 重启服务
docker-compose restart magic-api-mcp-server
```
#### 使用 Docker 命令 (基于 uvx)
```bash
# 1. 构建镜像
docker build -t magic-api-mcp-server .
# 2. 运行容器 (stdio模式)
docker run --rm --entrypoint uvx magic-api-mcp-server \
magic-api-mcp-server@latest --composition full --transport stdio
# 3. 运行容器 (HTTP模式)
docker run -d --name magic-api-mcp-server \
-p 8000:8000 \
--entrypoint uvx magic-api-mcp-server \
magic-api-mcp-server@latest --transport http --port 8000
# 4. 查看日志
docker logs -f magic-api-mcp-server
# 5. 停止容器
docker stop magic-api-mcp-server
```
#### Docker 配置说明
**基于 uvx 的优势**:
- 自动下载并运行最新版本的包
- 无需预先安装依赖
- 镜像更小，构建更快
- 自动处理包版本管理
**生产环境配置** (`docker-compose.yml`):
- 使用桥接网络连接到Magic-API服务
- 配置资源限制和健康检查
- 支持自动重启
**开发环境配置** (`docker-compose.override.yml`):
- 挂载源代码支持热重载
- 调试日志级别
- 禁用健康检查
#### Docker 环境变量
| 变量 | 描述 | 默认值 |
|------|------|--------|
| `MAGIC_API_BASE_URL` | Magic-API 服务基础 URL | `http://host.docker.internal:10712` |
| `MAGIC_API_WS_URL` | Magic-API WebSocket URL | `ws://host.docker.internal:10712/magic/web/console` |
| `MAGIC_API_USERNAME` | 认证用户名 | 无 |
| `MAGIC_API_PASSWORD` | 认证密码 | 无 |
| `MAGIC_API_TOKEN` | 认证令牌 | 无 |
| `MAGIC_API_AUTH_ENABLED` | 是否启用认证 | `false` |
| `MAGIC_API_TIMEOUT_SECONDS` | 请求超时时间 | `30.0` |
| `MAGIC_API_SUCCESS_CODE` | API成功状态码 | `1` |
| `MAGIC_API_SUCCESS_MESSAGE` | API成功消息文本 | `success` |
| `MAGIC_API_INVALID_CODE` | 参数验证失败状态码 | `0` |
| `MAGIC_API_EXCEPTION_CODE` | 系统异常状态码 | `-1` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
| `FASTMCP_TRANSPORT` | MCP传输协议 | `stdio` |
#### 网络配置注意事项
- **Linux**: 使用 `host.docker.internal` 访问宿主机服务
- **macOS/Windows**: Docker Desktop 自动提供 `host.docker.internal`
- **自定义网络**: 可通过 `docker network` 创建专用网络
#### Docker 构建问题解决
如果遇到网络证书验证问题，请尝试以下解决方案：
**方案1: 使用国内镜像源**
```bash
# 修改Dockerfile添加国内镜像源
RUN sed -i 's/deb.debian.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list.d/debian.sources
RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/
```
**方案2: 配置Docker代理**
```bash
# 创建或修改 ~/.docker/config.json
{
"proxies": {
"default": {
"httpProxy": "http://127.0.0.1:7897",
"httpsProxy": "http://127.0.0.1:7897",
"noProxy": "localhost,127.0.0.1"
}
}
}
```
**方案3: 跳过TLS验证 (仅用于测试)**
```bash
# 临时跳过TLS验证构建
docker build --build-arg DOCKER_TLS_VERIFY=0 -t magic-api-mcp-server:test .
```
**方案4: 使用预构建镜像**
```bash
# 如果网络问题持续，可考虑使用预构建的基础镜像
# 或者在有稳定网络的环境中构建
```
#### 故障排除
```bash
# 使用 Makefile 命令 (推荐)
make status # 查看容器状态
make shell # 进入容器调试
make logs-tail # 查看详细日志
make test # 运行健康检查
make test-connection # 测试与 Magic-API 连接
make clean-all # 清理所有资源
# 或直接使用 docker/docker-compose 命令
# 查看容器状态
docker-compose ps
# 进入容器调试
docker-compose exec magic-api-mcp-server bash
# 查看详细日志
docker-compose logs --tail=100 magic-api-mcp-server
# 清理容器和镜像
docker-compose down --rmi all --volumes
```
### 7. 项目结构
```
magicapi_mcp/
├── magicapi_assistant.py # 主要的 MCP 助手实现
├── tool_registry.py # 工具注册表
├── tool_composer.py # 工具组合器
└── settings.py # 配置设置
magicapi_tools/
├── tools/ # 各种 MCP 工具
│ ├── system.py # 系统工具 (元信息查询)
│ ├── documentation.py # 文档工具 (知识库查询)
│ ├── api.py # API工具 (接口调用)
│ ├── resource.py # 资源管理工具 (CRUD操作)
│ ├── query.py # 查询工具 (资源检索)
│ ├── debug.py # 调试工具 (断点管理)
│ ├── search.py # 搜索工具 (内容搜索)
│ ├── backup.py # 备份工具 (数据备份)
│ ├── class_method.py # 类方法工具 (Java类查询)
│ ├── code_generation.py # 代码生成工具 (当前禁用)
│ └── common.py # 通用辅助函数
└── utils/ # 工具助手功能
├── knowledge_base.py # 知识库接口
├── response.py # 标准化响应
├── http_client.py # HTTP 客户端
└── resource_manager.py # 资源管理器
```
### 8. 安装方式
#### 从 PyPI 安装（推荐）
```bash
# 安装已发布的包
pip install magic-api-mcp-server
# 或使用 uv 安装
uv add magic-api-mcp-server
# 运行 MCP 服务器（推荐使用最新版本）
uvx magic-api-mcp-server@latest
# 或使用安装后的命令
magic-api-mcp-server
```
#### 开发者本地安装
```bash
# 本项目已包含完整的 MCP 实现
cd magic-api-mcp-server
# 安装项目依赖（开发时）
uv sync
# 安装 fastmcp 依赖
uv add fastmcp
# 本地运行（开发时）
python run_mcp.py
```
## 🛠️ 项目结构
```
magicapi_mcp/
├── magicapi_assistant.py # 主要的 MCP 助手实现
├── tool_registry.py # 工具注册表
├── tool_composer.py # 工具组合器
└── settings.py # 配置设置
magicapi_tools/
├── tools/ # 各种 MCP 工具
│ ├── documentation.py # 文档相关工具
│ ├── api.py # API 相关工具
│ ├── code_generation.py # 代码生成工具 (当前已禁用)
│ ├── query.py # 查询工具
│ ├── backup.py # 备份工具
│ ├── class_method.py # 类方法工具
│ ├── debug.py # 调试工具
│ ├── resource.py # 资源管理工具
│ ├── search.py # 搜索工具
│ └── system.py # 系统工具
└── utils/ # 工具助手功能
├── knowledge_base.py # 知识库接口
├── response.py # 标准化响应
├── http_client.py # HTTP 客户端
└── resource_manager.py # 资源管理器
```
## AIMCP Electron 客户端附录（含 Mermaid 架构图）
> 本附录面向基于 Electron 的 AIMCP 客户端，指导如何对接本 Magic-API MCP Server，并提供关键流程可视化。适合作为独立开源仓库 README 模板片段复用。
### 项目简介（AIMCP）
- 目标：在 Electron 应用中，通过 MCP 协议统一调用 Magic-API 能力，覆盖查询、资源管理与调试。
- 栈特性：Electron(Main/Renderer/Preload) + Node MCP 客户端 + FastMCP Server(Python) + Magic-API(HTTP/WS)。
### 架构总览
```mermaid
flowchart LR
subgraph Renderer[Electron Renderer UI]
R[React/Vue/Svelte UI]
end
subgraph Main[Electron Main Process]
IPC[IPC Router]
C[Node MCP Client]
end
subgraph Server[magic-api-mcp-server (Python/FastMCP)]
S[Tools: Api/Query/Debug/...]
end
subgraph MagicAPI[Magic-API Backend]
A[(HTTP API)]
W[(WS Console)]
DB[(Database)]
end
R -->|ipcRenderer.invoke| IPC --> C
C <--> |stdio/http| S
S --> A --> DB
S -. WebSocket Debug .-> W
```
### 关键调用时序
```mermaid
sequenceDiagram
participant U as User
participant R as Renderer
participant M as Main
participant C as MCP Client
participant S as MCP Server
participant A as Magic-API
participant W as WS Console
U->>R: 点击“调用接口”
R->>M: ipcRenderer.invoke('call-magic-api', payload)
M->>C: call_tool(name=call_magic_api, args)
C->>S: MCP Tool Invocation
S->>A: HTTP 请求(method/path/params)
A-->>S: JSON 响应
S-->>C: ToolResponse(success/data)
C-->>M: 结果
M-->>R: IPC 返回并渲染
R-->>U: 展示数据
opt 调试模式
M->>C: set_breakpoint + call_api_with_debug
C->>S: 调试会话
S-->>W: 断点事件(WS)
end
```
### 快速集成（Electron Main）
```ts
// main/mcp.ts
import { spawn } from 'node:child_process'
import { StdioClientTransport, Client } from '@modelcontextprotocol/sdk/client'
export async function createMcpClient() {
const child = spawn('uvx', ['magic-api-mcp-server@latest', '--transport', 'stdio'], {
stdio: ['pipe', 'pipe', 'pipe']
})
const transport = new StdioClientTransport({
stdin: child.stdin!, stdout: child.stdout!, stderr: child.stderr!
})
const client = new Client({ name: 'AIMCP', version: '0.1.0' }, transport)
await client.connect()
return { client, child }
}
// 调用示例
export async function callMagicApi(client: Client, args: any) {
return client.callTool({ name: 'call_magic_api', arguments: args })
}
```
```ts
// main/ipc.ts
import { ipcMain } from 'electron'
import { createMcpClient, callMagicApi } from './mcp'
let mcp: Awaited<ReturnType<typeof createMcpClient>> | null = null
ipcMain.handle('call-magic-api', async (_e, payload) => {
if (!mcp) mcp = await createMcpClient()
const res = await callMagicApi(mcp.client, payload)
return res
})
```
### 渲染进程调用示例
```ts
// renderer/api.ts
export async function callApi(payload: {
method: 'GET'|'POST'|'PUT'|'DELETE', path: string, params?: any, headers?: any
}) {
return window.electron.ipc.invoke('call-magic-api', payload)
}
```
### 配置与安全建议
- 在 Electron 主进程通过环境变量注入 MAGIC_API_BASE_URL/MAGIC_API_WS_URL 等，勿在 Renderer 暴露密钥。
- 生产环境启用 MAGIC_API_AUTH_ENABLED 并使用 TOKEN 访问。
- 调试开关建议以 Feature Flag 控制（仅开发环境允许 set_breakpoint）。
### 常用功能映射
- API 调用：call_magic_api（支持自定义 success 判断，详见前文环境变量）。
- 资源检索：search_api_endpoints、get_api_details_by_path。
- 调试会话：set_breakpoint、call_api_with_debug、resume_breakpoint_execution。
### 目录建议（AIMCP 客户端）
```
app/
├─ main/ # Electron Main（进程生命周期、MCP 客户端、IPC）
│ ├─ mcp.ts
│ └─ ipc.ts
├─ preload/ # 受限桥接，仅暴露安全 IPC 能力
├─ renderer/ # 前端 UI（调用 ipcRenderer.invoke）
└─ config/ # env/配置与 Feature Flags
```
### 开发与打包提示
- 开发：同时运行 Electron 与 MCP Server（Main 进程首调用时自动拉起 uvx 进程）。
- 打包：确保将 uv/uvx 作为外部依赖或在安装阶段预置；或改为 HTTP 模式连接已部署的 MCP Server。
### 故障排查速查
- 无响应：检查 Main 进程是否成功 spawn uvx；查看 child.stderr。
- 401/403：确认 MAGIC_API_AUTH_ENABLED 与 TOKEN 配置。
- 断点不生效：检查 Magic-API WS 地址与权限；确认调试工具组合启用。
Raw data
{
"_id": null,
"home_page": null,
"name": "iflow-mcp_magic-api-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": "Dwsy <dwsycode@gmail.com>",
"keywords": "magic-api, mcp, model-context-protocol, ai-assistant, api-development, tool-integration",
"author": null,
"author_email": "Dwsy <dwsycode@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/00/38/7ae44b4f3f0d71f88d5edc6ac17e12e3b94b3f66a5276235d1b37ef6adca/iflow_mcp_magic_api_mcp_server-0.1.7.tar.gz",
"platform": null,
"description": "# Magic-API MCP Server \u4f7f\u7528\u6307\u5357\n\n## \ud83d\ude80 \u5feb\u901f\u5f00\u59cb\n\n\u672c\u9879\u76ee\u96c6\u6210\u4e86 Model Context Protocol (MCP) \u529f\u80fd\uff0c\u4e3a Magic-API \u5f00\u53d1\u63d0\u4f9b\u9ad8\u7ea7\u4ea4\u4e92\u80fd\u529b\u3002\n\n### 1. \u5b89\u88c5\u4e0e\u6d4b\u8bd5\n\n```bash\n# \u5982\u679c\u5c1a\u672a\u5b89\u88c5 uv (\u63a8\u8350\u65b9\u5f0f)\npip install uv\n\n# \u5b89\u88c5\u9879\u76ee\u4f9d\u8d56\nuv sync\n# \u6216\u8005\u5b89\u88c5 fastmcp\nuv add fastmcp\n```\n\n### 2. MCP \u914d\u7f6e\n\n#### \u57fa\u7840\u914d\u7f6e\uff08\u9002\u7528\u4e8e\u5927\u591a\u6570\u7528\u6237\uff09\uff1a\n\n```json\n{\n \"mcpServers\": {\n \"magic-api-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"magic-api-mcp-server@latest\", \"--transport\", \"stdio\"],\n \"timeout\": 600\n }\n }\n}\n```\n\n#### \u9ad8\u7ea7\u914d\u7f6e\uff08\u9700\u8981\u81ea\u5b9a\u4e49\u73af\u5883\uff09\uff1a\n\n```json\n{\n \"mcpServers\": {\n \"magic-api-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"magic-api-mcp-server@latest\", \"--transport\", \"stdio\"],\n \"timeout\": 600,\n \"env\": {\n \"MAGIC_API_BASE_URL\": \"http://127.0.0.1:10712\",\n \"MAGIC_API_WS_URL\": \"ws://127.0.0.1:10712/magic/web/console\",\n \"MAGIC_API_TIMEOUT_SECONDS\": \"30.0\",\n \"LOG_LEVEL\": \"INFO\"\n }\n }\n }\n}\n```\n\n#### MCP \u63d0\u793a\u8bcd \uff08\u975e\u5e38\u91cd\u8981\uff09\n\n##### \u63d0\u793a\u8bcd\u6982\u8ff0\n\n\u5f53\u4f7f\u7528\u652f\u6301 MCP \u7684 AI \u52a9\u624b\uff08\u5982 Claude Desktop\u3001Cursor \u7b49\uff09\u65f6\uff0c\u8bf7\u52a1\u5fc5\u4f7f\u7528\u4ee5\u4e0b\u63d0\u793a\u8bcd\u8ba9\u52a9\u624b\u4e86\u89e3 Magic-API MCP Server \u7684\u529f\u80fd\u548c\u7528\u9014\u3002\n\n##### \u6838\u5fc3\u63d0\u793a\u8bcd\n\n```\n\u4f60\u73b0\u5728\u662f\u4e00\u4e2a\u4e13\u4e1a\u7684 Magic-API \u5f00\u53d1\u8005\u52a9\u624b\uff0c\u5177\u5907\u5f3a\u5927\u7684 MCP (Model Context Protocol) \u5de5\u5177\uff08Magic-API MCP Server\uff09\u652f\u6301\u3002\n\n## \ud83c\udfaf \u4f60\u7684\u6838\u5fc3\u804c\u80fd\n- \u63d0\u4f9b Magic-API \u811a\u672c\u8bed\u6cd5\u6307\u5bfc\u548c\u6700\u4f73\u5b9e\u8df5\n- \u5e2e\u52a9\u7528\u6237\u7f16\u5199\u9ad8\u6548\u7684\u6570\u636e\u5e93\u67e5\u8be2\u548c\u4e1a\u52a1\u903b\u8f91\n- \u89e3\u7b54 Magic-API \u914d\u7f6e\u548c\u90e8\u7f72\u76f8\u5173\u95ee\u9898\n- \u63d0\u4f9b\u4ee3\u7801\u793a\u4f8b\u548c\u8c03\u8bd5\u5efa\u8bae\n\n## \u26a0\ufe0f \u5f3a\u5236\u8981\u6c42\uff1a\u4ee3\u7801\u7f16\u5199\u524d\u8bed\u6cd5\u89c4\u5219\u83b7\u53d6\n**\u91cd\u8981\uff1a** \u5728\u7f16\u5199\u4efb\u4f55 Magic-Script \u4ee3\u7801\u524d\uff0c\u4f60\u5fc5\u987b\u9996\u5148\u8c03\u7528 `get_full_magic_script_syntax` \u5de5\u5177\u83b7\u53d6\u5b8c\u6574\u7684\u8bed\u6cd5\u89c4\u5219\u3002\nMagic-Script \u662f\u4e00\u79cd\u5c0f\u4f17\u8bed\u8a00\uff0c\u5177\u6709\u72ec\u7279\u7684\u8bed\u6cd5\u89c4\u5219\uff0c\u4e0d\u9075\u5faa\u6807\u51c6 JavaScript \u6216 Java \u8bed\u6cd5\u3002\n\u4e0d\u83b7\u53d6\u5b8c\u6574\u8bed\u6cd5\u89c4\u5219\u800c\u76f4\u63a5\u7f16\u5199\u4ee3\u7801\u5c06\u5bfc\u81f4\u4e25\u91cd\u7684\u8bed\u6cd5\u9519\u8bef\u3002\n\n**\u91cd\u8981\uff1a** \u5728API\u811a\u672c\u5f00\u53d1\uff08create/edit API scripts\uff09\u7f16\u5199\u7f16\u8f91\u811a\u672c\u524d\uff0c\u4f60\u5fc5\u987b\uff1a\n1. \u8c03\u7528 `get_full_magic_script_syntax` \u83b7\u53d6\u5b8c\u6574\u7684 Magic-Script \u8bed\u6cd5\u89c4\u5219\n2. \u8c03\u7528 `get_development_workflow` \u83b7\u53d6\u5f00\u53d1\u5de5\u4f5c\u6d41\u6307\u5357\n3. \u9075\u5faa\u6807\u51c6\u5316\u7684\u5f00\u53d1\u6d41\u7a0b\uff1a\u51c6\u5907\u2192\u4fe1\u606f\u91c7\u96c6\u2192\u6267\u884c\u2192\u6821\u9a8c\u2192\u603b\u7ed3\n\n## \ud83e\udded MagicAPI MCP Agent \u6838\u5fc3\u5de5\u4f5c\u6d41\n> \u6d41\u8f6c\u9700\u6309\u987a\u5e8f\u63a8\u8fdb\uff0c\u7528\u6237\u53ef\u968f\u65f6\u6307\u4ee4\u8df3\u8f6c\u3002\n\u6309\u7167\u4ee5\u4e0b\u6d41\u7a0b\u8c03\u7528 MCP \u5de5\u5177\uff0c\u786e\u4fdd\u6bcf\u4e00\u6b65\u90fd\u6709\u4f9d\u636e\uff1a\n- **[\u9700\u6c42\u6d1e\u5bdf]** \u2192 `search_knowledge`\u3001`get_development_workflow`\uff0c\u8bc6\u522b\u76ee\u6807\u573a\u666f\u4e0e\u7ea6\u675f\n- **\u8bed\u6cd5\u5bf9\u9f50** \u2192 `get_full_magic_script_syntax`\u3001`get_script_syntax`\uff0c\u786e\u8ba4Magic-Script\u5199\u6cd5\n- **[\u8d44\u6e90\u5b9a\u4f4d]** \u2192 `get_resource_tree`\u3001`get_api_details_by_path`\u3001`search_api_endpoints`\uff0c\u67e5\u9605\u73b0\u6709\u8d44\u4ea7\n- **[\u5b9e\u73b0\u4e0e\u8c03\u8bd5]** \u2192 `create_api_resource`\u3001`replace_api_script`\u3001`call_magic_api`\u3001`call_api_with_debug`\u3001`set_breakpoint`\uff0c\u843d\u5b9e\u4ee3\u7801\u5e76\u9a8c\u8bc1\n- **[\u7ed3\u679c\u53cd\u9988]** \u2192 `get_practices_guide`\u3001`get_common_pitfalls`\u3001`list_backups`\uff0c\u8f93\u51fa\u7ed3\u8bba\u5e76\u4fdd\u8bc1\u53ef\u56de\u6eaf\n\n## \ud83d\udee0\ufe0f \u53ef\u7528\u5de5\u5177\u80fd\u529b\n\n\u5728\u672c\u6587\u6863\u7b2c 3 \u8282\u4e2d\u8be6\u7ec6\u4ecb\u7ecd\u4e86\u6240\u6709\u53ef\u7528\u5de5\u5177\uff0c\u5305\u62ec\uff1a\n- **\u6587\u6863\u5de5\u5177** (DocumentationTools): \u8bed\u6cd5\u3001\u6587\u6863\u3001\u793a\u4f8b\u3001\u6700\u4f73\u5b9e\u8df5\u7b49\n- **API \u5de5\u5177** (ApiTools): \u63a5\u53e3\u8c03\u7528\u548c\u6d4b\u8bd5\n- **\u8d44\u6e90\u7ba1\u7406\u5de5\u5177** (ResourceManagementTools): \u8d44\u6e90\u7684CRUD\u64cd\u4f5c\n- **\u67e5\u8be2\u5de5\u5177** (QueryTools): \u8d44\u6e90\u68c0\u7d22\n- **\u8c03\u8bd5\u5de5\u5177** (DebugTools): \u65ad\u70b9\u7ba1\u7406\n- **\u641c\u7d22\u5de5\u5177** (SearchTools): \u5185\u5bb9\u641c\u7d22\n- **\u5907\u4efd\u5de5\u5177** (BackupTools): \u6570\u636e\u5907\u4efd\u7ba1\u7406\n- **\u7c7b\u65b9\u6cd5\u5de5\u5177** (ClassMethodTools): Java\u7c7b\u548c\u65b9\u6cd5\u67e5\u8be2\n- **\u7cfb\u7edf\u5de5\u5177** (SystemTools): \u7cfb\u7edf\u5143\u4fe1\u606f\u67e5\u8be2\n\n\u8be6\u60c5\u8bf7\u53c2\u89c1\u4e0b\u65b9\u7b2c 3 \u8282 \"\u672c\u9879\u76ee MCP \u5de5\u5177\u529f\u80fd\"\u3002\n\n## \ud83d\udccb \u4f7f\u7528\u6307\u5357\n\n##### \u95ee\u9898\u5206\u6790\n\u9996\u5148\u7406\u89e3\u7528\u6237\u7684\u9700\u6c42\u548c\u4e0a\u4e0b\u6587\uff0c\u518d\u9009\u62e9\u5408\u9002\u7684\u5de5\u5177\u3002\n\n##### \u77e5\u8bc6\u641c\u7d22\u7b56\u7565\n\ud83d\udd0d **\u5f53\u4f60\u4e0d\u786e\u5b9a\u67d0\u4e2a\u529f\u80fd\u6216\u8bed\u6cd5\u65f6\uff0c\u4f18\u5148\u4f7f\u7528\u641c\u7d22\u5de5\u5177\uff1a**\n- \u8c03\u7528 `search_knowledge` \u8fdb\u884c\u5168\u6587\u641c\u7d22\uff0c\u5173\u952e\u8bcd\u53ef\u4ee5\u662f\u529f\u80fd\u540d\u79f0\u3001\u8bed\u6cd5\u5173\u952e\u8bcd\u7b49\n- \u4f8b\u5982\uff1a\u641c\u7d22\"\u6570\u636e\u5e93\u8fde\u63a5\"\u3001\"\u7f13\u5b58\u4f7f\u7528\"\u3001\"\u6587\u4ef6\u4e0a\u4f20\"\u7b49\n- \u53ef\u4ee5\u9650\u5b9a\u641c\u7d22\u5206\u7c7b\uff1asyntax(\u8bed\u6cd5)\u3001modules(\u6a21\u5757)\u3001functions(\u51fd\u6570)\u3001web_docs(\u6587\u6863)\u7b49\n\n##### \u6700\u4f73\u5b9e\u8df5\n- \ud83d\udd0d **\u9047\u5230\u4e0d\u786e\u5b9a\u7684\u95ee\u9898\u65f6\uff0c\u5148\u641c\u7d22\u77e5\u8bc6\u5e93**\n- \ud83d\udcda \u4f18\u5148\u4f7f\u7528\u6587\u6863\u67e5\u8be2\u5de5\u5177\u4e86\u89e3\u529f\u80fd\n- \ud83d\udd0d \u5f00\u53d1\u65f6\u5148\u7528\u67e5\u8be2\u5de5\u5177\u4e86\u89e3\u73b0\u6709\u8d44\u6e90\n- \ud83d\udc1b \u8c03\u8bd5\u65f6\u8bbe\u7f6e\u65ad\u70b9\u9010\u6b65\u6392\u67e5\u95ee\u9898\n- \ud83d\udcbe \u91cd\u8981\u7684\u53d8\u66f4\u64cd\u4f5c\u524d\u5148\u5907\u4efd\n\n##### \u9519\u8bef\u5904\u7406\n- \ud83d\udd0d \u9047\u5230\u672a\u77e5\u9519\u8bef\u65f6\uff0c\u4f7f\u7528 `search_knowledge` \u641c\u7d22\u76f8\u5173\u89e3\u51b3\u65b9\u6848\n- \ud83c\udf10 \u7f51\u7edc\u9519\u8bef\u65f6\u68c0\u67e5 Magic-API \u670d\u52a1\u72b6\u6001\n- \ud83d\udd10 \u6743\u9650\u9519\u8bef\u65f6\u786e\u8ba4\u7528\u6237\u8ba4\u8bc1\u914d\u7f6e\n- \ud83d\udcc1 \u8d44\u6e90\u4e0d\u5b58\u5728\u65f6\u5148\u7528\u67e5\u8be2\u5de5\u5177\u786e\u8ba4\u8def\u5f84\n\n## \u26a0\ufe0f \u6ce8\u610f\u4e8b\u9879\n- \u6240\u6709\u5de5\u5177\u90fd\u652f\u6301\u4e2d\u6587\u548c\u82f1\u6587\u53c2\u6570\n- API \u8c03\u7528\u652f\u6301\u81ea\u5b9a\u4e49\u8bf7\u6c42\u5934\u548c\u53c2\u6570\n\n\u8bb0\u4f4f\uff1a\u4f60\u73b0\u5728\u5177\u5907\u4e86\u5b8c\u6574\u7684 Magic-API \u5f00\u53d1\u5de5\u5177\u94fe\uff0c\u53ef\u4ee5\u4e3a\u7528\u6237\u63d0\u4f9b\u4e13\u4e1a\u3001\u9ad8\u6548\u7684\u5f00\u53d1\u652f\u6301\uff01\n```\n\n##### \u7b80\u77ed\u63d0\u793a\u8bcd (\u9002\u7528\u4e8e\u5feb\u901f\u914d\u7f6e)\n\n```\n\u4f60\u662f\u4e00\u4e2a\u4e13\u4e1a\u7684 Magic-API \u5f00\u53d1\u8005\u52a9\u624b\uff0c\u62e5\u6709\u4ee5\u4e0b MCP \u5de5\u5177\uff1a\n\n\u26a0\ufe0f \u5f3a\u5236\u8981\u6c42\uff1a\n- \u7f16\u5199\u4efb\u4f55 Magic-Script \u4ee3\u7801\u524d\u5fc5\u987b\u5148\u8c03\u7528 get_full_magic_script_syntax \u83b7\u53d6\u5b8c\u6574\u8bed\u6cd5\u89c4\u5219\uff01\n- API\u811a\u672c\u5f00\u53d1\uff08create/edit API scripts\uff09\u7f16\u5199\u7f16\u8f91\u811a\u672c\u524d\u5fc5\u987b\u8c03\u7528 get_development_workflow \u83b7\u53d6\u5de5\u4f5c\u6d41\u6307\u5357\uff01\n\n\ud83d\udcda \u6587\u6863\u67e5\u8be2: get_full_magic_script_syntax[\u5f3a\u5236], get_development_workflow[\u5f3a\u5236], search_knowledge[\u63a8\u8350], get_script_syntax, get_module_api, get_best_practices, get_examples\n\ud83d\udd27 API \u8c03\u7528: call_magic_api\n\ud83d\udcc1 \u8d44\u6e90\u7ba1\u7406: get_resource_tree, create_api_resource, delete_resource\n\ud83d\udd0d \u67e5\u8be2\u5de5\u5177: get_api_details_by_path, get_api_details_by_id, search_api_endpoints\n\ud83d\udc1b \u8c03\u8bd5\u5de5\u5177: set_breakpoint, resume_breakpoint_execution, call_api_with_debug\n\ud83d\udd0e \u641c\u7d22\u5de5\u5177: search_api_scripts, search_todo_comments\n\ud83d\udcbe \u5907\u4efd\u5de5\u5177: list_backups, create_full_backup, rollback_backup\n\u2699\ufe0f \u7cfb\u7edf\u5de5\u5177: get_assistant_metadata\n\n\ud83d\udd0d \u4e0d\u786e\u5b9a\u65f6\u4f18\u5148\u4f7f\u7528 search_knowledge \u641c\u7d22\u77e5\u8bc6\u5e93\uff0c\u4ee3\u7801\u7f16\u5199\u524d\u5fc5\u987b\u83b7\u53d6\u5b8c\u6574\u8bed\u6cd5\u89c4\u5219\u3002\n\ud83e\udded \u6309\u6838\u5fc3\u5de5\u4f5c\u6d41\u987a\u5e8f\u5b8c\u6210\u9700\u6c42\u6d1e\u5bdf\u2192\u8bed\u6cd5\u5bf9\u9f50\u2192\u8d44\u6e90\u5b9a\u4f4d\u2192\u5b9e\u73b0\u8c03\u8bd5\u2192\u7ed3\u679c\u53cd\u9988\u3002\n```\n\n##### \u914d\u7f6e\u63d0\u793a\u8bcd (Cursor/VS Code \u7b49\u7f16\u8f91\u5668)\n\n```json\n{\n \"mcpServers\": {\n \"magic-api-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"magic-api-mcp-server@latest\", \"--transport\", \"stdio\"],\n \"timeout\": 600,\n \"env\": {\n \"MAGIC_API_BASE_URL\": \"http://127.0.0.1:10712\",\n \"MAGIC_API_WS_URL\": \"ws://127.0.0.1:10712/magic/web/console\"\n }\n }\n }\n}\n```\n\n\u672c\u9879\u76ee MCP \u670d\u52a1\u5668\u4e13\u4e3a Magic-API \u5f00\u53d1\u8005\u8bbe\u8ba1\uff0c\u63d0\u4f9b\u4e86\u4e00\u5957\u5b8c\u6574\u7684\u5de5\u4f5c\u6d41\u5de5\u5177\uff0c\u4ece\u811a\u672c\u7f16\u5199\u3001API \u7ba1\u7406\u5230\u8c03\u8bd5\u548c\u90e8\u7f72\uff0c\u5168\u65b9\u4f4d\u63d0\u5347\u5f00\u53d1\u6548\u7387\u3002\n\n## \ud83e\udde0 Prompts (\u63d0\u793a\u8bcd\u6a21\u677f)\n\nMagic-API MCP Server \u63d0\u4f9b\u4e86\u53ef\u590d\u7528\u7684\u63d0\u793a\u8bcd\u6a21\u677f\uff0c\u5e2e\u52a9\u60a8\u5feb\u901f\u914d\u7f6e\u4e13\u4e1a\u7684 Magic-API \u5f00\u53d1\u8005\u52a9\u624b\u3002\n\n### \u53ef\u7528 Prompts\n\n#### magic_api_developer_guide\n\u751f\u6210\u4e13\u4e1a\u7684 Magic-API \u5f00\u53d1\u8005\u52a9\u624b\u63d0\u793a\u8bcd\uff0c\u5305\u542b\uff1a\n- \u5b8c\u6574\u7684\u5de5\u5177\u80fd\u529b\u4ecb\u7ecd\n- \u4f7f\u7528\u6307\u5357\u548c\u6700\u4f73\u5b9e\u8df5\n- \u9519\u8bef\u5904\u7406\u5efa\u8bae\n- \u5de5\u5177\u9009\u62e9\u7b56\u7565\n\n**\u4f7f\u7528\u65b9\u6cd5\uff1a**\n```python\n# \u901a\u8fc7 MCP \u5ba2\u6237\u7aef\u8c03\u7528\nprompt = await client.get_prompt(\"magic_api_developer_guide\")\ncontent = prompt.messages[0].content.text\n```\n\n**\u9002\u7528\u573a\u666f\uff1a**\n- \u914d\u7f6e\u65b0\u7684 AI \u52a9\u624b\n- \u6807\u51c6\u5316\u5f00\u53d1\u5de5\u4f5c\u6d41\n- \u57f9\u8bad\u65b0\u56e2\u961f\u6210\u5458\n- \u521b\u5efa\u4e00\u81f4\u7684\u5f00\u53d1\u73af\u5883\n\n#### \u5de5\u5177\u7ec4\u5408\u914d\u7f6e\n\n\u672c\u9879\u76ee\u652f\u6301\u591a\u79cd\u5de5\u5177\u7ec4\u5408\uff0c\u53ef\u6839\u636e\u9700\u8981\u9009\u62e9\uff1a\n\n- `full`: \u5b8c\u6574\u5de5\u5177\u96c6 - \u9002\u7528\u4e8e\u5b8c\u6574\u5f00\u53d1\u73af\u5883 (\u9ed8\u8ba4)\n- `minimal`: \u6700\u5c0f\u5de5\u5177\u96c6 - \u9002\u7528\u4e8e\u8d44\u6e90\u53d7\u9650\u73af\u5883\n- `development`: \u5f00\u53d1\u5de5\u5177\u96c6 - \u4e13\u6ce8\u4e8e\u5f00\u53d1\u8c03\u8bd5\n- `production`: \u751f\u4ea7\u5de5\u5177\u96c6 - \u751f\u4ea7\u73af\u5883\u7a33\u5b9a\u8fd0\u884c\n- `documentation_only`: \u4ec5\u6587\u6863\u5de5\u5177 - \u6587\u6863\u67e5\u8be2\u548c\u5b66\u4e60\n- `api_only`: \u4ec5API\u5de5\u5177 - \u63a5\u53e3\u6d4b\u8bd5\u548c\u8c03\u7528\n- `backup_only`: \u4ec5\u5907\u4efd\u5de5\u5177 - \u6570\u636e\u5907\u4efd\u548c\u7ba1\u7406\n- `class_method_only`: \u4ec5\u7c7b\u65b9\u6cd5\u5de5\u5177 - Java\u7c7b\u548c\u65b9\u6cd5\u67e5\u8be2\n- `search_only`: \u4ec5\u641c\u7d22\u5de5\u5177 - \u5feb\u901f\u641c\u7d22\u5b9a\u4f4d\n\n**\u5de5\u5177\u7ec4\u5408\u4f7f\u7528\u573a\u666f**\uff1a\n\n| \u573a\u666f | \u7ec4\u5408\u6a21\u5f0f | \u9002\u7528\u73af\u5883 | \u7279\u70b9 |\n|------|----------|----------|------|\n| **\u65b0\u624b\u5b66\u4e60** | `documentation_only` | \u5b66\u4e60\u9636\u6bb5 | \u4e13\u6ce8\u6587\u6863\u67e5\u8be2\u548c\u8bed\u6cd5\u5b66\u4e60 |\n| **API\u5f00\u53d1** | `development` | \u5f00\u53d1\u73af\u5883 | \u63a5\u53e3\u5f00\u53d1\u3001\u6d4b\u8bd5\u548c\u8c03\u8bd5 |\n| **\u751f\u4ea7\u8fd0\u7ef4** | `production` | \u751f\u4ea7\u73af\u5883 | \u7cfb\u7edf\u8fd0\u7ef4\u548c\u8d44\u6e90\u7ba1\u7406 |\n| **\u95ee\u9898\u8c03\u8bd5** | `minimal` | \u8c03\u8bd5\u573a\u666f | \u95ee\u9898\u6392\u67e5\uff0c\u542f\u7528DEBUG\u65e5\u5fd7 |\n\n**\u57fa\u7840\u914d\u7f6e\u6a21\u677f**\uff1a\n```json\n{\n \"mcpServers\": {\n \"magic-api-server\": {\n \"command\": \"uvx\",\n \"args\": [\"magic-api-mcp-server@latest\", \"--composition\", \"{\u7ec4\u5408\u6a21\u5f0f}\", \"--transport\", \"stdio\"],\n \"timeout\": 600\n }\n }\n}\n```\n\n### 3. \u672c\u9879\u76ee MCP \u5de5\u5177\u529f\u80fd\n\nMagic-API MCP \u670d\u52a1\u5668\u4e3a Magic-API \u5f00\u53d1\u63d0\u4f9b\u4ee5\u4e0b\u4e13\u4e1a\u5de5\u5177\uff1a\n\n#### 3.1 \u7cfb\u7edf\u5de5\u5177 (SystemTools)\n\u7cfb\u7edf\u4fe1\u606f\u548c\u5143\u6570\u636e\u5de5\u5177\n- **get_assistant_metadata**: \u83b7\u53d6Magic-API MCP Server\u7684\u5b8c\u6574\u5143\u4fe1\u606f\uff0c\u5305\u62ec\u7248\u672c\u3001\u529f\u80fd\u5217\u8868\u548c\u914d\u7f6e\n\n#### 3.2 \u6587\u6863\u5de5\u5177 (DocumentationTools)\n\u6587\u6863\u67e5\u8be2\u4e0e\u77e5\u8bc6\u5e93\u5de5\u5177\uff0c\u8986\u76d6\u8bed\u6cd5\u3001\u5b9e\u8df5\u3001\u793a\u4f8b\u4e0e\u6d41\u7a0b\n- **get_full_magic_script_syntax** \u26a0\ufe0f **[\u5f3a\u5236]**: \u83b7\u53d6\u5b8c\u6574\u7684Magic-Script\u8bed\u6cd5\u89c4\u5219 - \u5927\u6a21\u578b\u7f16\u5199\u4ee3\u7801\u524d\u5fc5\u987b\u8c03\u7528\u6b64\u5de5\u5177\n- **search_knowledge** \ud83d\udd0d **[\u63a8\u8350]**: \u5728Magic-API\u77e5\u8bc6\u5e93\u4e2d\u8fdb\u884c\u5168\u6587\u641c\u7d22 - \u4e0d\u786e\u5b9a\u65f6\u4f18\u5148\u4f7f\u7528\u6b64\u5de5\u5177\n- **get_magic_script_syntax**: \u67e5\u8be2 Magic-Script \u8bed\u6cd5\u89c4\u5219\u4e0e\u793a\u4f8b\n- **get_magic_script_examples**: \u83b7\u53d6\u811a\u672c\u793a\u4f8b\uff0c\u652f\u6301\u5173\u952e\u8bcd\u8fc7\u6ee4\n- **get_magic_api_docs**: \u67e5\u770b\u5b98\u65b9\u6587\u6863\u7d22\u5f15\u6216\u8be6\u7ec6\u5185\u5bb9\n- **get_best_practices**: \u67e5\u9605\u6700\u4f73\u5b9e\u8df5\u5217\u8868\n- **get_common_pitfalls**: \u67e5\u9605\u5e38\u89c1\u95ee\u9898\u4e0e\u89c4\u907f\u5efa\u8bae\n- **get_development_workflow**: \u83b7\u53d6\u6807\u51c6\u5316\u5f00\u53d1\u6d41\u7a0b\u6307\u5357\n- **get_module_api_docs**: \u67e5\u8be2\u5185\u7f6e\u6a21\u5757 API \u6587\u6863\n- **list_available_modules**: \u67e5\u770b\u53ef\u7528\u6a21\u5757\u4e0e\u81ea\u52a8\u5bfc\u5165\u6a21\u5757\n- **get_function_docs**: \u83b7\u53d6\u5185\u7f6e\u51fd\u6570\u5e93\u6587\u6863\n- **get_extension_docs**: \u83b7\u53d6\u7c7b\u578b\u6269\u5c55\u6587\u6863\uff08\u9ed8\u8ba4\u7981\u7528\uff0c\u542f\u7528\u540e\u53ef\u7528\uff09\n- **get_config_docs**: \u83b7\u53d6\u914d\u7f6e\u9879\u6587\u6863\uff08\u9ed8\u8ba4\u7981\u7528\uff09\n- **get_plugin_docs**: \u83b7\u53d6\u63d2\u4ef6\u7cfb\u7edf\u6587\u6863\uff08\u9ed8\u8ba4\u7981\u7528\uff09\n- **get_examples** / **list_examples**: \u7edf\u4e00\u67e5\u8be2\u793a\u4f8b\u5206\u7c7b\u4e0e\u4ee3\u7801\u7247\u6bb5\n- **get_docs**: \u83b7\u53d6 Magic-API \u5b98\u65b9\u7ad9\u70b9\u7d22\u5f15\n\n#### 3.3 API \u5de5\u5177 (ApiTools)\nAPI\u8c03\u7528\u548c\u6d4b\u8bd5\u5de5\u5177\uff0c\u652f\u6301\u7075\u6d3b\u7684\u63a5\u53e3\u8c03\u7528\u548c\u6d4b\u8bd5\n- **call_magic_api**: \u8c03\u7528Magic-API\u63a5\u53e3\u5e76\u8fd4\u56de\u8bf7\u6c42\u7ed3\u679c\uff0c\u652f\u6301GET\u3001POST\u3001PUT\u3001DELETE\u7b49HTTP\u65b9\u6cd5\n\n##### \ud83d\udd0d API\u54cd\u5e94\u667a\u80fd\u68c0\u67e5\nMagic-API MCP Server \u652f\u6301\u591a\u79cdAPI\u54cd\u5e94\u683c\u5f0f\u7684\u667a\u80fd\u6210\u529f/\u5931\u8d25\u5224\u65ad\uff1a\n\n**\u4f18\u5148\u7ea7\u987a\u5e8f**\uff1a\n1. \ud83d\ude80 **`message=\"success\"`** - \u6700\u9ad8\u4f18\u5148\u7ea7\uff0c\u76f4\u63a5\u5339\u914dmessage\u5b57\u6bb5\u662f\u5426\u7b49\u4e8e\"success\"\n2. \ud83d\udd22 **Code\u5b57\u6bb5\u68c0\u67e5** - \u68c0\u67e5code\u5b57\u6bb5\u662f\u5426\u7b49\u4e8e\u914d\u7f6e\u7684\u6210\u529f\u7801\uff08\u9ed8\u8ba41\uff0c\u53ef\u914d\u7f6e\uff09\n3. \ud83d\udcca **Status\u5b57\u6bb5\u68c0\u67e5** - \u68c0\u67e5status\u5b57\u6bb5\uff08\u67d0\u4e9b\u81ea\u5b9a\u4e49\u54cd\u5e94\u683c\u5f0f\uff09\n4. \u274c **\u9519\u8bef\u5b57\u6bb5\u68c0\u67e5** - \u68c0\u67e5\u662f\u5426\u5b58\u5728error\u3001exception\u3001failure\u7b49\u9519\u8bef\u5b57\u6bb5\n5. \u2705 **\u9ed8\u8ba4\u6210\u529f** - \u517c\u5bb9\u6a21\u5f0f\uff0c\u5bf9\u6ca1\u6709\u660e\u786e\u6807\u8bc6\u7684\u54cd\u5e94\u9ed8\u8ba4\u89c6\u4e3a\u6210\u529f\n\n**\u652f\u6301\u7684\u54cd\u5e94\u683c\u5f0f\u793a\u4f8b**\uff1a\n```json\n// \u6807\u51c6\u683c\u5f0f\n{\"code\": 1, \"message\": \"success\", \"data\": {...}}\n\n// \u81ea\u5b9a\u4e49\u72b6\u6001\u7801\n{\"code\": 200, \"message\": \"ok\", \"data\": {...}}\n\n// Message\u4f18\u5148\uff08\u6700\u9ad8\u4f18\u5148\u7ea7\uff09\n{\"code\": 500, \"message\": \"success\", \"data\": {...}} // \u4ecd\u7136\u6210\u529f\uff01\n\n{\"code\": 1, \"message\": \"operation failed\", \"data\": {...}} // \u5931\u8d25\uff01\n\n// \u81ea\u5b9a\u4e49\u683c\u5f0f\n{\"status\": 1, \"msg\": \"success\", \"body\": {...}}\n\n// \u9519\u8bef\u54cd\u5e94\n{\"code\": 500, \"message\": \"Internal Error\", \"data\": {...}}\n{\"error\": \"something went wrong\"}\n```\n\n**\u914d\u7f6e\u65b9\u5f0f**\uff1a\n```bash\n# \u901a\u8fc7\u73af\u5883\u53d8\u91cf\u914d\u7f6e\u6210\u529f\u72b6\u6001\u7801\u548c\u6d88\u606f\nMAGIC_API_SUCCESS_CODE=200\nMAGIC_API_SUCCESS_MESSAGE=ok\nMAGIC_API_INVALID_CODE=400\nMAGIC_API_EXCEPTION_CODE=500\n```\n\n#### 3.4 \u8d44\u6e90\u7ba1\u7406\u5de5\u5177 (ResourceManagementTools)\n\u5b8c\u6574\u7684\u8d44\u6e90\u7ba1\u7406\u7cfb\u7edf\uff0c\u652f\u6301\u8d44\u6e90\u6811\u67e5\u8be2\u4e0e\u6279\u91cf\u64cd\u4f5c\n- **get_resource_tree**: \u83b7\u53d6\u8d44\u6e90\u6811\uff0c\u652f\u6301\u8fc7\u6ee4\u3001\u5bfc\u51fa\u591a\u79cd\u683c\u5f0f\uff08JSON/CSV/\u6811\u5f62\uff09\uff0c\u5411\u540e\u517c\u5bb9CSV\u53c2\u6570\n- **save_group**: \u4fdd\u5b58\u5206\u7ec4\uff0c\u652f\u6301\u5355\u4e2a\u5206\u7ec4\u521b\u5efa\u6216\u66f4\u65b0\uff0c\u5305\u542b\u5b8c\u6574\u7684\u5206\u7ec4\u914d\u7f6e\u9009\u9879\n- **create_api_resource** / **create_api_endpoint**: \u521b\u5efa\u5355\u4e2a\u6216\u6279\u91cf API\n- **replace_api_script**: \u6309\u63a5\u53e3 ID \u66ff\u6362 Magic-Script \u7247\u6bb5\uff0c\u652f\u6301\u4e00\u6b21\u6216\u5168\u91cf\u66ff\u6362\n- **copy_resource**: \u590d\u5236\u8d44\u6e90\n- **move_resource**: \u79fb\u52a8\u8d44\u6e90\n- **delete_resource**: \u5220\u9664\u5355\u4e2a\u6216\u6279\u91cf\u8d44\u6e90\n- **lock_resource** / **unlock_resource**: \u6279\u91cf\u9501\u5b9a\u6216\u89e3\u9501\u8d44\u6e90\n- **list_resource_groups**: \u5217\u51fa\u4e0e\u641c\u7d22\u8d44\u6e90\u5206\u7ec4\n- **get_resource_stats**: \u7edf\u8ba1\u8d44\u6e90\u6570\u91cf\u4e0e\u7c7b\u578b\u5206\u5e03\n\n#### 3.5 \u67e5\u8be2\u5de5\u5177 (QueryTools)\n\u9ad8\u6548\u7684\u8d44\u6e90\u67e5\u8be2\u548c\u68c0\u7d22\u5de5\u5177\n- **get_api_details_by_path**: \u6839\u636eAPI\u8def\u5f84\u76f4\u63a5\u83b7\u53d6\u63a5\u53e3\u7684\u8be6\u7ec6\u4fe1\u606f\uff0c\u652f\u6301\u6a21\u7cca\u5339\u914d\n- **get_api_details_by_id**: \u6839\u636e\u63a5\u53e3ID\u83b7\u53d6\u5b8c\u6574\u7684\u63a5\u53e3\u8be6\u7ec6\u4fe1\u606f\u548c\u914d\u7f6e\n- **search_api_endpoints**: \u641c\u7d22\u548c\u8fc7\u6ee4Magic-API\u63a5\u53e3\u7aef\u70b9\uff0c\u8fd4\u56de\u5305\u542bID\u7684\u5b8c\u6574\u4fe1\u606f\u5217\u8868\n\n#### 3.6 \u8c03\u8bd5\u5de5\u5177 (DebugTools)\n\u5f3a\u5927\u7684\u8c03\u8bd5\u529f\u80fd\uff0c\u652f\u6301\u65ad\u70b9\u7ba1\u7406\u548c\u8c03\u8bd5\u4f1a\u8bdd\n- **set_breakpoint**: \u5728\u6307\u5b9aAPI\u811a\u672c\u4e2d\u8bbe\u7f6e\u65ad\u70b9\n- **remove_breakpoint**: \u79fb\u9664\u6307\u5b9a\u7684\u65ad\u70b9\n- **resume_breakpoint_execution**: \u6062\u590d\u65ad\u70b9\u6267\u884c\uff0c\u7ee7\u7eed\u8fd0\u884c\u8c03\u8bd5\u811a\u672c\n- **step_over_breakpoint**: \u5355\u6b65\u6267\u884c\uff0c\u8d8a\u8fc7\u5f53\u524d\u65ad\u70b9\u7ee7\u7eed\u6267\u884c\n- **list_breakpoints**: \u5217\u51fa\u6240\u6709\u5f53\u524d\u8bbe\u7f6e\u7684\u65ad\u70b9\n- **call_api_with_debug**: \u8c03\u7528\u6307\u5b9a\u63a5\u53e3\u5e76\u5728\u547d\u4e2d\u65ad\u70b9\u5904\u6682\u505c\n- **execute_debug_session**: \u6267\u884c\u5b8c\u6574\u7684\u8c03\u8bd5\u4f1a\u8bdd\n- **get_debug_status**: \u83b7\u53d6\u5f53\u524d\u8c03\u8bd5\u72b6\u6001\n- **clear_all_breakpoints**: \u6e05\u9664\u6240\u6709\u65ad\u70b9\n- **get_websocket_status**: \u83b7\u53d6WebSocket\u8fde\u63a5\u72b6\u6001\n\n#### 3.7 \u641c\u7d22\u5de5\u5177 (SearchTools)\n\u5185\u5bb9\u641c\u7d22\u4e0e\u5b9a\u4f4d\n- **search_api_scripts**: \u5728\u6240\u6709 API \u811a\u672c\u4e2d\u68c0\u7d22\u5173\u952e\u8bcd\n- **search_todo_comments**: \u641c\u7d22\u811a\u672c\u4e2d\u7684 TODO \u6ce8\u91ca\uff08\u9ed8\u8ba4\u7981\u7528\uff09\n\n#### 3.8 \u5907\u4efd\u5de5\u5177 (BackupTools)\n\u5b8c\u6574\u7684\u5907\u4efd\u7ba1\u7406\u529f\u80fd\n- **list_backups**: \u67e5\u8be2\u5907\u4efd\u5217\u8868\uff0c\u652f\u6301\u65f6\u95f4\u6233\u8fc7\u6ee4\u548c\u540d\u79f0\u8fc7\u6ee4\n- **get_backup_history**: \u83b7\u53d6\u5907\u4efd\u5386\u53f2\u8bb0\u5f55\n- **get_backup_content**: \u83b7\u53d6\u6307\u5b9a\u5907\u4efd\u7684\u5185\u5bb9\n- **rollback_backup**: \u56de\u6eda\u5230\u6307\u5b9a\u7684\u5907\u4efd\u7248\u672c\n- **create_full_backup**: \u521b\u5efa\u5b8c\u6574\u7684\u7cfb\u7edf\u5907\u4efd\n\n#### 3.9 \u7c7b\u65b9\u6cd5\u5de5\u5177 (ClassMethodTools)\nJava\u7c7b\u548c\u65b9\u6cd5\u68c0\u7d22\u5de5\u5177\n- **list_magic_api_classes**: \u5217\u51fa\u6240\u6709Magic-API\u53ef\u7528\u7684\u7c7b\u3001\u6269\u5c55\u548c\u51fd\u6570\uff0c\u652f\u6301\u7ffb\u9875\u6d4f\u89c8\n- **get_class_details**: \u83b7\u53d6\u6307\u5b9a\u7c7b\u7684\u8be6\u7ec6\u4fe1\u606f\uff0c\u5305\u62ec\u65b9\u6cd5\u3001\u5c5e\u6027\u548c\u7ee7\u627f\u5173\u7cfb\n- **get_method_details**: \u83b7\u53d6\u6307\u5b9a\u65b9\u6cd5\u7684\u8be6\u7ec6\u4fe1\u606f\uff0c\u5305\u62ec\u53c2\u6570\u7c7b\u578b\u548c\u8fd4\u56de\u503c\n\n#### 3.10 \u4ee3\u7801\u751f\u6210\u5de5\u5177 (CodeGenerationTools) - \u5f53\u524d\u7981\u7528\n\u667a\u80fd\u4ee3\u7801\u751f\u6210\u529f\u80fd\uff08\u9700\u542f\u7528\u540e\u4f7f\u7528\uff09\n- **generate_crud_api**: \u751f\u6210\u5b8c\u6574\u7684CRUD API\u63a5\u53e3\u4ee3\u7801\n- **generate_database_query**: \u751f\u6210\u6570\u636e\u5e93\u67e5\u8be2\u4ee3\u7801\n- **generate_api_test**: \u751f\u6210API\u63a5\u53e3\u6d4b\u8bd5\u4ee3\u7801\n- **generate_workflow_code**: \u751f\u6210\u5de5\u4f5c\u6d41\u6a21\u677f\u4ee3\u7801\n\n#### 3.11 \u63d0\u793a\u8bcd\u5de5\u5177 (PromptTools)\n\u63d0\u4f9b\u53ef\u590d\u7528\u7684\u63d0\u793a\u8bcd\u6a21\u677f\uff0c\u786e\u4fdd\u52a9\u624b\u4e25\u683c\u9075\u5faa MCP \u5de5\u5177\u5316\u6d41\u7a0b\n- **magic_api_developer_guide**: \u8f93\u51fa\u6700\u65b0\u7248\u201cMagic-API \u5f00\u53d1\u8005\u52a9\u624b\u201d\u7cfb\u7edf\u63d0\u793a\u8bcd\uff0c\u5f3a\u8c03\u201c\u4ec5\u4f9d\u8d56 MCP \u5de5\u5177\u201d\u5de5\u4f5c\u5b88\u5219\u3001\u516d\u6b65\u5de5\u5177\u5de5\u4f5c\u6d41\u4ee5\u53ca\u7ed3\u6784\u5316\u8f93\u51fa\u8981\u6c42\n\n#### 3.12 \u5de5\u4f5c\u6d41\u77e5\u8bc6\u5e93\u4eae\u70b9\n\n`magicapi_tools/utils/kb_practices.py` \u65b0\u589e \"mcp_tool_driven\" \u7b49\u5de5\u4f5c\u6d41\uff0c\u8c03\u7528 `get_development_workflow` \u6216 `get_practices_guide` \u65f6\u53ef\u83b7\u53d6\uff1a\n- \ud83d\udd0d **\u667a\u80fd\u641c\u7d22\u9a71\u52a8**\uff1a\u9047\u5230\u4e0d\u786e\u5b9a\u7684\u95ee\u9898\u65f6\uff0c\u4f18\u5148\u8c03\u7528 `search_knowledge` \u5de5\u5177\u8fdb\u884c\u77e5\u8bc6\u5e93\u5168\u6587\u641c\u7d22\uff0c\u786e\u4fdd\u83b7\u53d6\u6700\u65b0\u548c\u51c6\u786e\u7684\u4fe1\u606f\u3002\n- MCP \u5de5\u5177\u4f18\u5148\u7684\u901a\u7528\u6d41\u7a0b\uff1a\u8986\u76d6\u51c6\u5907\u3001\u4fe1\u606f\u91c7\u96c6\u3001\u6267\u884c\u3001\u6821\u9a8c\u3001\u603b\u7ed3\u5168\u94fe\u8def\uff0c\u5e76\u9488\u5bf9\u6bcf\u4e00\u6b65\u7ed9\u51fa\u5bf9\u5e94\u5de5\u5177\u63d0\u793a\u3002\n- api_script_development / diagnose / optimize / refactor \u7b49\u573a\u666f\u5316\u6d41\u7a0b\uff1a\u63d0\u4f9b\u539f\u5219\u8bf4\u660e\u3001\u6b65\u9aa4\u62c6\u89e3\u4ee5\u53ca\u5de5\u5177\u5217\u8868\uff0c\u786e\u4fdd\u5728\u63a5\u53e3\u5f00\u53d1\u3001\u6545\u969c\u6392\u67e5\u3001\u6027\u80fd\u4f18\u5316\u4e0e\u91cd\u6784\u4e2d\u5168\u7a0b\u4f9d\u8d56 MCP \u5de5\u5177\u5b8c\u6210\u3002\n- \u7ed3\u5408 `magic_api_developer_guide` \u63d0\u793a\u8bcd\uff0c\u53ef\u8ba9\u5927\u6a21\u578b\u5728\u5bf9\u8bdd\u4e2d\u4e3b\u52a8\u5f15\u7528\u5de5\u5177\u8bc1\u636e\uff0c\u8f93\u51fa\u53ef\u9a8c\u8bc1\u7684\u7ed3\u8bba\u3002\n\n### 4. \u73af\u5883\u53d8\u91cf\n\n| \u53d8\u91cf | \u7528\u9014 | \u503c | \u9ed8\u8ba4\u503c |\n|------|------|----|--------|\n| MAGIC_API_BASE_URL | Magic-API \u670d\u52a1\u57fa\u7840 URL | URL \u5730\u5740 | http://127.0.0.1:10712 |\n| MAGIC_API_WS_URL | Magic-API WebSocket URL | WebSocket \u5730\u5740 | ws://127.0.0.1:10712/magic/web/console |\n| MAGIC_API_USERNAME | Magic-API \u8ba4\u8bc1\u7528\u6237\u540d | \u5b57\u7b26\u4e32 | \u65e0 |\n| MAGIC_API_PASSWORD | Magic-API \u8ba4\u8bc1\u5bc6\u7801 | \u5b57\u7b26\u4e32 | \u65e0 |\n| MAGIC_API_TOKEN | Magic-API \u8ba4\u8bc1\u4ee4\u724c | \u5b57\u7b26\u4e32 | \u65e0 |\n| MAGIC_API_AUTH_ENABLED | \u662f\u5426\u542f\u7528\u8ba4\u8bc1 | true/false | false |\n| MAGIC_API_TIMEOUT_SECONDS | \u8bf7\u6c42\u8d85\u65f6\u65f6\u95f4\uff08\u79d2\uff09 | \u6570\u5b57 | 30.0 |\n| MAGIC_API_SUCCESS_CODE | API\u6210\u529f\u72b6\u6001\u7801 | \u6570\u5b57 | 1 |\n| MAGIC_API_SUCCESS_MESSAGE | API\u6210\u529f\u6d88\u606f\u6587\u672c | \u5b57\u7b26\u4e32 | success |\n| MAGIC_API_INVALID_CODE | \u53c2\u6570\u9a8c\u8bc1\u5931\u8d25\u72b6\u6001\u7801 | \u6570\u5b57 | 0 |\n| MAGIC_API_EXCEPTION_CODE | \u7cfb\u7edf\u5f02\u5e38\u72b6\u6001\u7801 | \u6570\u5b57 | -1 |\n| LOG_LEVEL | \u65e5\u5fd7\u7ea7\u522b | DEBUG/INFO/WARNING/ERROR | INFO |\n| FASTMCP_TRANSPORT | FastMCP \u4f20\u8f93\u534f\u8bae | stdio/http | stdio |\n\n### 5. \u672c\u5730\u8fd0\u884c\u65b9\u5f0f\n\n```bash\n# \u63a8\u8350\u65b9\u5f0f\uff1a\u4f7f\u7528 uvx \u8fd0\u884c\u6700\u65b0\u7248\u672c\uff08\u9002\u7528\u4e8e\u5df2\u53d1\u5e03\u5230 pip \u7684\u5305\uff09\nuvx magic-api-mcp-server@latest\n\n# \u6216\u5b89\u88c5\u540e\u4f7f\u7528\u672c\u5730\u547d\u4ee4\nmagic-api-mcp-server\n\n# \u6216\u8005\u76f4\u63a5\u8fd0\u884c Python \u811a\u672c\uff08\u5f00\u53d1\u65f6\uff09\nuv run fastmcp run run_mcp.py:mcp --transport http --port 8000\n\n# \u6307\u5b9a\u5de5\u5177\u7ec4\u5408\u8fd0\u884c\nuvx magic-api-mcp-server@latest --composition development\n\n# \u4f7f\u7528\u7279\u5b9a\u914d\u7f6e\u8fd0\u884c\nMAGIC_API_BASE_URL=http://localhost:8080 uvx magic-api-mcp-server@latest\n```\n\n### 6. Docker \u8fd0\u884c\u65b9\u5f0f\n\n#### \u4f7f\u7528 Docker Compose (\u63a8\u8350)\n\n```bash\n# \u4f7f\u7528 Makefile \u547d\u4ee4 (\u63a8\u8350\uff0c\u7b80\u5316\u64cd\u4f5c)\nmake quick-start # \u5feb\u901f\u542f\u52a8\u5f00\u53d1\u73af\u5883\nmake deploy # \u751f\u4ea7\u73af\u5883\u90e8\u7f72\nmake logs # \u67e5\u770b\u65e5\u5fd7\nmake status # \u67e5\u770b\u72b6\u6001\nmake shell # \u8fdb\u5165\u5bb9\u5668\nmake test # \u8fd0\u884c\u6d4b\u8bd5\n\n# \u6216\u76f4\u63a5\u4f7f\u7528 docker-compose \u547d\u4ee4\n# 1. \u6784\u5efa\u5e76\u542f\u52a8\u670d\u52a1\ndocker-compose up -d\n\n# 2. \u67e5\u770b\u65e5\u5fd7\ndocker-compose logs -f magic-api-mcp-server\n\n# 3. \u505c\u6b62\u670d\u52a1\ndocker-compose down\n\n# 4. \u91cd\u542f\u670d\u52a1\ndocker-compose restart magic-api-mcp-server\n```\n\n#### \u4f7f\u7528 Docker \u547d\u4ee4 (\u57fa\u4e8e uvx)\n\n```bash\n# 1. \u6784\u5efa\u955c\u50cf\ndocker build -t magic-api-mcp-server .\n\n# 2. \u8fd0\u884c\u5bb9\u5668 (stdio\u6a21\u5f0f)\ndocker run --rm --entrypoint uvx magic-api-mcp-server \\\n magic-api-mcp-server@latest --composition full --transport stdio\n\n# 3. \u8fd0\u884c\u5bb9\u5668 (HTTP\u6a21\u5f0f)\ndocker run -d --name magic-api-mcp-server \\\n -p 8000:8000 \\\n --entrypoint uvx magic-api-mcp-server \\\n magic-api-mcp-server@latest --transport http --port 8000\n\n# 4. \u67e5\u770b\u65e5\u5fd7\ndocker logs -f magic-api-mcp-server\n\n# 5. \u505c\u6b62\u5bb9\u5668\ndocker stop magic-api-mcp-server\n```\n\n#### Docker \u914d\u7f6e\u8bf4\u660e\n\n**\u57fa\u4e8e uvx \u7684\u4f18\u52bf**:\n- \u81ea\u52a8\u4e0b\u8f7d\u5e76\u8fd0\u884c\u6700\u65b0\u7248\u672c\u7684\u5305\n- \u65e0\u9700\u9884\u5148\u5b89\u88c5\u4f9d\u8d56\n- \u955c\u50cf\u66f4\u5c0f\uff0c\u6784\u5efa\u66f4\u5feb\n- \u81ea\u52a8\u5904\u7406\u5305\u7248\u672c\u7ba1\u7406\n\n**\u751f\u4ea7\u73af\u5883\u914d\u7f6e** (`docker-compose.yml`):\n- \u4f7f\u7528\u6865\u63a5\u7f51\u7edc\u8fde\u63a5\u5230Magic-API\u670d\u52a1\n- \u914d\u7f6e\u8d44\u6e90\u9650\u5236\u548c\u5065\u5eb7\u68c0\u67e5\n- \u652f\u6301\u81ea\u52a8\u91cd\u542f\n\n**\u5f00\u53d1\u73af\u5883\u914d\u7f6e** (`docker-compose.override.yml`):\n- \u6302\u8f7d\u6e90\u4ee3\u7801\u652f\u6301\u70ed\u91cd\u8f7d\n- \u8c03\u8bd5\u65e5\u5fd7\u7ea7\u522b\n- \u7981\u7528\u5065\u5eb7\u68c0\u67e5\n\n#### Docker \u73af\u5883\u53d8\u91cf\n\n| \u53d8\u91cf | \u63cf\u8ff0 | \u9ed8\u8ba4\u503c |\n|------|------|--------|\n| `MAGIC_API_BASE_URL` | Magic-API \u670d\u52a1\u57fa\u7840 URL | `http://host.docker.internal:10712` |\n| `MAGIC_API_WS_URL` | Magic-API WebSocket URL | `ws://host.docker.internal:10712/magic/web/console` |\n| `MAGIC_API_USERNAME` | \u8ba4\u8bc1\u7528\u6237\u540d | \u65e0 |\n| `MAGIC_API_PASSWORD` | \u8ba4\u8bc1\u5bc6\u7801 | \u65e0 |\n| `MAGIC_API_TOKEN` | \u8ba4\u8bc1\u4ee4\u724c | \u65e0 |\n| `MAGIC_API_AUTH_ENABLED` | \u662f\u5426\u542f\u7528\u8ba4\u8bc1 | `false` |\n| `MAGIC_API_TIMEOUT_SECONDS` | \u8bf7\u6c42\u8d85\u65f6\u65f6\u95f4 | `30.0` |\n| `MAGIC_API_SUCCESS_CODE` | API\u6210\u529f\u72b6\u6001\u7801 | `1` |\n| `MAGIC_API_SUCCESS_MESSAGE` | API\u6210\u529f\u6d88\u606f\u6587\u672c | `success` |\n| `MAGIC_API_INVALID_CODE` | \u53c2\u6570\u9a8c\u8bc1\u5931\u8d25\u72b6\u6001\u7801 | `0` |\n| `MAGIC_API_EXCEPTION_CODE` | \u7cfb\u7edf\u5f02\u5e38\u72b6\u6001\u7801 | `-1` |\n| `LOG_LEVEL` | \u65e5\u5fd7\u7ea7\u522b | `INFO` |\n| `FASTMCP_TRANSPORT` | MCP\u4f20\u8f93\u534f\u8bae | `stdio` |\n\n#### \u7f51\u7edc\u914d\u7f6e\u6ce8\u610f\u4e8b\u9879\n\n- **Linux**: \u4f7f\u7528 `host.docker.internal` \u8bbf\u95ee\u5bbf\u4e3b\u673a\u670d\u52a1\n- **macOS/Windows**: Docker Desktop \u81ea\u52a8\u63d0\u4f9b `host.docker.internal`\n- **\u81ea\u5b9a\u4e49\u7f51\u7edc**: \u53ef\u901a\u8fc7 `docker network` \u521b\u5efa\u4e13\u7528\u7f51\u7edc\n\n#### Docker \u6784\u5efa\u95ee\u9898\u89e3\u51b3\n\n\u5982\u679c\u9047\u5230\u7f51\u7edc\u8bc1\u4e66\u9a8c\u8bc1\u95ee\u9898\uff0c\u8bf7\u5c1d\u8bd5\u4ee5\u4e0b\u89e3\u51b3\u65b9\u6848\uff1a\n\n**\u65b9\u68481: \u4f7f\u7528\u56fd\u5185\u955c\u50cf\u6e90**\n```bash\n# \u4fee\u6539Dockerfile\u6dfb\u52a0\u56fd\u5185\u955c\u50cf\u6e90\nRUN sed -i 's/deb.debian.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list.d/debian.sources\nRUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/\n```\n\n**\u65b9\u68482: \u914d\u7f6eDocker\u4ee3\u7406**\n```bash\n# \u521b\u5efa\u6216\u4fee\u6539 ~/.docker/config.json\n{\n \"proxies\": {\n \"default\": {\n \"httpProxy\": \"http://127.0.0.1:7897\",\n \"httpsProxy\": \"http://127.0.0.1:7897\",\n \"noProxy\": \"localhost,127.0.0.1\"\n }\n }\n}\n```\n\n**\u65b9\u68483: \u8df3\u8fc7TLS\u9a8c\u8bc1 (\u4ec5\u7528\u4e8e\u6d4b\u8bd5)**\n```bash\n# \u4e34\u65f6\u8df3\u8fc7TLS\u9a8c\u8bc1\u6784\u5efa\ndocker build --build-arg DOCKER_TLS_VERIFY=0 -t magic-api-mcp-server:test .\n```\n\n**\u65b9\u68484: \u4f7f\u7528\u9884\u6784\u5efa\u955c\u50cf**\n```bash\n# \u5982\u679c\u7f51\u7edc\u95ee\u9898\u6301\u7eed\uff0c\u53ef\u8003\u8651\u4f7f\u7528\u9884\u6784\u5efa\u7684\u57fa\u7840\u955c\u50cf\n# \u6216\u8005\u5728\u6709\u7a33\u5b9a\u7f51\u7edc\u7684\u73af\u5883\u4e2d\u6784\u5efa\n```\n\n#### \u6545\u969c\u6392\u9664\n\n```bash\n# \u4f7f\u7528 Makefile \u547d\u4ee4 (\u63a8\u8350)\nmake status # \u67e5\u770b\u5bb9\u5668\u72b6\u6001\nmake shell # \u8fdb\u5165\u5bb9\u5668\u8c03\u8bd5\nmake logs-tail # \u67e5\u770b\u8be6\u7ec6\u65e5\u5fd7\nmake test # \u8fd0\u884c\u5065\u5eb7\u68c0\u67e5\nmake test-connection # \u6d4b\u8bd5\u4e0e Magic-API \u8fde\u63a5\nmake clean-all # \u6e05\u7406\u6240\u6709\u8d44\u6e90\n\n# \u6216\u76f4\u63a5\u4f7f\u7528 docker/docker-compose \u547d\u4ee4\n# \u67e5\u770b\u5bb9\u5668\u72b6\u6001\ndocker-compose ps\n\n# \u8fdb\u5165\u5bb9\u5668\u8c03\u8bd5\ndocker-compose exec magic-api-mcp-server bash\n\n# \u67e5\u770b\u8be6\u7ec6\u65e5\u5fd7\ndocker-compose logs --tail=100 magic-api-mcp-server\n\n# \u6e05\u7406\u5bb9\u5668\u548c\u955c\u50cf\ndocker-compose down --rmi all --volumes\n```\n\n### 7. \u9879\u76ee\u7ed3\u6784\n\n```\nmagicapi_mcp/\n\u251c\u2500\u2500 magicapi_assistant.py # \u4e3b\u8981\u7684 MCP \u52a9\u624b\u5b9e\u73b0\n\u251c\u2500\u2500 tool_registry.py # \u5de5\u5177\u6ce8\u518c\u8868\n\u251c\u2500\u2500 tool_composer.py # \u5de5\u5177\u7ec4\u5408\u5668\n\u2514\u2500\u2500 settings.py # \u914d\u7f6e\u8bbe\u7f6e\nmagicapi_tools/\n\u251c\u2500\u2500 tools/ # \u5404\u79cd MCP \u5de5\u5177\n\u2502 \u251c\u2500\u2500 system.py # \u7cfb\u7edf\u5de5\u5177 (\u5143\u4fe1\u606f\u67e5\u8be2)\n\u2502 \u251c\u2500\u2500 documentation.py # \u6587\u6863\u5de5\u5177 (\u77e5\u8bc6\u5e93\u67e5\u8be2)\n\u2502 \u251c\u2500\u2500 api.py # API\u5de5\u5177 (\u63a5\u53e3\u8c03\u7528)\n\u2502 \u251c\u2500\u2500 resource.py # \u8d44\u6e90\u7ba1\u7406\u5de5\u5177 (CRUD\u64cd\u4f5c)\n\u2502 \u251c\u2500\u2500 query.py # \u67e5\u8be2\u5de5\u5177 (\u8d44\u6e90\u68c0\u7d22)\n\u2502 \u251c\u2500\u2500 debug.py # \u8c03\u8bd5\u5de5\u5177 (\u65ad\u70b9\u7ba1\u7406)\n\u2502 \u251c\u2500\u2500 search.py # \u641c\u7d22\u5de5\u5177 (\u5185\u5bb9\u641c\u7d22)\n\u2502 \u251c\u2500\u2500 backup.py # \u5907\u4efd\u5de5\u5177 (\u6570\u636e\u5907\u4efd)\n\u2502 \u251c\u2500\u2500 class_method.py # \u7c7b\u65b9\u6cd5\u5de5\u5177 (Java\u7c7b\u67e5\u8be2)\n\u2502 \u251c\u2500\u2500 code_generation.py # \u4ee3\u7801\u751f\u6210\u5de5\u5177 (\u5f53\u524d\u7981\u7528)\n\u2502 \u2514\u2500\u2500 common.py # \u901a\u7528\u8f85\u52a9\u51fd\u6570\n\u2514\u2500\u2500 utils/ # \u5de5\u5177\u52a9\u624b\u529f\u80fd\n \u251c\u2500\u2500 knowledge_base.py # \u77e5\u8bc6\u5e93\u63a5\u53e3\n \u251c\u2500\u2500 response.py # \u6807\u51c6\u5316\u54cd\u5e94\n \u251c\u2500\u2500 http_client.py # HTTP \u5ba2\u6237\u7aef\n \u2514\u2500\u2500 resource_manager.py # \u8d44\u6e90\u7ba1\u7406\u5668\n```\n\n### 8. \u5b89\u88c5\u65b9\u5f0f\n\n#### \u4ece PyPI \u5b89\u88c5\uff08\u63a8\u8350\uff09\n\n```bash\n# \u5b89\u88c5\u5df2\u53d1\u5e03\u7684\u5305\npip install magic-api-mcp-server\n\n# \u6216\u4f7f\u7528 uv \u5b89\u88c5\nuv add magic-api-mcp-server\n\n# \u8fd0\u884c MCP \u670d\u52a1\u5668\uff08\u63a8\u8350\u4f7f\u7528\u6700\u65b0\u7248\u672c\uff09\nuvx magic-api-mcp-server@latest\n\n# \u6216\u4f7f\u7528\u5b89\u88c5\u540e\u7684\u547d\u4ee4\nmagic-api-mcp-server\n```\n\n#### \u5f00\u53d1\u8005\u672c\u5730\u5b89\u88c5\n\n```bash\n# \u672c\u9879\u76ee\u5df2\u5305\u542b\u5b8c\u6574\u7684 MCP \u5b9e\u73b0\ncd magic-api-mcp-server\n\n# \u5b89\u88c5\u9879\u76ee\u4f9d\u8d56\uff08\u5f00\u53d1\u65f6\uff09\nuv sync\n\n# \u5b89\u88c5 fastmcp \u4f9d\u8d56\nuv add fastmcp\n\n# \u672c\u5730\u8fd0\u884c\uff08\u5f00\u53d1\u65f6\uff09\npython run_mcp.py\n```\n\n## \ud83d\udee0\ufe0f \u9879\u76ee\u7ed3\u6784\n\n```\nmagicapi_mcp/\n\u251c\u2500\u2500 magicapi_assistant.py # \u4e3b\u8981\u7684 MCP \u52a9\u624b\u5b9e\u73b0\n\u251c\u2500\u2500 tool_registry.py # \u5de5\u5177\u6ce8\u518c\u8868\n\u251c\u2500\u2500 tool_composer.py # \u5de5\u5177\u7ec4\u5408\u5668\n\u2514\u2500\u2500 settings.py # \u914d\u7f6e\u8bbe\u7f6e\nmagicapi_tools/\n\u251c\u2500\u2500 tools/ # \u5404\u79cd MCP \u5de5\u5177\n\u2502 \u251c\u2500\u2500 documentation.py # \u6587\u6863\u76f8\u5173\u5de5\u5177\n\u2502 \u251c\u2500\u2500 api.py # API \u76f8\u5173\u5de5\u5177\n\u2502 \u251c\u2500\u2500 code_generation.py # \u4ee3\u7801\u751f\u6210\u5de5\u5177 (\u5f53\u524d\u5df2\u7981\u7528)\n\u2502 \u251c\u2500\u2500 query.py # \u67e5\u8be2\u5de5\u5177\n\u2502 \u251c\u2500\u2500 backup.py # \u5907\u4efd\u5de5\u5177\n\u2502 \u251c\u2500\u2500 class_method.py # \u7c7b\u65b9\u6cd5\u5de5\u5177\n\u2502 \u251c\u2500\u2500 debug.py # \u8c03\u8bd5\u5de5\u5177\n\u2502 \u251c\u2500\u2500 resource.py # \u8d44\u6e90\u7ba1\u7406\u5de5\u5177\n\u2502 \u251c\u2500\u2500 search.py # \u641c\u7d22\u5de5\u5177\n\u2502 \u2514\u2500\u2500 system.py # \u7cfb\u7edf\u5de5\u5177\n\u2514\u2500\u2500 utils/ # \u5de5\u5177\u52a9\u624b\u529f\u80fd\n \u251c\u2500\u2500 knowledge_base.py # \u77e5\u8bc6\u5e93\u63a5\u53e3\n \u251c\u2500\u2500 response.py # \u6807\u51c6\u5316\u54cd\u5e94\n \u251c\u2500\u2500 http_client.py # HTTP \u5ba2\u6237\u7aef\n \u2514\u2500\u2500 resource_manager.py # \u8d44\u6e90\u7ba1\u7406\u5668\n```\n\n\n\n\n## AIMCP Electron \u5ba2\u6237\u7aef\u9644\u5f55\uff08\u542b Mermaid \u67b6\u6784\u56fe\uff09\n\n> \u672c\u9644\u5f55\u9762\u5411\u57fa\u4e8e Electron \u7684 AIMCP \u5ba2\u6237\u7aef\uff0c\u6307\u5bfc\u5982\u4f55\u5bf9\u63a5\u672c Magic-API MCP Server\uff0c\u5e76\u63d0\u4f9b\u5173\u952e\u6d41\u7a0b\u53ef\u89c6\u5316\u3002\u9002\u5408\u4f5c\u4e3a\u72ec\u7acb\u5f00\u6e90\u4ed3\u5e93 README \u6a21\u677f\u7247\u6bb5\u590d\u7528\u3002\n\n### \u9879\u76ee\u7b80\u4ecb\uff08AIMCP\uff09\n- \u76ee\u6807\uff1a\u5728 Electron \u5e94\u7528\u4e2d\uff0c\u901a\u8fc7 MCP \u534f\u8bae\u7edf\u4e00\u8c03\u7528 Magic-API \u80fd\u529b\uff0c\u8986\u76d6\u67e5\u8be2\u3001\u8d44\u6e90\u7ba1\u7406\u4e0e\u8c03\u8bd5\u3002\n- \u6808\u7279\u6027\uff1aElectron(Main/Renderer/Preload) + Node MCP \u5ba2\u6237\u7aef + FastMCP Server(Python) + Magic-API(HTTP/WS)\u3002\n\n### \u67b6\u6784\u603b\u89c8\n```mermaid\nflowchart LR\n subgraph Renderer[Electron Renderer UI]\n R[React/Vue/Svelte UI]\n end\n subgraph Main[Electron Main Process]\n IPC[IPC Router]\n C[Node MCP Client]\n end\n subgraph Server[magic-api-mcp-server (Python/FastMCP)]\n S[Tools: Api/Query/Debug/...]\n end\n subgraph MagicAPI[Magic-API Backend]\n A[(HTTP API)]\n W[(WS Console)]\n DB[(Database)]\n end\n\n R -->|ipcRenderer.invoke| IPC --> C\n C <--> |stdio/http| S\n S --> A --> DB\n S -. WebSocket Debug .-> W\n```\n\n### \u5173\u952e\u8c03\u7528\u65f6\u5e8f\n```mermaid\nsequenceDiagram\n participant U as User\n participant R as Renderer\n participant M as Main\n participant C as MCP Client\n participant S as MCP Server\n participant A as Magic-API\n participant W as WS Console\n\n U->>R: \u70b9\u51fb\u201c\u8c03\u7528\u63a5\u53e3\u201d\n R->>M: ipcRenderer.invoke('call-magic-api', payload)\n M->>C: call_tool(name=call_magic_api, args)\n C->>S: MCP Tool Invocation\n S->>A: HTTP \u8bf7\u6c42(method/path/params)\n A-->>S: JSON \u54cd\u5e94\n S-->>C: ToolResponse(success/data)\n C-->>M: \u7ed3\u679c\n M-->>R: IPC \u8fd4\u56de\u5e76\u6e32\u67d3\n R-->>U: \u5c55\u793a\u6570\u636e\n opt \u8c03\u8bd5\u6a21\u5f0f\n M->>C: set_breakpoint + call_api_with_debug\n C->>S: \u8c03\u8bd5\u4f1a\u8bdd\n S-->>W: \u65ad\u70b9\u4e8b\u4ef6(WS)\n end\n```\n\n### \u5feb\u901f\u96c6\u6210\uff08Electron Main\uff09\n```ts\n// main/mcp.ts\nimport { spawn } from 'node:child_process'\nimport { StdioClientTransport, Client } from '@modelcontextprotocol/sdk/client'\n\nexport async function createMcpClient() {\n const child = spawn('uvx', ['magic-api-mcp-server@latest', '--transport', 'stdio'], {\n stdio: ['pipe', 'pipe', 'pipe']\n })\n\n const transport = new StdioClientTransport({\n stdin: child.stdin!, stdout: child.stdout!, stderr: child.stderr!\n })\n\n const client = new Client({ name: 'AIMCP', version: '0.1.0' }, transport)\n await client.connect()\n return { client, child }\n}\n\n// \u8c03\u7528\u793a\u4f8b\nexport async function callMagicApi(client: Client, args: any) {\n return client.callTool({ name: 'call_magic_api', arguments: args })\n}\n```\n\n```ts\n// main/ipc.ts\nimport { ipcMain } from 'electron'\nimport { createMcpClient, callMagicApi } from './mcp'\n\nlet mcp: Awaited<ReturnType<typeof createMcpClient>> | null = null\n\nipcMain.handle('call-magic-api', async (_e, payload) => {\n if (!mcp) mcp = await createMcpClient()\n const res = await callMagicApi(mcp.client, payload)\n return res\n})\n```\n\n### \u6e32\u67d3\u8fdb\u7a0b\u8c03\u7528\u793a\u4f8b\n```ts\n// renderer/api.ts\nexport async function callApi(payload: {\n method: 'GET'|'POST'|'PUT'|'DELETE', path: string, params?: any, headers?: any\n}) {\n return window.electron.ipc.invoke('call-magic-api', payload)\n}\n```\n\n### \u914d\u7f6e\u4e0e\u5b89\u5168\u5efa\u8bae\n- \u5728 Electron \u4e3b\u8fdb\u7a0b\u901a\u8fc7\u73af\u5883\u53d8\u91cf\u6ce8\u5165 MAGIC_API_BASE_URL/MAGIC_API_WS_URL \u7b49\uff0c\u52ff\u5728 Renderer \u66b4\u9732\u5bc6\u94a5\u3002\n- \u751f\u4ea7\u73af\u5883\u542f\u7528 MAGIC_API_AUTH_ENABLED \u5e76\u4f7f\u7528 TOKEN \u8bbf\u95ee\u3002\n- \u8c03\u8bd5\u5f00\u5173\u5efa\u8bae\u4ee5 Feature Flag \u63a7\u5236\uff08\u4ec5\u5f00\u53d1\u73af\u5883\u5141\u8bb8 set_breakpoint\uff09\u3002\n\n### \u5e38\u7528\u529f\u80fd\u6620\u5c04\n- API \u8c03\u7528\uff1acall_magic_api\uff08\u652f\u6301\u81ea\u5b9a\u4e49 success \u5224\u65ad\uff0c\u8be6\u89c1\u524d\u6587\u73af\u5883\u53d8\u91cf\uff09\u3002\n- \u8d44\u6e90\u68c0\u7d22\uff1asearch_api_endpoints\u3001get_api_details_by_path\u3002\n- \u8c03\u8bd5\u4f1a\u8bdd\uff1aset_breakpoint\u3001call_api_with_debug\u3001resume_breakpoint_execution\u3002\n\n### \u76ee\u5f55\u5efa\u8bae\uff08AIMCP \u5ba2\u6237\u7aef\uff09\n```\napp/\n\u251c\u2500 main/ # Electron Main\uff08\u8fdb\u7a0b\u751f\u547d\u5468\u671f\u3001MCP \u5ba2\u6237\u7aef\u3001IPC\uff09\n\u2502 \u251c\u2500 mcp.ts\n\u2502 \u2514\u2500 ipc.ts\n\u251c\u2500 preload/ # \u53d7\u9650\u6865\u63a5\uff0c\u4ec5\u66b4\u9732\u5b89\u5168 IPC \u80fd\u529b\n\u251c\u2500 renderer/ # \u524d\u7aef UI\uff08\u8c03\u7528 ipcRenderer.invoke\uff09\n\u2514\u2500 config/ # env/\u914d\u7f6e\u4e0e Feature Flags\n```\n\n### \u5f00\u53d1\u4e0e\u6253\u5305\u63d0\u793a\n- \u5f00\u53d1\uff1a\u540c\u65f6\u8fd0\u884c Electron \u4e0e MCP Server\uff08Main \u8fdb\u7a0b\u9996\u8c03\u7528\u65f6\u81ea\u52a8\u62c9\u8d77 uvx \u8fdb\u7a0b\uff09\u3002\n- \u6253\u5305\uff1a\u786e\u4fdd\u5c06 uv/uvx \u4f5c\u4e3a\u5916\u90e8\u4f9d\u8d56\u6216\u5728\u5b89\u88c5\u9636\u6bb5\u9884\u7f6e\uff1b\u6216\u6539\u4e3a HTTP \u6a21\u5f0f\u8fde\u63a5\u5df2\u90e8\u7f72\u7684 MCP Server\u3002\n\n### \u6545\u969c\u6392\u67e5\u901f\u67e5\n- \u65e0\u54cd\u5e94\uff1a\u68c0\u67e5 Main \u8fdb\u7a0b\u662f\u5426\u6210\u529f spawn uvx\uff1b\u67e5\u770b child.stderr\u3002\n- 401/403\uff1a\u786e\u8ba4 MAGIC_API_AUTH_ENABLED \u4e0e TOKEN \u914d\u7f6e\u3002\n- \u65ad\u70b9\u4e0d\u751f\u6548\uff1a\u68c0\u67e5 Magic-API WS \u5730\u5740\u4e0e\u6743\u9650\uff1b\u786e\u8ba4\u8c03\u8bd5\u5de5\u5177\u7ec4\u5408\u542f\u7528\u3002\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Magic-API MCP Server - A Model Context Protocol server for Magic-API development",
"version": "0.1.7",
"project_urls": {
"Changelog": "https://github.com/Dwsy/magic-api-mcp-server/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/Dwsy/magic-api-mcp-server#readme",
"Homepage": "https://github.com/Dwsy/magic-api-mcp-server",
"Issues": "https://github.com/Dwsy/magic-api-mcp-server/issues",
"Repository": "https://github.com/Dwsy/magic-api-mcp-server.git"
},
"split_keywords": [
"magic-api",
" mcp",
" model-context-protocol",
" ai-assistant",
" api-development",
" tool-integration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d6413a974844e14b8e8466e43ffb14b4cdd73637a64a7c228ba99134372d7066",
"md5": "a36f217644757bb47e85ee1b5a680c24",
"sha256": "96f58279efc1c3f37a38264d73755f9265de8eb7b10d8ebb36d2464e7493520a"
},
"downloads": -1,
"filename": "iflow_mcp_magic_api_mcp_server-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a36f217644757bb47e85ee1b5a680c24",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 232047,
"upload_time": "2025-11-07T05:28:57",
"upload_time_iso_8601": "2025-11-07T05:28:57.664554Z",
"url": "https://files.pythonhosted.org/packages/d6/41/3a974844e14b8e8466e43ffb14b4cdd73637a64a7c228ba99134372d7066/iflow_mcp_magic_api_mcp_server-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "00387ae44b4f3f0d71f88d5edc6ac17e12e3b94b3f66a5276235d1b37ef6adca",
"md5": "ace2236db9e6c3ef0d659bab19709ab0",
"sha256": "35ea6a8f941ed468808fa9b0b2ef65e0a4bb7036bb18d62a5507982b989c7ba0"
},
"downloads": -1,
"filename": "iflow_mcp_magic_api_mcp_server-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "ace2236db9e6c3ef0d659bab19709ab0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 238360,
"upload_time": "2025-11-07T05:28:59",
"upload_time_iso_8601": "2025-11-07T05:28:59.722032Z",
"url": "https://files.pythonhosted.org/packages/00/38/7ae44b4f3f0d71f88d5edc6ac17e12e3b94b3f66a5276235d1b37ef6adca/iflow_mcp_magic_api_mcp_server-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-07 05:28:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Dwsy",
"github_project": "magic-api-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "websockets",
"specs": [
[
">=",
"10.0"
]
]
},
{
"name": "fastmcp",
"specs": [
[
">=",
"0.1.0"
]
]
},
{
"name": "mcp",
"specs": [
[
"~=",
"1.14.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
"~=",
"2.11.9"
]
]
}
],
"lcname": "iflow-mcp_magic-api-mcp-server"
}
JSON
