Magic Api MCP Server

🚀 Magic-API MCP Server 使用指南

本項目集成了 Model Context Protocol (MCP) 功能，為 Magic-API 開發提供高級交互能力，能全方位提升從腳本編寫、API 管理到調試和部署等環節的開發效率。

🚀 快速開始

本項目集成了 Model Context Protocol (MCP) 功能，為 Magic-API 開發提供高級交互能力。

1. 安裝與測試

# 如果尚未安裝 uv (推薦方式)
pip install uv

# 安裝項目依賴
uv sync
# 或者安裝 fastmcp
uv add fastmcp

2. MCP 配置

基礎配置（適用於大多數用戶）

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

高級配置（需要自定義環境）

{
  "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 服務狀態
- 🔐 權限錯誤時確認用戶認證配置
- 📁 資源不存在時先用查詢工具確認路徑

簡短提示詞 (適用於快速配置)

你是一個專業的 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 等編輯器)

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

🧠 Prompts (提示詞模板)

Magic-API MCP Server 提供了可複用的提示詞模板，幫助您快速配置專業的 Magic-API 開發者助手。

可用 Prompts

magic_api_developer_guide

生成專業的 Magic-API 開發者助手提示詞，包含：

• 完整的工具能力介紹
• 使用指南和最佳實踐
• 錯誤處理建議
• 工具選擇策略

使用方法：

# 通過 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日誌

基礎配置模板：

{
  "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. ✅ 默認成功 - 兼容模式，對沒有明確標識的響應默認視為成功

支持的響應格式示例：

// 標準格式
{"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"}

配置方式：

# 通過環境變量配置成功狀態碼和消息
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. 本地運行方式

# 推薦方式：使用 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 (推薦)

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

# 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: 使用國內鏡像源

# 修改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代理

# 創建或修改 ~/.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驗證 (僅用於測試)

# 臨時跳過TLS驗證構建
docker build --build-arg DOCKER_TLS_VERIFY=0 -t magic-api-mcp-server:test .

方案4: 使用預構建鏡像

# 如果網絡問題持續，可考慮使用預構建的基礎鏡像
# 或者在有穩定網絡的環境中構建

故障排除

# 使用 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 安裝（推薦）

# 安裝已發佈的包
pip install magic-api-mcp-server

# 或使用 uv 安裝
uv add magic-api-mcp-server

# 運行 MCP 服務器（推薦使用最新版本）
uvx magic-api-mcp-server@latest

# 或使用安裝後的命令
magic-api-mcp-server

開發者本地安裝

# 本項目已包含完整的 MCP 實現
cd magic-api-mcp-server

# 安裝項目依賴（開發時）
uv sync

# 安裝 fastmcp 依賴
uv add fastmcp

# 本地運行（開發時）
python run_mcp.py