Scouter MCP

scouter-mcp

韩语文档请参阅 README.ko.md。

一个通过 TCP 直接连接 Scouter Collector 并查询 XLogs、计数器和对象的 stdio MCP 服务。它旨在让 AI 快速探索 Scouter 指标并诊断根本原因。每条结果都包含 txid / gxid / objName / endTimeIso，可将其用作键，与 OpenSearch 或 Datadog 等其他可观测性工具进行交叉分析。

架构

Java 17。它复用 scouter-common，并将 scouter.webapp 的 net/server 类移植到 scouter.mcp.client 包中。MCP 使用 Java SDK 2.0.0 stdio 传输。所有针对 Collector 的操作均为只读。

构建

./gradlew shadowJar
# output: build/libs/scouter-mcp-<version>-all.jar

.mcpb bundle 仅由发布 CI 生成（它会封装此 jar）；本地构建只会生成 jar。

注册（Claude Code、Claude Desktop 等）

对于单个 Collector，可从 GitHub Release 安装 .mcpb bundle，一键完成设置；也可以复制 .mcp.json.example，将其指向 fat jar（从发布版本下载或本地构建），并填写凭据。有关多个 Collector 的设置，请参阅多个 Collector。

Env var	描述
SCOUTER_COLLECTOR_HOST	Collector 主机
SCOUTER_COLLECTOR_PORT	Collector TCP 端口（默认值为 6100）
SCOUTER_USER	登录用户名
SCOUTER_PASSWORD	登录密码
SCOUTER_TZ	时区（例如 Asia/Seoul）
SCOUTER_LOCALE	面向用户的消息语言：en 或 ko。如果未设置，则根据 JVM 默认值确定（仅当 JVM 语言为韩语时使用韩语，否则使用英语）
SCOUTER_INCLUDE_BIND_PARAMS	SQL 绑定参数的运维级紧急开关，适用于 get_xlog_detail（默认值为 true）。设置为 false 后，无论单次调用参数如何，都会在服务端移除绑定参数；LLM 无法重新启用。绑定值可能包含个人身份信息（PII）时，请使用此设置。

多个 Collector

官方发布版本提供一个 .mcpb bundle（一键安装，仅支持单个 Collector）以及独立的 fat jar。.mcpb 只能定义一个 MCP 服务和一组凭据，因此无法同时注册两个 Collector。若需连接多个 Collector（它们通常在整套连接配置上有所不同，包括主机/端口以及用户名/密码），请直接使用 jar，并为每个 Collector 添加一个条目：

1. 从 GitHub Release 下载 scouter-mcp-<version>-all.jar。
2. 在客户端配置（.mcp.json / claude_desktop_config.json）中为每个 Collector 添加一个 mcpServers 条目，所有条目都指向同一个 jar，但分别使用各自的 env 配置。这样可以隔离每组凭据：

{
  "mcpServers": {
    "scouter-prod": {
      "command": "java",
      "args": ["-jar", "/ABSOLUTE/PATH/scouter-mcp-<version>-all.jar"],
      "env": {
        "SCOUTER_COLLECTOR_HOST": "prod-collector", "SCOUTER_COLLECTOR_PORT": "6100",
        "SCOUTER_USER": "prod-user", "SCOUTER_PASSWORD": "***", "SCOUTER_TZ": "Asia/Seoul"
      }
    },
    "scouter-stg": {
      "command": "java",
      "args": ["-jar", "/ABSOLUTE/PATH/scouter-mcp-<version>-all.jar"],
      "env": {
        "SCOUTER_COLLECTOR_HOST": "stg-collector", "SCOUTER_COLLECTOR_PORT": "6100",
        "SCOUTER_USER": "stg-user", "SCOUTER_PASSWORD": "***", "SCOUTER_TZ": "Asia/Seoul"
      }
    }
  }
}

随后由 AI 协调多个 Collector 之间的操作。

工具（14）

