vantage-peers-mcp 2.3.1 → 2.3.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v2.3.2 — 2026-05-28
+
+**Hotfix** — Expose `fields="lite"` + `status` array/aliases in MCP tool schemas (Day 82 sprint gap).
+
+Backend support for these params shipped in v2.3.1 but the MCP wrapper Zod schemas never exposed them, so MCP clients couldn't pass them. Fixed for 4 list tools:
+
+- `list_tasks`: + `fields`, status now accepts aliases (`"open"`, `"active"`, `"all"`) and arrays
+- `list_tasks_by_mission`: same
+- `list_missions`: + `fields`, status accepts aliases and arrays
+- `list_briefing_notes`: + `fields`
+
+Aliases NOT permitted inside arrays (matches backend rejection contract).
+
+Tests: 14 new cases (`src/__tests__/list-queries-schema-v2.3.2.test.ts`), 0 regression on 295+ existing.
+
+Fix-pattern (fleet-wide): When backend query supports a new param, ALWAYS update the MCP wrapper tool schema in the SAME PR.
+
+VP task: `k17e09ng1tf217n93z9m4tr0mx87hfe0`.
+
 ## 2.3.1 — 2026-05-26
 
 ### Fixed (Eta PR #530 delta-review)

package/dist/src/tools.d.ts

@@ -46,4 +46,95 @@ export declare const updateBriefingNoteSchema: z.ZodObject<{
     decisions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     linkedMemoryIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+export declare const taskStatusSchema: z.ZodEnum<{
+    todo: "todo";
+    in_progress: "in_progress";
+    review: "review";
+    blocked: "blocked";
+    done: "done";
+}>;
+export declare const missionStatusSchema: z.ZodEnum<{
+    brainstorm: "brainstorm";
+    plan: "plan";
+    execute: "execute";
+    validate: "validate";
+    complete: "complete";
+}>;
+export declare const taskStatusFilterSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    todo: "todo";
+    in_progress: "in_progress";
+    review: "review";
+    blocked: "blocked";
+    done: "done";
+    active: "active";
+    open: "open";
+    all: "all";
+}>, z.ZodArray<z.ZodEnum<{
+    todo: "todo";
+    in_progress: "in_progress";
+    review: "review";
+    blocked: "blocked";
+    done: "done";
+}>>]>;
+export declare const missionStatusFilterSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    brainstorm: "brainstorm";
+    plan: "plan";
+    execute: "execute";
+    validate: "validate";
+    complete: "complete";
+    active: "active";
+    open: "open";
+    all: "all";
+}>, z.ZodArray<z.ZodEnum<{
+    brainstorm: "brainstorm";
+    plan: "plan";
+    execute: "execute";
+    validate: "validate";
+    complete: "complete";
+}>>]>;
+export declare const fieldsSchema: z.ZodEnum<{
+    lite: "lite";
+    full: "full";
+}>;
+export interface ParsedConvexError {
+    code: string;
+    message: string;
+    path: string | null;
+    hint: string | null;
+}
+/**
+ * Parse a Convex error message string into a structured object.
+ *
+ * Input example (from ConvexHttpClient):
+ *   "[CONVEX M(briefingNotes:create)] ArgumentValidationError: Found ID
+ *    \"js72ewf0m...\" from table briefingNotes, which does not match the table
+ *    name in validator v.id(\"memories\"). Path: .linkedMemoryIds[4]"
+ *
+ * Returns { code, message, path, hint } where:
+ *  - code  = "ArgumentValidationError" (or the parsed error type)
+ *  - message = the full human-readable error description after the code prefix
+ *  - path  = e.g. ".linkedMemoryIds[4]" extracted from "Path: ..." suffix
+ *  - hint  = a concise guidance string derived from the error, or null
+ *
+ * For unrecognised error strings, code = "ServerError" and path/hint = null.
+ *
+ * Exported for unit testing.
+ */
+export declare function parseConvexError(rawMessage: string): ParsedConvexError;
+/**
+ * Produce a structured MCP error response for any error thrown by a Convex
+ * operation. For ConvexError / ArgumentValidationError the response body
+ * contains a JSON object with { code, message, path, hint } so the MCP client
+ * can display actionable diagnostics instead of a bare "Server Error" string.
+ *
+ * For unrecognised errors the response falls back to the plain text format
+ * used by `mcpError`.
+ */
+export declare function mcpConvexError(error: unknown): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};
 export declare function registerTools(server: McpServer, convex: ConvexHttpClient, oauthCtx?: OAuthContext): void;

package/dist/src/tools.js

