New Windows clients append an optional 20-byte WINDOWINFO_MCP_DESKTOP block (virtual desktop rect, magic 'VDCP') after the window list, so the server can map window-relative coordinates into the capture frame. remote_mouse accepts an optional window_hwnd; x/y and drag x2/y2 are then normalized against the intersection of the window and the virtual desktop, which is exactly the source rect of get_screenshot mode=window. The target window must be foreground by default, and window_hwnd/expect_hwnd must agree when both are given. structuredContent gains coordinateWindow and resolved (frame coords plus the basis rect), so callers can verify the mapping. terminal_exec now allows pipes, && and || in PTY sessions (ConPTY on Windows, POSIX PTY on Linux) because the sentinel runs on its own line; legacy non-PTY sessions still reject & and |. A read-only PeekTermSession lets the server reject unsupported syntax before BeginTermCommand. POSIX still rejects bare background & (&&, &>, 2>&1 stay allowed). Docs: Mcp_Design.md sections 12.1/20.2/22 and Mcp_Terminal_Design.md 4.4/4.6 are synchronized with the protocol, the new validation order, and the basis rect semantics. Co-Authored-By: deepseek-flash
208 lines
11 KiB
C++
208 lines
11 KiB
C++
#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>
|
||
#include <vector>
|
||
|
||
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);
|
||
|
||
// ===== 窗口信息 RPC(CLIENT_CAP_WINDOW_INFO)=====
|
||
|
||
// 一条窗口记录(WINDOWINFO_MCP 的解码结果;标题已转 UTF-8)。
|
||
struct WindowEntry {
|
||
uint32_t hwnd = 0;
|
||
uint32_t pid = 0;
|
||
int32_t left = 0;
|
||
int32_t top = 0;
|
||
int32_t right = 0;
|
||
int32_t bottom = 0;
|
||
uint32_t flags = 0; // WINDOWINFO_*
|
||
int32_t zorder = -1; // 0 = 最顶层
|
||
std::string title; // UTF-8
|
||
};
|
||
|
||
// WindowEntry → 输出 JSON(hwnd/pid/title/left/top/right/bottom/width/height/visible/
|
||
// minimized/maximized/isForeground/zOrder)。机器管理与远程控制共用同一字段口径。
|
||
Json::Value WindowEntryToJson(const WindowEntry& e);
|
||
|
||
// 窗口信息响应尾块里的虚拟桌面矩形(WINDOWINFO_MCP_DESKTOP 的解码结果)。
|
||
// valid=false 表示客户端是老版本、没带这个尾块。
|
||
struct WindowDesktopRect {
|
||
int32_t left = 0;
|
||
int32_t top = 0;
|
||
int32_t width = 0;
|
||
int32_t height = 0;
|
||
bool valid = false;
|
||
};
|
||
|
||
// 下发 COMMAND_MCP_WINDOW_INFO(主连接 RPC,不建子连接、不弹框),解析 TOKEN_MCP_WINDOW_INFO。
|
||
// timeoutMs <= 0 时取 McpServer().ToolTimeoutMs()。out 按客户端的 z 序返回。
|
||
// desktop(可选):新客户端的虚拟桌面矩形;老客户端保持 valid=false。
|
||
// 返回:0=ok;1=设备忙;2=发送失败/超时;3=响应畸形;4=客户端未声明 CLIENT_CAP_WINDOW_INFO。
|
||
// truncated(可选):true 表示客户端还有更多可见窗口没装进这个包(单包上限 96 条)。
|
||
int FetchWindowInfo(context* ctx, uint64_t devId, const char* tool, int timeoutMs,
|
||
std::vector<WindowEntry>& out, std::string& errMsg,
|
||
bool* truncated = nullptr, WindowDesktopRect* desktop = nullptr);
|
||
|
||
// 客户端是否为 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);
|
||
|
||
// ===== 批量只读调用(ids[])=====
|
||
//
|
||
// 支持批量的只读工具清单(写操作一律不支持,避免一次误操作波及多台主机)。
|
||
// 清单同时被两处使用:tools/call 的入口判定,以及 tools/list 的 outputSchema 补丁。
|
||
bool IsBatchReadOnlyTool(const std::string& toolName);
|
||
|
||
// 给 tools/list 里的批量只读工具补第二个 outputSchema 分支。
|
||
//
|
||
// 单机调用返回工具自己的字段(如 host / processes / entries),批量调用返回
|
||
// { tool, total, succeeded, failed, skipped, results[] }——两者形状完全不同。
|
||
// 只声明单机形状会让任何 ids 调用在客户端校验 structuredContent 时直接失败
|
||
// (实测 -32602: data must have required property 'host'),而 inputSchema 又
|
||
// 明确写着「支持 ids 批量」,等于把批量能力整条封死。这里统一改成 anyOf 两支。
|
||
void ApplyBatchOutputSchema(Json::Value& tools);
|
||
|
||
// ===== 工具注解(A3)=====
|
||
//
|
||
// 给 tools/list 里的每个工具补 MCP annotations(readOnlyHint / destructiveHint /
|
||
// idempotentHint / openWorldHint),让 MCP 客户端能按语义分组审批、默认折叠只读工具。
|
||
// 名称未在注解表里的工具按 schema 规范的默认值处理(destructiveHint=true),
|
||
// 即「新增工具必须显式登记」,漏登记只会更保守,不会误标成只读。
|
||
void ApplyToolAnnotations(Json::Value& tools);
|
||
|
||
} // namespace McpInternal
|