Fix: Three blocking defects found by the MCP tool survey
The survey in docs/Mcp_Test_Report_2026-10-29.md turned up three P0s, each
of which stopped a whole capability rather than degrading it. Two of them
were the same mistake: the input schema promised something the output
schema then rejected. The third was an output with no size limit, plus a
client that never implemented the command at all.
Batch calls could never succeed. A call carrying ids[] goes through
BuildBatchCall, which returns {tool, total, succeeded, failed, skipped,
results[]}; every tool declares only the single-host shape. The client
validates structuredContent against that declaration, so any batch call
failed with -32602: data must have required property 'host' - the input
schema advertises ids, the output schema kills it. Tools/call cannot fix
this one call at a time, so ApplyBatchOutputSchema runs at the end of
tools/list, next to ApplyToolAnnotations, and rewrites the schema of every
tool in the batch list to {type: object, anyOf: [single, batch]}. Placing
it at the end is what makes it cover all three registration points
(inline, McpMachine, McpChat) and any tool added later. IsBatchReadOnlyTool
moved from McpServer.cpp to McpInternal.cpp for the same reason: the list
is now read by tools/call and tools/list, and the two must not drift.
list_registry failed whenever path was omitted. The root-key branch
returns keys only, while the output schema listed values in required as
well, so the first usage the documentation describes - omit path, get the
five root keys - could not work. values is no longer required and the
schema says it is absent in that branch. The root branch also returns
path: "" now, so both branches carry the same field set and callers need
not branch.
get_client_log was unusable on both platforms, for two unrelated reasons.
Windows returned the whole 1000-line ring buffer, 90,473 characters, over
the client's result limit: fetched, then not deliverable. Linux and macOS
timed out because their clients never handled COMMAND_QUERY_LOG at all -
only client/ClientLogManager.cpp does - so TOKEN_REPORT_LOG never arrived.
Adding a limit alone would have left Linux broken; fixing the client alone
would have left Windows over the limit.
The server now takes limit (default 200, max 2000) and filter, and reads
backwards from the end: troubleshooting wants the last thing that happened,
not the first line after boot. A 64 KB byte budget sits under the line
count, because one line can be a stack dump; when the final line alone
exceeds it, the tail is returned and truncated says so. Responses carry
lines_total, lines_matched, lines_returned and truncated. The timeout
message now names the likely cause and two ways around it instead of
saying only "Timeout waiting for client log".
The POSIX clients get common/ClientLogHandler.h, a counterpart to the
Windows CClientLogManager, and one line each in linux/main.cpp and
macos/main.mm. It must open a sub-connection: MessageHandle's
TOKEN_REPORT_LOG branch takes the first packet and then calls CancelIO on
that connection, so answering on the main connection would close the main
connection and drop the client offline.
Verified against a server built at 21:17:21 with both clients rebuilt. A
batch get_host_detail over the two A6 records returns succeeded=2 with
per-host data; host_list_processes with ids returns 2 of 2, which exercises
the McpMachine registration point rather than the inline one; a mixed
Windows/Linux batch of get_client_log returns 2 of 2. list_registry with
no path returns the five root keys and path ""; with a path it still
returns its values. get_client_log on Windows goes from 1000 lines to 200
with truncated=true, and limit=3 with filter=ConnAuth yields 28 matched and
3 returned. On Ubuntu 24.04 it returns logs at all, and the client's own
log shows Enter ClientLogThread, TOKEN_REPORT_LOG, then Leave about a
second later when the server cancels the connection - paired, no leak.
The connector still caches an old input schema for get_client_log, so
limit and filter are rejected locally until it reconnects; the defaults
already cover the P0, and this is the same cache problem as the
copy_files_c2c.overwrite entry in the report's P1 list.
docs/Mcp_Design.md section 18 records the implementation and the reasoning;
section 7 of the test report carries the verification table.
Co-Authored-By: deepseek-flash
This commit is contained in:
1 parent
dc4fd792f6
commit
56a937fabb
8 files changed
+796
-21
No files matched your search
+158
-21
@@ -770,6 +770,9 @@ std::string BuildRegistryRoots(const Json::Value& id) {
|
||||
|
||||
Json::Value result(Json::objectValue);
|
||||
Json::Value structuredContent(Json::objectValue);
|
||||
// path 恒为 "":根键这一层没有路径,但补上它能让「列根键」与「列子键」返回同一组
|
||||
// 字段(path/keys,子键那次多一个 values),调用方不必按分支判断。
|
||||
structuredContent["path"] = "";
|
||||
structuredContent["keys"] = keys;
|
||||
result["structuredContent"] = structuredContent;
|
||||
|
||||
@@ -1484,6 +1487,7 @@ Json::Value BuildListRegistryOutputSchema() {
|
||||
|
||||
Json::Value valsProp(Json::objectValue);
|
||||
valsProp["type"] = "array";
|
||||
valsProp["description"] = u8"该键下的值;path 为空(列根键)时不返回本字段";
|
||||
Json::Value valItems(Json::objectValue);
|
||||
valItems["type"] = "object";
|
||||
Json::Value valProps(Json::objectValue);
|
||||
@@ -1500,9 +1504,11 @@ Json::Value BuildListRegistryOutputSchema() {
|
||||
Json::Value schema(Json::objectValue);
|
||||
schema["type"] = "object";
|
||||
schema["properties"] = props;
|
||||
// 只把 keys 标成必填。values 在「列根键」分支里不存在(根键下没有值),
|
||||
// 早先把它一并 required,导致文档描述的第一种用法(省略 path)必然被
|
||||
// 客户端判为不符合 outputSchema(-32602: data must have required property 'values')。
|
||||
Json::Value required(Json::arrayValue);
|
||||
required.append("keys");
|
||||
required.append("values");
|
||||
schema["required"] = required;
|
||||
return schema;
|
||||
}
|
||||
@@ -1560,14 +1566,62 @@ Json::Value BuildExecCommandOutputSchema() {
|
||||
return schema;
|
||||
}
|
||||
|
||||
// get_client_log 的 outputSchema(原始日志文本)
|
||||
// get_client_log 的 inputSchema:{ id } + limit / filter(+ ids 批量)
|
||||
//
|
||||
// 不加 limit 时,一次快照是客户端 ring buffer 的全量(最多 1000 行、实测 90 KB),
|
||||
// 单条工具结果直接超出客户端上限——取到了却塞不下,等于取不到。默认只回末尾
|
||||
// 200 行:故障排查看的是最后发生了什么,不是开机时的第一行。
|
||||
Json::Value BuildClientLogInputSchema() {
|
||||
Json::Value props(Json::objectValue);
|
||||
|
||||
Json::Value idProp(Json::objectValue);
|
||||
idProp["type"] = "string";
|
||||
idProp["description"] = u8"主机 id,取 list_online_hosts / search_hosts 返回的 id 字段;与 ids 二选一";
|
||||
props["id"] = idProp;
|
||||
|
||||
Json::Value limitProp(Json::objectValue);
|
||||
limitProp["type"] = "integer";
|
||||
limitProp["description"] = u8"最多返回末尾多少行,默认 200,上限 2000;返回的是最近的日志,不是开头的";
|
||||
props["limit"] = limitProp;
|
||||
|
||||
Json::Value filterProp(Json::objectValue);
|
||||
filterProp["type"] = "string";
|
||||
filterProp["description"] = u8"只看包含该子串的行(ASCII 不区分大小写,如 error / TIMEOUT);过滤后再取末尾 limit 行";
|
||||
props["filter"] = filterProp;
|
||||
|
||||
AppendBatchIdsProp(props);
|
||||
|
||||
Json::Value schema(Json::objectValue);
|
||||
schema["type"] = "object";
|
||||
schema["properties"] = props;
|
||||
MakeIdOrIdsRequired(schema);
|
||||
return schema;
|
||||
}
|
||||
|
||||
// get_client_log 的 outputSchema(日志文本 + 行数统计)
|
||||
Json::Value BuildClientLogOutputSchema() {
|
||||
Json::Value props(Json::objectValue);
|
||||
|
||||
Json::Value logProp(Json::objectValue);
|
||||
logProp["type"] = "string";
|
||||
logProp["description"] = u8"日志文本(按行,\\n 分隔);已按 limit/filter 裁剪";
|
||||
props["log"] = logProp;
|
||||
|
||||
auto intProp = [](const char* desc) {
|
||||
Json::Value p(Json::objectValue);
|
||||
p["type"] = "integer";
|
||||
p["description"] = desc;
|
||||
return p;
|
||||
};
|
||||
props["lines_total"] = intProp(u8"客户端快照的总行数");
|
||||
props["lines_matched"] = intProp(u8"filter 命中后的行数(无 filter 时等于 lines_total)");
|
||||
props["lines_returned"] = intProp(u8"本次实际返回的行数");
|
||||
|
||||
Json::Value truncProp(Json::objectValue);
|
||||
truncProp["type"] = "boolean";
|
||||
truncProp["description"] = u8"true 表示命中行数多于本次返回,log 只是末尾一段";
|
||||
props["truncated"] = truncProp;
|
||||
|
||||
Json::Value schema(Json::objectValue);
|
||||
schema["type"] = "object";
|
||||
schema["properties"] = props;
|
||||
@@ -1987,9 +2041,9 @@ std::string BuildToolsListResult(const Json::Value& id) {
|
||||
{
|
||||
Json::Value tool(Json::objectValue);
|
||||
tool["name"] = "get_client_log";
|
||||
tool["description"] = u8"获取指定在线主机 YAMA 客户端的内存运行日志(最近最多 1000 条,含时间戳/源文件/行号)。客户端持续增量上报,本工具取当前时刻的全量快照后即断开。只读。";
|
||||
tool["description"] = u8"获取指定在线主机 YAMA 客户端的内存运行日志(客户端 ring buffer,最多 1000 行,含时间戳/源文件/行号)。客户端持续增量上报,本工具取当前时刻的快照后即断开。默认只返回末尾 200 行(故障排查看的是最后发生了什么);可用 limit 调整(上限 2000)、filter 只保留包含某子串的行。返回里的 lines_total / lines_matched / lines_returned / truncated 说明裁剪情况。只读。";
|
||||
|
||||
tool["inputSchema"] = BuildGetHostDetailInputSchema(); // 复用 { id } 必填 schema
|
||||
tool["inputSchema"] = BuildClientLogInputSchema();
|
||||
tool["outputSchema"] = BuildClientLogOutputSchema();
|
||||
|
||||
tools.append(tool);
|
||||
@@ -2448,6 +2502,12 @@ std::string BuildToolsListResult(const Json::Value& id) {
|
||||
// 以后新增工具只需在 McpInternal.cpp 的 kToolHints 表里登记一行。
|
||||
ApplyToolAnnotations(tools);
|
||||
|
||||
// 22) 批量只读工具补第二个 outputSchema 分支(N2):批量结果的形状是
|
||||
// { tool, total, ..., results[] },与单机形状不同;只声明单机形状会让
|
||||
// 任何 ids 调用在客户端校验 structuredContent 时以 -32602 失败。
|
||||
// 同样放在最后一步,三个注册点一视同仁。
|
||||
ApplyBatchOutputSchema(tools);
|
||||
|
||||
result["tools"] = tools;
|
||||
return BuildResult(id, result);
|
||||
}
|
||||
@@ -3639,7 +3699,11 @@ std::string BuildGetClientLog(const Json::Value& id, const Json::Value& args, CM
|
||||
|
||||
std::vector<BYTE> data;
|
||||
if (!mcp.WaitPending(devId, data, mcp.ToolTimeoutMs()))
|
||||
return BuildError(id, -32001, "Timeout waiting for client log");
|
||||
return BuildError(id, -32001,
|
||||
u8"Timeout waiting for client log. 客户端在超时内没有回传日志:常见原因是该客户端"
|
||||
u8"版本尚未实现日志上报(Linux/MAC 需 2026-10-30 之后的客户端),也可能是子连接"
|
||||
u8"建立失败。可先用 get_host_detail 看 capabilities,或改用 download_file 直接取"
|
||||
u8"客户端日志文件。");
|
||||
|
||||
// data[0]=token,其后为 Logger 内存 ring buffer 的日志文本(无 '\0' 终止)。
|
||||
// 客户端在子连接建立时 m_sentIdx=0 返回全量,随后每 3s 推增量;MessageHandle 在
|
||||
@@ -3654,16 +3718,100 @@ std::string BuildGetClientLog(const Json::Value& id, const Json::Value& args, CM
|
||||
log = ToUtf8(raw.c_str(), cp);
|
||||
}
|
||||
|
||||
// 行级裁剪:客户端快照是全量(最多 1000 行、实测 90 KB),直接整段塞进结果会超出
|
||||
// 客户端的工具结果上限。默认只回末尾 200 行——排障关心的是最后发生了什么。
|
||||
int limit = 200;
|
||||
if (args.isMember("limit") && args["limit"].isInt())
|
||||
limit = args["limit"].asInt();
|
||||
if (limit <= 0) limit = 200;
|
||||
if (limit > 2000) limit = 2000;
|
||||
const std::string filter = GetStringArg(args, "filter");
|
||||
|
||||
std::vector<std::string> lines;
|
||||
{
|
||||
size_t b = 0;
|
||||
while (b < log.size()) {
|
||||
size_t e = log.find('\n', b);
|
||||
std::string one = (e == std::string::npos) ? log.substr(b) : log.substr(b, e - b);
|
||||
if (!one.empty() && one.back() == '\r') one.pop_back();
|
||||
lines.push_back(one);
|
||||
if (e == std::string::npos) break;
|
||||
b = e + 1;
|
||||
}
|
||||
}
|
||||
const int linesTotal = (int)lines.size();
|
||||
|
||||
std::vector<std::string> matched;
|
||||
matched.reserve(lines.size());
|
||||
for (const auto& one : lines) {
|
||||
if (filter.empty() || ContainsCI(one, filter))
|
||||
matched.push_back(one);
|
||||
}
|
||||
const int linesMatched = (int)matched.size();
|
||||
|
||||
// 从末尾往前取:同时受 limit 行数与 64 KB 字节预算约束(单行可能是超长的堆栈或
|
||||
// 报文转储,只按行数截断仍可能撑爆结果)。两个约束哪个先到就用哪个。
|
||||
const size_t kMaxBytes = 64 * 1024;
|
||||
std::string shown;
|
||||
int linesReturned = 0;
|
||||
bool contentTruncated = false;
|
||||
{
|
||||
size_t budget = kMaxBytes;
|
||||
size_t firstKept = (size_t)linesMatched; // 保留 [firstKept, linesMatched)
|
||||
while (firstKept > 0 && (int)((size_t)linesMatched - firstKept) < limit) {
|
||||
const size_t need = matched[firstKept - 1].size() + 1;
|
||||
if (need > budget) break;
|
||||
budget -= need;
|
||||
--firstKept;
|
||||
}
|
||||
|
||||
if (firstKept == (size_t)linesMatched && linesMatched > 0) {
|
||||
// 末尾一行自己就超过预算:至少回它的尾部(排障看的是最后发生了什么),
|
||||
// 而不是回空串让人以为客户端没有日志。
|
||||
const std::string& last = matched.back();
|
||||
if (last.size() > kMaxBytes) {
|
||||
shown = last.substr(last.size() - kMaxBytes);
|
||||
contentTruncated = true;
|
||||
} else {
|
||||
shown = last;
|
||||
}
|
||||
shown += '\n';
|
||||
linesReturned = 1;
|
||||
} else {
|
||||
for (size_t i = firstKept; i < (size_t)linesMatched; ++i) {
|
||||
shown += matched[i];
|
||||
shown += '\n';
|
||||
}
|
||||
linesReturned = linesMatched - (int)firstKept;
|
||||
}
|
||||
}
|
||||
|
||||
Json::Value result(Json::objectValue);
|
||||
Json::Value structuredContent(Json::objectValue);
|
||||
structuredContent["log"] = log;
|
||||
structuredContent["log"] = shown;
|
||||
structuredContent["lines_total"] = linesTotal;
|
||||
structuredContent["lines_matched"] = linesMatched;
|
||||
structuredContent["lines_returned"] = linesReturned;
|
||||
structuredContent["truncated"] = (linesMatched > linesReturned) || contentTruncated;
|
||||
result["structuredContent"] = structuredContent;
|
||||
|
||||
std::string text;
|
||||
if (linesTotal == 0) {
|
||||
text = u8"客户端暂无内存日志。";
|
||||
} else {
|
||||
text = std::string(u8"客户端运行日志:共 ") + std::to_string(linesTotal) + std::string(u8" 行");
|
||||
if (!filter.empty())
|
||||
text += std::string(u8",匹配 \"") + filter + std::string(u8"\" 的 ") + std::to_string(linesMatched) + std::string(u8" 行");
|
||||
text += std::string(u8",返回末尾 ") + std::to_string(linesReturned) + std::string(u8" 行");
|
||||
if (linesMatched > linesReturned || contentTruncated)
|
||||
text += std::string(u8"(还有更多,可调大 limit 或加 filter)");
|
||||
text += std::string(u8"。");
|
||||
}
|
||||
|
||||
Json::Value content(Json::arrayValue);
|
||||
Json::Value item(Json::objectValue);
|
||||
item["type"] = "text";
|
||||
item["text"] = log.empty() ? std::string(u8"客户端暂无内存日志。")
|
||||
: std::string(u8"客户端运行日志快照如下。");
|
||||
item["text"] = text;
|
||||
content.append(item);
|
||||
result["content"] = content;
|
||||
result["isError"] = false;
|
||||
@@ -8550,19 +8698,8 @@ static const size_t kBatchMaxIds = 50;
|
||||
// 所以真实上限约为 50s + 单机超时(20s)。要更紧就得把 deadline 一路传进各工具。
|
||||
static const long long kBatchDeadlineMs = 50000;
|
||||
|
||||
bool IsBatchReadOnlyTool(const std::string& t) {
|
||||
static const char* kReadOnly[] = {
|
||||
"get_host_detail", "list_processes", "list_windows", "list_services",
|
||||
"list_files", "list_registry", "get_client_log", "get_activity_history",
|
||||
"list_network_connections",
|
||||
"host_list_processes", "host_list_windows", "host_list_network_state",
|
||||
"host_list_software", "host_list_browser_history", "host_list_favorites",
|
||||
"host_list_win32_services", "host_list_driver_services",
|
||||
"host_list_scheduled_tasks", "host_get_hosts_file",
|
||||
};
|
||||
for (const char* x : kReadOnly) if (t == x) return true;
|
||||
return false;
|
||||
}
|
||||
// IsBatchReadOnlyTool 定义在 McpInternal.cpp:tools/list 要用它补 outputSchema,
|
||||
// tools/call 要用它做批量入口判定,两处必须共用同一份清单,故不再在此重复定义。
|
||||
|
||||
// 单主机分派:批量路径复用它,保证批量与单机走同一套实现。
|
||||
std::string DispatchSingleHostTool(const Json::Value& id, const std::string& toolName,
|
||||
|
||||
Reference in new issue
Block a user