Files
SimpleRemoter/server/2015Remote/McpInternal.h
T
yuanyuanxianganddeepseek-flash 1c832ff7f2 Feature: Add MCP cancellation, progress notifications and dry runs
P11 closes the plan's last batch, entirely on the server side: no client
change is required for any of it.

Long-running tools now expose a cancellation flag that every wait loop
checks in 500 ms slices. A cancelled tool returns through the cleanup
branch it already had (late first packets still get absorbed, sub
connections still get closed, pending entries still get deleted), so
there is no second cleanup path to keep in sync, and the host is released
within a second. Three sources set the flag: notifications/cancelled
(matched on the exact JSON-RPC id, with a fallback to the display form so
a request_id copied out of the session list round-trips), mcp_cancel_session
(by request_id, host id or session id), and a failed SSE write when the
client has gone away. The dispatcher rewrites a cancel-induced failure to
-32800 so callers do not mistake it for a host fault.

tools/call requests carrying _meta.progressToken are answered as
text/event-stream on the same POST: the tool runs on its own thread and
both the notifications/progress events and the final JSON-RPC response go
out through one chunked provider. Requests without a token are unchanged.
download_file reports files done vs. expected, upload_file reports bytes
sent vs. total.

Two new local-only tools, mcp_list_sessions and mcp_cancel_session, list
and cancel in-flight sessions (calls, pending one-shots, terminal, remote
control, file transfer, chat). They are deliberately not gated by the
feature switches or readonly mode, since that is the only way out of a
stuck request. The -32003 busy message now names the occupier:
"Device busy: ... (tool=download_file, elapsed=12s)".

power_action gains wait/wait_ms to verify the result against the main
connection's presence (went_offline, came_back, elapsed_ms); not seeing
the transition is reported as ok, not as a failure. kill_process,
operate_window and the four host_control_* tools accept dry_run, which
validates the target against one fresh snapshot and returns what would be
affected without sending anything. Validation rejections now use -32012;
-32008 stays as documented historical alias.

One implementation note worth recording: the per-thread call context uses
FLS, not thread_local. Any static thread_local in this server crashes the
process about a second after start, because some threads come from
shellcode/MemoryModule images that never ran PE TLS initialisation.

Verified against a real Debug server and a real Windows client over MCP:
the smoke test now passes 104 checks with 0 failures, including
cancellation releasing the host in under a second, the cancelled request
returning -32800, notifications/cancelled returning 202, 63 progress
events with exact byte counts for a 64 MB upload, and a cleanly
terminated SSE stream. Not exercised in this pass: power_action's
wait=true path (it would take the test host down) and the -32006
readonly/switch-off section (every switch was on during the run).

Co-Authored-By: deepseek-flash
2026-10-28 21:25:49 +01:00

