DebugTools MCP 工具清单
DebugTools 提供 56 个 MCP 工具，按九类工作流组织。先在 IDEA MCP Server 中启用工具，再按任务选择；跨组操作示例见 MCP 工作流。
公共约定
projectPath用于定位 IDEA 项目，多项目时建议提供；所有工具均支持此参数，下表省略。- 涉及运行中应用时，用
connectionId选择活跃连接。表中列出此参数的工具在多连接时需要明确选择；只操作项目文件或本地快照的工具不一定使用连接。 - 下表“必填”表示 schema 必填项；
action对应的额外必填字段、目标选择和功能限制仍需按正文处理。 get_agent_capabilities返回实际 Agent 能力与agentInstanceId。工具已出现在 IDEA 中不代表目标 Agent 支持该能力。- 新工具通常返回
success/data或success=false/error，原有方法调用、启动、热重载等工具保留各自结果结构。结合业务状态、error.code、候选项、retryable和nextAction判断后续操作。
连接与 JVM
工具组：DebugToolsConnectionsToolset，共 7 个工具。
| 工具 | 用途 | 必填参数 | 可选参数 |
|---|---|---|---|
get_debug_tools_status | 聚合项目、连接、JVM 和调试会话快照。 | 无 | 无 |
list_debug_tools_connections | 读取连接状态及上下文。 | 无 | 无 |
list_attachable_jvms | 列出可附着的本地 JVM。 | 无 | 无 |
attach_local_jvm | 附着指定 PID 并等待连接。 | pid | attachName、waitForConnectionMillis |
manage_debug_tools_connection | 连接远程 Agent、重连、断开或请求停止 Agent。 | action | connectionId、host、tcpPort、httpPort、remark、waitMillis |
manage_connection_context | 读取或更新连接 Header、默认 ClassLoader 和前后置脚本。 | 无 | connectionId、action、headers、classLoaderIdentity、methodAroundName |
get_agent_capabilities | 读取 Agent 版本、实例 ID、能力和限额。 | 无 | connectionId |
manage_debug_tools_connection.action 支持 CONNECT_REMOTE、RECONNECT、DISCONNECT、STOP_AGENT。远程连接需明确 host、tcpPort 和 httpPort；其余动作需 connectionId。DISCONNECT 关闭客户端连接；STOP_AGENT 返回 STOP_REQUESTED，停止结果需要继续确认。
manage_connection_context 默认为 GET；UPDATE 只替换提供的字段。headers={} 清空连接 Header，classLoaderIdentity=null 或 methodAroundName=null 清除对应默认值。ClassLoader 与脚本会先校验。
运行与热重载
工具组：DebugToolsHotswapToolset，共 5 个工具。
| 工具 | 用途 | 必填参数 | 可选参数 |
|---|---|---|---|
list_debug_tools_run_configurations | 查询 IDEA 运行配置。 | 无 | moduleName、mainClassNameContains、typeDisplayName |
execute_debug_tools_run_configuration | 使用 DebugTools Hotswap 启动准确的运行配置。 | configurationName | 无 |
manage_run_instance | 列举、启动、停止或重启受管理的 Run/Debug 实例。 | 无 | connectionId、action、instanceId、configurationName、executor、allowParallel、waitMillis |
compile_and_reload_modified_files | 提交或继续等待 IDEA Java Debugger 编译与热重载。 | 无 | sessionName、compileBeforeReload、waitMillis、operationId |
get_hotswap_operation | 查询当前项目保存的热重载状态。 | operationId | 无 |
manage_run_instance.action 支持 LIST、START、STOP、RESTART。启动需准确的 configurationName，executor 为 RUN 或 DEBUG；停止、重启需返回的 instanceId。先用 LIST 获取当前 IDEA 运行实例的 ID；RESTART 还需要准确的 configurationName。
热重载应保留 operationId，以最终 status=SUCCESS 确认完成；参数、状态与恢复方式见 Hotswap MCP。
方法调用
工具组：DebugToolsMethodInvocationToolset，共 17 个工具。
| 工具 | 用途 | 必填参数 | 可选参数 |
|---|---|---|---|
generate_method_args_template | 根据源码签名生成参数模板。 | className、methodName | parameterTypes、genParamType |
invoke_java_method | 在选定 JVM 调用一次 Java 方法。 | className、methodName | agentInstanceId、connectionId、parameterTypes、argsJson、headers、xxlJobParam、traceMethodDTO、methodAroundContent、methodAroundName、methodAroundContentIdentity、classLoaderIdentity、timeoutMillis、resultView |
run_and_invoke | 按需连接、等待就绪和热重载，再调用方法并查询证据。 | className、methodName | agentInstanceId、connectionId、parameterTypes、argsJson、headers、xxlJobParam、traceMethodDTO、methodAroundContent、methodAroundName、methodAroundContentIdentity、classLoaderIdentity、timeoutMillis、resultView、sessionName、compileBeforeReload、waitMillis、operationId、springReadiness、allowStart、runConfigurationName、allowAttach、pid、verifyLogs、verifySql |
list_method_around_scripts | 列举已保存前后置脚本。 | 无 | 无 |
get_method_around_script | 读取已保存前后置脚本。 | name | 无 |
manage_method_around_script | 列举、读取、语法校验、保存或删除前后置脚本。 | action | connectionId、name、content、expectedIdentity、offset、limit |
manage_method_preset | 保存和复用方法签名及参数 JSON。 | action | connectionId、name、className、methodName、parameterTypes、argsJson、expectedIdentity、offset、limit |
get_invocation_result | 按调用 ID 恢复已有执行的结果。 | invocationId | connectionId、waitMillis |
inspect_run_result | 转换结果视图或分页展开对象。 | offsetPath | connectionId、view、offset、limit、maxDepth、maxNodes |
release_run_results | 按偏移路径定向释放 Agent 结果缓存。 | offsetPaths | connectionId |
read_invocation_stream | 按游标读取已有 Flux/SSE 事件。 | invocationId | connectionId、afterCursor、limit |
cancel_invocation_stream | 请求取消指定调用的流订阅。 | invocationId | connectionId |
capture_result_snapshot | 把已有结果冻结为项目内比较快照。 | offsetPath | connectionId、label、maxDepth、maxNodes |
compare_result_snapshots | 比较两个快照，可忽略精确 JSON Pointer 路径。 | afterSnapshotId、beforeSnapshotId | connectionId、ignorePaths、allowDifferentTargets |
release_result_snapshot | 释放项目内比较快照。 | snapshotId | connectionId |
get_method_trace | 读取有界调用树、耗时摘要和热点。 | traceOffsetPath | connectionId、maxDepth、maxNodes、minDurationMillis、topN |
diagnose_invocation | 查询调用状态、执行线程和可用的关联证据。 | invocationId | connectionId、maxDepth |
调用参数与结果详见 方法调用 MCP。manage_method_around_script 的 action 支持 LIST/GET/VALIDATE/SAVE/DELETE，manage_method_preset 支持 LIST/GET/SAVE/DELETE。除列表外需要 name；脚本校验/保存需要 content，预设保存需要 className、methodName 和 argsJson。覆盖保存和删除前先读取 identity，再作为 expectedIdentity 提交。脚本仅做 Java 语法校验，目标 JVM 类型检查与编译发生在实际调用时。
超时后用 get_invocation_result 恢复原调用，不重新执行方法。流读取沿用 invocationId 与 nextCursor，留意 gap、droppedEvents；取消请求需要读取终态确认。快照默认保留 30 分钟、每项目最多 32 个，截断的数据不能用于证明完整结果相等。release_result_snapshot 与 release_run_results 分别清理本地快照和 Agent 结果缓存。
HTTP 调试
工具组：DebugToolsHttpToolset，共 3 个工具。
| 工具 | 用途 | 必填参数 | 可选参数 |
|---|---|---|---|
search_http_url | 从源码索引查找 HTTP 映射。 | 无 | path、method、moduleName、limit |
build_controller_http_request | 生成 Controller HTTP 请求及 cURL，不发送请求。 | baseUrl、className、methodName | connectionId、parameterTypes、path、query、headers、body、bodyMode |
execute_http_request | 向明确的应用地址发送一次真实 HTTP 请求。 | method、url | connectionId、headers、body、timeoutMillis、maxResponseBytes |
build_controller_http_request 仅从 Spring Controller 源码和显式输入生成请求；存在多个注解映射时使用首个声明映射，发送前检查生成的 URL 和方法。baseUrl 是业务服务地址，不能使用 Agent HTTP 端口替代。bodyMode 为 NONE/JSON/TEXT/XML。
execute_http_request 经过真实 HTTP 过滤器、认证和序列化流程；Java 方法反射调用不经过这些环节。工具不自动跟随重定向或重试，超时表示请求结果未知。
脚本与部署
工具组：DebugToolsScriptsAndDeploymentToolset，共 5 个工具。
| 工具 | 用途 | 必填参数 | 可选参数 |
|---|---|---|---|
execute_groovy_script | 在选定 ClassLoader 中执行 Groovy。 | classLoaderIdentity、script | connectionId、agentInstanceId、operationId、waitMillis |
compile_and_deploy_java | 在目标 JVM 编译 Java，可选择重定义已加载类。 | classLoaderIdentity、files | connectionId、agentInstanceId、operationId、waitMillis、deploy |
deploy_class_files | 用明确的 class 字节码重定义已加载类。 | classLoaderIdentity、files | connectionId、agentInstanceId、operationId、waitMillis |
deploy_resources | 向选定资源监听目录写入资源文件。 | classLoaderIdentity、files | connectionId、agentInstanceId、operationId、waitMillis |
get_agent_operation | 查询已有脚本、编译或部署操作。 | agentInstanceId、operationId | connectionId、waitMillis |
四个执行工具均要求明确 classLoaderIdentity，返回可恢复的 operationId 和 agentInstanceId；waitMillis 为 0 到 30000 毫秒，默认不等待。超时或响应丢失后使用 get_agent_operation，保留原实例 ID，不换 ID 重复执行。
compile_and_deploy_java.files 使用“类全限定名 → Java 源码”映射，deploy=false（默认）仅编译；deploy=true 才重定义选定 ClassLoader 中已加载且可修改的类。deploy_class_files.files 使用“类全限定名 → Base64 class 字节码”映射；两者都不把 class 写入磁盘。
deploy_resources.files 使用“资源相对路径 → Base64 文件内容”映射，目标 ClassLoader 必须恰好配置一个文件类型的 watchResources 根目录。返回每个文件的写入、大小和哈希信息；frameworkReloadConfirmed=false 表示仍需验证框架实际刷新。
Spring
工具组：DebugToolsSpringToolset，共 4 个工具。
| 工具 | 用途 | 必填参数 | 可选参数 |
|---|---|---|---|
wait_for_application_ready | 有界等待 Spring 就绪。 | 无 | connectionId、waitMillis |
get_spring_config | 按 key 读取 Spring Environment 最终值。 | keys | connectionId |
inspect_spring_beans | 列出上下文，读取 Bean 定义和已有单例/代理元数据。 | classLoaderIdentity | connectionId、action、contextId、nameContains、offset、limit |
explain_spring_config | 解释配置值及 PropertySource 优先级、覆盖链。 | classLoaderIdentity、keys | connectionId、contextId |
wait_for_application_ready 返回 ready、state 和 retryable，只有 STARTING 且可重试时继续等待。get_spring_config.keys 按需指定配置键。
inspect_spring_beans 默认 action=CONTEXTS，先取得准确的 contextId，再用 BEANS 查询。它不会初始化 lazy Bean 或 FactoryBean。explain_spring_config 在多个上下文时也需要 contextId，返回配置最终值、PropertySource 顺序及覆盖来源。
运行时诊断
工具组：DebugToolsRuntimeDiagnosticsToolset，共 7 个工具。
| 工具 | 用途 | 必填参数 | 可选参数 |
|---|---|---|---|
find_class_loaders | 分页列举 ClassLoader，可校验目标类能否加载。 | 无 | connectionId、className、limit、offset |
inspect_runtime_class | 读取已加载类、方法签名、ClassLoader 和来源。 | 无 | connectionId、className、nameContains、classLoaderIdentity、offset、limit、methodLimit |
get_jvm_snapshot | 查询内存、GC、类和线程计数。 | 无 | connectionId |
get_thread_snapshot | 分页查询线程栈和死锁信息。 | 无 | connectionId、offset、limit、maxDepth |
manage_method_watch | 有界观察真实方法调用，读取、停止和释放观察会话。 | agentInstanceId | connectionId、action、watchId、classLoaderIdentity、className、methodName、descriptor、maxCalls、durationMillis、afterCursor、limit |
manage_trace_selection | 管理运行时方法 Trace 选择。 | 无 | connectionId、action、scope、agentInstanceId、className、methodName、descriptor、offset、limit |
manage_async_context | 为明确的应用 Executor 管理调用上下文传播。 | agentInstanceId | connectionId、action、contextId、className、classLoaderIdentity |
inspect_runtime_class 至少提供准确 className 或不少于三个字符的 nameContains。只查询已加载类，不初始化类。get_thread_snapshot 支持分页与栈深度限制；get_jvm_snapshot 不触发 GC 或堆转储，不支持的指标可能为 -1。
manage_method_watch 的 START 需准确的 classLoaderIdentity、className、methodName 和 JVM descriptor，按 maxCalls/durationMillis 限制观察；READ/STOP/RELEASE 使用 watchId。manage_trace_selection 的增删需明确 agentInstanceId、方法签名和 scope=ALL_CLASSLOADERS，这是所有 ClassLoader 范围的选择。
manage_async_context 用 START 为明确的应用 Executor 类和 ClassLoader 开启传播，STOP 使用返回的 contextId；不承诺任意线程池、commonPool 或响应式调度器都自动关联。结束任务后清理本次创建的观察与传播会话。
日志与 SQL
工具组：DebugToolsLogsAndSqlToolset，共 6 个工具。
| 工具 | 用途 | 必填参数 | 可选参数 |
|---|---|---|---|
manage_business_log_capture | 查看、开启或停止 Logback/Log4j2 业务日志采集。 | 无 | connectionId、action、classLoaderIdentity、framework |
read_target_application_logs | 按时间、级别、关键字和调用 ID 查询最近日志。 | 无 | connectionId、limit、since、level、keyword、invocationId |
get_last_sql_statements | 按时间、关键字和调用 ID 查询最近 SQL。 | 无 | connectionId、limit、since、keyword、invocationId |
manage_sql_capture | 查询或切换 SQL 打印模式。 | 无 | connectionId、action、mode |
aggregate_sql_statements | 按归一化 SQL 聚合次数与耗时。 | 无 | connectionId、since、limit、sortBy |
read_sql_history | 列举或分页读取 IDEA 本地 SQL 历史。 | 无 | connectionId、historyId、includeLegacy、applicationName、date、offset、limit、maxBytes |
业务日志采集、按调用关联、SQL 聚合与历史读取详见 日志和 SQL MCP。空结果只表示当前采集范围及过滤条件内没有记录。
Kubernetes
工具组：DebugToolsKubernetesToolset，共 2 个工具。
| 工具 | 用途 | 必填参数 | 可选参数 |
|---|---|---|---|
discover_kubernetes_targets | 发现 context、namespace、Pod、Deployment 或容器 JVM。 | 无 | connectionId、kind、context、namespace、pod、container、labelSelector、offset、limit |
manage_kubernetes_connection | 检查、建立或关闭指定 Kubernetes 实例的端口转发连接。 | 无 | connectionId、action、context、namespace、pod、container、expectedPodUid、expectedContainerId、pid、injectAgent、remoteTcpPort、remoteHttpPort、localTcpPort、localHttpPort、replaceExistingTunnel、waitMillis |
discover_kubernetes_targets.kind 支持 CONTEXTS/NAMESPACES/PODS/DEPLOYMENTS/JVMS。除 context 列表外需明确 context；Pod/Deployment 查询还需 namespace，JVM 查询需明确 pod 和 container。
manage_kubernetes_connection 默认为 STATUS。CONNECT 需要 context/namespace/pod/container、发现结果中的 expectedPodUid/expectedContainerId 及明确的 remoteTcpPort/remoteHttpPort。injectAgent=false 复用已有 Agent；设为 true 时需明确容器 JVM 的 pid，才会上传并附着 Agent。每项目只维护一个转发隧道，替换需 replaceExistingTunnel=true。
Pod UID、容器 ID 或 Agent 实例变化后，重新发现并选择目标。STOP_TUNNEL 关闭隧道，不能据此认定远端 JVM 或 Agent 已停止。连接建立也不等于应用就绪。