名称	用途	关键输入
list_objects	列出对象／Agent	objType?、nameLike?（不区分大小写）
search_xlog	搜索 XLog（延迟／错误）	from、to、objNameLike?、objHash?、service?、login?、ip?、desc?、minElapsedMs?、onlyError?、limit?（默认值为 20，最大值为 200）
get_service_summary	按服务汇总（数量／平均值／最大值／p95／错误率），最多 50 项	from、to，以及与 search_xlog 相同的筛选条件
get_summary	Collector 每日预聚合统计（排名前 50 的 SQL／服务／错误等，无需扫描）	category（service/sql/apiCall/ip/userAgent/error/alert）、from、to（最多 31 天）、objType?、objNameLike?、objHash?
get_xlog_detail	XLog 详情（SQL／绑定参数）	txid、date?／at?、includeBindParams?（默认值为 true）
get_xlog_by_gxid	分布式事务组	gxid、date?／at?
get_counter	计数器时间序列（同一天，完整分辨率）	objNameLike|objHashes|objType、counter、from、to
get_counter_stat	长时间范围的计数器统计（5 分钟分辨率，最多 31 天）	objNameLike|objHashes|objType、counter、from、to
list_counters	列出某个 objType 可用的计数器	objType
list_alerts	Collector 过去的警报	from、to、level?、object?、key?、limit?
get_active_services	当前运行的服务	objNameLike|objType|objHash
list_threads	JVM 线程列表（状态直方图 + 按 CPU 排名前 50）	objNameLike|objHash（最多 5 个存活实例）
get_thread_detail	活跃事务的实时线程（堆栈／锁持有者／当前 SQL）	txid（必填，且事务必须活跃）、id?、objNameLike|objHash
get_object_env	Agent JVM 系统属性（机密信息已屏蔽）	objNameLike|objHash、keyLike?

模糊定位（objNameLike）

用户会输入应用名称片段（“shop-order-api”），但实际的 objName 中包含 k8s Pod 名称 （/shop-order-api-deployment-5f4b8c7d9-abcde/shop-order-api1），因此 objHash 会在每次部署时变化， 而一个应用可能跨多个实例。objNameLike 可解决此问题：系统会将不区分大小写的片段解析为所有匹配的实例（优先选择存活实例，最多 20 个），并在这些实例上进行查询——始终无需 objHash。对于 XLog 搜索／汇总，解析时还会合并 Collector 的每日对象数据库，因此在查询时间范围内因部署而被替换的 Pod 也能找到。如果没有匹配项，错误会返回 NOT_FOUND，并附带 candidates 提示，列出实际的 objName，方便调用方一步修正查询。

不严谨的服务查询

Scouter 服务名称的形式类似 /api/order/.../search-order-info-grade<POST>，但用户可能会输入 “GET orderDetail”或“order info grade”。service 筛选条件会规范化此类输入：无论 HTTP 方法出现在任何位置（GET x、x POST、粘贴的 <POST>），都会将其提取出来；以空格分隔的词会在服务端回退为最长的词；显式的 * 模式则会原样传递。服务端匹配仍区分大小写，因此当模式没有匹配项时，系统会在同一时间范围内重新扫描（有范围限制），不应用 service 筛选条件，并将与查询词不区分大小写匹配的实际服务名称作为 serviceCandidates 返回，按流量排序。只需重试一次并使用精确名称即可找到结果。

默认情况下，service／login／ip／desc 使用子字符串匹配（服务端的 StrMatch），因此像 search-order-info-grade 这样的短词也能匹配 /api/order/ext/order-info/search-order-info-grade<POST>。 objNameLike／login／ip／desc 会被视为服务端筛选条件，因此可放宽未筛选时间范围的 5 分钟上限。list_counters 也接受 objNameLike 并据此推导 objType，因此用户无需了解 Scouter 的类型分类。

所有工具都会标记为 readOnlyHint。diagnose_root_cause MCP 提示词会提供延迟／错误调查的推荐工具顺序。

资源 / 令牌安全策略

生产环境中的 Scouter 在 5 分钟内可能产生数十万个 XLog，因此 search_xlog 会强制执行防护措施（参见 scouter.mcp.policy.Limits）：

