vantage-peers-mcp 2.4.2 → 2.4.6

package/README.md

@@ -9,6 +9,8 @@ MCP server for [VantagePeers](https://vantagepeers.com) — shared memory, messa
 
 84 tools across 18 categories: memory, profiles, tasks, missions, mission templates, messages, diary, briefing notes, search (RAG), issues, fix patterns, error monitoring, deployments, business units, components, mandates, recurring tasks, and session. All tools ship with ChatGPT Apps SDK annotations (`readOnlyHint`, `openWorldHint`, `destructiveHint`) for native UX in ChatGPT custom connectors.
 
+**Companion plugin — 32 skills (target v2.7.0):** the `vantage-peers` Claude Code plugin wraps these 84 tools with 32 high-level skills split across three phases — Phase A (11 skills, v2.5.0): `dispatch-message`, `dispatch-task-create`, `dispatch-task-complete`, `dispatch-task-start`, `dispatch-subagent`, `identity-set`, `mission-bootstrap`, `check-messages` v5.1, `check-tasks` v2, `daily-start` v3, `close-day` v2 — Phase B (10 skills, v2.6.0): `memory-write`, `briefing-write`, `mission-template-apply`, `task-structure`, `component-register`, `component-discover`, `issue-triage`, `fix-pattern-cycle`, `episode-log`, `recall-deep` — Phase C (11 skills, v2.7.0): `briefing-recall`, `repo-link`, `recurring-schedule`, `deploy-track`, `profile-lookup`, `peers-discovery`, `mandate-lifecycle`, `bu-manage`, `messages-history`, `memory-edit`, `diary-discover`.
+
 ## Quick start
 
 ```bash
@@ -400,6 +402,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
 // ─────────────────────────────────────────────────────────────────────────────
 /**
@@ -815,6 +865,9 @@ export function registerTools(server, convex, oauthCtx) {
         type: memoryTypeSchema
             .optional()
             .describe("Filter to a specific type — omit to return all types"),
+        createdBy: assigneeSchema
+            .optional()
+            .describe("Filter by creator/orchestrator role — mirrors list_tasks pattern for cross-tool consistency."),
         limit: z
             .number()
             .int()
@@ -828,7 +881,7 @@ export function registerTools(server, convex, oauthCtx) {
         openWorldHint: false,
         destructiveHint: false,
         title: "List memories",
-    }, async ({ namespace, type, limit }) => {
+    }, async ({ namespace, type, createdBy, limit }) => {
         try {
             const nsDenied = guardRead(namespace);
             if (nsDenied)
@@ -836,6 +889,7 @@ export function registerTools(server, convex, oauthCtx) {
             const memories = await convex.query("memories:listMemories", {
                 namespace,
                 type,
+                createdBy,
                 limit: limit ?? 20,
             });
             const rawList = Array.isArray(memories)
@@ -843,7 +897,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 +1190,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 +1230,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 +1273,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 +1410,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 +1796,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 +1906,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)
@@ -2083,6 +2137,9 @@ export function registerTools(server, convex, oauthCtx) {
         orchestrator: creatorSchema
             .optional()
             .describe("Filter to a specific orchestrator — omit for all"),
+        createdBy: assigneeSchema
+            .optional()
+            .describe("Filter by creator/orchestrator role — alias of `orchestrator` for cross-tool consistency (mirrors list_tasks pattern). If both are passed, `createdBy` wins."),
         limit: z
             .number()
             .int()
@@ -2096,23 +2153,25 @@ export function registerTools(server, convex, oauthCtx) {
         openWorldHint: false,
         destructiveHint: false,
         title: "List diary entries",
-    }, async ({ orchestrator, limit }) => {
+    }, async ({ orchestrator, createdBy, limit }) => {
         try {
+            // createdBy is an alias of orchestrator (diary's author field). If both set, createdBy wins.
+            const effectiveOrchestrator = createdBy ?? orchestrator;
             // Non-master: must scope to own orchestrator id.
             if (oauthCtx && !isMasterScope(oauthCtx)) {
-                if (orchestrator !== oauthCtx.userId) {
+                if (effectiveOrchestrator !== oauthCtx.userId) {
                     return mcpError(`Forbidden: list_diaries requires orchestrator='${oauthCtx.userId}' for non-master scope (current: ${oauthCtx.scopeProfile}).`);
                 }
             }
             const entries = await convex.query("diary:list", {
-                orchestrator,
+                orchestrator: effectiveOrchestrator,
                 limit: limit ?? 20,
             });
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(entries, null, 2),
+                        text: capListResponseBytes(entries, JSON.stringify(entries, null, 2), "list_diaries"),
                     },
                 ],
             };
@@ -2266,7 +2325,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 +2444,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 +2666,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 +3016,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 +3226,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 +3321,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 +3421,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 +3782,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 +3790,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 +4077,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.6",
   "description": "MCP server for VantagePeers — shared memory, messaging, and task coordination for AI agent teams",
   "type": "module",
   "main": "./dist/server.js",