vantage-peers-mcp 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## [2.8.0] — 2026-06-14 — Day 101 CRUD baseline PR-A: search_memories_by_keyword + search_memories_by_semantic (mission k575kc1ryps0n8br95jw3q7d0x88m2v9, task k1735qk9kx6agjjyt3e38rdvvh88mk0p)
+
+Mission `mcp-crud-baseline-standard` PR-A under T2 `[CRUD-T2] Implémentation gaps VP MCP`. First of 4 sub-PRs aligning the MCP surface with the Day 101 doctrine `j57dhrmkzjerjtssnr0z9ba57n88n7q7` ("5 ops per entity: get / list / search_by_keyword / search_by_semantic / create-or-upsert"). PR-A handles the convention drift on the `memories` entity — the only entity that already had both keyword + semantic search wired, but under non-canonical names.
+
+### Added (canonical names)
+
+- **`search_memories_by_keyword`** — BM25 full-text search over memories, identical wire to `text_search`. Calls `search:textSearch` Convex action 1:1, same params (`query`, `namespace?`, `type?`, `limit?`, `fields?`), same `guardRead` namespace gate, same 20-item default limit + 200 cap, same `mcpConvexError` error surface (2.7.1 sweep). Annotations: `readOnlyHint=true`, `openWorldHint=false`, `destructiveHint=false`, title `"Search memories by keyword (BM25)"`.
+- **`search_memories_by_semantic`** — semantic vector cosine search over memories, identical wire to `recall`. Calls `search:recall` Convex action 1:1, same params, same gate, same defaults. Annotations: `readOnlyHint=true`, `openWorldHint=false`, `destructiveHint=false`, title `"Search memories by semantic (vector cosine)"`.
+
+### Deprecated (alias-only, one minor window)
+
+- **`text_search`** — alias of `search_memories_by_keyword`. Description now leads with `DEPRECATED ALIAS`, source comment marks it for removal in `2.9.0`. Wire unchanged — existing callers continue to work for one minor.
+- **`recall`** — alias of `search_memories_by_semantic`. Description now leads with `DEPRECATED ALIAS`, source comment marks it for removal in `2.9.0`. Wire unchanged.
+
+### Why
+
+Per mission `k575kc1r` brief + Pi arbitrage `jn77rpx2msfy2v174sdqyjzp6n88m9bw` Q4 (RENAME CLEAN, optional one-minor dual-emit buffer if Sigma judges useful): the legacy `text_search` / `recall` pair predates the Day 101 CRUD baseline naming convention. Other entities will gain `search_<entity>s_by_keyword` / `search_<entity>s_by_semantic` in PR-C (cluster of 13) and PR-D (vectorIndex add for briefing_notes + diary). Aligning the `memories` entity FIRST means PR-C/D ship into a fleet that already understands the new naming, and skill / plugin / docs propagation (T-SKILLS, T-PLUGIN, T-DOC) has a single canonical truth to follow.
+
+`hybrid_search` is intentionally NOT renamed — it remains a cross-cutting RRF-fusion tool, not entity-scoped, per the audit `analysis/mcp-crud-baseline-vp-audit-2026-06-14.md` § 4.
+
+### Refs
+
+- Mission `k575kc1ryps0n8br95jw3q7d0x88m2v9` (MCP CRUD Baseline Standard, pilot Sigma + agents Sigma + Eta).
+- Task T2 `k1735qk9kx6agjjyt3e38rdvvh88mk0p`.
+- Audit T1 deliverable: `analysis/mcp-crud-baseline-vp-audit-2026-06-14.md` (140 lines, 53 table rows).
+- Doctrine memory: `j57dhrmkzjerjtssnr0z9ba57n88n7q7` (5 ops per entity).
+- Pi Q4 arbitrage: msg `jn77rpx2msfy2v174sdqyjzp6n88m9bw`.
+
+## [2.7.1] — 2026-06-14 — Day 101 FIX-B mcpError() → mcpConvexError() sweep (task k1744wk2gfgqt2gdqh41d4r91h88n410)
+
+Patch-level fix to make every tool wrapper surface structured ConvexError
+diagnostics instead of opaque `"Server Error [Request ID: ...]"` strings.
+
+**Problem (Day 101):** when a Convex mutation/query threw a `ConvexError`
+(e.g. `TASK_START_BLOCKED`, `COMPLETION_NOTE_REQUIRED`) or an
+`ArgumentValidationError`, the tool wrapper called
+`mcpError(error.message ?? String(error))` which returned a plain
+`Error: <message>` text payload. The MCP client (Claude Code) then often
+re-displayed this as a generic `Server Error [Request ID:...]`, masking the
+actual root cause and triggering misdiagnosis sprees (Pi msg
+`jn7c5tfj0347vaenyqgrezehk188mr11` mistakenly attributed the symptoms to
+a backend regression that did not exist — see Sigma report msg
+`jn773p8qnfp6ycb1f7gajhs8vn88m11a`).
+
+**Fix:** sweep all 99 occurrences of
+`return mcpError(error.message ?? String(error))` →
+`return mcpConvexError(error)`. The `mcpConvexError` helper (already
+present at `src/tools.ts:535`, shipped 2.4.x) parses ConvexError messages
+into a structured JSON `{ code, message, path, hint }` payload that
+surfaces the actual error code (`ArgumentValidationError`,
+`ConvexError`, `AuthorizationError`, `SchemaValidationError`, etc.)
+along with a path and a concise hint for ID-table mismatches.
+
+Total counts post-sweep: `grep mcpConvexError(` → 102 ; `grep
+mcpError(error.message` → 0.
+
+Type check: `npx tsc --noEmit` exits 0.
+
+Mission/refs: `k575kc1ryps0n8br95jw3q7d0x88m2v9` MCP CRUD Baseline Standard,
+task FIX-B `k1744wk2gfgqt2gdqh41d4r91h88n410`. Co-shipped with hook
+`enforce-friction-field.py` v1.1.0 STDERR clarification (Day 101 task
+FIX-A `k17ads7kh7qk7yxgfe0dh73ggx88ny9f`).
+
 ## [2.7.0] — 2026-06-13 — Day 100 get_by_id surface Phase 2b (task k172735brsw6bc3j2dkkkfxqrx88kkjq)
 
 Phase 2b wires 2 MCP wrappers calling the Phase 2a Convex queries deployed

