Magic-API

You are equipped with a Magic-API MCP Server that enables Advanced Model Context Protocol interactions for Magic-API development. This server coordinates with clients to run MCP tools, manage resources, debug APIs, and streamline deployment workflows, giving you a structured, automated way to build, test, and ship Magic-API capabilities.

How to use

You use the MCP Server by connecting an MCP client to the local stdio transport or a remote HTTP endpoint. Start by running the MCP server locally to enable scripting, querying, and debugging Magic-API resources. The server exposes a structured workflow that guides you from insight through execution to verification, with built‑in tools for documentation, API calls, resource management, debugging, and backups.

How to install

Prerequisites you need before installation include Python and a Python package manager, plus a node-based tooling path used for MCP orchestration. You will install a lightweight utility to launch the MCP server, then pull in the MCP server package and start it.

# Install the required Python utility (uv)
pip install uv

# Install project dependencies via uv
uv sync

# Or add FastMCP integration (alternative)
uv add fastmcp

Step-by-step start options

Run the MCP server in the most common configuration where it communicates over stdio with an MCP client. The following commands assume you are using the latest published package.

uvx magic-api-mcp-server@latest

Configure the MCP server (stdio)

Use the standard configuration to launch the MCP server with stdio transport. You can customize timeouts if needed.

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

Advanced configuration with environment variables

For environments that require explicit connections to your Magic-API instance, provide base URLs and timeouts via environment variables.

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

Configuration prompts and workflow

Follow the core workflow when using MCP tools: start with understanding the demand, align syntax rules, locate resources, implement and debug, then review outcomes. Use the provided prompts to configure your MCP client for a consistent development experience.

# Example prompt for a developer assistant (highly structured and MCP-driven)
你现在是一个专业的 Magic-API 开发者助手，具备强大的 MCP (Model Context Protocol) 工具（Magic-API MCP Server）支持。

## 🎯 你的核心职能
- 提供 Magic-API 脚本语法指导和最佳实践
- 帮助用户编写高效的数据库查询和业务逻辑
- 解答 Magic-API 配置和部署相关问题
- 提供代码示例和调试建议

Security and operational notes

When deploying, enable authentication in the Magic‑API setup and store credentials securely. Use environment variables to inject sensitive values and avoid exposing them in the Renderer or client code. For debugging, control access with feature flags and limit breakpoint exposure to development environments.

Troubleshooting

If you encounter issues, verify that the MCP server process is running, and check the MCP client connection status. Validate environment variables and timeouts, and ensure that the base URL points to your Magic‑API instance. For authentication errors, confirm that the token or credentials are correctly configured.

Available tools

get_full_magic_script_syntax

Fetches the complete Magic-Script syntax rules prior to code generation

search_knowledge

Full-text search in the knowledge base for answers when unclear

call_magic_api

Invoke Magic-API endpoints and receive structured responses

get_resource_tree

Retrieve and filter the resource tree for management

create_api_resource

Create new API resources in bulk or individually

replace_api_script

Replace a Magic-Script for an API by ID

set_breakpoint

Set a breakpoint in a Magic-Script for debugging

call_api_with_debug

Call an API with debugging hook to pause at breakpoints

list_backups

List available backups with filters

rollback_backup

Rollback to a previous backup version

list_magic_api_classes

List available Java-like classes and methods for Magic-API

generate_crud_api

Generate CRUD API scaffolding (currently disabled)

magic_api_developer_guide

Prompt template for MCP-driven developer assistant

get_development_workflow

Fetch the standard development workflow guidance

search_api_endpoints

Search API endpoints with filters

get_api_details_by_path

Fetch API details by path

get_api_details_by_id

Fetch API details by ID

list_available_modules

List available modules for import

get_function_docs

Fetch built-in function documentation

get_config_docs

Fetch configuration item documents

get_examples

Retrieve code examples by category