Magic-API MCP Server

# Magic-API 类和方法检索工具使用指南 ## 概述 `extract_class_methods.py` 是一个专门用于检索 Magic-API 中类和方法信息的命令行工具。它基于 Magic-API 的 `/magic/web/classes` 和 `/magic/web/class` 两个端点，提供类搜索、方法查询和详细信息查看功能。 ## 功能特性 - 📦 **类信息检索**: 获取所有可用的脚本类、扩展类和全局函数 - 🔍 **关键词搜索**: 搜索包含指定关键词的类或函数 - 🎯 **方法搜索**: 查找包含特定方法的类 - 📋 **类详情查看**: 显示指定类的完整方法和字段信息 - 📄 **JSON输出**: 支持结构化数据输出，便于程序处理 ## 安装依赖 确保已安装必要的依赖包： ```bash pip install -r requirements.txt ``` ## 使用方法 ### 基本语法 ```bash python3 extract_class_methods.py --url <服务器地址> [选项] ``` ### 命令选项 | 选项 | 参数 | 说明 | |------|------|------| | `--url` | URL | Magic-API 服务器基础 URL（默认: http://127.0.0.1:10712/） | | `--limit` | NUMBER | 限制输出结果的最大数量（默认: 10，节约大模型 token） | | `--page` | NUMBER | 指定页码进行翻页浏览（默认: 1，从第1页开始） | | `--page-size` | NUMBER | 每页显示的数量（默认: 10，与 limit 配合使用） | | `--list` | 无 | 列出所有可用的类、扩展和函数 | | `--search` | KEYWORD | 搜索包含关键词的类、扩展或函数 | | `--regex` | PATTERN | 使用正则表达式搜索类、扩展或函数 | | `--case-sensitive` | 无 | 搜索时区分大小写（默认不区分） | | `--logic` | and/or | 多关键词搜索逻辑（默认 or） | | `--scope` | all/class/method/field | 搜索范围（默认 all） | | `--exact` | 无 | 精确匹配关键词（默认包含匹配） | | `--exclude` | KEYWORD | 排除包含指定关键词的结果 | | `--txt` | 无 | 显示压缩格式的类信息（classes.txt） | | `--txt-search` | KEYWORD | 在压缩格式类信息中搜索关键词 | | `--class` | CLASS_NAME | 显示指定类的详细信息 | | `--method` | METHOD_NAME | 搜索包含指定方法名的类 | | `--json` | 无 | 以 JSON 格式输出结果 | | `--csv` | 无 | 以 CSV 格式输出结果 | | `--timeout` | SECONDS | HTTP 请求超时时间（默认: 30秒） | ### 使用示例 #### 1. 列出所有类信息 ```bash # 基本列表显示（默认限制10项） python3 extract_class_methods.py --url http://127.0.0.1:9999 --list # 限制显示前5项（节约大模型token） python3 extract_class_methods.py --url http://127.0.0.1:9999 --list --limit 5 # 翻页浏览第2页（每页3项） python3 extract_class_methods.py --url http://127.0.0.1:9999 --list --page 2 --page-size 3 # JSON格式输出 python3 extract_class_methods.py --url http://127.0.0.1:9999 --list --json ``` 输出示例： ``` === Magic-API 类和方法检索 === 📦 脚本类 (15 个): • DateUtil • HttpClient • JSONUtil • SQLModule 🔧 扩展类 (8 个): • CacheModule • FileUtil • LogUtil ⚡ 全局函数 (23 个): • assert • debug • log ``` #### 2. 搜索关键词 ```bash # 搜索包含 "http" 的类 python3 extract_class_methods.py --url http://127.0.0.1:9999 --search http # 限制搜索结果数量（节约token） python3 extract_class_methods.py --url http://127.0.0.1:9999 --search http --limit 3 # 搜索结果翻页浏览 python3 extract_class_methods.py --url http://127.0.0.1:9999 --search http --page 1 --page-size 2 # JSON格式输出 python3 extract_class_methods.py --url http://127.0.0.1:9999 --search http --json ``` 输出示例： ``` 🔍 搜索结果: 'http' (共 3 个匹配) 📦 匹配的脚本类 (2 个): • HttpClient • HttpUtil ⚡ 匹配的全局函数 (1 个): • httpGet ``` #### 3. 搜索方法 ```bash # 查找包含 "get" 方法的类 python3 extract_class_methods.py --url http://127.0.0.1:9999 --method get # JSON格式输出 python3 extract_class_methods.py --url http://127.0.0.1:9999 --method get --json ``` 输出示例： ``` 🔍 方法搜索结果: 'get' (共 8 个匹配) 📦 包含该方法的脚本类 (5 个): • HttpClient • JSONUtil • SQLModule • CacheModule 🔧 包含该方法的扩展类 (3 个): • FileUtil • LogUtil • ConfigUtil ``` #### 4. 查看类详情 ```bash # 查看 HttpClient 类的详细信息 python3 extract_class_methods.py --url http://127.0.0.1:10712 --class HttpClient # JSON格式输出 python3 extract_class_methods.py --url http://127.0.0.1:10712 --class HttpClient --json # CSV格式输出 python3 extract_class_methods.py --url http://127.0.0.1:10712 --class HttpClient --csv #### 5. 增强搜索功能 ##### 5.1 正则表达式搜索 ```bash # 搜索以"Http"开头的类 python3 extract_class_methods.py --url http://127.0.0.1:10712 --regex "^Http" # 搜索包含数字的类名 python3 extract_class_methods.py --url http://127.0.0.1:10712 --regex ".*[0-9]+.*" # 搜索以"Util"结尾的类 python3 extract_class_methods.py --url http://127.0.0.1:10712 --regex "Util$" ``` ##### 5.2 大小写敏感搜索 ```bash # 区分大小写搜索（只会匹配大写的"Util"） python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "Util" --case-sensitive # 默认不区分大小写（会匹配"util"、"Util"、"UTIL"等） python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "util" ``` ##### 5.3 多关键词搜索 ```bash # OR逻辑：包含"get"或"post"的类（默认） python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "get post" # AND逻辑：同时包含"get"和"post"的类 python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "get post" --logic and ``` ##### 5.4 搜索范围限定 ```bash # 仅搜索类名 python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "Client" --scope class # 仅搜索方法名 python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "parse" --scope method # 仅搜索字段名 python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "timeout" --scope field # 搜索全部（类名、方法名、字段名、参数名、返回类型等） python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "String" --scope all ``` ##### 5.5 精确匹配 vs 包含匹配 ```bash # 包含匹配（默认）：类名中包含"Http"的 python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "Http" # 精确匹配：类名完全等于"Http"的 python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "Http" --exact ``` ##### 5.6 排除搜索 ```bash # 搜索包含"Util"的类，但排除包含"Test"的 python3 extract_class_methods.py --url http://127.0.0.1:10712 --search "Util" --exclude "Test" # 结合其他选项使用 python3 extract_class_methods.py --url http://127.0.0.1:10712 --regex ".*Util.*" --exclude "Mock" --case-sensitive ``` ##### 5.7 组合使用示例 ```bash # 复杂搜索：大小写敏感，正则表达式，仅搜索方法，排除测试相关 python3 extract_class_methods.py --url http://127.0.0.1:10712 \ --regex "get.*Data" \ --case-sensitive \ --scope method \ --exclude "Test" \ --csv ``` #### 6. 压缩类信息功能 ##### 6.1 显示压缩格式类信息 ```bash # 显示原始压缩格式类信息 python3 extract_class_methods.py --url http://127.0.0.1:10712 --txt # CSV格式输出压缩类信息 python3 extract_class_methods.py --url http://127.0.0.1:10712 --txt --csv ``` 输出示例： ``` === 压缩格式类信息 === java.lang:String,Boolean,Integer,Long,Double,Float java.util:List,Map,Set,ArrayList,HashMap,HashSet org.springframework.web.bind.annotation:RequestMapping,GetMapping,PostMapping ``` ##### 6.2 在压缩类信息中搜索 ```bash # 搜索包含"String"的类 python3 extract_class_methods.py --url http://127.0.0.1:10712 --txt-search "String" # 限制压缩搜索结果数量 python3 extract_class_methods.py --url http://127.0.0.1:10712 --txt-search "String" --limit 5 # 压缩搜索结果翻页 python3 extract_class_methods.py --url http://127.0.0.1:10712 --txt-search "String" --page 2 --page-size 3 # 区分大小写搜索 python3 extract_class_methods.py --url http://127.0.0.1:10712 --txt-search "List" --case-sensitive # CSV格式输出搜索结果 python3 extract_class_methods.py --url http://127.0.0.1:10712 --txt-search "Map" --csv ``` 输出示例： ``` 🔍 压缩类信息搜索: 关键词 'String' (不区分大小写) 📦 包: java.lang • String ✓ 📦 包: java.util • String • StringBuffer • StringBuilder 找到 4 个类，分布在 2 个包中 ``` ##### 6.3 压缩格式说明 `/classes.txt` 端点返回的压缩格式具有以下特点： - **格式结构**: `包名:类名1,类名2,类名3` - **每行一个包**: 同一包的类用逗号分隔 - **过滤规则**: 不包含内部类（$符号）和 `package-info` 类 - **排序**: 类名按字典序排序 - **用途**: 提供快速的类浏览和搜索功能 ``` 输出示例： ``` 📋 类详情: HttpClient 实例 1: 方法: • java.lang.String get(java.lang.String) • java.lang.String post(java.lang.String, java.lang.Object) • java.lang.String put(java.lang.String, java.lang.Object) • java.lang.String delete(java.lang.String) • void setTimeout(int) 字段: • int timeout • java.lang.String userAgent ``` #### CSV 输出格式说明 不同操作的 CSV 输出格式： **1. --list --csv**: 列出所有类 ```csv type,name class,HttpClient class,JSONUtil extension,java.util.Iterator function,assert ``` **2. --search KEYWORD --csv**: 搜索结果 ```csv type,name,keyword class,HttpClient,http extension,java.util.Iterator,util function,assert,http ``` **3. --method METHOD_NAME --csv**: 方法搜索结果 ```csv type,class_name,method_name class,HttpClient,get extension,java.util.Iterator,get ``` **4. --class CLASS_NAME --csv**: 类详情 ```csv class_name,method_name,return_type,parameters,field_name,field_type HttpClient,get,java.lang.String,java.lang.String arg0,, HttpClient,post,java.lang.String,java.lang.String arg0; java.lang.Object arg1,, HttpClient,,int,,timeout HttpClient,,java.lang.String,,userAgent ``` ## API 端点说明 该工具基于以下 Magic-API 端点： ### `/magic/web/classes` (POST) - **用途**: 获取所有类信息 - **返回数据**: - `classes`: 脚本类映射 - `extensions`: 扩展脚本类 - `functions`: 全局函数映射 ### `/magic/web/class` (POST) - **用途**: 获取单个类详细信息 - **请求参数**: `className` (类名) - **返回数据**: 指定类的 ScriptClass 集合 ### `/magic/web/classes.txt` (GET) - **用途**: 获取压缩格式的类信息文本 - **返回格式**: `text/plain` - **压缩格式**: `包名:类名1,类名2,类名3`（每行一个包） - **特点**: - 过滤内部类（包含 `$` 符号）和 `package-info` 类 - 类名按字典序排序 - 提供快速的类浏览和搜索功能 ## 注意事项 1. **认证要求**: 这些端点标记为 `@Valid(requireLogin = false)`，通常不需要登录认证，但具体取决于服务器配置。 2. **网络连接**: 确保能够访问指定的 Magic-API 服务器地址。 3. **超时设置**: 默认超时时间为30秒，可根据网络情况调整。 4. **数据格式**: 实际的类详情格式可能因 Magic-API 版本和配置而异。 ## 故障排除 ### 常见错误 1. **连接失败** ``` 错误：获取类信息失败: Connection refused ``` - 检查服务器地址和端口是否正确 - 确认 Magic-API 服务正在运行 2. **认证失败** ``` 错误：API 返回错误: {"success": false, "message": "Unauthorized"} ``` - 检查服务器是否需要认证 - 可能需要通过其他方式获取认证令牌 3. **类不存在** ``` ⚠️ 类 'UnknownClass' 没有可用的详细信息 ``` - 确认类名拼写正确 - 检查该类是否在当前 Magic-API 实例中注册 ### 调试技巧 - 使用 `--json` 选项查看原始响应数据 - 检查服务器日志了解具体的错误原因 - 使用浏览器直接访问端点进行验证 ## 集成使用 该工具可以与其他脚本结合使用： ```bash # 获取所有类名列表，用于其他脚本处理 python3 extract_class_methods.py --url http://127.0.0.1:9999 --list --json | jq '.classes | keys[]' # 批量检查特定方法的分布 python3 extract_class_methods.py --url http://127.0.0.1:9999 --method execute --json > method_analysis.json ``` ## 版本兼容性 - Magic-API v2.x+ - Python 3.7+ - requests 2.25.0+