• 流式传输期间，达到 limit 或扫描上限（检查 5,000 个数据包）后即停止并关闭套接字，这也会停止 Collector 的扫描 / 传输，从而同时限制服务器负载、网络流量和 MCP 堆内存使用。
• 未设置 service 或 objHash 筛选条件时，仅允许查询最长 5 分钟的时间窗口；绝对时间窗口上限为 24 小时。
• limit 默认为 20，上限为 200。结果中包含 truncated/scanCapReached 和 hint，以便调用方缩小筛选范围，而不是重新获取数据。
• get_service_summary 不保留任何行（仅保留每个服务的计数器），因此使用较高的扫描上限（200,000），以低成本覆盖更宽的时间窗口；它也会报告 scanCapReached/examined。
• get_counter 将每个 objType 的扇出限制为 20 个实例，并使用保留峰值 / 谷值的最小值 / 最大值方案对较长的序列进行降采样（摘要中的 min/max/avg 根据完整序列计算）。
• 跨越午夜的时间窗口会按日历日拆分（collector 按天划分 XLog/计数器 / 告警），因此边界两侧的数据都不会丢失。
• 响应文本预算：SQL 文本最多 1,500 个字符，错误消息最多 500 个字符，线程堆栈跟踪最多 4,000 个字符，环境变量值最多 500 个字符——每项都会附带标明原始长度的截断标记。get_xlog_detail 的 profile 步骤上限为 150，并通过 totalSteps/stepsTruncated 标示。
• 单次请求最多可触发 40 次 Collector 往返（实例数 x 日期片段数）。当客户端筛选条件（minElapsedMs/onlyError）丢弃超过 99% 的已扫描行时，低选择性提示会引导模型改用服务端筛选条件或 get_summary。
• get_summary/get_counter_stat 读取 Collector 每日预聚合的数据（不进行扫描），时间跨度上限为 31 天；摘要会返回每个类别中排名前 50 的行。list_threads 最多处理 5 个存活实例，每个实例最多返回 50 行线程数据（状态直方图始终涵盖所有线程）。
• 每个请求的遥测数据（passes/examined/kept/tookMs）会以结构化的 key=value 行记录到 stderr，供事后分析负载。

国际化

只有动态的、面向用户的输出（工具错误消息、结果提示、说明）会通过 messages.properties / messages_ko.properties 本地化为英语和韩语。静态架构 / 工具描述以及结构化 stderr 日志（key=value）仍使用英语，以保持契约稳定并便于解析日志。

安全说明

• 对 Collector 仅提供只读访问（不公开写入命令）。
• 凭据仅通过环境变量注入（绝不会以明文形式写入文件或作为参数传递）。建议使用遵循最小权限原则的只读 Scouter 账号。
• 传输使用明文 TCP（Scouter 协议不支持 TLS）：SHA-256 密码摘要、会话令牌以及所有 XLog/计数器数据都会以未加密形式通过网络传输。仅在受信任的网络内运行，或通过 SSH/VPN 隧道传输。请勿将 Collector 端口暴露在公共互联网中。
• get_xlog_detail 绑定参数可能包含个人身份信息（PII）。设置 SCOUTER_INCLUDE_BIND_PARAMS=false，即可在服务端移除这些参数（LLM 无法重新启用它们）。请参阅上方的环境变量表。get_thread_detail 的实时绑定值（SQLActiveBindVar）遵循相同的禁用开关。
• get_object_env 始终会屏蔽键名匹配 password/secret/token/credential/private 的值；这是服务端策略，LLM 无法选择退出。
• stdout 专用于 JSON-RPC，因此所有日志只会写入 stderr。

许可证 / 声明

scouter.mcp.client 包移植自 Scouter v2.20.0 客户端代码（Apache License 2.0）。 详情请参阅 NOTICE。

已知限制

1. search_xlog/get_service_summary 的 minElapsedMs/onlyError/limit 由客户端应用，因为 Collector 没有对应的原生参数。truncated=true 是一种启发式判断（返回数量 == limit），可能出现误报。
2. 会话过期（INVALID_SESSION）时，客户端会重新登录一次并重试请求；若再次失败，则返回 SCOUTER_AUTH_FAILED（不会无限重试）。上游每隔 2 秒刷新的时间差守护进程尚未移植，因此长时间运行的进程在实时相对查询中可能会出现轻微偏差。绝对纪元时间（历史）查询不受影响。
3. list_alerts/get_active_services 移植自上游协议，并通过烟雾测试（SmokeIT）在 Collector 上进行了验证；字段覆盖范围可能因 Collector 版本而异。