@@ -101,7 +101,9 @@ export const updateBriefingNoteSchema = z.object({
     linkedMemoryIds: z
         .array(memoryIdSchema)
         .optional()
-        .describe("Optional new linkedMemoryIds array — full replace, not append. Each ID must point to memories table, NOT briefingNotes or any other table."),
+        .describe("Optional new linkedMemoryIds array — full replace, not append. " +
+        "DISCLAIMER: Memory IDs only — NOT briefingNotes IDs or any other table. " +
+        "Passing a briefingNotes ID causes ArgumentValidationError at path .linkedMemoryIds[N]."),
 });
 const assigneeSchema = z
     .string()
@@ -113,12 +115,53 @@ const prioritySchema = z
 const componentTypeSchema = z
     .enum(["agent", "skill", "hook", "plugin"])
     .describe("Component type");
-const taskStatusSchema = z
-    .enum(["todo", "in_progress", "review", "blocked", "done"])
-    .describe("Task status");
-const missionStatusSchema = z
-    .enum(["brainstorm", "plan", "execute", "validate", "complete"])
+const taskStatusValues = [
+    "todo",
+    "in_progress",
+    "review",
+    "blocked",
+    "done",
+];
+const taskStatusAliases = ["open", "active", "all"];
+export const taskStatusSchema = z.enum(taskStatusValues).describe("Task status");
+const missionStatusValues = [
+    "brainstorm",
+    "plan",
+    "execute",
+    "validate",
+    "complete",
+];
+const missionStatusAliases = ["open", "active", "all"];
+export const missionStatusSchema = z
+    .enum(missionStatusValues)
     .describe("Mission lifecycle status");
+// v2.3.2 — filter-only schemas: expose status aliases ("open"/"active"/"all")
+// AND multi-status arrays to the MCP client. Backend (convex/tasks.ts +
+// convex/missions.ts) handles alias expansion + array validation.
+// Aliases NOT allowed inside arrays (matches backend rejection).
+export const taskStatusFilterSchema = z
+    .union([
+    z.enum([...taskStatusValues, ...taskStatusAliases]),
+    z.array(z.enum(taskStatusValues)).min(1),
+])
+    .describe('Task status filter. Single status ("todo"|"in_progress"|"review"|"blocked"|"done"), ' +
+    'alias ("open" = todo+in_progress+review+blocked, "active" = todo+in_progress, "all" = no filter), ' +
+    'or array of direct statuses (no aliases inside array).');
+export const missionStatusFilterSchema = z
+    .union([
+    z.enum([...missionStatusValues, ...missionStatusAliases]),
+    z.array(z.enum(missionStatusValues)).min(1),
+])
+    .describe('Mission status filter. Single status ("brainstorm"|"plan"|"execute"|"validate"|"complete"), ' +
+    'alias ("open" = brainstorm+plan+execute+validate, "active" = plan+execute, "all" = no filter), ' +
+    'or array of direct statuses (no aliases inside array).');
+// v2.3.2 — fields projection toggle. "lite" returns compact projection
+// (5-10× smaller payload), "full" (default) returns full doc.
+export const fieldsSchema = z
+    .enum(["lite", "full"])
+    .describe('Field projection — "lite" returns compact fields only ' +
+    '(typical 5-10× smaller payload for large list scans), ' +
+    '"full" (default) returns the full document.');
 const mandateStatusSchema = z
     .enum(["requested", "accepted", "in_progress", "delivered", "settled"])
     .describe("Mandate lifecycle status");
@@ -180,6 +223,103 @@ function mcpError(message) {
         isError: true,
     };
 }
