Hotswap MCP
DebugTools 提供运行配置查询、Hotswap 启动、运行实例管理、Java Debugger 热重载和操作查询工具，归入 DebugToolsHotswapToolset。本页也介绍位于方法调用组的 run_and_invoke 编排工具。
本页是工具参考手册，只说明每个工具的作用、输入参数和返回值。AI 应该如何选择运行配置、怎样处理自动附着、什么时候触发热重载等组合规则，由 Hotswap Skill 负责。
工具概览
| 工具 | 作用 |
|---|---|
list_debug_tools_run_configurations | 查询当前 IDEA 项目中的运行配置，并支持按模块、主类和配置类型筛选。 |
execute_debug_tools_run_configuration | 使用 DebugTools Hotswap executor 启动指定 IDEA 运行配置。 |
manage_run_instance | 查询 IDEA 运行实例，按明确实例停止或重启，或用 Run/Debug 启动准确配置。 |
compile_and_reload_modified_files | 对已附着的 Java Debugger 会话触发 Compile and Reload Modified Files。 |
get_hotswap_operation | 查询之前提交的热重载操作状态。 |
run_and_invoke | 编排状态检查、可选启动/附着、热重载、方法调用以及可选日志/SQL 验证。 |
公共约定
这些工具都支持可选参数 projectPath：
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
projectPath | 否 | string | IDEA 项目目录或项目内文件路径。MCP 上下文无法确定项目，或 IDEA 同时打开多个项目时用于指定目标项目。 |
省略 projectPath 时，插件会从 IDEA MCP 调用上下文和当前打开的项目中解析目标项目。如果无法确定项目，工具会返回 MCP error。
工具的正常结果以 JSON 文本返回。参数缺失、项目不存在或工具执行异常时，插件可能直接返回 MCP error；可以预期的业务失败会通过返回对象中的 success=false 和 message 表达。
1. 查看 IDEA 运行配置
工具名：list_debug_tools_run_configurations
作用
读取当前 IDEA 项目 RunManager 中的运行配置，并返回配置名称、类型、主类和模块信息。它只查询配置，不会启动应用。
返回列表与 IDEA 原生运行配置列表保持一致，不会预先过滤“不支持 DebugTools Hotswap executor”的配置。是否支持启动由 execute_debug_tools_run_configuration 实际检查。
参数
没有工具专属的必填参数。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
projectPath | 否 | string | 目标 IDEA 项目路径，含义见“公共约定”。 |
moduleName | 否 | string | 模块名称筛选，和返回值中的 moduleName 精确匹配。 |
mainClassNameContains | 否 | string | 主类名包含筛选，检查 mainClassName 是否包含指定文本。 |
typeDisplayName | 否 | string | 运行配置类型展示名筛选，精确匹配，例如 Spring Boot 或 Application。 |
同时提供多个筛选参数时，运行配置必须满足全部条件才会返回。空字符串按未提供处理。
返回值
| 字段 | 类型 | 说明 |
|---|---|---|
count | integer | 筛选后返回的运行配置数量。 |
configurations | array | 运行配置摘要列表。 |
configurations[].name | string | IDEA 运行配置名称。该名称可传给 execute_debug_tools_run_configuration.configurationName。 |
configurations[].typeName | string | 运行配置类型名称。 |
configurations[].typeDisplayName | string | IDEA 中显示的配置类型名称。 |
configurations[].mainClassName | string | null | 能从该配置读取到的 Java 主类全限定名。 |
configurations[].moduleName | string | null | 运行配置关联的 IDEA 模块名称。 |
请求示例：
{
"moduleName": "demo-service",
"mainClassNameContains": "DemoApplication",
"typeDisplayName": "Spring Boot"
}返回示例：
{
"count": 1,
"configurations": [
{
"name": "DemoApplication",
"typeName": "Spring Boot",
"typeDisplayName": "Spring Boot",
"mainClassName": "com.example.DemoApplication",
"moduleName": "demo-service"
}
]
}2. 启动运行配置
工具名：execute_debug_tools_run_configuration
作用
按名称查找 IDEA 运行配置，并使用 DebugTools Hotswap executor 发起启动。这个动作等价于在 IDEA 中选择对应配置并执行 Hotswap '<configuration>' with DebugTools。
参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
configurationName | 是 | string | 要启动的 IDEA 运行配置名称，按完整名称精确匹配。 |
projectPath | 否 | string | 目标 IDEA 项目路径，含义见“公共约定”。 |
返回值
| 字段 | 类型 | 说明 |
|---|---|---|
success | boolean | 是否成功把启动请求交给 IDEA 执行系统。 |
configurationName | string | 本次请求的运行配置名称。 |
executorId | string | 实际使用的 DebugTools executor ID，当前为 DebugTools Debug Executor。 |
autoAttachEnabled | boolean | DebugTools 全局“自动附着”开关是否启用。 |
requiresManualAttach | boolean | 本次启动后是否需要手动附着 DebugTools agent。 |
nextAction | string | null | 给 MCP 客户端的后续动作提示；启动失败时为空。 |
expectedMainClassName | string | null | 从运行配置读取到的预期主类名。 |
expectedModuleName | string | null | 从运行配置读取到的预期模块名。 |
message | string | 启动或失败说明。 |
availableConfigurationNames | string[] | 找不到指定配置时返回当前项目的可用配置名称；其他结果通常为空数组。 |
nextAction 当前可能返回：
| 值 | 含义 |
|---|---|
LIST_DEBUG_TOOLS_CONNECTIONS | 自动附着已开启，建议客户端后续查询 DebugTools 连接。 |
LIST_ATTACHABLE_JVMS | 自动附着未开启，建议客户端后续查询可附着 JVM。 |
null | 启动失败，没有后续动作提示。 |
WARNING
success=true 只表示 IDEA 已经接受启动请求，不表示 JVM 已启动完成，也不表示 DebugTools 连接已经建立。
请求示例：
{
"configurationName": "DemoApplication"
}成功返回示例：
{
"success": true,
"configurationName": "DemoApplication",
"executorId": "DebugTools Debug Executor",
"autoAttachEnabled": true,
"requiresManualAttach": false,
"nextAction": "LIST_DEBUG_TOOLS_CONNECTIONS",
"expectedMainClassName": "com.example.DemoApplication",
"expectedModuleName": "demo-service",
"message": "DebugTools run configuration start requested",
"availableConfigurationNames": []
}找不到运行配置时的返回示例：
{
"success": false,
"configurationName": "UnknownApplication",
"executorId": "DebugTools Debug Executor",
"autoAttachEnabled": false,
"requiresManualAttach": false,
"nextAction": null,
"expectedMainClassName": null,
"expectedModuleName": null,
"message": "Run configuration not found: UnknownApplication",
"availableConfigurationNames": ["DemoApplication", "DemoTests"]
}配置存在但当前 runner 不支持 DebugTools Hotswap executor，或当前 IDEA 中无法取得该 executor 时，也会返回 success=false，具体原因写在 message 中。
3. 编译并热重载修改类
工具名：compile_and_reload_modified_files
作用
选择当前项目中已附着的 IDEA Java Debugger 会话，并调用 IDEA Java Debugger 的 Compile and Reload Modified Files 能力。
这里的 modified files 是 Java Debugger 从调试会话启动后或上一次 reload 后跟踪到的变更文件和类，不是 Git 工作区中的 modified 文件。
参数
没有工具专属的无条件必填参数。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
projectPath | 否 | string | 目标 IDEA 项目路径，含义见“公共约定”。 |
sessionName | 条件必填 | string | Java Debugger 会话名称。只有一个可用会话时可省略；存在多个会话时必须指定。 |
compileBeforeReload | 否 | boolean | 是否先编译再热重载。省略时使用 IDEA Java Debugger 当前的 COMPILE_BEFORE_HOTSWAP 设置。 |
waitMillis | 否 | integer | 等待编译和热重载完成的毫秒数，默认 0（立即返回），最多 120000。 |
operationId | 否 | string | 继续等待当前项目中的已有操作，不重复提交；可配合 waitMillis 使用。只查询快照时使用 get_hotswap_operation。 |
返回值
| 字段 | 类型 | 说明 |
|---|---|---|
success | boolean | 请求被接受或操作已成功；必须结合 status 区分已提交与已完成。 |
sessionName | string | null | 实际选中的调试会话名称；选择失败时可能是请求中传入的名称或空值。 |
compileBeforeReload | boolean | 本次请求最终采用的“先编译再重载”设置。 |
message | string | 请求结果或失败原因。 |
availableSessionNames | string[] | 多会话未指定、指定会话不存在等情况下返回的候选会话名称。 |
operationId | string | null | 用于查询操作的 ID。 |
status | string | 请求或操作状态。 |
errorCode | string | null | 可用时返回结构化热重载错误码。 |
WARNING
status=SUCCESS 才表示 IDEA 完成回调确认热重载成功。REQUESTED/COMPILING/RELOADING 表示仍在处理；FAILED/CANCELLED 表示失败或取消。TIMEOUT 只表示本次等待结束，操作仍可继续查询。IDEA 原生界面与通知仍会显示编译和热重载详情。
请求示例：
{
"sessionName": "DemoApplication",
"compileBeforeReload": true,
"waitMillis": 30000
}完成返回示例：
{
"success": true,
"sessionName": "DemoApplication",
"compileBeforeReload": true,
"message": "HotSwap success",
"availableSessionNames": [],
"operationId": "example-operation-id",
"status": "SUCCESS"
}存在多个调试会话但没有指定 sessionName 时的返回示例：
{
"success": false,
"sessionName": null,
"compileBeforeReload": true,
"message": "Multiple attached Java debugger sessions are available; pass sessionName to choose one",
"availableSessionNames": ["DemoApplication", "WorkerApplication"]
}当前项目没有已附着的 Java Debugger 会话时，返回 success=false，message 为 No attached Java debugger session is available for hotswap。
4. 查询热重载操作
工具名：get_hotswap_operation。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
operationId | 是 | string | compile_and_reload_modified_files 成功返回的操作 ID。 |
{
"operationId": "example-operation-id"
}查询结果使用结构化包装，data 是保存的热重载请求结果，包含 sessionName、compileBeforeReload、operationId、status 等字段。操作不存在时返回 HOTSWAP_OPERATION_NOT_FOUND。
热重载通过 IDEA 编译与重载回调更新状态。get_hotswap_operation 查询当前状态，不等待；需要继续等待时，再调用 compile_and_reload_modified_files 并提供原 operationId 和 waitMillis。
{
"operationId": "example-operation-id",
"waitMillis": 30000
}等待超时不会取消实际操作。操作按项目保存，同一调试会话有未完成操作时会复用；项目关闭后清理。changedFiles、compiledClasses、reloadedClasses、skippedClasses 和 classResults 未提供明细时保持空值，不能据此推算修改范围。
5. 编排启动与方法调用
工具名：run_and_invoke。按需启动或附着目标，等待就绪和热重载成功后调用 Java 方法。工具可追加最近日志和 SQL 查询。
参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
className | 是 | string | 目标 Java 类全限定名。 |
methodName | 是 | string | 方法名。 |
projectPath | 否 | string | 目标 IDEA 项目路径。 |
connectionId | 条件必填 | string | 方法调用目标；多活跃连接时必须明确指定。 |
sessionName | 条件必填 | string | 热重载的 Java 调试会话；多会话时必须指定，并确认和方法调用属于同一 JVM。 |
compileBeforeReload | 否 | boolean | 是否先编译，省略时使用 IDEA Java Debugger 设置。 |
waitMillis | 否 | integer | 启动、就绪检查和热重载各阶段的有界等待参数，默认 30000，范围 0 到 120000 毫秒；不是整个流程共用的总时限。 |
operationId | 否 | string | 复用已有热重载操作，避免等待超时后重新提交。 |
springReadiness | 否 | string | AUTO（默认）、REQUIRED 或 SKIP。自动模式允许明确无 Spring 上下文的非 Spring 目标；Bean 调用建议 REQUIRED。 |
agentInstanceId | 否 | string | 能力查询返回的目标实例 ID，用于检测目标是否已替换。 |
headers | 否 | object | 本次调用 Header。 |
xxlJobParam | 否 | string | 本次 XXL-JOB 参数。 |
traceMethodDTO | 否 | object | 本次 Trace 配置。 |
classLoaderIdentity | 否 | string | 选定 ClassLoader。 |
timeoutMillis | 否 | integer | 方法结果等待时间，默认 30000 毫秒。 |
parameterTypes | 否 | string[] | 方法参数类型，按声明顺序排列。 |
argsJson | 否 | string | DebugTools 参数 JSON 字符串。 |
resultView | 否 | string | TO_STRING、JSON、DEBUG 或 NONE。 |
methodAroundName | 否 | string | 已保存前后置脚本名，不含 .java。 |
methodAroundContent | 否 | string | 显式 Method Around Java 源码。 |
methodAroundContentIdentity | 否 | string | 源码内容标识。 |
allowStart | 否 | boolean | 没有活跃连接时允许启动配置，默认不启动。 |
runConfigurationName | 条件必填 | string | allowStart=true 且需要启动时，提供准确的 IDEA 运行配置名。 |
allowAttach | 否 | boolean | 没有活跃连接时允许附着指定进程，默认不附着。 |
pid | 条件必填 | string | allowAttach=true 且需要附着时，提供明确 PID。 |
verifyLogs | 否 | boolean | 调用后追加最近日志查询，固定最多 100 条。 |
verifySql | 否 | boolean | 调用后追加最近 SQL 查询，固定最多 50 条。 |
有活跃连接时不会启动或附着新目标。没有活跃连接且两个开关都为 true 时，先尝试附着；附着失败会直接返回，不会转而启动配置。建议每次只选择一种方式。
请求示例
已有连接与 Java 调试会话时：
{
"connectionId": "demo-connection",
"sessionName": "DemoApplication",
"className": "com.example.HealthService",
"methodName": "status",
"parameterTypes": [],
"argsJson": "{}",
"compileBeforeReload": true,
"resultView": "JSON"
}没有连接、需要启动明确的运行配置时：
{
"allowStart": true,
"runConfigurationName": "DemoApplication",
"waitMillis": 30000,
"className": "com.example.HealthService",
"methodName": "status",
"argsJson": "{}"
}启动后需要 DebugTools 自动附着建立连接；自动附着关闭时建议分步启动、选 PID 并附着。allowAttach 只附着 DebugTools Agent，不会建立 Java Debugger 会话，因此仍需事先连接调试器。
返回值与使用限制
正常工具结果使用结构化包装；顶层 success=true 表示得到编排结果，流程是否成功需要读取 data.success：
data 字段 | 说明 |
|---|---|
success | 所需步骤全部成功且方法执行成功时为 true；额外结果读取或所要求的日志/SQL 查询失败也会令其为 false。 |
steps | 包含目标选择、就绪、热重载、调用和所选证据步骤的状态；失败步骤提供 errorCode。 |
invokeResult | 方法调用结果，包括额外结果获取状态。 |
hotswap | 热重载状态与操作 ID。 |
error | 导致编排失败的结构化错误。 |
logs、sql | 开启对应查询时的最近记录；没有取得结果时为空。 |
编排固定选中的连接，并按 PID 匹配 Java 调试会话；无法自动关联时要求明确 sessionName，已知 PID 不匹配时返回 TARGET_MISMATCH。springReadiness=AUTO 会等待 Spring 启动；明确无 Spring 上下文时，仅对类名不符合常见 Bean 命名规则的目标跳过，依赖 Spring 的自定义类应使用 REQUIRED。只有明确无需 Spring 时才设为 SKIP。
热重载未达到 SUCCESS 时不会调用业务方法。保留 hotswap.operationId 查询状态，或在确认本次尚未进入调用步骤时，用 operationId 恢复编排的热重载等待。已经执行过方法时应恢复原调用结果，避免重跑整个编排。
verifyLogs 和 verifySql 读取同一个已选连接，并按调用开始时间过滤。它们仍可能包含并发请求记录；精确关联需使用 invokeResult.invocationId 查询。证据读取失败会记录失败步骤并令编排失败；即使编排失败，方法也可能已经执行成功，应查看 invokeResult，不能直接重试业务。
运行实例的 LIST/START/STOP/RESTART 操作和参数见 MCP 工具清单。
6. 管理运行实例
工具名：manage_run_instance。通过 IDEA 的实际运行实例与 ProcessHandler 管理生命周期。
| 参数 | 用途 |
|---|---|
action | LIST（默认）、START、STOP、RESTART。 |
configurationName | START/RESTART 必填，必须是准确且唯一的运行配置名。 |
executor | RUN（默认）或 DEBUG。 |
instanceId | STOP/RESTART 必填，先用 LIST 取得目标实例 ID。 |
allowParallel | 默认 false，存在同名活跃实例时拒绝并行启动。 |
waitMillis | 等待停止的时间，默认 5000，范围 0 到 30000 毫秒。 |
{
"action": "START",
"configurationName": "DemoApplication",
"executor": "DEBUG"
}START_REQUESTED 只表示已请求启动，随后重新查询实例、DebugTools 连接与就绪状态。停止返回 TERMINATED 才表示已结束；STOP_REQUESTED 仍需继续确认。重启先验证新配置和 runner，再停止明确实例并启动；停止未完成时不会继续启动。