Magic-API MCP Server User Guide

🚀 Quick Start

This project integrates the Model Context Protocol (MCP) functionality, providing advanced interaction capabilities for Magic-API development.

1. Installation and Testing

# 如果尚未安装 uv (推荐方式)

pip install uv



# 安装项目依赖

uv sync

# 或者安装 fastmcp

uv add fastmcp

2. MCP Configuration

Basic Configuration (Suitable for Most Users):

{

  "mcpServers": {

    "magic-api-mcp-server": {

      "command": "uvx",

      "args": ["magic-api-mcp-server@latest", "--transport", "stdio"],

      "timeout": 600

    }

  }

}

Advanced Configuration (For Custom Environments):

{

  "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 Prompts (Very Important)

Overview of Prompts

When using AI assistants that support MCP (such as Claude Desktop, Cursor, etc.), it is essential to use the following prompts to inform the assistant about the features and purposes of the Magic-API MCP Server.

Core Prompts

你现在是一个专业的 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`，输出结论并保证可回溯



## 🛠️ 可用工具能力



### 文档查询 (DocumentationTools)

- **get_full_magic_script_syntax** ⚠️ [强制]: 获取完整的 Magic-Script 语法规则（代码编写前必须调用）

- **get_script_syntax**: 获取 Magic-API 脚本语法说明

- **get_development_workflow** ⚠️ [强制]: 获取 Magic-API 开发标准化工作流指南（API脚本开发前必须调用）

- **search_knowledge** 🔍 [推荐]: 在知识库中进行全文搜索（不确定时优先使用）

- **get_module_api**: 获取内置模块 API 文档 (db, http, request, response, log, env, cache, magic)

- **get_function_docs**: 获取内置函数库文档

- **get_best_practices**: 获取最佳实践指南

- **get_pitfalls**: 获取常见问题和陷阱

- **get_examples**: 获取具体代码示例和分类概览



### API 调用 (ApiTools)

- **call_magic_api**: 调用 Magic-API 接口，支持 GET/POST/PUT/DELETE 等所有 HTTP 方法



### 资源管理 (ResourceManagementTools)

- **get_resource_tree**: 获取完整的资源树结构

- **save_api_endpoint**: 保存API接口（支持创建和更新，根据是否提供file_id自动判断）

- **delete_resource**: 删除资源

- **get_resource_detail**: 获取资源详细信息

- **copy_resource**: 复制资源

- **move_resource**: 移动资源到其他分组



### 查询工具 (QueryTools)

- **get_api_details_by_path**: 根据路径获取接口详细信息

- **get_api_details_by_id**: 根据ID获取接口详细信息

- **search_api_endpoints**: 搜索和过滤接口端点



### 搜索工具 (SearchTools)

- **search_api_scripts**: 在所有 API 脚本中搜索关键词

- **search_todo_comments**: 搜索 TODO 注释



### 备份工具 (BackupTools)

- **list_backups**: 查看备份列表

- **create_full_backup**: 创建完整备份

- **rollback_backup**: 回滚到指定备份



### 系统工具 (SystemTools)

- **get_assistant_metadata**: 获取系统元信息和配置



## 📋 使用指南



##### 问题分析

首先理解用户的需求和上下文，再选择合适的工具。



##### 知识搜索策略

🔍 **当你不确定某个功能或语法时，优先使用搜索工具：**

- 调用 `search_knowledge` 进行全文搜索，关键词可以是功能名称、语法关键词等

- 例如：搜索"数据库连接"、"缓存使用"、"文件上传"等

- 可以限定搜索分类：syntax(语法)、modules(模块)、functions(函数)等



##### 最佳实践

- 🔍 **遇到不确定的问题时，先搜索知识库**

- 📚 优先使用文档查询工具了解功能

- 🔍 开发时先用查询工具了解现有资源

- 🐛 调试时设置断点逐步排查问题

- 💾 重要的变更操作前先备份



##### 错误处理

- 🔍 遇到未知错误时，使用 `search_knowledge` 搜索相关解决方案

- 🌐 网络错误时检查 Magic-API 服务状态

- 🔐 权限错误时确认用户认证配置

- 📁 资源不存在时先用查询工具确认路径



## ⚠️ 注意事项

- 所有工具都支持中文和英文参数

- API 调用支持自定义请求头和参数



记住：你现在具备了完整的 Magic-API 开发工具链，可以为用户提供专业、高效的开发支持！

Short Prompt (For Quick Configuration)

你是一个专业的 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 搜索知识库，代码编写前必须获取完整语法规则。

🧭 按核心工作流顺序完成需求洞察→语法对齐→资源定位→实现调试→结果反馈。

Configuration Prompts (For Editors like Cursor/VS Code)

{

  "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"

      }

    }

  }

}

This project's MCP server is specifically designed for Magic-API developers, offering a comprehensive set of workflow tools from script writing, API management, to debugging and deployment, thereby enhancing development efficiency across the board.

🧠 Prompts (Prompt Templates)

The Magic-API MCP Server provides reusable prompt templates to help you quickly configure professional Magic-API developer assistants.

Available Prompts

magic_api_developer_guide

Generates professional prompts for Magic-API developer assistants, including:

• A full introduction to tool capabilities
• Usage guides and best practices
• Error handling recommendations
• Tool selection strategies

Usage:

# 通过 MCP 客户端调用
prompt = await client.get_prompt("magic_api_developer_guide")
content = prompt.messages[0].content.text

Applicable Scenarios:

• Configuring new AI assistants
• Standardizing development workflows
• Training new team members
• Creating consistent development environments

Tool Combination Scenarios:

Basic Configuration Template:

{
  "mcpServers": {
    "magic-api-server": {
      "command": "uvx",
      "args": ["magic-api-mcp-server@latest", "--composition", "{组合模式}", "--transport", "stdio"],
      "timeout": 600
    }
  }
}

Tool Combination Scenarios:

Basic Configuration Template:

{
  "mcpServers": {
    "magic-api-server": {
      "command": "uvx",
      "args": ["magic-api-mcp-server@latest", "--composition", "{组合模式}", "--transport", "stdio"],
      "timeout": 600
    }
  }
}

3. MCP Tools in This Project

The Magic-API MCP Server provides the following professional tools for Magic-API development:

3.1 System Tools (SystemTools)

System information and metadata tools

• get_assistant_metadata: Retrieves the complete metadata of the Magic-API MCP Server, including version, feature list, and configuration

3.2 Documentation Tools (DocumentationTools)

Documentation query and knowledge base tools, covering syntax, practices, examples, and processes

• get_full_magic_script_syntax ⚠️ [Mandatory]: Retrieves the complete Magic-Script syntax rules - this tool must be called before large models write code
• search_knowledge 🔍 [Recommended]: Performs a full-text search in the Magic-API knowledge base - use this tool first when unsure
• get_magic_script_syntax: Queries Magic-Script syntax rules and examples
• get_magic_script_examples: Retrieves script examples, supporting keyword filtering
• get_magic_api_docs: Views the official documentation index or detailed content
• get_best_practices: Consults the list of best practices
• get_common_pitfalls: Consults common issues and avoidance suggestions
• get_development_workflow: Obtains standardized development process guidelines
• get_module_api_docs: Queries built-in module API documentation
• list_available_modules: Views available modules and auto-imported modules
• get_function_docs: Retrieves built-in function library documentation
• get_extension_docs: Retrieves type extension documentation (disabled by default, available after enabling)
• get_config_docs: Retrieves configuration item documentation (disabled by default)
• get_plugin_docs: Retrieves plugin system documentation (disabled by default)- get_examples / list_examples: Unified query for example categories and code snippets
• get_docs: Obtain the index of the Magic-API official site

3.3 API Tools (ApiTools)

API calling and testing tools, supporting flexible interface calls and tests

• call_magic_api: Call a Magic-API interface and return the request result, supporting HTTP methods such as GET, POST, PUT, DELETE

🔍 Intelligent API Response Check

Magic-API MCP Server supports intelligent success/failure determination for various API response formats:

Priority Order:

1. 🚀 message="success" - Highest priority, directly matches if the message field equals "success"
2. 🔢 Code Field Check - Checks if the code field equals the configured success code (default is 1, configurable)
3. 📊 Status Field Check - Checks the status field (for some custom response formats)
4. ❌ Error Field Check - Checks for the presence of error, exception, failure, or other error fields
5. ✅ Default Success - Compatibility mode, treats responses without clear indicators as successful by default

Supported Response Format Examples:

// 标准格式
{"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"}

Configuration Method:

# 通过环境变量配置成功状态码和消息
MAGIC_API_SUCCESS_CODE=200
MAGIC_API_SUCCESS_MESSAGE=ok
MAGIC_API_INVALID_CODE=400
MAGIC_API_EXCEPTION_CODE=500

3.4 Resource Management Tools (ResourceManagementTools)

A complete resource management system, supporting resource tree queries and batch operations

• get_resource_tree: Get the resource tree, supporting filtering, exporting in multiple formats (JSON/CSV/tree), and backward compatibility with CSV parameters
• save_group: Save a group, supporting creation or update of a single group, including full group configuration options
• create_api_resource / create_api_endpoint: Create a single or batch of APIs
• replace_api_script: Replace Magic-Script segments by API ID, supporting one-time or full replacement
• copy_resource: Copy resources
• move_resource: Move resources
• delete_resource: Delete a single or batch of resources
• lock_resource / unlock_resource: Batch lock or unlock resources
• list_resource_groups: List and search resource groups
• get_resource_stats: Count the number and type distribution of resources

3.5 Query Tools (QueryTools)

Efficient resource querying and retrieval tools

• get_api_details_by_path: Directly obtain detailed information about an interface based on the API path, supporting fuzzy matching
• get_api_details_by_id: Obtain complete detailed information and configuration of an interface based on the API ID
• search_api_endpoints: Search and filter Magic-API endpoints, returning a list of complete information including IDs

3.6 Debugging Tools (DebugTools)

Powerful debugging features, supporting breakpoint management and debug sessions

• set_breakpoint: Set a breakpoint in a specified API script
• remove_breakpoint: Remove a specified breakpoint
• resume_breakpoint_execution: Resume execution from a breakpoint, continuing to run the debug script
• step_over_breakpoint: Step over, continue executing after the current breakpoint
• list_breakpoints: List all currently set breakpoints
• call_api_with_debug: Call a specified interface and pause at the hit breakpoint
• execute_debug_session: Execute a complete debug session
• get_debug_status: Get the current debug status
• clear_all_breakpoints: Clear all breakpoints
• get_websocket_status: Get the WebSocket connection status

3.7 Search Tools (SearchTools)

Content search and location

• search_api_scripts: Search for keywords in all API scripts
• search_todo_comments: Search for TODO comments in scripts (disabled by default)

3.8 Backup Tools (BackupTools)

Complete backup management functions

• list_backups: Query the backup list, supporting timestamp and name filtering
• get_backup_history: Get the backup history
• get_backup_content: Get the content of a specified backup
• rollback_backup: Roll back to a specified backup version
• create_full_backup: Create a full system backup

3.9 Class Method Tools (ClassMethodTools)

Java class and method retrieval tools

• list_magic_api_classes: List all available classes, extensions, and functions for Magic-API, supporting pagination
• get_class_details: Get detailed information about a specified class, including methods, properties, and inheritance relationships
• get_method_details: Get detailed information about a specified method, including parameter types and return values

3.10 Code Generation Tools (CodeGenerationTools) - Currently Disabled

Intelligent code generation features (requires enabling before use)- generate_crud_api: Generate complete CRUD API interface code

• generate_database_query: Generate database query code
• generate_api_test: Generate API interface test code
• generate_workflow_code: Generate workflow template code

3.11 Prompt Tools (PromptTools)

Provides reusable prompt templates to ensure the assistant strictly follows the MCP tooling process.

• magic_api_developer_guide: Outputs the latest "Magic-API Developer Assistant" system prompts, emphasizing the "rely solely on MCP tools" working principle, six-step tool workflow, and structured output requirements.

3.12 Workflow Knowledge Base Highlights

magicapi_tools/utils/kb_practices.py adds new workflows such as "mcp_tool_driven". When calling get_development_workflow or get_practices_guide, you can obtain:

• 🔍 Intelligent Search Driven: When encountering uncertain issues, prioritize calling the search_knowledge tool for full-text knowledge base search to ensure the acquisition of the latest and accurate information.
• General process prioritizing MCP tools: Covers the entire chain from preparation, information gathering, execution, verification, to summary, and provides corresponding tool prompts for each step.
• Scenario-based processes such as api_script_development / diagnose / optimize / refactor: Provide principle explanations, step breakdowns, and tool lists to ensure that the entire process in interface development, troubleshooting, performance optimization, and refactoring is completed relying on MCP tools.
• Combined with the magic_api_developer_guide prompts, it allows the large model to proactively reference tool evidence in conversations and output verifiable conclusions.

4. Toolset Configuration

This project supports multiple toolset combinations, which can be selected based on needs:

• full: Full toolset - Suitable for a complete development environment (default)
• minimal: Minimal toolset - Suitable for resource-constrained environments
• development: Development toolset - Focused on development and debugging
• production: Production toolset - For stable operation in production environments
• documentation_only: Documentation-only toolset - For documentation queries and learning
• api_only: API-only toolset - For API testing and invocation
• backup_only: Backup-only toolset - For data backup and management
• class_method_only: Class method-only toolset - For Java class and method queries
• search_only: Search-only toolset - For quick search and location

5. Environment Variables

6. Local Running Method

# 推荐方式：使用 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

7. Docker Running Method

Using Docker Compose (Recommended)

# 使用 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

Using Docker Command (Based on uvx)

# 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 Configuration Explanation

Advantages of using uvx:

• Automatically downloads and runs the latest version of the package
• No need to pre-install dependencies
• Smaller image size, faster build
• Automatic handling of package version management

Production Environment Configuration (docker-compose.yml):

• Connects to the Magic-API service using a bridge network
• Configures resource limits and health checks
• Supports automatic restart

Development Environment Configuration (docker-compose.override.yml):

• Mounts source code for hot reloading
• Debug log level
• Disables health checks

Docker Environment Variables

Network Configuration Notes

• Linux: Use host.docker.internal to access the host machine's services
• macOS/Windows: Docker Desktop automatically provides host.docker.internal
• Custom Networks: You can create a dedicated network using docker network

Resolving Docker Build Issues

If you encounter network certificate verification issues, try the following solutions:

Solution 1: Use a domestic mirror

# 修改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/

Solution 2: Configure Docker Proxy

# 创建或修改 ~/.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"
    }
  }
}

Solution 3: Skip TLS Verification (for testing only)

# 临时跳过TLS验证构建
docker build --build-arg DOCKER_TLS_VERIFY=0 -t magic-api-mcp-server:test .

Solution 4: Use Pre-built Images

# 如果网络问题持续，可考虑使用预构建的基础镜像
# 或者在有稳定网络的环境中构建

Troubleshooting

# 使用 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

8. Project Structure

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 # 资源管理器

9. Installation Methods

Install from PyPI (Recommended)

# 安装已发布的包

pip install magic-api-mcp-server



# 或使用 uv 安装

uv add magic-api-mcp-server



# 运行 MCP 服务器（推荐使用最新版本）

uvx magic-api-mcp-server@latest



# 或使用安装后的命令

magic-api-mcp-server

Local Installation for Developers

# 本项目已包含完整的 MCP 实现

cd magic-api-mcp-server



# 安装项目依赖（开发时）

uv sync



# 安装 fastmcp 依赖

uv add fastmcp



# 本地运行（开发时）

python run_mcp.py

🛠️ Project Structure

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  # 资源管理器