vantage-peers-mcp 2.4.2 → 2.4.3

package/README.md

@@ -400,6 +400,9 @@ All orchestrator names are open strings — any lowercase name is accepted. The
 
 ## Changelog
 
+### 2.4.3 — 2026-05-31 (Day 89)
+- fix(overflow): defensive byte-cap on all 17 `list_*` tools — `capListResponseBytes` truncates any list response above 60 KB and wraps the result in a `_meta` envelope (`_truncated`, `_showing`, `_total`, `_advice`) so MCP clients (Claude.ai, ChatGPT, Claude Code) never reject a list result for exceeding their token budget. Day 89 Pi 75,003-char `list_tasks` overflow incident reproduced and capped in regression test. PR #565.
+
 ### 2.4.1 — 2026-05-30 (Day 88)
 - fix(dcr): `oauthDcr:validateAccessToken` exposed as PUBLIC `query` (was `internalQuery`, unreachable via `ConvexHttpClient.query()` → Path 3 DCR returned 401 even with valid token) — issue #556 / PR #557.
 - fix(dcr): `WWW-Authenticate` header now emits `Bearer resource_metadata="..."` per MCP spec §Protected Resource Metadata Discovery (was `resource="..."` — broke Claude.ai PRM discovery bootstrap on 401) — PR #557.

package/dist/src/tools.d.ts

@@ -21,6 +21,8 @@ export declare const MAX_CONTENT_BYTES = 900000;
  * @param toolName  Caller tool name (used only in the error message).
  */
 export declare function assertContentSize(content: string, toolName: string): number;
