vantage-peers-mcp 2.4.12 → 2.4.13

package/CHANGELOG.md

@@ -1,10 +1,29 @@
 # Changelog
 
-## [2.4.0] — 2026-05-28 — M3 iframeEmbedSessions + __VP_TOOL_RESULT__ stream marker + ack-checklist
+## [2.4.13] — 2026-06-02 — Post-public republish: attribution + CHANGELOG day-numbers + RULE #7 narrative scrub
+
+Repository visibility flip to PUBLIC on 2026-06-02 (mission D62 `k57e4t21sr55rhz8ng554eseb987wvh3`). This patch republishes the npm package so the published README + CHANGELOG + attribution match the now-public source.
+
+No runtime / API / schema changes. Documentation + metadata only.
+
+What changed since v2.4.12:
+- `mcp-server/package.json`: author restructured to "VantageOS AI Orchestrator Team" with contributors block (Pi, Laurent Perello, ElPi Corp). Dependency `@vantageos/mosaic@^0.1.2` added for Phase 1 Mosaic groundwork (PR #605, server-side createMosaicResource API ready for Phase 2 primitive swap).
+- `mcp-server/CHANGELOG.md`: version headers simplified to `X.Y.Z — YYYY-MM-DD` (Day N anchors dropped per Laurent verdict 2026-06-02 — dates are self-explanatory, day numbers added noise). Narrative client-name mentions (Marie/Iris RH/Cédric Delport) genericized to "early-access RH cohort" / "self-host incident" per RULE #7 pre-public scrub.
+- Root README rework (PR #611 + PR #610 + PR #616 chain): TL;DR + Mermaid architecture diagram + 5 hero features + 22-features collapsed details + 84-tools 8-groups + Backend: Convex 3-paths + attribution Credits section. README /team 404 hotfix landed in PR #616.
+
+Merged PRs in this republish window:
+- PR #611 (`9464f9a`) — T5ter README rework + CHANGELOG day-numbers + attribution
+- PR #615 (`c189a1d`) — Phase 1 RULE #7 pre-public scrub
+- PR #616 (`99eeae5`) — README /team 404 hotfix
+
+Mission: D62 pre-public cleanup `k57e4t21sr55rhz8ng554eseb987wvh3`.
+Friction capitalize: `post-public-flip-must-trigger-npm-republish-for-consistency-not-just-repo-visibility-flip` + `day-79-hook-should-validate-tree-not-commit-sha`.
+
+## [2.4.0] — 2026-05-29 — 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).
+**Eta sign-off** : ETA_APPROVED_TASK_ID=`k171ep964sxabbrgmb21fk9axd87ka1n` at commit `338a7b9e6130ce69dc5fe7f3e2e9ecc4648b4f6a` (SHA-pinned).
 **Merge** : PR #545 squash `f509c8d92f0b142bc063a0e9dd070e1993cc729b`.
 
 M3 delivers the session registry and stream-marker protocol that connects the VP MCP server
@@ -56,7 +75,7 @@ Change is surgical — existing return shape is preserved; marker is appended as
 ### 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,
+for the beta verifier cohort. Covers: package install, primitive reads, Shadow DOM scoping,
 stream marker emit + parse, bilingual spot check, WCAG AA (contrast + role attrs),
 default-OFF guard.
 
@@ -80,7 +99,7 @@ default-OFF guard.
 **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) :
+M1 Foundation (adapted MCP-pure paradigm per Pi arbitrage 2026-05-28) :
 - 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.
@@ -102,11 +121,13 @@ Bearer sha256 validation : Already in place since v2.3.4 DCR security fix. `mcp-
 
 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.
+M3 next : Registry json-render + `__VP_TOOL_RESULT__<json>` stream marker + smoke E2E + ack-checklist + PI-SIGNED Convex prod deploy + visual ack from beta cohort verifiers.
+
+---
 
 ## 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.
+**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 (2026-05-27) also could not trigger because Zod `.default(50)` / `.default(20)` on `limit` overrode the absent-value signal before it reached the backend.
 
 Fixes:
 - `mcp-server/src/tools.ts` : 4 list tools now expose `createdBy` (`list_tasks` + `list_tasks_by_mission` only — `list_missions` + `list_briefing_notes` do not accept it backend-side) and `updatedSince` (all 4).
@@ -114,15 +135,15 @@ Fixes:
 
 Tests : 8 new boundary-forwarding cases (`src/__tests__/list-queries-v2.3.5-wire-createdby-updatedsince.test.ts`) — verify MCP layer actually forwards new params to `convex.query` instead of dropping them. 0 regression on existing suites.
 
-Detection : Vantage-Bridge architecture review Sigma scope Day 84 — direct `grep`/`sed` inspection of `tools.ts` confirmed the gap. Backend already correct since v2.3.3 (`convex/tasks.ts:354-357`).
+Detection : Vantage-Bridge architecture review Sigma scope 2026-05-28 — direct `grep`/`sed` inspection of `tools.ts` confirmed the gap. Backend already correct since v2.3.3 (`convex/tasks.ts:354-357`).
 
-Fix-pattern (Day 84 capitalize) : when adding a new param across backend + MCP wrapper, the test suite MUST cover not only schema validation but also the tool-handler→convex.query forwarding boundary. Schema-only tests passed cleanly in v2.3.3 while the actual feature was broken in prod.
+Fix-pattern (2026-05-28 capitalize) : when adding a new param across backend + MCP wrapper, the test suite MUST cover not only schema validation but also the tool-handler→convex.query forwarding boundary. Schema-only tests passed cleanly in v2.3.3 while the actual feature was broken in prod.
 
 VP task : `k177tsvdxzase5sjy2qm9fdvp187kbwr`. Predecessor v2.3.3 PR #539 (`k1796s5j6jfkvkx0tn5n926ftd87jx9p`).
 
 ## v2.3.4 — 2026-05-28
 
-**Security fix** — DCR (Dynamic Client Registration) self-registration now defaults to tenant-scope only. Master scope requires explicit admin authorization (`ADMIN_DCR_TOKEN` / `BEARER_SECRET_MASTER` env var). Closes beta blocker for Marie/Iris RH onboarding identified in VP Cloud audit Day 84.
+**Security fix** — DCR (Dynamic Client Registration) self-registration now defaults to tenant-scope only. Master scope requires explicit admin authorization (`ADMIN_DCR_TOKEN` / `BEARER_SECRET_MASTER` env var). Closes beta blocker for early-access RH cohort onboarding identified in VP Cloud audit 2026-05-28.
 
 Changes:
 - `convex/oauth.ts`: `registerPublicClient` now explicitly rejects `scopeProfile="master"` with a `ScopeViolation` error. Previously only the HTTP server enforced this; the Convex-layer was bypassable via direct internal call.
@@ -131,11 +152,11 @@ Changes:
 
 Tests: 5 new Convex security tests (`convex/oauth-dcr-security.test.ts`) + 5 new MCP scope enforcement tests (`mcp-server/src/__tests__/dcr-scope-enforcement.test.ts`), 0 regression on existing suites.
 
-VP task: k17218rvqyncs1v6rwj3qdzfsn87jj4n. Beta unblock chain: DCR fix → 5 quick wins onboarding (seed-profiles + marie-iris-rh client + README VP Cloud + runbook + email).
+VP task: k17218rvqyncs1v6rwj3qdzfsn87jj4n. Beta unblock chain: DCR fix → 5 quick wins onboarding (seed-profiles + early-access RH cohort client + README VP Cloud + runbook + email).
 
 ## v2.3.3 — 2026-05-28
 
-**Follow-up to v2.3.2 (Day 84 scope élargi)** — Extend list queries with `createdBy` + `updatedSince` filters + auto-clamp safeguard.
+**Follow-up to v2.3.2 (2026-05-28 scope élargi)** — Extend list queries with `createdBy` + `updatedSince` filters + auto-clamp safeguard.
 
 Backend (Convex) :
 - `tasks.list` + `tasks.listByMission` : + `createdBy` (filter by task creator) + `updatedSince` (Unix ms window) + auto-clamp limit=30 when `fields="full"` and no explicit limit
@@ -157,7 +178,7 @@ VP task: `k1796s5j6jfkvkx0tn5n926ftd87jx9p`. Successor of `k17e09ng1tf217n93z9m4
 
 ## v2.3.2 — 2026-05-28
 
-**Hotfix** — Expose `fields="lite"` + `status` array/aliases in MCP tool schemas (Day 82 sprint gap).
+**Hotfix** — Expose `fields="lite"` + `status` array/aliases in MCP tool schemas (2026-05-26 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:
 

package/dist/server-http.js

@@ -578,16 +578,7 @@ app.all("/mcp", bearerAuthMiddleware(), async (c) => {
             // 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,
-                },
-            ],
-        };
+        return await readUiResource(uri.toString(), fetchConvex);
     });
     const transport = new WebStandardStreamableHTTPServerTransport();
     await server.connect(transport);