package/README.md

@@ -242,7 +242,7 @@ Example:
 ### Session (1)
 `set_summary`
 
-## Compact payloads and status aliases (v2.3.0)
+## Compact payloads and status aliases (v2.8.0 — feature since v2.3.0)
 
 ### `fields=lite` — reduced token payloads
 

package/dist/server.js

@@ -102,7 +102,7 @@ const convexUrl = loadConvexUrl();
 const convex = new ConvexHttpClient(convexUrl);
 const server = new McpServer({
     name: "vantage-peers",
-    version: "2.5.0",
+    version: "2.8.0",
 });
 // ─────────────────────────────────────────────────────────────────────────────
 // Helper: structured error response for MCP tool handlers

package/dist/src/tools.js

@@ -849,7 +849,7 @@ export function registerTools(server, convex, oauthCtx) {
                 createdBy,
                 errorMessage: error?.message ?? String(error),
             });
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── soft_delete_memory ──────────────────────────────────────────────────────
@@ -882,7 +882,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_memory ──────────────────────────────────────────────────────────────
@@ -912,12 +912,15 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── recall ──────────────────────────────────────────────────────────────────
-    server.tool("recall", "Semantic vector search over VantagePeers memories, ranked by cosine similarity. " +
-        "WHEN: use at session start or before decisions — prefer over text_search for intent-based queries. " +
+    // DEPRECATED (Day 101 v2.8.0) — alias of search_memories_by_semantic. Retained
+    // for one minor version as a back-compat shim. New callers should use
+    // `search_memories_by_semantic`. To be removed in 2.9.0.
+    server.tool("recall", "DEPRECATED ALIAS of search_memories_by_semantic — semantic vector search over VantagePeers memories, ranked by cosine similarity. " +
+        "WHEN: use at session start or before decisions — prefer over text_search for intent-based queries. New callers: use search_memories_by_semantic. " +
         "EXAMPLE: recall query='Pi feedback rules' namespace='global' type='feedback' limit=20.", {
         query: z
             .string()
@@ -967,12 +970,15 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── text_search ─────────────────────────────────────────────────────────────
-    server.tool("text_search", "BM25 full-text keyword search over VantagePeers memories for exact term matching. " +
-        "WHEN: use when recall returns too-broad results and you need a specific exact phrase or ID. " +
+    // DEPRECATED (Day 101 v2.8.0) — alias of search_memories_by_keyword. Retained
+    // for one minor version as a back-compat shim. New callers should use
+    // `search_memories_by_keyword`. To be removed in 2.9.0.
+    server.tool("text_search", "DEPRECATED ALIAS of search_memories_by_keyword — BM25 full-text keyword search over VantagePeers memories for exact term matching. " +
+        "WHEN: use when search_memories_by_semantic returns too-broad results and you need a specific exact phrase or ID. New callers: use search_memories_by_keyword. " +
         "EXAMPLE: text_search query='Day 92 C3 descriptions' namespace='project/vantage-peers' limit=10.", {
         query: z.string().describe("Search query text"),
         namespace: z
@@ -1013,7 +1019,114 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
+        }
+    });
+    // ── search_memories_by_keyword ─────────────────────────────────────────────
+    // Day 101 v2.8.0 — canonical name under MCP CRUD baseline doctrine.
+    // Mirrors text_search 1:1 (same Convex action `search:textSearch`).
+    // text_search is retained as a deprecated alias until 2.9.0.
+    server.tool("search_memories_by_keyword", "BM25 full-text keyword search over VantagePeers memories for exact term matching. " +
+        "WHEN: use when search_memories_by_semantic returns too-broad results and you need a specific exact phrase or ID. " +
+        "EXAMPLE: search_memories_by_keyword query='Day 92 C3 descriptions' namespace='project/vantage-peers' limit=10.", {
+        query: z.string().describe("Search query text"),
+        namespace: z
+            .string()
+            .optional()
+            .describe("Namespace filter (e.g. 'global', 'project/my-project')"),
+        type: memoryTypeSchema.optional().describe("Filter by memory type"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Search memories by keyword (BM25)",
+    }, async ({ query, namespace, type, limit, fields }) => {
+        try {
+            const nsDenied = guardRead(namespace);
+            if (nsDenied)
+                return nsDenied;
+            const results = await convex.action("search:textSearch", {
+                query,
+                namespace,
+                type,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+            };
+        }
+        catch (error) {
+            return mcpConvexError(error);
+        }
+    });
+    // ── search_memories_by_semantic ────────────────────────────────────────────
+    // Day 101 v2.8.0 — canonical name under MCP CRUD baseline doctrine.
+    // Mirrors recall 1:1 (same Convex action `search:recall`).
+    // recall is retained as a deprecated alias until 2.9.0.
+    server.tool("search_memories_by_semantic", "Semantic vector search over VantagePeers memories, ranked by cosine similarity. " +
+        "WHEN: use at session start or before decisions — prefer over search_memories_by_keyword for intent-based queries. " +
+        "EXAMPLE: search_memories_by_semantic query='Pi feedback rules' namespace='global' type='feedback' limit=20.", {
+        query: z
+            .string()
+            .describe("Natural language query to search for relevant memories"),
+        namespace: z
+            .string()
+            .optional()
+            .describe("Filter to a specific namespace — omit to search all"),
+        type: memoryTypeSchema
+            .optional()
+            .describe("Filter to a specific memory type — omit to search all"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Search memories by semantic (vector cosine)",
+    }, async ({ query, namespace, type, limit, fields }) => {
+        try {
+            const nsDenied = guardRead(namespace);
+            if (nsDenied)
+                return nsDenied;
+            const results = await convex.action("search:recall", {
+                query,
+                namespace,
+                type,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(results, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return mcpConvexError(error);
         }
     });
     // ── hybrid_search ───────────────────────────────────────────────────────────
@@ -1070,7 +1183,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── store_episode ───────────────────────────────────────────────────────────
@@ -1124,7 +1237,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_profile ─────────────────────────────────────────────────────────────
@@ -1157,7 +1270,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_profile ──────────────────────────────────────────────────────────
@@ -1215,7 +1328,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_memories ───────────────────────────────────────────────────────────
@@ -1316,7 +1429,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── send_message ────────────────────────────────────────────────────────────
@@ -1394,7 +1507,7 @@ export function registerTools(server, convex, oauthCtx) {
                 channel,
                 errorMessage: error?.message ?? String(error),
             });
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── check_messages ──────────────────────────────────────────────────────────
@@ -1473,7 +1586,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── mark_as_read ────────────────────────────────────────────────────────────
@@ -1519,7 +1632,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── delete_message ──────────────────────────────────────────────────────────
@@ -1558,7 +1671,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── set_summary ─────────────────────────────────────────────────────────────
@@ -1597,7 +1710,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_peers ──────────────────────────────────────────────────────────────
@@ -1683,7 +1796,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_messages ───────────────────────────────────────────────────────────
@@ -1774,7 +1887,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_broadcast_status ───────────────────────────────────────────────────
@@ -1826,7 +1939,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── create_task ─────────────────────────────────────────────────────────────
@@ -1903,7 +2016,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_tasks ──────────────────────────────────────────────────────────────
@@ -2014,7 +2127,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_task ─────────────────────────────────────────────────────────────
@@ -2099,7 +2212,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── complete_task ───────────────────────────────────────────────────────────
@@ -2140,7 +2253,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── start_task ──────────────────────────────────────────────────────────────
@@ -2177,7 +2290,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── checkout_task ───────────────────────────────────────────────────────────
@@ -2215,7 +2328,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── delete_task ─────────────────────────────────────────────────────────────
@@ -2252,7 +2365,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── block_task ──────────────────────────────────────────────────────────────
@@ -2301,7 +2414,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── add_task_dependency ─────────────────────────────────────────────────────
@@ -2346,7 +2459,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_tasks_by_mission ───────────────────────────────────────────────────
@@ -2429,7 +2542,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── create_mission ──────────────────────────────────────────────────────────
@@ -2490,7 +2603,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_missions ───────────────────────────────────────────────────────────
@@ -2588,7 +2701,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_mission ─────────────────────────────────────────────────────────────
@@ -2618,7 +2731,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_mission ──────────────────────────────────────────────────────────
@@ -2675,7 +2788,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_mission_status ───────────────────────────────────────────────────
@@ -2710,7 +2823,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── write_diary ─────────────────────────────────────────────────────────────
@@ -2766,7 +2879,7 @@ export function registerTools(server, convex, oauthCtx) {
                 orchestrator,
                 errorMessage: error?.message ?? String(error),
             });
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_diary ───────────────────────────────────────────────────────────────
@@ -2809,7 +2922,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_diaries ────────────────────────────────────────────────────────────
@@ -2902,7 +3015,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── create_briefing_note ────────────────────────────────────────────────────
@@ -3041,7 +3154,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_briefing_notes ─────────────────────────────────────────────────────
@@ -3140,7 +3253,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── register_component ──────────────────────────────────────────────────────
@@ -3202,7 +3315,7 @@ export function registerTools(server, convex, oauthCtx) {
                 createdBy,
                 errorMessage: error?.message ?? String(error),
             });
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_components ─────────────────────────────────────────────────────────
@@ -3280,7 +3393,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_component ───────────────────────────────────────────────────────────
@@ -3312,7 +3425,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_component ────────────────────────────────────────────────────────
@@ -3361,7 +3474,7 @@ export function registerTools(server, convex, oauthCtx) {
                 componentId,
                 errorMessage: error?.message ?? String(error),
             });
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── delete_component ────────────────────────────────────────────────────────
@@ -3390,7 +3503,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── search_components ───────────────────────────────────────────────────────
@@ -3441,7 +3554,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── create_recurring_task ───────────────────────────────────────────────────
@@ -3500,7 +3613,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_recurring_tasks ────────────────────────────────────────────────────
@@ -3573,7 +3686,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── pause_recurring_task ────────────────────────────────────────────────────
@@ -3600,7 +3713,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── resume_recurring_task ───────────────────────────────────────────────────
@@ -3627,7 +3740,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── delete_recurring_task ───────────────────────────────────────────────────
@@ -3654,7 +3767,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_recurring_task ───────────────────────────────────────────────────
@@ -3700,7 +3813,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── create_mandate ──────────────────────────────────────────────────────────
@@ -3759,7 +3872,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── accept_mandate ──────────────────────────────────────────────────────────
@@ -3794,7 +3907,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_mandate ──────────────────────────────────────────────────────────
@@ -3838,7 +3951,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── settle_mandate ──────────────────────────────────────────────────────────
@@ -3875,7 +3988,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── validate_mandate_spending ───────────────────────────────────────────────
@@ -3902,7 +4015,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_mandates ───────────────────────────────────────────────────────────
@@ -3988,7 +4101,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── create_bu ───────────────────────────────────────────────────────────────
@@ -4058,7 +4171,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_bu ───────────────────────────────────────────────────────────────
@@ -4127,7 +4240,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_bu ──────────────────────────────────────────────────────────────────
@@ -4157,7 +4270,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_bus ────────────────────────────────────────────────────────────────
@@ -4237,7 +4350,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── delete_bu ───────────────────────────────────────────────────────────────
@@ -4271,7 +4384,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── add_repo_mapping ────────────────────────────────────────────────────────
@@ -4319,7 +4432,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_repo_mappings ──────────────────────────────────────────────────────
@@ -4393,7 +4506,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── remove_repo_mapping ─────────────────────────────────────────────────────
@@ -4427,7 +4540,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_issues ─────────────────────────────────────────────────────────────
@@ -4547,7 +4660,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_issue ───────────────────────────────────────────────────────────────
@@ -4581,7 +4694,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_issue_status ─────────────────────────────────────────────────────
@@ -4621,7 +4734,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── link_commit_to_issue ────────────────────────────────────────────────────
@@ -4659,7 +4772,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── verify_issue ────────────────────────────────────────────────────────────
@@ -4695,7 +4808,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── issue_stats ─────────────────────────────────────────────────────────────
@@ -4728,7 +4841,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── create_fix_pattern ──────────────────────────────────────────────────────
@@ -4786,7 +4899,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── add_fix_attempt ─────────────────────────────────────────────────────────
@@ -4827,7 +4940,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── validate_fix ────────────────────────────────────────────────────────────
@@ -4861,7 +4974,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── search_fix_patterns ─────────────────────────────────────────────────────
@@ -4912,7 +5025,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_fix_patterns ───────────────────────────────────────────────────────
@@ -5001,7 +5114,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── link_issue_to_pattern ───────────────────────────────────────────────────
@@ -5035,7 +5148,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_mission_template ────────────────────────────────────────────────────
@@ -5063,7 +5176,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_mission_template ─────────────────────────────────────────────────
@@ -5131,7 +5244,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── instantiate_template_into_mission ───────────────────────────────────────
@@ -5192,7 +5305,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── add_deployment ──────────────────────────────────────────────────────────
@@ -5242,7 +5355,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── remove_deployment ───────────────────────────────────────────────────────
@@ -5274,7 +5387,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_errors ─────────────────────────────────────────────────────────────
@@ -5353,7 +5466,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_error ───────────────────────────────────────────────────────────────
@@ -5383,7 +5496,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── whoami ──────────────────────────────────────────────────────────────────
@@ -5512,7 +5625,7 @@ export function registerTools(server, convex, oauthCtx) {
         repo: z.string(),
         orchestrator: z.string(),
         project: z.string().optional(),
-    }, async ({ repo, orchestrator, project }) => {
+    }, { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: "Register repo mapping (alias)" }, async ({ repo, orchestrator, project }) => {
         const masterDenied = guardMasterOnly("register_repo_mapping");
         if (masterDenied)
             return masterDenied;
@@ -5525,7 +5638,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // delete_repo_mapping → was remove_repo_mapping [ALIAS of remove_repo_mapping — C0.3 master-only]
@@ -5533,7 +5646,7 @@ export function registerTools(server, convex, oauthCtx) {
         "WHEN: use when a repo is archived or its events should no longer generate VP notifications. " +
         "EXAMPLE: delete_repo_mapping repo='vantageos-agency/vantage-peers'.", {
         repo: z.string(),
-    }, async ({ repo }) => {
+    }, { readOnlyHint: false, openWorldHint: false, destructiveHint: true, title: "Delete repo mapping (alias)" }, async ({ repo }) => {
         const masterDenied = guardMasterOnly("delete_repo_mapping");
         if (masterDenied)
             return masterDenied;
@@ -5542,7 +5655,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // register_deployment → was add_deployment [ALIAS of add_deployment — C0.1 master-only]
@@ -5554,7 +5667,7 @@ export function registerTools(server, convex, oauthCtx) {
         deployKeyEnvVar: z.string(),
         githubRepo: z.string(),
         orchestrator: z.string(),
-    }, async ({ name, deploymentUrl, deployKeyEnvVar, githubRepo, orchestrator }) => {
+    }, { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: "Register deployment (alias)" }, async ({ name, deploymentUrl, deployKeyEnvVar, githubRepo, orchestrator }) => {
         const masterDenied = guardMasterOnly("register_deployment");
         if (masterDenied)
             return masterDenied;
@@ -5569,7 +5682,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // delete_deployment → was remove_deployment [ALIAS of remove_deployment — C0.1 master-only]
@@ -5577,7 +5690,7 @@ export function registerTools(server, convex, oauthCtx) {
         "WHEN: use when a deployment is retired or moved to a different monitoring config. " +
         "EXAMPLE: delete_deployment name='vantage-prod'.", {
         name: z.string(),
-    }, async ({ name }) => {
+    }, { readOnlyHint: false, openWorldHint: false, destructiveHint: true, title: "Delete deployment (alias)" }, async ({ name }) => {
         const masterDenied = guardMasterOnly("delete_deployment");
         if (masterDenied)
             return masterDenied;
@@ -5586,7 +5699,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // check_mandate_spending → was validate_mandate_spending (not C0-gated — read-only check)
@@ -5595,7 +5708,7 @@ export function registerTools(server, convex, oauthCtx) {
         "EXAMPLE: check_mandate_spending mandateId='j57aaaaa...' proposedAmount=500.", {
         mandateId: z.string(),
         proposedAmount: z.number(),
-    }, async ({ mandateId, proposedAmount }) => {
+    }, { readOnlyHint: true, openWorldHint: false, destructiveHint: false, title: "Check mandate spending (alias)" }, async ({ mandateId, proposedAmount }) => {
         try {
             const result = await convex.query("mandates:validateSpending", {
                 mandateId,
@@ -5604,7 +5717,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // check_fix → was validate_fix [ALIAS of validate_fix — C0.5 master-only]
@@ -5613,7 +5726,7 @@ export function registerTools(server, convex, oauthCtx) {
         "EXAMPLE: check_fix patternId='j57aaaaa...' validatedFix='Add suppressHydrationWarning to date elements'.", {
         patternId: z.string(),
         validatedFix: z.string(),
-    }, async ({ patternId, validatedFix }) => {
+    }, { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: "Check/validate fix (alias)" }, async ({ patternId, validatedFix }) => {
         const masterDenied = guardMasterOnly("check_fix");
         if (masterDenied)
             return masterDenied;
@@ -5625,7 +5738,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // create_fix_attempt → was add_fix_attempt (not C0-gated — uses guardFrom(createdBy))
@@ -5638,7 +5751,7 @@ export function registerTools(server, convex, oauthCtx) {
         why: z.string().optional(),
         commitSha: z.string().optional(),
         createdBy: z.string(),
-    }, async ({ patternId, description, worked, why, commitSha, createdBy }) => {
+    }, { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: "Create fix attempt (alias)" }, async ({ patternId, description, worked, why, commitSha, createdBy }) => {
         const fromDenied = guardFrom(createdBy);
         if (fromDenied)
             return fromDenied;
@@ -5654,7 +5767,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // create_task_dependency → was add_task_dependency (not C0-gated — uses callerOrchestrator auth)
@@ -5664,7 +5777,7 @@ export function registerTools(server, convex, oauthCtx) {
         taskId: z.string(),
         dependsOn: z.array(z.string()),
         callerOrchestrator: z.string(),
-    }, async ({ taskId, dependsOn, callerOrchestrator }) => {
+    }, { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: "Create task dependency (alias)" }, async ({ taskId, dependsOn, callerOrchestrator }) => {
         try {
             const result = await convex.mutation("tasks:update", {
                 taskId,
@@ -5674,7 +5787,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // update_summary → was set_summary (not C0-gated — uses orchestratorId auth)
@@ -5684,7 +5797,7 @@ export function registerTools(server, convex, oauthCtx) {
         orchestratorId: z.string(),
         instanceId: z.string().optional(),
         summary: z.string(),
-    }, async ({ orchestratorId, instanceId, summary }) => {
+    }, { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: "Update summary (alias)" }, async ({ orchestratorId, instanceId, summary }) => {
         try {
             const result = await convex.mutation("profiles:updateDynamic", {
                 orchestratorId,
@@ -5694,7 +5807,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // create_diary → was write_diary (not C0-gated — uses guardFrom(author) when present)
@@ -5705,7 +5818,7 @@ export function registerTools(server, convex, oauthCtx) {
         orchestrator: z.string(),
         content: z.string(),
         author: z.string().optional(),
-    }, async ({ date, orchestrator, content, author }) => {
+    }, { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: "Create diary entry (alias)" }, async ({ date, orchestrator, content, author }) => {
         assertContentSize(content, "content");
         if (author !== undefined) {
             const fromDenied = guardFrom(author);
@@ -5722,7 +5835,7 @@ export function registerTools(server, convex, oauthCtx) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_task ────────────────────────────────────────────────────────────────
@@ -5749,7 +5862,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_fix_pattern ─────────────────────────────────────────────────────────
@@ -5775,7 +5888,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_mandate ─────────────────────────────────────────────────────────────
@@ -5801,7 +5914,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_repo_mapping ────────────────────────────────────────────────────────
@@ -5832,7 +5945,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_message ─────────────────────────────────────────────────────────────
@@ -5861,7 +5974,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── get_recurring_task ──────────────────────────────────────────────────────
@@ -5890,7 +6003,7 @@ export function registerTools(server, convex, oauthCtx) {
             };
         }
         catch (error) {
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
 }

package/package.json

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