154 lines
7.8 KiB
C++
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#pragma once
// MCP 工具实现共享的内部辅助函数。
//
// 这些函数原先都定义在 McpServer.cpp 的匿名命名空间里;主机管理 / 连接管理
// 工具族(McpMachine.cpp)需要复用同一套 JSON、host id 解析与编码转换逻辑,
// 故抽出到独立编译单元,由 McpServer.cpp 与 McpMachine.cpp 共同引用。
//
// 约定:函数语义与实现与抽取前完全一致(McpServer.cpp 通过 using-directive
// 引入,调用点不变),不做行为改动。
#include <Windows.h>
#include "jsoncpp/json.h"
#include <string>
#include <cstdint>
class CMy2015RemoteDlg;
class context;
namespace McpInternal {
// ===== 错误码(-32000 系列,见 docs/Mcp_Design.md §12)=====
//
// -32012 参数被校验拒绝:参数内容非法、按 message 改正后重试即可(shell 元字符、
// 控制字符之类)。-32008 是同一语义的历史别名:早期实现用它,已发布的文档与客户端
// 可能仍在匹配,故保留不改;新代码一律用 -32012。
const int kErrValidation = -32012;
const int kErrValidationOld = -32008; // 历史别名,勿新增使用
// -32800 请求被客户端取消:收到 notifications/cancelled 或 mcp_cancel_session 后,
// 在飞的工具提前退出(走各自的超时清理路径),结果统一以这个码回报。
const int kErrCancelled = -32800;
// Json::Value → 紧凑 JSON 字符串
std::string JsonToString(const Json::Value& v);
// JSON-RPC 2.0 成功 / 错误响应
std::string BuildResult(const Json::Value& id, const Json::Value& result);
std::string BuildError(const Json::Value& id, int code, const std::string& msg);
// ===== 结果外露(content 文本块)=====
//
// MCP 规范(Tools > Structured Content)要求:返回 structuredContent 的工具,
// 应同时把序列化后的 JSON 放进一个 TextContent 块。有些客户端(如 WorkBuddy)
// 只把 content 交给模型、完全忽略 structuredContent——不补这一块,模型就拿不到
// id / session_id / pid 这类串联下一跳的关键字段,只能看到「共 N 台主机匹配」。
//
// 因此 BuildResult 默认给每个带非空 structuredContent 的结果追加一个文本块
// (紧凑 JSON)。工具的正文已经承载同一份载荷时,用 SetStructuredTextPayload
// 指定只外露哪部分,避免同一份内容在上下文里出现两三次:
//
// exec_command / terminal_exec → {"exit_code":N} (stdout 已在正文里)
// get_keylog → 行数/字节数等元数据(行已在正文里)
// get_activity_history → {"records":[…]}
// host_get_hosts_file → 去掉 content 的 sc (原文已在 lines 里)
void AppendStructuredText(Json::Value& result, const Json::Value& payload); // 内部用
void AppendStructuredText(Json::Value& result); // 内部用
// 本次结果只外露 payload(BuildResult 消费后移除,不出现在响应里)。
// payload 为空对象/空数组时本次不追加文本块。
void SetStructuredTextPayload(Json::Value& result, const Json::Value& payload);
// 仅 ASCII 小写化;不区分大小写的子串匹配
std::string ToLowerAscii(const std::string& s);
bool ContainsCI(const std::string& haystack, const std::string& needle);
// 入参读取
std::string JsonStrField(const Json::Value& v, const char* key);
bool IsDigits(const std::string& s);
std::string GetStringArg(const Json::Value& args, const char* key);
bool GetIntArg(const Json::Value& args, const char* key, int& out);
bool ReadUInt64(const Json::Value& v, uint64_t& out);
bool ReadUInt64Arg(const Json::Value& args, const char* key, uint64_t& out);
// 解析 id 入参(必填、纯数字)为 uint64;非法返回 false 并写 err。
bool ParseHostIdArg(const Json::Value& args, uint64_t& out, std::string& err);
// 在 m_HostList 中按 clientID 找在线主 context(锁内遍历 m_cs)。
context* FindMainContext(CMy2015RemoteDlg* parent, uint64_t id);
// 客户端是否为 Windows 形态(EXE/DLL/MEXE/SC/MDLL);LNX / MAC / APK 返回 false。
// 用于「只有 Windows 客户端实现了这个能力」的判断(注册表、窗口、服务等)。
bool IsWindowsClient(context* ctx);
// 有界 strlen:p 最多可读 avail 字节,返回 n < avail 表示遇到 '\0'。
size_t BoundedStrlen(const char* p, size_t avail);
// 编码转换:任意代码页 → UTF-8(输出 JSON 用);UTF-8 → 目标代码页(下发客户端用)。
std::string ToUtf8(const char* s, UINT cp);
std::string ToAnsi(const std::string& utf8, UINT cp);
// 严格 UTF-8 → 目标代码页:任一字符无法表示即失败(不用 '?' 顶替)。
// UTF-8 本身非法也失败。聊天消息用它拒绝 GBK 不可表示的字符(emoji 等)。
bool Utf8ToCpExact(const std::string& utf8, UINT cp, std::string& out);
// 校验字节串是否为合法 UTF-8(n=0 视为合法)。
bool IsValidUtf8(const char* s, size_t n);
// 写操作审计:PostMessageA(WM_SHOWERRORMSG) 落到服务端消息/审计日志(不可关闭)。
void AuditManageAction(CMy2015RemoteDlg* parent, uint64_t devId,
const std::string& tool, const std::string& detail);
// 远程交谈审计:与 AuditManageAction 同落地方式,标题区分(MCP远程交谈)。
// 只记录会话 id / 字节数,绝不记录消息正文。
void AuditChatAction(CMy2015RemoteDlg* parent, uint64_t devId,
const std::string& tool, const std::string& detail);
// ===== 列表输出治理 =====
//
// 列表类工具统一走 limit/offset:默认 limit=100,硬上限 1000,offset 默认 0。
// structuredContent 里同时给出 total/totalAll/offset/limit/hasMore,与
// McpMachine.cpp 的 host_list_*/list_network_connections 保持同一套字段,
// 调用方据此翻页,而不是让一次返回把上下文撑爆。
struct PageWindow {
int offset = 0;
int limit = 100;
int total = 0; // ApplyPageWindow 填入:切片前的总条数(本工具无二次过滤,故等于 totalAll)
int totalAll = 0;
int returned = 0; // 本次实际返回条数
bool hasMore = false; // 窗口之后还有条目(供调用方判断是否继续翻页)
};
// 读 args 里的 limit/offset(缺省/非法/非正数按默认值,limit 超上限截断到上限)。
PageWindow ResolvePageWindow(const Json::Value& args, int defaultLimit = 100, int maxLimit = 1000);
// 按窗口切片:out = all[offset, offset+limit),并回填 w.total/totalAll/returned/hasMore。
void ApplyPageWindow(const Json::Value& all, PageWindow& w, Json::Value& out);
// 把 total/totalAll/offset/limit/hasMore 写进 structuredContent。
void WritePageFields(Json::Value& structuredContent, const PageWindow& w);
// 往 inputSchema 的 properties 追加 limit / offset 两个字段。
void AppendPagingProps(Json::Value& props, int defaultLimit = 100, int maxLimit = 1000);
// 往 inputSchema 的 properties 追加 ids(只读工具的批量入口,最多 50 个 id)。
void AppendBatchIdsProp(Json::Value& props);
// 把 inputSchema 的必填约束改成「id 或 ids 二选一」。
void MakeIdOrIdsRequired(Json::Value& schema);
// 统一的提示文字,例如「共 283 个进程,本次返回第 1-100 条(还有更多,可用 offset 继续取)。」
std::string PageSummary(const PageWindow& w, const char* unit);
// ===== 工具注解(A3)=====
//
// 给 tools/list 里的每个工具补 MCP annotations(readOnlyHint / destructiveHint /
// idempotentHint / openWorldHint),让 MCP 客户端能按语义分组审批、默认折叠只读工具。
// 名称未在注解表里的工具按 schema 规范的默认值处理(destructiveHint=true),
// 即「新增工具必须显式登记」,漏登记只会更保守,不会误标成只读。
void ApplyToolAnnotations(Json::Value& tools);
} // namespace McpInternal