package/dist/src/ui-resources/index.d.ts

@@ -1,20 +1,27 @@
 /**
  * SEP-1865 ui:// resources for VantagePeers Generative UI.
  *
+ * Canonical PR #1865 (MERGED 2026-01-28) compliance:
+ *  - MIME: text/html;profile=mcp-app (RESOURCE_MIME_TYPE)
+ *  - _meta.ui: UIResourceMeta envelope (nested, NOT flat _meta["ui/resourceUri"])
+ *  - Capability key declared at server initialize: io.modelcontextprotocol/ui
+ *  - Fallback markdown content item in resources/read response (Critical Rule #1)
+ *
+ * Uses @mcp-ui/server createUIResource() helper (reference impl by SEP-1865 co-author).
+ *
  * URI pattern : ui://vp/v1/<primitive>?<query>
  * Examples :
  *   ui://vp/v1/tasks-table?assignedTo=pi&status=review&fields=lite&limit=10
  *   ui://vp/v1/messages-feed?recipient=sigma&limit=20
  *
- * M1 scope : 1 primitive (tasks-table) — proves the pipeline.
- * M2 scope : ≥6 primitives (tasks/messages/diary/missions/briefingNotes/memories).
- *
  * Pattern Hybrid 60% static lit-ui + 11% Gen UI + 27% Hybrid (cf vp-gui-views-research-2026-05-28.md).
- * Returns HTML inline with embedded JS + CSS Shadow DOM scoped.
  *
  * Reference instance Theta : theta-vantage-crm-gui-iframe-embed-v1 (blissful-gopher-531).
  * Mission Sigma : sigma-vantage-peers-mcp-gui-iframe-embed-v1 (k5730xct6rvrwkvxhy5t5js12d87jwfw).
  */
