vantage-peers-mcp 2.7.1 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 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

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

@@ -916,8 +916,11 @@ export function registerTools(server, convex, oauthCtx) {
         }
     });
     // ── 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()
@@ -971,8 +974,11 @@ export function registerTools(server, convex, oauthCtx) {
         }
     });
     // ── 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
@@ -1016,6 +1022,113 @@ export function registerTools(server, convex, oauthCtx) {
             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 ───────────────────────────────────────────────────────────
     server.tool("hybrid_search", "Combined vector + BM25 search via Reciprocal Rank Fusion for best semantic and keyword coverage. " +
         "WHEN: use when neither recall nor text_search alone yields good results — highest recall quality. " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vantage-peers-mcp",
-  "version": "2.7.1",
+  "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",