Supports containerized deployment with Docker and Docker Compose configurations for running the Magic-API MCP server in isolated environments
Distributed through PyPI package manager for easy installation and deployment of the Magic-API MCP server
Built on Python with comprehensive tooling for Magic-API development, providing script syntax guidance, API management, debugging capabilities, and resource operations
Magic-API MCP Server 使用指南
🚀 快速开始
本项目集成了 Model Context Protocol (MCP) 功能,为 Magic-API 开发提供高级交互能力。
1. 安装与测试
2. MCP 配置
基础配置(适用于大多数用户):
高级配置(需要自定义环境):
MCP 提示词 (非常重要)
提示词概述
当使用支持 MCP 的 AI 助手(如 Claude Desktop、Cursor 等)时,请务必使用以下提示词让助手了解 Magic-API MCP Server 的功能和用途。
核心提示词
简短提示词 (适用于快速配置)
配置提示词 (Cursor/VS Code 等编辑器)
本项目 MCP 服务器专为 Magic-API 开发者设计,提供了一套完整的工作流工具,从脚本编写、API 管理到调试和部署,全方位提升开发效率。
🧠 Prompts (提示词模板)
Magic-API MCP Server 提供了可复用的提示词模板,帮助您快速配置专业的 Magic-API 开发者助手。
可用 Prompts
magic_api_developer_guide
生成专业的 Magic-API 开发者助手提示词,包含:
完整的工具能力介绍
使用指南和最佳实践
错误处理建议
工具选择策略
使用方法:
适用场景:
配置新的 AI 助手
标准化开发工作流
培训新团队成员
创建一致的开发环境
工具组合使用场景:
场景 | 组合模式 | 适用环境 | 特点 |
新手学习 |
| 学习阶段 | 专注文档查询和语法学习 |
API开发 |
| 开发环境 | 接口开发、测试和调试 |
生产运维 |
| 生产环境 | 系统运维和资源管理 |
问题调试 |
| 调试场景 | 问题排查,启用DEBUG日志 |
基础配置模板:
工具组合使用场景:
场景 | 组合模式 | 适用环境 | 特点 |
新手学习 |
| 学习阶段 | 专注文档查询和语法学习 |
API开发 |
| 开发环境 | 接口开发、测试和调试 |
生产运维 |
| 生产环境 | 系统运维和资源管理 |
问题调试 |
| 调试场景 | 问题排查,启用DEBUG日志 |
基础配置模板:
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方法
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. 工具组合配置
本项目支持多种工具组合,可根据需要选择:
full: 完整工具集 - 适用于完整开发环境 (默认)minimal: 最小工具集 - 适用于资源受限环境development: 开发工具集 - 专注于开发调试production: 生产工具集 - 生产环境稳定运行documentation_only: 仅文档工具 - 文档查询和学习api_only: 仅API工具 - 接口测试和调用backup_only: 仅备份工具 - 数据备份和管理class_method_only: 仅类方法工具 - Java类和方法查询search_only: 仅搜索工具 - 快速搜索定位
5. 环境变量
变量 | 用途 | 值 | 默认值 |
MAGIC_API_BASE_URL | Magic-API 服务基础 URL | URL 地址 | |
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 |
LOG_LEVEL | 日志级别 | DEBUG/INFO/WARNING/ERROR | INFO |
FASTMCP_TRANSPORT | FastMCP 传输协议 | stdio/http | stdio |
6. 本地运行方式
7. Docker 运行方式
使用 Docker Compose (推荐)
使用 Docker 命令 (基于 uvx)
Docker 配置说明
基于 uvx 的优势:
自动下载并运行最新版本的包
无需预先安装依赖
镜像更小,构建更快
自动处理包版本管理
生产环境配置 (docker-compose.yml):
使用桥接网络连接到Magic-API服务
配置资源限制和健康检查
支持自动重启
开发环境配置 (docker-compose.override.yml):
挂载源代码支持热重载
调试日志级别
禁用健康检查
Docker 环境变量
变量 | 描述 | 默认值 |
| Magic-API 服务基础 URL |
|
| Magic-API WebSocket URL |
|
| 认证用户名 | 无 |
| 认证密码 | 无 |
| 认证令牌 | 无 |
| 是否启用认证 |
|
| 请求超时时间 |
|
| 日志级别 |
|
| MCP传输协议 |
|
网络配置注意事项
Linux: 使用
host.docker.internal访问宿主机服务macOS/Windows: Docker Desktop 自动提供
host.docker.internal自定义网络: 可通过
docker network创建专用网络
Docker 构建问题解决
如果遇到网络证书验证问题,请尝试以下解决方案:
方案1: 使用国内镜像源
方案2: 配置Docker代理
方案3: 跳过TLS验证 (仅用于测试)
方案4: 使用预构建镜像
故障排除
8. 项目结构
9. 安装方式
从 PyPI 安装(推荐)
开发者本地安装
🛠️ 项目结构
This server cannot be installed