DebugTools 日志和 SQL MCP

通过选定 Agent 读取最近的进程内日志和 SQL，也可以显式开启业务日志采集、管理 SQL 打印模式、查看聚合和 IDEA 本地历史。先确认当前项目有活跃 DebugTools 连接，Agent 支持相应能力且 HTTP 端口可达；远程或 Kubernetes 连接需要对应的 HTTP 转发。

业务日志采集

read_target_application_logs 默认可读取 DebugTools 自身记录。需要 Logback 或 Log4j2 业务日志时，用 manage_business_log_capture 开启采集：

json

{
  "connectionId": "demo-connection",
  "action": "START",
  "classLoaderIdentity": "selected-loader-id",
  "framework": "LOGBACK"
}

参数	用途
`action`	`STATUS`（默认）、`START`、`STOP`。
`connectionId`	目标连接；多个活跃连接时必须明确。
`classLoaderIdentity`	`START/STOP` 必填，使用目标 Agent 返回的真实 ClassLoader 标识。
`framework`	`START/STOP` 必填，`LOGBACK` 或 `LOG4J2`。

采集器挂到选定日志上下文的 root logger，不改变应用的日志级别，只采集开启后产生的事件；不保证覆盖关闭日志继承的 logger，也不采集完整标准输出。查看 STATUS 中的实际状态和覆盖信息，任务结束后用相同目标和框架执行 STOP，保留用户原有采集会话。

工具名：read_target_application_logs。

参数	必填	类型	说明
`projectPath`	否	`string`	目标 IDEA 项目路径。
`connectionId`	条件必填	`string`	多个活跃连接时必须指定。
`limit`	否	`integer`	默认 `100`，范围 `1` 到 `200`。
`since`	否	`integer`	Unix 毫秒时间戳，仅保留不早于此时间的记录，默认 `0`。
`level`	否	`string`	日志级别精确匹配，忽略大小写；`ERROR` 不自动包含其他级别。
`keyword`	否	`string`	消息子串，区分大小写。
`invocationId`	否	`string`	只读取关联到指定调用的记录。

json

{
  "connectionId": "demo-connection",
  "invocationId": "returned-invocation-id",
  "limit": 20,
  "level": "ERROR"
}

记录包含 timestamp、level、logger、thread、message、throwable、source 和 invocationId。source 区分 DebugTools 与业务日志来源；没有关联信息的记录，其调用 ID 可能为空。

工具名：get_last_sql_statements。SQL 只包含已进入 DebugTools 打印流程、且未被过滤的语句，需要先开启 SQL 打印。

json

{
  "connectionId": "demo-connection",
  "invocationId": "returned-invocation-id",
  "limit": 10
}

记录包含 timestamp、sql、consumeTimeMillis、dbType、applicationName 和 invocationId。SQL 文本按当前打印模式保存，耗时单位为毫秒。

工具	用法
`manage_sql_capture`	`GET_MODE` 查询模式；`SET_MODE` 时必须传 `mode=Pretty/Compress/No`。`No` 关闭 SQL 打印。
`aggregate_sql_statements`	用 `since` 选时间窗口，`sortBy=TOTAL/MAX/COUNT` 分别按总耗时、最大耗时、次数排序；`limit` 控制返回条数。
`read_sql_history`	不传 `historyId` 时列出当前项目历史来源；选择后按字节 `offset/maxBytes` 读取，沿用 `nextByteOffset`；列表用 `offset/limit` 分页，可按应用名和日期过滤。

聚合基于当前 Agent 的有界 SQL 缓冲；不是数据库全量慢查询统计。read_sql_history 读取 IDEA 本地已保存文件，需要启用 SQL 自动保存且存在历史；includeLegacy 用于显式包含旧目录记录，与 Agent 的实时缓冲查询分开使用。

invocationId 用于精确筛选已关联记录。Agent 自身日志和 SQL 使用调用上下文；业务日志关联依赖事件中的 MDC 信息。异步线程需要所用 Executor 的上下文传播支持，缺失关联不能证明该线程没有执行。

可用 manage_async_context 管理明确的应用 Executor，或用 manage_method_watch 观察真实方法调用。具体选择与清理要求见工具清单。仅以 since 筛选得到的是时间窗口证据，可能混入并发业务记录。

日志和最近 SQL 查询的正常结果均使用结构化包装，data 为记录数组。符合条件的最近记录按时间从旧到新排列。

两个缓冲各保留最多 500 条；日志另有大小限额，旧记录会被淘汰，目标 JVM 重启后清空。实时查询不要求启用 SQL 自动保存。

结果	含义与处理
`success=true`、`data=[]`	当前缓冲内无匹配记录，检查采集范围、打印模式和筛选条件。
`LOGS_UNAVAILABLE` / `SQL_HISTORY_UNAVAILABLE`	查询或结果解析失败，检查 Agent 能力和 HTTP 连接。
`CAPABILITY_UNAVAILABLE`	目标未提供所需端点或能力。
`CONNECTION_AMBIGUOUS`	目标不明确，选择准确 `connectionId`。
`NO_CONNECTION`	先建立活跃连接。

查询成功也只能说明已采集的范围；不要把空记录或能力缺失解释为整个业务过程没有日志或 SQL。