+export declare const MAX_LIST_RESPONSE_BYTES = 60000;
+export declare function capListResponseBytes(items: unknown, rawText: string, toolName: string, maxBytes?: number): string;
 /**
  * Convex document IDs are 32 lowercase alphanumeric characters (a-z0-9).
  * Exported so tests can validate the schema independently of the MCP server.

package/dist/src/tools.js

@@ -71,6 +71,56 @@ export function assertContentSize(content, toolName) {
     return contentBytes;
 }
 // ─────────────────────────────────────────────────────────────────────────────
+// List response byte cap (overflow protection for MCP clients)
+//
+// MCP clients (Claude.ai, ChatGPT, Claude Code) reject tool results that
+// exceed their token budget — typical ceiling ~25k tokens ≈ 75 KB JSON.
+// When that happens the entire response is lost to a downstream truncation
+// error and the user must fall back to reading the on-disk overflow file.
+//
+// `capListResponseBytes` guards every bulk list_* tool: if the serialized
+// payload exceeds MAX_LIST_RESPONSE_BYTES (60 KB), it truncates the items
+// array (halving until it fits) and wraps the result in a _meta envelope
+// that tells the caller exactly how to refine the query.
+//
+// 60 KB leaves headroom for tool-call JSON framing and the UI stream marker
+// before any MCP client hits its own ceiling. The cap is byte-counted on the
+// raw JSON string, not on item count, because content-heavy rows
+// (memories / diaries / briefing notes) blow past 30 items easily.
+// ─────────────────────────────────────────────────────────────────────────────
+export const MAX_LIST_RESPONSE_BYTES = 60_000;
+export function capListResponseBytes(items, rawText, toolName, maxBytes = MAX_LIST_RESPONSE_BYTES) {
+    const byteLen = Buffer.byteLength(rawText, "utf8");
+    if (byteLen <= maxBytes)
+        return rawText;
+    if (!Array.isArray(items) || items.length === 0)
+        return rawText;
+    let n = items.length;
+    let truncated = items;
+    let truncatedText = rawText;
+    while (n > 1) {
+        n = Math.max(1, Math.floor(n / 2));
+        truncated = items.slice(0, n);
+        truncatedText = JSON.stringify(truncated, null, 2);
+        if (Buffer.byteLength(truncatedText, "utf8") <= maxBytes - 600)
+            break;
+    }
+    const envelope = {
+        _meta: {
+            _truncated: true,
+            _showing: truncated.length,
+            _total: items.length,
+            _bytesOriginal: byteLen,
+            _bytesCap: maxBytes,
+            _tool: toolName,
+            _advice: `Response exceeded ${maxBytes} bytes. Showing first ${truncated.length}/${items.length}. ` +
+                `Pass fields="lite", a smaller limit, stricter filters (status, assignedTo, project, namespace, updatedSince), or paginate.`,
+        },
+        items: truncated,
+    };
+    return JSON.stringify(envelope, null, 2);
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // Shared Zod schemas
 // ─────────────────────────────────────────────────────────────────────────────
 /**
@@ -843,7 +893,7 @@ export function registerTools(server, convex, oauthCtx) {
                 : Array.isArray(memories?.page)
                     ? memories.page
                     : [];
-            const baseText = JSON.stringify(memories, null, 2);
+            const baseText = capListResponseBytes(memories, JSON.stringify(memories, null, 2), "list_memories");
             const text = appendMarkerIfEnabled(baseText, () => ({
                 kind: "memory-quote",
                 items: rawList.map((m) => ({
@@ -1136,7 +1186,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(peers, null, 2),
+                        text: capListResponseBytes(peers, JSON.stringify(peers, null, 2), "list_peers"),
                     },
                 ],
             };
@@ -1176,7 +1226,7 @@ export function registerTools(server, convex, oauthCtx) {
                 from,
                 limit: limit ?? 100,
             });
-            const baseText = JSON.stringify(messages, null, 2);
+            const baseText = capListResponseBytes(messages, JSON.stringify(messages, null, 2), "list_messages");
             const text = appendMarkerIfEnabled(baseText, () => ({
                 kind: "messages-feed",
                 items: Array.isArray(messages)
@@ -1219,7 +1269,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(status, null, 2),
+                        text: capListResponseBytes(status, JSON.stringify(status, null, 2), "list_broadcast_status"),
                     },
                 ],
             };
@@ -1356,7 +1406,7 @@ export function registerTools(server, convex, oauthCtx) {
                 createdBy,
                 updatedSince,
             });
-            const baseText = JSON.stringify(tasks, null, 2);
+            const baseText = capListResponseBytes(tasks, JSON.stringify(tasks, null, 2), "list_tasks");
             const text = appendMarkerIfEnabled(baseText, () => ({
                 kind: "tasks-table",
                 items: Array.isArray(tasks)
@@ -1742,7 +1792,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(tasks, null, 2),
+                        text: capListResponseBytes(tasks, JSON.stringify(tasks, null, 2), "list_tasks_by_mission"),
                     },
                 ],
             };
@@ -1852,7 +1902,7 @@ export function registerTools(server, convex, oauthCtx) {
                 fields,
                 updatedSince,
             });
-            const baseText = JSON.stringify(missions, null, 2);
+            const baseText = capListResponseBytes(missions, JSON.stringify(missions, null, 2), "list_missions");
             const text = appendMarkerIfEnabled(baseText, () => ({
                 kind: "mission-timeline",
                 items: Array.isArray(missions)
@@ -2112,7 +2162,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(entries, null, 2),
+                        text: capListResponseBytes(entries, JSON.stringify(entries, null, 2), "list_diaries"),
                     },
                 ],
             };
@@ -2266,7 +2316,7 @@ export function registerTools(server, convex, oauthCtx) {
                 fields,
                 updatedSince,
             });
-            const baseText = JSON.stringify(notes, null, 2);
+            const baseText = capListResponseBytes(notes, JSON.stringify(notes, null, 2), "list_briefing_notes");
             const text = appendMarkerIfEnabled(baseText, () => {
                 const items = Array.isArray(notes) ? notes : [];
                 if (items.length === 0)
@@ -2385,7 +2435,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(components, null, 2),
+                        text: capListResponseBytes(components, JSON.stringify(components, null, 2), "list_components"),
                     },
                 ],
             };
@@ -2607,7 +2657,7 @@ export function registerTools(server, convex, oauthCtx) {
                 limit: limit ?? 50,
             });
             return {
-                content: [{ type: "text", text: JSON.stringify(tasks, null, 2) }],
+                content: [{ type: "text", text: capListResponseBytes(tasks, JSON.stringify(tasks, null, 2), "list_recurring_tasks") }],
             };
         }
         catch (error) {
@@ -2957,7 +3007,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(mandates, null, 2),
+                        text: capListResponseBytes(mandates, JSON.stringify(mandates, null, 2), "list_mandates"),
                     },
                 ],
             };
@@ -3167,7 +3217,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(bus, null, 2),
+                        text: capListResponseBytes(bus, JSON.stringify(bus, null, 2), "list_bus"),
                     },
                 ],
             };
@@ -3262,7 +3312,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(mappings, null, 2),
+                        text: capListResponseBytes(mappings, JSON.stringify(mappings, null, 2), "list_repo_mappings"),
                     },
                 ],
             };
@@ -3362,7 +3412,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ count: results.length, issues: results }, null, 2),
+                        text: capListResponseBytes(results, JSON.stringify({ count: results.length, issues: results }, null, 2), "list_issues"),
                     },
                 ],
             };
@@ -3723,7 +3773,7 @@ export function registerTools(server, convex, oauthCtx) {
                     limit,
                 });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+                    content: [{ type: "text", text: capListResponseBytes(results, JSON.stringify(results, null, 2), "list_fix_patterns") }],
                 };
             }
             const allResults = await convex.query("fixPatterns:listAll", {
@@ -3731,7 +3781,7 @@ export function registerTools(server, convex, oauthCtx) {
             });
             return {
                 content: [
-                    { type: "text", text: JSON.stringify(allResults, null, 2) },
+                    { type: "text", text: capListResponseBytes(allResults, JSON.stringify(allResults, null, 2), "list_fix_patterns") },
                 ],
             };
         }
@@ -4018,7 +4068,7 @@ export function registerTools(server, convex, oauthCtx) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(errors, null, 2),
+                        text: capListResponseBytes(errors, JSON.stringify(errors, null, 2), "list_errors"),
                     },
                 ],
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vantage-peers-mcp",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "MCP server for VantagePeers — shared memory, messaging, and task coordination for AI agent teams",
   "type": "module",
   "main": "./dist/server.js",