vantage-peers-mcp 2.3.5 → 2.4.1

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## [2.4.0] — 2026-05-28 — M3 iframeEmbedSessions + __VP_TOOL_RESULT__ stream marker + ack-checklist
+
+**Mission instance** : `sigma-vantage-peers-mcp-gui-iframe-embed-v1` (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+**Pi sign-off** : PI_AUTHORIZED_TASK_ID=`k1793m1qgn0zaay6r87dhvsh7187kwya` (PROD-DEPLOY-AUTHORIZED).
+**Eta sign-off** : ETA_APPROVED_TASK_ID=`k171ep964sxabbrgmb21fk9axd87ka1n` at commit `338a7b9e6130ce69dc5fe7f3e2e9ecc4648b4f6a` (Day 79 SHA-pinned).
+**Merge** : PR #545 squash `f509c8d92f0b142bc063a0e9dd070e1993cc729b`.
+
+M3 delivers the session registry and stream-marker protocol that connects the VP MCP server
+to the Gen UI iframe bridge. All marker emission is gated behind `VP_EMIT_UI_MARKERS=1`
+so production behaviour is unchanged until the bridge is deployed.
+
+### Convex schema — `iframeEmbedSessions` table
+
+NEW table `iframeEmbedSessions` in `convex/schema.ts` :
+- Fields : `sessionId` (string), `tenantId` (optional string), `origin` (string),
+  `userId` (optional string), `createdAt` (number), `lastSeenAt` (number),
+  `expiresAt` (number), `revoked` (boolean).
+- Indexes : `by_session_id` on `["sessionId"]`, `by_origin_expires` on `["origin", "expiresAt"]`.
+
+NEW `convex/iframeEmbedSessions.ts` — 4 operations :
+- `createSession` mutation — inserts a new session row.
+- `getSession` query — returns session or null (null for expired / revoked).
+- `touchSession` mutation — bumps `lastSeenAt` to now; returns bool.
+- `revokeSession` mutation — sets `revoked=true`; returns bool.
+
+### Stream marker — `mcp-server/src/ui-resources/stream-marker.ts`
+
+NEW `MARKER_START = "__VP_TOOL_RESULT__"`, `MARKER_END = "__END__"`.
+
+NEW `wrapToolResult(payload: VpToolResult): string` :
+- Validates via `VpToolResultSchema`, throws `TypeError` on schema failure.
+- Returns `__VP_TOOL_RESULT__<json>__END__`.
+
+NEW `parseToolResult(text: string): VpToolResult | null` :
+- Extracts marker substring (handles bare, embedded, surrounding text).
+- Returns validated `VpToolResult` or null on any failure (no-throw contract).
+
+### MCP tools — marker emission gated by `VP_EMIT_UI_MARKERS=1`
+
+`mcp-server/src/tools.ts` — 6 tools now append `wrapToolResult(...)` after the JSON payload
+when `VP_EMIT_UI_MARKERS=1` (default OFF) :
+
+| Tool                  | kind               |
+|-----------------------|--------------------|
+| `list_tasks`          | `tasks-table`      |
+| `list_messages`       | `messages-feed`    |
+| `get_diary`           | `diary-entry`      |
+| `list_missions`       | `mission-timeline` |
+| `list_briefing_notes` | `briefing-note`    |
+| `list_memories`       | `memory-quote`     |
+
+Change is surgical — existing return shape is preserved; marker is appended as a new line.
+
+### Ack checklist
+
+NEW `docs/M3-ACK-CHECKLIST.md` — bilingual FR/EN post-deploy verification checklist
+for Marie + Ismaël. Covers: package install, primitive reads, Shadow DOM scoping,
+stream marker emit + parse, bilingual spot check, WCAG AA (contrast + role attrs),
+default-OFF guard.
+
+### Tests
+
+15+ new vitest cases (≥264 total after M3, baseline 253 after M2) :
+- `mcp-server/src/__tests__/m3-stream-marker.test.ts` — 14 cases:
+  `wrapToolResult` ×6 valid kinds, ×2 throws on invalid, `parseToolResult` roundtrip,
+  non-marker text ×2, embedded text, malformed JSON ×2, schema rejects unknown kind ×2.
+- `convex/iframeEmbedSessions.test.ts` — 7 cases:
+  create+get, optional fields, getSession unknown, expired session null,
+  touchSession updates lastSeenAt, touchSession unknown false,
+  revokeSession marks revoked (getSession null), revokeSession unknown false.
+
+0 regression on M1+M2 suites (253/253 baseline).
+
+---
+
+## [Unreleased] — M1 SEP-1865 ui:// resources backend + M2 primitives + Zod schemas
+
+**Mission instance** : `sigma-vantage-peers-mcp-gui-iframe-embed-v1` (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+**Template VR consumed** : `gui-iframe-embed-v1` v1.0.0 (jx7bzk0x1086tgwgj2zrssk2pn87k1ga).
+
+M1 Foundation (adapted MCP-pure paradigm per Pi arbitrage Day 84) :
+- NEW `mcp-server/src/ui-resources/index.ts` : URI parser `ui://vp/v1/<primitive>?<query>` + primitive registry + handler factory.
+- NEW `mcp-server/src/ui-resources/primitives/tasks-table.ts` : M1 MVP primitive returning HTML inline (Shadow DOM scoped CSS) — WCAG AA + bilingual FR+EN.
+- `mcp-server/server-http.ts` : wired `ListResourcesRequestSchema` + `ReadResourceRequestSchema` MCP handlers on the existing McpServer instance.
+
+Tests : 14 new vitest cases (`src/__tests__/ui-resources-sep-1865.test.ts`) — URI parsing, primitive registry, render variants (empty, populated, FR), backend arg forwarding, XSS escape, error fallback, limit clamping, unknown primitive rejection. 0 regression on existing suites.
+
+### M2 — Resolve 5 Gaps + Bearer sha256 hardening (adapted MCP-pure paradigm)
+
+5 new ui:// primitives :
+- `messages-feed` (`messages:listMessages` backend — channel filter applied client-side)
+- `diary-entry` (`diary:get` single-entry + `diary:list` multi-entry backend)
+- `mission-timeline` (`missions:list` backend with fields=lite)
+- `briefing-note` (`briefingNotes:get` by noteId OR `briefingNotes:list` by topic backend)
+- `memory-quote` (`memories:listMemories` backend — supports both plain-array and paginated result shapes)
+
+Zod discriminated union schemas : `mcp-server/src/ui-resources/schemas.ts` exports `VpTaskPayloadSchema` + `VpMessagePayloadSchema` + `VpDiaryEntryPayloadSchema` + `VpMissionPayloadSchema` + `VpBriefingNotePayloadSchema` + `VpMemoryPayloadSchema` + `VpToolResultSchema` (discriminated union by `kind`). Cross-fleet ready for Mu vantage-bridge sidepanel S3 consumer.
+
+Bearer sha256 validation : Already in place since v2.3.4 DCR security fix. `mcp-server/src/auth.ts` line 275 calls `sha256Hex(token)` before every Convex lookup (layers 2 and 4). Raw token never reaches Convex. No further hardening needed in M2.
+
+Tests : 42 new vitest cases in `src/__tests__/ui-resources-m2-primitives.test.ts` (target was ≥22). Covers : PRIMITIVES registry (6 entries), each of 5 new primitives (empty + populated + FR labels + XSS escape + error fallback = 5 cases each), Zod schema roundtrip (VpToolResultSchema all 6 variants accepted, malformed rejected, individual payload schema validations). 0 regression on M1 17 cases + 194 other MCP tests (253/253 total).
+
+M3 next : Registry json-render + `__VP_TOOL_RESULT__<json>` stream marker + smoke E2E + ack-checklist + PI-SIGNED Convex prod deploy + visual ack Marie/Ismaël.
+
 ## v2.3.5 — 2026-05-28
 
 **Critical hotfix** — v2.3.3 (PR #539) shipped the backend filters `createdBy` + `updatedSince` and the Zod schema exports but did NOT wire those params into the 4 list MCP tool args blocks. Pi pull-cycle quickstart `list_tasks createdBy="pi" status="review" fields="lite"` was silently dropping `createdBy` at the MCP boundary and returning all visible tasks. Auto-clamp safeguard (Day 83) also could not trigger because Zod `.default(50)` / `.default(20)` on `limit` overrode the absent-value signal before it reached the backend.

package/README.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/vantage-peers-mcp)](https://www.npmjs.com/package/vantage-peers-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/vantage-peers-mcp)](https://www.npmjs.com/package/vantage-peers-mcp)
 [![License: FSL-1.1-Apache-2.0](https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-blue)](https://github.com/vantageos-agency/vantage-peers/blob/main/LICENSE)
-[![Tests: 82/82](https://img.shields.io/badge/MCP_tools-82_registered-green)]()
+[![Tests: 84/84](https://img.shields.io/badge/MCP_tools-84_registered-green)]()
 
 MCP server for [VantagePeers](https://vantagepeers.com) — shared memory, messaging, and task coordination for AI agent teams.
 
-82 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.
+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.
 
 ## Quick start
 
@@ -74,7 +74,7 @@ VantagePeers ships a built-in OAuth 2.1 authorization server so Claude.ai web ca
 
 The server also reads `CONVEX_URL` from `.env.local` in the parent directory if not set via environment.
 
-## Tools (82)
+## Tools (84)
 
 ### Memory (6)
 `store_memory`, `recall`, `list_memories`, `soft_delete_memory`, `get_memory`, `store_episode`
@@ -400,6 +400,17 @@ All orchestrator names are open strings — any lowercase name is accepted. The
 
 ## Changelog
 
+### 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.
+- feat(mcp): ChatGPT Apps SDK tool annotations on all 84 tools (`readOnlyHint`, `openWorldHint`, `destructiveHint`) — 34 read-only + 41 write + 9 destructive — PR #555.
+- security(dcr): DCR scope isolation — new `public-readonly` profile + cross-tenant assertion tests + `scopeProfile` forced to `client-generic` for auto-discovery flow (never `master`) — PR #554.
+- docs(cloud): dedicated `/docs/cloud/` section in vantage-peers-site for VantagePeers Cloud (multi-tenant, multi-clients MCP: Claude.ai, ChatGPT, Claude Code, Codex) — site PR #120.
+
+### 2.4.0 — 2026-05-29 (Day 86)
+- feat(m3): `iframeEmbedSessions` table + `__VP_TOOL_RESULT__` stream marker + ack-checklist primitive — PR #545.
+- feat(v0.0.2-auth): `credentials:issueBearerFromClerk` httpAction + audit log + iter 2 P1 fixes — PR #546.
+
 ### 2.3.0 — 2026-05-26
 - `list_tasks`, `list_missions`, `list_tasks_by_mission`, `list_briefing_notes` now accept `fields=lite` for compact payloads (less tokens).
 - Status filters now accept arrays and aliases: `status=["todo","in_progress"]`, `status="open"` (expands to non-terminal), `status="active"` (in_progress only on tasks; plan+execute on missions), `status="all"` (no filter).

package/dist/server-http.js

@@ -25,13 +25,14 @@
  *   NODE_ENV              — set to "production" on Railway
  */
 import { readFileSync } from "node:fs";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { ConvexHttpClient } from "convex/browser";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { bearerAuthMiddleware, internalClient, masterOnlyMiddleware, sha256Base64Url, sha256Hex, } from "./src/auth.js";
 import { registerTools } from "./src/tools.js";
+import { listUiResources, readUiResource } from "./src/ui-resources/index.js";
 let pkg;
 try {
     // Source mode: server-http.ts → ./package.json = mcp-server/package.json
@@ -563,6 +564,31 @@ app.all("/mcp", bearerAuthMiddleware(), async (c) => {
         version: pkg.version,
     });
     registerTools(server, convex, oauthCtx);
+    // SEP-1865 ui:// resources for Generative UI primitives
+    // Uses McpServer.resource() high-level API with a ResourceTemplate so that
+    // resources/list (via listCallback) and resources/read both work.
+    // URI pattern: ui://vp/v1/{primitive}  — query params read from the URL object.
+    const uiResourceTemplate = new ResourceTemplate("ui://vp/v1/{primitive}", {
+        list: async () => ({ resources: listUiResources() }),
+    });
+    server.resource("vp-ui", uiResourceTemplate, {
+        description: "SEP-1865 VantagePeers Generative UI primitives (HTML inline, Shadow DOM scoped)",
+    }, async (uri) => {
+        const fetchConvex = async (functionName, args) => {
+            // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+            return convex.query(functionName, args);
+        };
+        const resource = await readUiResource(uri.toString(), fetchConvex);
+        return {
+            contents: [
+                {
+                    uri: resource.uri,
+                    mimeType: resource.mimeType,
+                    text: resource.text,
+                },
+            ],
+        };
+    });
     const transport = new WebStandardStreamableHTTPServerTransport();
     await server.connect(transport);
     return transport.handleRequest(c.req.raw);

package/dist/src/auth.js

@@ -139,11 +139,13 @@ export function checkNamespaceWrite(ctx, namespace) {
 // ─────────────────────────────────────────────────────────────────────────────
 export function bearerAuthMiddleware() {
     return async (c, next) => {
-        // RFC 6750 §3 — point clients at the protected-resource metadata so
-        // Claude.ai's OAuth connector can bootstrap discovery from any 401.
+        // MCP spec §"Protected Resource Metadata Discovery Requirements" + RFC 6750 §3 —
+        // the param MUST be `resource_metadata=` (not `resource=`). Claude.ai's OAuth
+        // connector looks for `resource_metadata=` to bootstrap PRM discovery; with
+        // `resource=` the entire DCR chain breaks before any token is issued.
         const publicBaseUrl = process.env.PUBLIC_BASE_URL ??
             "https://vantage-peers-production.up.railway.app";
-        const wwwAuthHeader = `Bearer resource="${publicBaseUrl}/.well-known/oauth-protected-resource"`;
+        const wwwAuthHeader = `Bearer resource_metadata="${publicBaseUrl}/.well-known/oauth-protected-resource"`;
         const authHeader = c.req.header("Authorization");
         if (!authHeader?.startsWith("Bearer ")) {
             c.header("WWW-Authenticate", wwwAuthHeader);
@@ -215,6 +217,10 @@ export function bearerAuthMiddleware() {
         // ── (3) DCR OAuth token — check oauthTokens via oauthDcr:validateAccessToken
         // Uses raw token (not hashed) — the DCR table stores tokens in plaintext.
         // This path handles Claude.ai clients registered via POST /register.
+        // NOTE: validateAccessToken is exposed as a PUBLIC query (not internalQuery)
+        // because ConvexHttpClient.query() only resolves public functions. Making it
+        // internal silently breaks the DCR path (#556). Security: lookup is keyed
+        // on the high-entropy opaque token; returns null on miss with no PII echo.
         let dcrResult = null;
         try {
             dcrResult = (await internalClient().query(