diff --git a/docs/Mcp_Go_Minimal_Design.md b/docs/Mcp_Go_Minimal_Design.md index fe20d90..116925e 100644 --- a/docs/Mcp_Go_Minimal_Design.md +++ b/docs/Mcp_Go_Minimal_Design.md @@ -246,6 +246,30 @@ M5 之前传任一参数都返回 `-32005` 并在 message 里点名。细节见 **整文件上限 2 MiB**(`YAMA_MCP_READ_MAX`):V2 下载没有区间参数,只能整文件拉,超过就拒绝 (`-32602`)。`offset`/`limit` 是下载后的窗口裁剪,绕不过这个门。 +### 3.3 文本块(`content[].text`) + +`structuredContent` 是权威数据,但部分 MCP 客户端只把 `content[].text` 交给模型, +`structuredContent` 不会出现在模型上下文里。因此列表类工具的文本块不能只有「共 N 台」 +这样的汇总——主机 64 位 id 是 `read_file`、`get_host_detail`、`terminal_exec` 等后续调用 +的寻址键,模型拿不到就等于工具不可用。 + +| 工具 | 汇总行之后 | +|---|---| +| `list_hosts` | 表头 `id name ip group os online clientType last_seen`,随后每台一行 | +| `get_host_detail` | 单台:主机 JSON(compact);批量:`id ok detail`,成功行是主机 JSON,失败行是错误信息 | +| `list_files` | 盘符 `drive typeName fileSystem totalMB freeMB`;目录 `name isDir size mtime` | +| `get_audit_log` | `time type msg`,`msg` 是去掉信封字段后的 compact JSON | + +列用制表符分隔,首列一定是后续调用的寻址键(主机 id / 文件名)。单元格内的制表符与换行 +替换成空格,精确值以 `structuredContent` 为准;空值显示 `-`。分页只渲染当前页,不会把 +全表塞进文本块。 + +MFC 端不需要同样的改动:`McpInternal.cpp` 的 `BuildResult` 会把整个 +`structuredContent` 作为**第二个** `type:"text"` 项追加到 `content`(除非 builder 用 +`SetStructuredTextPayload` 指定了更小的载荷)。实测线上 `list_hosts` / `get_audit_log` +的 `content[1]` 已是完整 JSON(含主机 id),文本型客户端本来就能拿到。Go 的 +`newToolResult` 只写一个 text 项,所以把行放进第一项。 + --- ## 4. 端点 diff --git a/server/go/mcp/filemgr.go b/server/go/mcp/filemgr.go index bdf2d7c..6492f33 100644 --- a/server/go/mcp/filemgr.go +++ b/server/go/mcp/filemgr.go @@ -6,6 +6,7 @@ import ( "encoding/json" "errors" "fmt" + "strconv" "strings" "sync" "time" @@ -580,6 +581,8 @@ func listFilesResult(args listFilesArgs, drives []driveEntry, files []fileEntry, var structured map[string]any var text string + var header []string + var rows [][]string if drives != nil { total := len(drives) begin := min(offset, total) @@ -593,6 +596,14 @@ func listFilesResult(args listFilesArgs, drives []driveEntry, files []fileEntry, "hasMore": end < total, } text = pageSummary(total, limit, offset, "个驱动器") + header = []string{"drive", "typeName", "fileSystem", "totalMB", "freeMB"} + rows = make([][]string, 0, end-begin) + for _, d := range drives[begin:end] { + rows = append(rows, []string{ + d.Drive, d.TypeName, d.FileSystem, + strconv.FormatUint(d.TotalMB, 10), strconv.FormatUint(d.FreeMB, 10), + }) + } } else { total := len(files) begin := min(offset, total) @@ -606,9 +617,18 @@ func listFilesResult(args listFilesArgs, drives []driveEntry, files []fileEntry, "hasMore": end < total, } text = pageSummary(total, limit, offset, "个条目") + header = []string{"name", "isDir", "size", "mtime"} + rows = make([][]string, 0, end-begin) + for _, f := range files[begin:end] { + rows = append(rows, []string{ + f.Name, strconv.FormatBool(f.IsDir), + strconv.FormatUint(f.Size, 10), strconv.FormatInt(f.Mtime, 10), + }) + } } if truncated { text += fmt.Sprintf("目录条目超过 %d 条,只解析了前 %d 条。", fileListMaxEntries, fileListMaxEntries) } + text = appendRows(text, header, rows) return newToolResult(text, structured) } diff --git a/server/go/mcp/filemgr_test.go b/server/go/mcp/filemgr_test.go index 3394f39..0bda610 100644 --- a/server/go/mcp/filemgr_test.go +++ b/server/go/mcp/filemgr_test.go @@ -304,6 +304,10 @@ func TestListFilesDrives(t *testing.T) { if !strings.Contains(c.res.Content[0].Text, "共 2 个驱动器") { t.Fatalf("summary = %q", c.res.Content[0].Text) } + if !strings.Contains(c.res.Content[0].Text, "drive\ttypeName\tfileSystem\ttotalMB\tfreeMB") || + !strings.Contains(c.res.Content[0].Text, "C:\\\t本地磁盘\tNTFS\t500000\t123456") { + t.Fatalf("text = %q, want drive rows", c.res.Content[0].Text) + } // A drive-only listing still leaves the sub-conn to be retired. if got := r.next(sub); !bytes.Equal(got, []byte{protocol.CommandBye}) { @@ -376,6 +380,15 @@ func TestListFilesDirectory(t *testing.T) { !strings.Contains(c.res.Content[0].Text, "第 2-3 条") { t.Fatalf("summary = %q", c.res.Content[0].Text) } + if !strings.Contains(c.res.Content[0].Text, "name\tisDir\tsize\tmtime") || + !strings.Contains(c.res.Content[0].Text, "a.txt\tfalse\t12345\t1700000000") || + !strings.Contains(c.res.Content[0].Text, "中文文档.docx\tfalse\t5368709120\t1600000000") { + t.Fatalf("text = %q, want file rows for the returned page", c.res.Content[0].Text) + } + // The page window (offset 1) applies to the table as well. + if strings.Contains(c.res.Content[0].Text, "子目录") { + t.Fatalf("text = %q, offset-skipped entry leaked into the table", c.res.Content[0].Text) + } if got := r.next(sub); !bytes.Equal(got, []byte{protocol.CommandBye}) { t.Fatalf("retire wire = %v, want COMMAND_BYE", got) @@ -713,6 +726,10 @@ func TestListFilesTruncationNote(t *testing.T) { if !strings.Contains(c.res.Content[0].Text, "只解析了前") { t.Fatalf("summary does not mention the cap: %q", c.res.Content[0].Text) } + // The note must stay on its own line, before the table. + if !strings.Contains(c.res.Content[0].Text, "。\nname\tisDir\tsize\tmtime\n") { + t.Fatalf("truncation note glued to the table: %q", c.res.Content[0].Text) + } } func TestParseFileListEntryCap(t *testing.T) { diff --git a/server/go/mcp/tools_local.go b/server/go/mcp/tools_local.go index 2d0177a..3fd1ee1 100644 --- a/server/go/mcp/tools_local.go +++ b/server/go/mcp/tools_local.go @@ -195,6 +195,7 @@ func (s *Server) callListHosts(_ context.Context, raw json.RawMessage) (any, *rp if total != totalAll { text += fmt.Sprintf("过滤前共 %d 台。", totalAll) } + text = appendHostRows(text, hosts) return newToolResult(text, structured), nil } @@ -298,7 +299,7 @@ func (s *Server) callGetHostDetail(_ context.Context, raw json.RawMessage) (any, if rerr != nil { return nil, rerr } - return newToolResult(hostSummary(host), map[string]any{"host": host}), nil + return newToolResult(hostDetailText(host), map[string]any{"host": host}), nil } func (s *Server) hostDetailBatch(ids []string) (any, *rpcError) { @@ -339,6 +340,7 @@ func (s *Server) hostDetailBatch(ids []string) (any, *rpcError) { } text := fmt.Sprintf("批量调用 get_host_detail:共 %d 台,成功 %d 台,失败 %d 台。", len(ids), succeeded, failed) + text = appendBatchRows(text, results) return newToolResult(text, structured), nil } @@ -416,6 +418,58 @@ func hostSummary(h map[string]any) string { return fmt.Sprintf("主机 %s (%s) 的详情。", name, ip) } +// hostDetailText is the text block for one host: the summary line followed by +// the host object as compact JSON. Text-only MCP clients never surface +// structuredContent, so without this they would see neither the id nor any +// field of the host they just asked about. +func hostDetailText(h map[string]any) string { + summary := hostSummary(h) + b, err := json.Marshal(h) + if err != nil { + return summary + } + return summary + "\n" + string(b) +} + +// appendHostRows renders the returned page as a tab-separated table. The host +// id comes first because every follow-up tool (read_file, get_host_detail, +// terminal_exec, ...) is addressed by it. +func appendHostRows(text string, hosts []map[string]any) string { + rows := make([][]string, 0, len(hosts)) + for _, h := range hosts { + online, _ := h["online"].(bool) + rows = append(rows, []string{ + tableText(h["id"]), tableText(h["name"]), tableText(h["ip"]), + tableText(h["group"]), tableText(h["os"]), strconv.FormatBool(online), + tableText(h["clientType"]), tableText(h["last_seen"]), + }) + } + return appendRows(text, + []string{"id", "name", "ip", "group", "os", "online", "clientType", "last_seen"}, + rows) +} + +// appendBatchRows lists each batch result on its own line: failures carry the +// error message, successes the full host JSON. +func appendBatchRows(text string, results []map[string]any) string { + rows := make([][]string, 0, len(results)) + for _, r := range results { + ok, _ := r["ok"].(bool) + var detail string + if ok { + if data, _ := r["data"].(map[string]any); data != nil { + if b, err := json.Marshal(data["host"]); err == nil { + detail = string(b) + } + } + } else { + detail, _ = r["text"].(string) + } + rows = append(rows, []string{tableText(r["id"]), strconv.FormatBool(ok), detail}) + } + return appendRows(text, []string{"id", "ok", "detail"}, rows) +} + // ----- get_server_status ---------------------------------------------------- func (s *Server) callGetServerStatus(_ context.Context, _ json.RawMessage) (any, *rpcError) { @@ -510,6 +564,11 @@ func (s *Server) callGetAuditLog(_ context.Context, raw json.RawMessage) (any, * if res.Truncated { text += "(审计文件较大,仅扫描最近 32 MB。)" } + rows := make([][]string, 0, len(entries)) + for _, e := range entries { + rows = append(rows, []string{tableText(e["time"]), tableText(e["type"]), tableText(e["msg"])}) + } + text = appendRows(text, []string{"time", "type", "msg"}, rows) return newToolResult(text, structured), nil } @@ -547,6 +606,46 @@ func clampPageLimit(n int) int { return n } +// appendRows appends a tab-separated table to a summary line. The first +// column is always the addressable key (host id, file name, ...), because a +// text-only client sees only content[].text and needs the key for the next +// call. structuredContent remains the authoritative, exact copy. +func appendRows(text string, header []string, rows [][]string) string { + if len(rows) == 0 { + return text + } + var b strings.Builder + b.WriteString(text) + b.WriteByte('\n') + b.WriteString(strings.Join(header, "\t")) + for _, row := range rows { + b.WriteByte('\n') + for i, cell := range row { + if i > 0 { + b.WriteByte('\t') + } + b.WriteString(oneLine(cell)) + } + } + return b.String() +} + +// tableText extracts a string field. An absent field yields "", which oneLine +// renders as "-". +func tableText(v any) string { + s, _ := v.(string) + return s +} + +// oneLine keeps a table cell on one line: a tab or newline inside a value +// would break the column layout. The exact value stays in structuredContent. +func oneLine(s string) string { + if s == "" { + return "-" + } + return strings.NewReplacer("\t", " ", "\r", " ", "\n", " ").Replace(s) +} + // pageSummary mirrors the Win32 server's summary line: // 「共 N 台主机,本次返回第 1-100 条(还有更多,可用 offset 继续取)。」 func pageSummary(total, limit, offset int, unit string) string { diff --git a/server/go/mcp/tools_local_test.go b/server/go/mcp/tools_local_test.go index cb6b701..ac5d9d7 100644 --- a/server/go/mcp/tools_local_test.go +++ b/server/go/mcp/tools_local_test.go @@ -201,6 +201,18 @@ func wantIDs(t *testing.T, hosts []map[string]any, want ...string) { } } +func TestAppendRowsSanitizesCells(t *testing.T) { + got := appendRows("head", []string{"a", "b"}, + [][]string{{"x\ty", "line\nbreak"}, {"", ""}}) + want := "head\na\tb\nx y\tline break\n-\t-" + if got != want { + t.Fatalf("appendRows = %q, want %q", got, want) + } + if got := appendRows("head", []string{"a"}, nil); got != "head" { + t.Fatalf("empty rows = %q, want unchanged summary", got) + } +} + func TestListHostsPoolsAndProjection(t *testing.T) { f := newLocalFixture(t) @@ -222,6 +234,14 @@ func TestListHostsPoolsAndProjection(t *testing.T) { if !strings.Contains(text, "共 3 台主机") { t.Fatalf("text = %q, want host count", text) } + // Text-only MCP clients never see structuredContent, so the table in the + // text block must carry the id every follow-up call is addressed by. + if !strings.Contains(text, "id\tname\tip\tgroup\tos\tonline\tclientType\tlast_seen") { + t.Fatalf("text = %q, want host table header", text) + } + if !strings.Contains(text, "1001\tALPHA\t10.0.0.1\tdefault\tWindows 10\ttrue\tEXE\t-") { + t.Fatalf("text = %q, want ALPHA row with id first", text) + } alpha := hosts[0] if got := strField(t, alpha, "name"); got != "ALPHA" { @@ -384,7 +404,11 @@ func TestListHostsPaging(t *testing.T) { func TestGetHostDetailOnlineAndOffline(t *testing.T) { f := newLocalFixture(t) - _, sc := mustCallLocal(t, f.srv, "get_host_detail", `{"id":"1001"}`) + text, sc := mustCallLocal(t, f.srv, "get_host_detail", `{"id":"1001"}`) + if !strings.Contains(text, "\n") || !strings.Contains(text, `"id":"1001"`) || + !strings.Contains(text, `"name":"ALPHA"`) { + t.Fatalf("text = %q, want summary plus host JSON", text) + } host, ok := sc["host"].(map[string]any) if !ok { t.Fatalf("host = %v", sc["host"]) @@ -457,7 +481,12 @@ func TestGetHostDetailOnlineAndOffline(t *testing.T) { func TestGetHostDetailBatch(t *testing.T) { f := newLocalFixture(t) - _, sc := mustCallLocal(t, f.srv, "get_host_detail", `{"ids":["1001","9999","2001"]}`) + text, sc := mustCallLocal(t, f.srv, "get_host_detail", `{"ids":["1001","9999","2001"]}`) + if !strings.Contains(text, "id\tok\tdetail") || + !strings.Contains(text, "1001\ttrue\t{") || + !strings.Contains(text, "9999\tfalse\t") { + t.Fatalf("text = %q, want one row per id", text) + } if got := strField(t, sc, "tool"); got != "get_host_detail" { t.Fatalf("tool = %q", got) } @@ -573,7 +602,11 @@ func TestGetAuditLog(t *testing.T) { ) s := New(Config{Token: "test-token", AuditPath: path}) - _, sc := mustCallLocal(t, s, "get_audit_log", `{}`) + text, sc := mustCallLocal(t, s, "get_audit_log", `{}`) + if !strings.Contains(text, "time\ttype\tmsg") || + !strings.Contains(text, "2026-11-12T10:03:00Z\tdevice.online\t") { + t.Fatalf("text = %q, want audit rows", text) + } entries, ok := sc["entries"].([]any) if !ok || len(entries) != 4 { t.Fatalf("entries = %v, want 4", sc["entries"])