+/**
+ * Parse a Convex error message string into a structured object.
+ *
+ * Input example (from ConvexHttpClient):
+ *   "[CONVEX M(briefingNotes:create)] ArgumentValidationError: Found ID
+ *    \"js72ewf0m...\" from table briefingNotes, which does not match the table
+ *    name in validator v.id(\"memories\"). Path: .linkedMemoryIds[4]"
+ *
+ * Returns { code, message, path, hint } where:
+ *  - code  = "ArgumentValidationError" (or the parsed error type)
+ *  - message = the full human-readable error description after the code prefix
+ *  - path  = e.g. ".linkedMemoryIds[4]" extracted from "Path: ..." suffix
+ *  - hint  = a concise guidance string derived from the error, or null
+ *
+ * For unrecognised error strings, code = "ServerError" and path/hint = null.
+ *
+ * Exported for unit testing.
+ */
+export function parseConvexError(rawMessage) {
+    // Known Convex validation/runtime error codes surfaced as plaintext
+    const knownCodes = [
+        "ArgumentValidationError",
+        "AuthorizationError",
+        "ConvexError",
+        "SchemaValidationError",
+        "QueryError",
+        "MutationError",
+        "ActionError",
+    ];
+    // Strip the [CONVEX M(path)] / [CONVEX Q(path)] prefix if present
+    const stripped = rawMessage.replace(/^\[CONVEX [A-Z]+\([^\]]*\)\]\s*/, "");
+    // Detect the error code
+    let code = "ServerError";
+    let remainder = stripped;
+    for (const candidate of knownCodes) {
+        if (stripped.startsWith(candidate + ":") || stripped.startsWith(candidate + " ")) {
+            code = candidate;
+            remainder = stripped.slice(candidate.length).replace(/^[:\s]+/, "");
+            break;
+        }
+    }
+    // Extract "Path: .<fieldPath>" from the tail of the message
+    // Convex appends this as the last sentence: "Path: .linkedMemoryIds[4]"
+    let path = null;
+    const pathMatch = remainder.match(/\bPath:\s*([\w.\[\]"']+)\s*$/);
+    if (pathMatch) {
+        path = pathMatch[1];
+        remainder = remainder.slice(0, pathMatch.index).trim().replace(/\.\s*$/, "");
+    }
+    // Build a concise hint for common patterns
+    let hint = null;
+    if (code === "ArgumentValidationError") {
+        const tableMatch = remainder.match(/from table (\w+),.*validator v\.id\("(\w+)"\)/);
+        if (tableMatch) {
+            hint = `ID belongs to table "${tableMatch[1]}" but validator expects v.id("${tableMatch[2]}"). Check that you are passing the correct document ID from the "${tableMatch[2]}" table.`;
+        }
+    }
+    return { code, message: remainder || rawMessage, path, hint };
+}
+/**
+ * Produce a structured MCP error response for any error thrown by a Convex
+ * operation. For ConvexError / ArgumentValidationError the response body
+ * contains a JSON object with { code, message, path, hint } so the MCP client
+ * can display actionable diagnostics instead of a bare "Server Error" string.
+ *
+ * For unrecognised errors the response falls back to the plain text format
+ * used by `mcpError`.
+ */
+export function mcpConvexError(error) {
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const parsed = parseConvexError(rawMessage);
+    // For ArgumentValidationError and other known Convex codes, return structured JSON
+    if (parsed.code !== "ServerError") {
+        const payload = {
+            code: parsed.code,
+            message: parsed.message,
+        };
+        if (parsed.path !== null)
+            payload.path = parsed.path;
+        if (parsed.hint !== null)
+            payload.hint = parsed.hint;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(payload, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Fallback: generic error, preserve existing plain-text format
+    return {
+        content: [{ type: "text", text: `Error: ${rawMessage}` }],
+        isError: true,
+    };
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Main export: register all tools against a server + convex client pair
 // ─────────────────────────────────────────────────────────────────────────────
@@ -991,7 +1131,9 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .optional()
             .describe("Filter by instance — e.g. 'pi-vps'. Returns only tasks assigned to that instance."),
-        status: taskStatusSchema.optional().describe("Filter by status"),
+        status: taskStatusFilterSchema
+            .optional()
+            .describe("Filter by status (single, alias, or array)"),
         project: z.string().optional().describe("Filter by project name"),
         limit: z
             .number()
@@ -1001,7 +1143,10 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(50)
             .describe("Maximum number of tasks to return (default 50)"),
-    }, async ({ assignedTo, assignedToInstance, status, project, limit }) => {
+        fields: fieldsSchema
+            .optional()
+            .describe('Field projection ("lite"|"full")'),
+    }, async ({ assignedTo, assignedToInstance, status, project, limit, fields, }) => {
         try {
             const tasks = await convex.query("tasks:list", {
                 assignedTo,
@@ -1009,6 +1154,7 @@ export function registerTools(server, convex, oauthCtx) {
                 status,
                 project,
                 limit: limit ?? 50,
+                fields,
             });
             return {
                 content: [
@@ -1315,7 +1461,9 @@ export function registerTools(server, convex, oauthCtx) {
     // ── list_tasks_by_mission ───────────────────────────────────────────────────
     server.tool("list_tasks_by_mission", "List all tasks linked to a specific mission. Optionally filter by status.", {
         missionId: z.string().describe("Convex document ID of the mission"),
-        status: taskStatusSchema.optional().describe("Filter by task status"),
+        status: taskStatusFilterSchema
+            .optional()
+            .describe("Filter by task status (single, alias, or array)"),
         limit: z
             .number()
             .int()
@@ -1324,12 +1472,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(50)
             .describe("Maximum number of tasks to return (default 50)"),
-    }, async ({ missionId, status, limit }) => {
+        fields: fieldsSchema
+            .optional()
+            .describe('Field projection ("lite"|"full")'),
+    }, async ({ missionId, status, limit, fields }) => {
         try {
             const tasks = await convex.query("tasks:listByMission", {
                 missionId: missionId,
                 status,
                 limit: limit ?? 50,
+                fields,
             });
             return {
                 content: [
@@ -1404,7 +1556,9 @@ export function registerTools(server, convex, oauthCtx) {
         "Filter by project, pilot, and/or status. Returns newest first.", {
         project: z.string().optional().describe("Filter by project name"),
         pilot: creatorSchema.optional().describe("Filter by pilot orchestrator"),
-        status: missionStatusSchema.optional().describe("Filter by status"),
+        status: missionStatusFilterSchema
+            .optional()
+            .describe("Filter by status (single, alias, or array)"),
         limit: z
             .number()
             .int()
@@ -1413,13 +1567,17 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(50)
             .describe("Maximum number of missions to return (default 50)"),
-    }, async ({ project, pilot, status, limit }) => {
+        fields: fieldsSchema
+            .optional()
+            .describe('Field projection ("lite"|"full")'),
+    }, async ({ project, pilot, status, limit, fields }) => {
         try {
             const missions = await convex.query("missions:list", {
                 project,
                 pilot,
                 status,
                 limit: limit ?? 50,
+                fields,
             });
             return {
                 content: [
@@ -1630,7 +1788,9 @@ export function registerTools(server, convex, oauthCtx) {
     // ── create_briefing_note ────────────────────────────────────────────────────
     server.tool("create_briefing_note", "Create a briefing note — a structured record of a topic discussion, with participants, " +
         "content, optional decisions, and optional links to existing memories. " +
-        "linkedMemoryIds MUST contain IDs from the memories table only — NOT briefingNotes IDs or IDs from any other table.", {
+        "linkedMemoryIds MUST contain IDs from the memories table only — NOT briefingNotes IDs or IDs from any other table. " +
+        "IMPORTANT: If you need to cross-link briefing notes together, use linkedBriefingIds (not yet shipped) — " +
+        "passing a briefingNotes document ID into linkedMemoryIds will produce an ArgumentValidationError at the Convex validator boundary.", {
         title: z.string().describe("Briefing note title"),
         topic: z
             .string()
@@ -1643,7 +1803,10 @@ export function registerTools(server, convex, oauthCtx) {
         linkedMemoryIds: z
             .array(memoryIdSchema)
             .optional()
-            .describe("Convex document IDs of related memories — each must be a 32-char ID from the memories table, NOT briefingNotes or any other table"),
+            .describe("Convex document IDs of related memories — each must be a 32-char ID from the memories table, NOT briefingNotes or any other table. " +
+            "DISCLAIMER: Memory IDs only. Do NOT pass briefingNotes IDs here — they share the same 32-char alphanumeric format but belong to a different table. " +
+            "Passing a briefingNotes ID will fail with ArgumentValidationError at path .linkedMemoryIds[N]. " +
+            "If cross-linking briefings is needed, request the linkedBriefingIds feature instead."),
         createdBy: creatorSchema,
     }, async ({ title, topic, participants, content, decisions, linkedMemoryIds, createdBy, }) => {
         let contentBytes = 0;
@@ -1680,7 +1843,7 @@ export function registerTools(server, convex, oauthCtx) {
                 title,
                 errorMessage: error?.message ?? String(error),
             });
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── update_briefing_note ────────────────────────────────────────────────────
@@ -1721,7 +1884,7 @@ export function registerTools(server, convex, oauthCtx) {
                 noteId,
                 errorMessage: error?.message ?? String(error),
             });
-            return mcpError(error.message ?? String(error));
+            return mcpConvexError(error);
         }
     });
     // ── list_briefing_notes ─────────────────────────────────────────────────────
@@ -1738,11 +1901,15 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(20)
             .describe("Maximum notes to return (default 20)"),
-    }, async ({ topic, limit }) => {
+        fields: fieldsSchema
+            .optional()
+            .describe('Field projection ("lite"|"full")'),
+    }, async ({ topic, limit, fields }) => {
         try {
             const notes = await convex.query("briefingNotes:list", {
                 topic,
                 limit: limit ?? 20,
+                fields,
             });
             return {
                 content: [

package/package.json

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