troubleshoot-binlog-mcp

排查 Binlog MCP 启动问题

说明插件的 binlog MCP 服务无法连接的原因，并给出有证据依据且符合安全策略的恢复方案。此处排查的是服务启动，而非构建中记录的故障。 无需 binlog 文件或项目构建。

此技能按需运行。它无法查看未向 Agent 暴露的主机错误，无法注入会话启动上下文，也无法保证仅因安装了插件就会激活。

1. 确定故障原因

使用用户提供的错误，以及当前可用的任何主机 MCP 状态或启动日志。 CONNECTION_CLOSED 仅说明传输已关闭，并未说明原因。不要直接将其解读为“缺少程序包”。

• 如果 binlog 服务已连接且可发现其工具，请停止排查启动问题。 继续原始 binlog 分析；不要更改正常工作的配置。
• 如果插件技能已加载，但其 binlog 服务未加载，请继续执行下文步骤。
• 如果插件本身未安装或未启用，或者未注册任何服务，请先处理主机配置。未尝试启动前，不要排查 NuGet 程序包解析问题。
• 如果无法获取执行记录或主机日志，请说明这一限制，并提供下一条由用户运行的命令。绝不要声称自己检查过日志或修复了连接。

2. 匹配主机工作区和 SDK

从可用配置中查明受影响的工作区目录，以及主机实际使用的 MCP 命令、参数和环境。 随附的命令为：

dotnet dnx Microsoft.AITools.BinlogMcp --yes --prerelease

使用主机环境在该工作区中运行诊断，而不是在插件目录或 NuGet 设置不同的临时目录中运行。检查：

dotnet --info
dotnet --version
dotnet nuget list source

检查适用的 global.json 和继承的 NuGet 配置，包括父级/用户配置、clear、已禁用的源以及 packageSourceMapping。工作区中的 clear 可能会用缺少此程序包的私有镜像替换默认的 nuget.org 源。 已安装的 SDK 不一定是此目录中选用的 SDK。随附的 dotnet dnx 命令需要 .NET 10+ SDK。

不要在回答中泄露凭据设置、私有源 URL、令牌或凭据提供程序输出。根据需要在本地检查，并报告经过脱敏的源标签和相关错误。

3. 捕获实际启动错误

优先使用发生故障的宿主已有的启动日志。否则，从受影响的工作区执行一次未更改的启动命令，并捕获标准输出、标准错误和退出代码。最初不要添加 --source、替换配置、移除 global.json、清除缓存或安装另一个副本：这些操作会改变诊断条件。

stdio MCP 服务可能会保持运行，等待协议输入。观察启动情况时，请保持 stdin 打开，并使用有时限的执行（例如 30 秒），且只清理诊断进程树，包括凭据提供程序的子进程。使用宿主支持的超时／取消机制；如果无法安全清理，请让用户在本地运行命令。不要让后台服务继续运行，也不要终止无关的 dotnet 进程。超时、无输出或进程仍在运行，都不能证明 MCP 已初始化。

只有在包是否可用仍不明确时，才在相同的工作区设置下运行以下辅助探测，并设置执行时限：

dotnet package search Microsoft.AITools.BinlogMcp --exact-match --prerelease --format json

检查 searchResult[].packages 中的确切包 ID 和版本，并检查顶层及各来源的 problems。仅凭退出代码为零，不能证明搜索成功。

观察到的证据	诊断和下一步
dnx 报告配置的软件源中没有匹配的版本	这些设置未能解析该包。检查获准的镜像是否提供此确切包的预发布版本。
搜索未返回任何包，也没有来源问题	只有已搜索的软件源没有列出匹配项。这不能证明 dnx 一定会失败：缓存中的工具或未列出的版本仍可能可用。
搜索出现顶层／来源问题、HTTP 401/403、TLS、网络或凭据提供程序错误	可用性尚未验证，不能据此认定“缺少包”。先解决具体的软件源／访问故障，即使搜索以零退出也一样。
搜索找到了包，但 dnx 失败	根据启动错误继续排查。搜索不会应用包源映射；请检查映射、还原／下载访问权限和运行时要求。不要宣称连接正常。
缺少 dotnet、无法识别 dnx，或 SDK 选择错误	修复宿主的 PATH／SDK 选择。考虑 global.json；不要悄悄升级存储库或移除其 SDK 固定版本。
超时、不支持搜索命令，或输出格式错误／非 JSON	报告探测结果不确定。使用启动日志或让用户运行诊断；不要推断包不存在或搜索成功。
启动成功，但宿主连接仍失败	调查宿主实际使用的命令／环境和 MCP 初始化日志；此时，已证明的问题不再是包发现。

一旦证据足以确定下一步，就不要重复运行耗时的探测。

4. 选择符合策略的恢复方案

根据观察到的故障，建议最小的变更：

• 请源的所有者将 Microsoft.AITools.BinlogMcp 及其所需版本和依赖项镜像到获批源，或修正排除该包的获批映射。
• 如果观察到的问题是获批源的身份验证、连接或证书配置，请修复相应配置。切勿建议禁用证书验证。
• 仅在组织策略允许且用户批准变更时，才添加 nuget.org。不要移除 clear、禁用源映射或覆盖源来绕过企业策略。
• 如果合适且获得批准，请从获批源安装该工具，并向宿主注册其 binlog-mcp 可执行文件，将其作为替代 MCP 服务。确认可执行文件的路径，并避免注册重复的服务。仅安装并不能恢复连接。
• 对于 SDK/PATH 问题，请确保宿主可以使用所需的 SDK，或采用经过明确配置的替代启动方式。更改仓库的 SDK 选择前，请先征求批准。

未经用户批准，不要编辑 NuGet 设置、宿主注册或 SDK 固定版本。 如果策略阻止恢复，请如实说明。对于现有的 binlog，请提供 binlog-failure-analysis 中的文本日志回放备用方案，不要因修复 MCP 而阻碍构建诊断。

5. 验证并报告

获批变更后，使用宿主支持的控件重新连接/重启服务。 确认 MCP 初始化成功，且工具列表中包含 binlog_overview 等 binlog 工具。如果有 binlog，请继续原始分析。

报告观察到的原因（或仍未知的部分）、相关的脱敏证据、最小恢复措施，以及实际验证的内容。最后以一行状态结束：

MCP status: connected

仅当宿主发现该服务的工具后，才使用 connected；观察到启动/连接故障时使用 failed；仅有探测结果或建议时使用 unverified。 切勿用“找到包”或“工具已安装”替代经验证的 MCP 连接。