+export declare const MCP_UI_CAPABILITY_KEY: "io.modelcontextprotocol/ui";
+export declare const MCP_UI_MIME_TYPE = "text/html;profile=mcp-app";
+type UIResourceMeta = Record<string, never>;
 export type UiResourceParsed = {
     primitive: string;
     query: URLSearchParams;
@@ -23,14 +30,30 @@ export declare function parseUiUri(uri: string): UiResourceParsed | null;
 export declare const PRIMITIVES: readonly ["tasks-table", "messages-feed", "diary-entry", "mission-timeline", "briefing-note", "memory-quote"];
 export type Primitive = (typeof PRIMITIVES)[number];
 export declare const PRIMITIVE_DESCRIPTIONS: Record<Primitive, string>;
-export declare function listUiResources(): Array<{
+export type UiResourceListEntry = {
     uri: string;
     name: string;
     description: string;
     mimeType: string;
-}>;
-export declare function readUiResource(uri: string, fetchConvex: (functionName: string, args: Record<string, unknown>) => Promise<unknown>): Promise<{
+    _meta: {
+        ui: UIResourceMeta;
+    };
+};
+export declare function listUiResources(): UiResourceListEntry[];
+export type UiResourceContent = {
     uri: string;
     mimeType: string;
     text: string;
-}>;
+    _meta?: {
+        ui: UIResourceMeta;
+    };
+} | {
+    uri: string;
+    mimeType: "text/markdown";
+    text: string;
+};
+export type UiResourceReadResult = {
+    contents: UiResourceContent[];
+};
+export declare function readUiResource(uri: string, fetchConvex: (functionName: string, args: Record<string, unknown>) => Promise<unknown>): Promise<UiResourceReadResult>;
+export {};

package/dist/src/ui-resources/index.js

@@ -1,26 +1,37 @@
 /**
  * SEP-1865 ui:// resources for VantagePeers Generative UI.
  *
+ * Canonical PR #1865 (MERGED 2026-01-28) compliance:
+ *  - MIME: text/html;profile=mcp-app (RESOURCE_MIME_TYPE)
+ *  - _meta.ui: UIResourceMeta envelope (nested, NOT flat _meta["ui/resourceUri"])
+ *  - Capability key declared at server initialize: io.modelcontextprotocol/ui
+ *  - Fallback markdown content item in resources/read response (Critical Rule #1)
+ *
+ * Uses @mcp-ui/server createUIResource() helper (reference impl by SEP-1865 co-author).
+ *
  * URI pattern : ui://vp/v1/<primitive>?<query>
  * Examples :
  *   ui://vp/v1/tasks-table?assignedTo=pi&status=review&fields=lite&limit=10
  *   ui://vp/v1/messages-feed?recipient=sigma&limit=20
  *
- * M1 scope : 1 primitive (tasks-table) — proves the pipeline.
- * M2 scope : ≥6 primitives (tasks/messages/diary/missions/briefingNotes/memories).
- *
  * Pattern Hybrid 60% static lit-ui + 11% Gen UI + 27% Hybrid (cf vp-gui-views-research-2026-05-28.md).
- * Returns HTML inline with embedded JS + CSS Shadow DOM scoped.
  *
  * Reference instance Theta : theta-vantage-crm-gui-iframe-embed-v1 (blissful-gopher-531).
  * Mission Sigma : sigma-vantage-peers-mcp-gui-iframe-embed-v1 (k5730xct6rvrwkvxhy5t5js12d87jwfw).
  */
+import { RESOURCE_MIME_TYPE } from "@mcp-ui/server";
 import { renderBriefingNote } from "./primitives/briefing-note.js";
 import { renderDiaryEntry } from "./primitives/diary-entry.js";
 import { renderMemoryQuote } from "./primitives/memory-quote.js";
 import { renderMessagesFeed } from "./primitives/messages-feed.js";
 import { renderMissionTimeline } from "./primitives/mission-timeline.js";
 import { renderTasksTable } from "./primitives/tasks-table.js";
+// MCP Apps capability negotiation key (declared at server initialize handshake).
+// Tools opting into UI resources reference it from their _meta.ui field.
+export const MCP_UI_CAPABILITY_KEY = "io.modelcontextprotocol/ui";
+// PR #1865 MIME — re-export from @mcp-ui/server for downstream visibility.
+export const MCP_UI_MIME_TYPE = RESOURCE_MIME_TYPE;
+const DEFAULT_UI_META = {};
 // URI parser : ui://vp/v1/<primitive>?<query>
 const UI_URI_RE = /^ui:\/\/vp\/v1\/([a-z][a-z0-9-]*)(?:\?(.*))?$/;
 export function parseUiUri(uri) {
@@ -51,16 +62,36 @@ export const PRIMITIVE_DESCRIPTIONS = {
     "briefing-note": "Render briefing note details. Query params: noteId or (topic + limit), lang.",
     "memory-quote": "Render memory quotes from a namespace. Query params: namespace, type, limit, lang.",
 };
-// Resource list — returned by resources/list MCP handler
+// Resource list — returned by resources/list MCP handler.
+// PR #1865 canonical: mimeType=text/html;profile=mcp-app + _meta.ui envelope.
 export function listUiResources() {
     return PRIMITIVES.map((p) => ({
         uri: `ui://vp/v1/${p}`,
         name: p,
         description: PRIMITIVE_DESCRIPTIONS[p],
-        mimeType: "text/html",
+        mimeType: MCP_UI_MIME_TYPE,
+        _meta: { ui: DEFAULT_UI_META },
     }));
 }
-// Resource read — dispatched by primitive name. Returns HTML inline.
+// Markdown fallback per Critical Rule #1: every UI resource MUST provide a
+// meaningful text-only payload for hosts without the UI extension. We render a
+// short hint + the primitive description so model + non-UI clients still get
+// usable output (raw HTML is not a substitute — it is the same content the iframe
+// would render, defeating the fallback purpose).
+function renderMarkdownFallback(uri, primitive) {
+    const desc = PRIMITIVE_DESCRIPTIONS[primitive];
+    return [
+        `# ${primitive}`,
+        "",
+        `This resource (${uri}) provides an interactive UI rendering for VantagePeers \`${primitive}\` data.`,
+        "",
+        desc,
+        "",
+        "Your client does not appear to support the MCP UI extension (`text/html;profile=mcp-app`). For a textual view of the same data, call the corresponding VantagePeers tool directly (e.g. `list_tasks`, `list_messages`, `list_diaries`, `list_missions`, `list_briefing_notes`, `recall`) with equivalent filters.",
+    ].join("\n");
+}
+// Resource read — dispatched by primitive name. Returns canonical
+// resources/read contents array: [HTML profile=mcp-app, markdown fallback].
 export async function readUiResource(uri, fetchConvex) {
     const parsed = parseUiUri(uri);
     if (!parsed) {
@@ -69,8 +100,9 @@ export async function readUiResource(uri, fetchConvex) {
     if (!PRIMITIVES.includes(parsed.primitive)) {
         throw new Error(`[VP UI Resources] Unknown primitive: ${parsed.primitive}. Available: ${PRIMITIVES.join(", ")}`);
     }
+    const primitive = parsed.primitive;
     let html;
-    switch (parsed.primitive) {
+    switch (primitive) {
         case "tasks-table":
             html = await renderTasksTable(parsed.query, fetchConvex);
             break;
@@ -93,8 +125,18 @@ export async function readUiResource(uri, fetchConvex) {
             throw new Error(`[VP UI Resources] Unimplemented primitive: ${parsed.primitive}`);
     }
     return {
-        uri,
-        mimeType: "text/html",
-        text: html,
+        contents: [
+            {
+                uri,
+                mimeType: MCP_UI_MIME_TYPE,
+                text: html,
+                _meta: { ui: DEFAULT_UI_META },
+            },
+            {
+                uri,
+                mimeType: "text/markdown",
+                text: renderMarkdownFallback(uri, primitive),
+            },
+        ],
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vantage-peers-mcp",
-  "version": "2.4.12",
+  "version": "2.4.13",
   "description": "MCP server for VantagePeers — shared memory, messaging, and task coordination for AI agent teams",
   "type": "module",
   "main": "./dist/server.js",
@@ -54,11 +54,18 @@
     "rag",
     "vector-search"
   ],
-  "author": "ElPi Corp",
+  "author": "VantageOS AI Orchestrator Team",
+  "contributors": [
+    "Pi (π) — Lead orchestrator",
+    "Laurent Perello — Founder, supervisor",
+    "ElPi Corp"
+  ],
   "license": "FSL-1.1-Apache-2.0",
   "dependencies": {
+    "@mcp-ui/server": "^6.1.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "convex": "^1.34.0",
+    "@vantageos/mosaic": "^0.1.2",
+    "convex": ">=1.0.0",
     "dotenv": "^17.4.2",
     "zod": "^4.3.6"
   },
@@ -66,14 +73,14 @@
     "convex": ">=1.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.9.3",
-    "@types/node": "^24.12.2"
+    "@types/node": "^24.12.2",
+    "typescript": "^5.9.3"
   },
   "overrides": {
     "path-to-regexp": "^8.4.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public",