vantage-peers-mcp 2.0.2 → 2.1.0

package/dist/server-http.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * VantagePeers MCP Server — HTTP Transport (Railway deploy)
+ *
+ * Wraps the same 82 tool definitions as the stdio server (server.ts) but
+ * serves them over Streamable HTTP for Claude web clients.
+ *
+ * Architecture:
+ *   - One Railway instance, many tenants / OAuth clients
+ *   - Each /mcp request authenticated via bearer token → either:
+ *       · master bearer (admin shortcut, scopeProfile=master)
+ *       · OAuth access_token (scoped, persisted in oauth_access_tokens)
+ *       · legacy mcpTenants bearer (internal orchestrators on their own deployment)
+ *   - Per-request ConvexHttpClient pointed at the resolved deployment
+ *   - Stateless mode: fresh McpServer + transport per request (no session state)
+ *
+ * OAuth state (clients, codes, access/refresh tokens, scope profiles) is
+ * persisted in Convex (see convex/oauth.ts) — no more in-memory Maps.
+ *
+ * ENV VARS (see README.md "HTTP deploy" section):
+ *   CONVEX_URL_INTERNAL   — internal VantagePeers Convex URL
+ *   BEARER_SECRET_MASTER  — master admin token
+ *   PUBLIC_BASE_URL       — public URL of this server (for OAuth discovery)
+ *   PORT                  — HTTP port (default 3000)
+ *   NODE_ENV              — set to "production" on Railway
+ */
+export {};

package/dist/server-http.js

@@ -0,0 +1,515 @@
+#!/usr/bin/env node
+/**
+ * VantagePeers MCP Server — HTTP Transport (Railway deploy)
+ *
+ * Wraps the same 82 tool definitions as the stdio server (server.ts) but
+ * serves them over Streamable HTTP for Claude web clients.
+ *
+ * Architecture:
+ *   - One Railway instance, many tenants / OAuth clients
+ *   - Each /mcp request authenticated via bearer token → either:
+ *       · master bearer (admin shortcut, scopeProfile=master)
+ *       · OAuth access_token (scoped, persisted in oauth_access_tokens)
+ *       · legacy mcpTenants bearer (internal orchestrators on their own deployment)
+ *   - Per-request ConvexHttpClient pointed at the resolved deployment
+ *   - Stateless mode: fresh McpServer + transport per request (no session state)
+ *
+ * OAuth state (clients, codes, access/refresh tokens, scope profiles) is
+ * persisted in Convex (see convex/oauth.ts) — no more in-memory Maps.
+ *
+ * ENV VARS (see README.md "HTTP deploy" section):
+ *   CONVEX_URL_INTERNAL   — internal VantagePeers Convex URL
+ *   BEARER_SECRET_MASTER  — master admin token
+ *   PUBLIC_BASE_URL       — public URL of this server (for OAuth discovery)
+ *   PORT                  — HTTP port (default 3000)
+ *   NODE_ENV              — set to "production" on Railway
+ */
+import { McpServer } 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";
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+const PUBLIC_BASE_URL = process.env.PUBLIC_BASE_URL ??
+    "https://vantage-peers-production.up.railway.app";
+const ACCESS_TOKEN_TTL_SECONDS = 3600; // 1 hour
+const REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 3600; // 30 days
+const AUTH_CODE_TTL_SECONDS = 600; // 10 minutes
+// Default profile for anonymous DCR (Claude.ai connector without pre-provisioning).
+// Deny-by-default; Pi must manually elevate a client post-registration via the
+// admin endpoints if they intend to grant real scopes.
+const DEFAULT_PUBLIC_DCR_PROFILE = "client-generic";
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function randomOpaqueToken() {
+    // 2× UUID → ~256 bits of entropy. Strip dashes for compactness.
+    return `${crypto.randomUUID()}${crypto.randomUUID()}`.replace(/-/g, "");
+}
+async function loadScopeProfile(profileId) {
+    return (await internalClient().query(
+    // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+    "oauth:getScopeProfile", { profileId }));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// App
+// ─────────────────────────────────────────────────────────────────────────────
+const app = new Hono();
+// CORS — Claude web sends requests from claude.ai origin
+app.use("*", cors({
+    origin: "*",
+    allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
+    allowHeaders: [
+        "Content-Type",
+        "Authorization",
+        "mcp-session-id",
+        "Last-Event-ID",
+        "mcp-protocol-version",
+    ],
+    exposeHeaders: ["mcp-session-id", "mcp-protocol-version"],
+}));
+// ─────────────────────────────────────────────────────────────────────────────
+// OAuth 2.0 discovery (unauthenticated)
+// ─────────────────────────────────────────────────────────────────────────────
+// RFC 9728 — OAuth 2.0 Protected Resource Metadata
+app.get("/.well-known/oauth-protected-resource", (c) => c.json({
+    resource: `${PUBLIC_BASE_URL}/mcp`,
+    authorization_servers: [PUBLIC_BASE_URL],
+    bearer_methods_supported: ["header"],
+    scopes_supported: ["vantage:read", "vantage:write"],
+}));
+// RFC 8414 — OAuth 2.0 Authorization Server Metadata
+app.get("/.well-known/oauth-authorization-server", (c) => c.json({
+    issuer: PUBLIC_BASE_URL,
+    authorization_endpoint: `${PUBLIC_BASE_URL}/authorize`,
+    token_endpoint: `${PUBLIC_BASE_URL}/token`,
+    registration_endpoint: `${PUBLIC_BASE_URL}/register`,
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    code_challenge_methods_supported: ["S256"],
+    token_endpoint_auth_methods_supported: [
+        "client_secret_post",
+        "client_secret_basic",
+        "none",
+    ],
+    scopes_supported: ["vantage:read", "vantage:write"],
+}));
+// ─────────────────────────────────────────────────────────────────────────────
+// RFC 7591 — Dynamic Client Registration
+// Anonymous registrations get DEFAULT_PUBLIC_DCR_PROFILE ("client-generic").
+// Pi must elevate the client via admin endpoint before real scopes are granted.
+// ─────────────────────────────────────────────────────────────────────────────
+app.post("/register", async (c) => {
+    let body = {};
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        // allow empty body — Claude sometimes posts nothing
+    }
+    const redirectUris = Array.isArray(body.redirect_uris)
+        ? body.redirect_uris
+        : [];
+    const clientId = crypto.randomUUID();
+    const clientSecret = randomOpaqueToken();
+    const clientSecretHash = await sha256Hex(clientSecret);
+    const clientName = typeof body.client_name === "string" ? body.client_name : "anonymous-dcr";
+    // SECURITY: public DCR is ALWAYS bound to the deny-by-default profile. Do
+    // NOT read body.scope_profile here — an attacker could register with
+    // {"scope_profile": "master"} and chain through /authorize + /token to
+    // obtain master-level access. Non-default profiles are provisioned only
+    // via POST /admin/oauth/clients (master-token gated).
+    const scopeProfile = DEFAULT_PUBLIC_DCR_PROFILE;
+    try {
+        await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:registerPublicClient", {
+            clientId,
+            clientSecretHash,
+            name: clientName,
+            redirectUris,
+            scopeProfile,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error("[oauth] /register failed:", message);
+        return c.json({ error: "server_error", error_description: "failed to persist client" }, 500);
+    }
+    return c.json({
+        client_id: clientId,
+        client_secret: clientSecret,
+        client_id_issued_at: Math.floor(Date.now() / 1000),
+        client_secret_expires_at: 0, // never expires
+        redirect_uris: redirectUris,
+        client_name: clientName,
+        token_endpoint_auth_method: "client_secret_post",
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        scope: "vantage:read vantage:write",
+        scope_profile: scopeProfile,
+    }, 201);
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// GET /authorize — auto-approve, no user consent UI (MVP, scoped)
+// ─────────────────────────────────────────────────────────────────────────────
+app.get("/authorize", async (c) => {
+    const q = c.req.query();
+    const clientId = q.client_id;
+    const redirectUri = q.redirect_uri;
+    const codeChallenge = q.code_challenge;
+    const codeChallengeMethod = q.code_challenge_method ?? "S256";
+    const state = q.state;
+    const scope = q.scope ?? "vantage:read vantage:write";
+    const responseType = q.response_type;
+    if (!clientId || !redirectUri || !codeChallenge) {
+        return c.json({
+            error: "invalid_request",
+            error_description: "missing client_id, redirect_uri, or code_challenge",
+        }, 400);
+    }
+    if (responseType && responseType !== "code") {
+        return c.json({ error: "unsupported_response_type" }, 400);
+    }
+    if (codeChallengeMethod !== "S256") {
+        return c.json({ error: "invalid_request", error_description: "only S256 supported" }, 400);
+    }
+    // Verify the client exists and is not revoked
+    const client = (await internalClient().query(
+    // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+    "oauth:getClientByClientId", { clientId }));
+    if (!client) {
+        return c.json({ error: "invalid_client", error_description: "unknown client_id" }, 400);
+    }
+    if (client.revokedAt !== undefined) {
+        return c.json({ error: "invalid_client", error_description: "client revoked" }, 400);
+    }
+    const masterTokenForAuthCode = process.env.BEARER_SECRET_MASTER;
+    if (!masterTokenForAuthCode) {
+        console.error("[oauth] BEARER_SECRET_MASTER not set — cannot mint authorization code");
+        return c.json({ error: "server_misconfigured" }, 500);
+    }
+    const code = randomOpaqueToken();
+    await internalClient().mutation(
+    // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+    "oauth:createAuthorizationCode", {
+        callerToken: masterTokenForAuthCode,
+        code,
+        clientId,
+        redirectUri,
+        codeChallenge,
+        scope,
+        // userId defaults to the scope profile (1:1 with the client by default).
+        // When future multi-user consent UI ships, this resolves to the Clerk user.
+        userId: client.scopeProfile,
+        expiresAt: Date.now() + AUTH_CODE_TTL_SECONDS * 1000,
+    });
+    const redirect = new URL(redirectUri);
+    redirect.searchParams.set("code", code);
+    if (state)
+        redirect.searchParams.set("state", state);
+    return c.redirect(redirect.toString(), 302);
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// POST /token — authorization_code + refresh_token grants
+// ─────────────────────────────────────────────────────────────────────────────
+app.post("/token", async (c) => {
+    const contentType = c.req.header("Content-Type") ?? "";
+    let body = {};
+    if (contentType.includes("application/x-www-form-urlencoded")) {
+        const text = await c.req.text();
+        body = Object.fromEntries(new URLSearchParams(text));
+    }
+    else {
+        try {
+            body = (await c.req.json());
+        }
+        catch {
+            return c.json({ error: "invalid_request", error_description: "unreadable body" }, 400);
+        }
+    }
+    const grantType = body.grant_type;
+    // ── authorization_code grant ────────────────────────────────────────────
+    if (grantType === "authorization_code") {
+        const { code, code_verifier: codeVerifier, redirect_uri: redirectUri, client_id: clientId, } = body;
+        if (!code || !codeVerifier) {
+            return c.json({
+                error: "invalid_request",
+                error_description: "missing code or code_verifier",
+            }, 400);
+        }
+        // Consume code (atomic: delete + return)
+        const record = (await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:consumeAuthorizationCode", { code }));
+        if (!record) {
+            return c.json({ error: "invalid_grant", error_description: "unknown code" }, 400);
+        }
+        if (Date.now() > record.expiresAt) {
+            return c.json({ error: "invalid_grant", error_description: "code expired" }, 400);
+        }
+        if (redirectUri && redirectUri !== record.redirectUri) {
+            return c.json({
+                error: "invalid_grant",
+                error_description: "redirect_uri mismatch",
+            }, 400);
+        }
+        if (clientId && clientId !== record.clientId) {
+            return c.json({ error: "invalid_grant", error_description: "client_id mismatch" }, 400);
+        }
+        // PKCE: base64url(SHA256(code_verifier)) === code_challenge
+        const challengeCheck = await sha256Base64Url(codeVerifier);
+        if (challengeCheck !== record.codeChallenge) {
+            return c.json({
+                error: "invalid_grant",
+                error_description: "PKCE verification failed",
+            }, 400);
+        }
+        // Resolve the client's scope profile (materialised into the token row)
+        const client = (await internalClient().query(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:getClientByClientId", { clientId: record.clientId }));
+        if (!client || client.revokedAt !== undefined) {
+            return c.json({ error: "invalid_client" }, 400);
+        }
+        const profile = await loadScopeProfile(client.scopeProfile);
+        if (!profile) {
+            console.error("[oauth] scope_profile not found during token issue:", client.scopeProfile);
+            return c.json({ error: "server_error" }, 500);
+        }
+        // Issue access_token + refresh_token
+        const masterTokenForIssue = process.env.BEARER_SECRET_MASTER;
+        if (!masterTokenForIssue) {
+            console.error("[oauth] BEARER_SECRET_MASTER not set — cannot mint tokens");
+            return c.json({ error: "server_misconfigured" }, 500);
+        }
+        const accessToken = randomOpaqueToken();
+        const refreshToken = randomOpaqueToken();
+        const accessTokenHash = await sha256Hex(accessToken);
+        const refreshTokenHash = await sha256Hex(refreshToken);
+        const now = Date.now();
+        await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:createAccessToken", {
+            callerToken: masterTokenForIssue,
+            tokenHash: accessTokenHash,
+            clientId: record.clientId,
+            userId: record.userId,
+            scopes: record.scope.split(/\s+/).filter(Boolean),
+            scopeProfile: profile.profileId,
+            fromAllowList: profile.fromAllowList,
+            namespaceReadPrefixes: profile.namespaceReadPrefixes,
+            namespaceWritePrefixes: profile.namespaceWritePrefixes,
+            expiresAt: now + ACCESS_TOKEN_TTL_SECONDS * 1000,
+            refreshTokenHash,
+        });
+        await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:createRefreshToken", {
+            callerToken: masterTokenForIssue,
+            tokenHash: refreshTokenHash,
+            clientId: record.clientId,
+            userId: record.userId,
+            scopeProfile: profile.profileId,
+            expiresAt: now + REFRESH_TOKEN_TTL_SECONDS * 1000,
+        });
+        return c.json({
+            access_token: accessToken,
+            token_type: "Bearer",
+            expires_in: ACCESS_TOKEN_TTL_SECONDS,
+            refresh_token: refreshToken,
+            scope: record.scope,
+        });
+    }
+    // ── refresh_token grant ─────────────────────────────────────────────────
+    if (grantType === "refresh_token") {
+        const refreshTokenRaw = body.refresh_token;
+        if (!refreshTokenRaw) {
+            return c.json({ error: "invalid_request" }, 400);
+        }
+        const refreshTokenHash = await sha256Hex(refreshTokenRaw);
+        const record = (await internalClient().query(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:getRefreshTokenByHash", { tokenHash: refreshTokenHash }));
+        if (!record) {
+            return c.json({ error: "invalid_grant" }, 400);
+        }
+        const profile = await loadScopeProfile(record.scopeProfile);
+        if (!profile) {
+            return c.json({ error: "server_error" }, 500);
+        }
+        const masterTokenForRefresh = process.env.BEARER_SECRET_MASTER;
+        if (!masterTokenForRefresh) {
+            console.error("[oauth] BEARER_SECRET_MASTER not set — cannot refresh token");
+            return c.json({ error: "server_misconfigured" }, 500);
+        }
+        const accessToken = randomOpaqueToken();
+        const accessTokenHash = await sha256Hex(accessToken);
+        const now = Date.now();
+        await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:createAccessToken", {
+            callerToken: masterTokenForRefresh,
+            tokenHash: accessTokenHash,
+            clientId: record.clientId,
+            userId: record.userId,
+            scopes: ["vantage:read", "vantage:write"],
+            scopeProfile: profile.profileId,
+            fromAllowList: profile.fromAllowList,
+            namespaceReadPrefixes: profile.namespaceReadPrefixes,
+            namespaceWritePrefixes: profile.namespaceWritePrefixes,
+            expiresAt: now + ACCESS_TOKEN_TTL_SECONDS * 1000,
+            refreshTokenHash,
+        });
+        return c.json({
+            access_token: accessToken,
+            token_type: "Bearer",
+            expires_in: ACCESS_TOKEN_TTL_SECONDS,
+            refresh_token: refreshTokenRaw, // reused
+            scope: "vantage:read vantage:write",
+        });
+    }
+    return c.json({ error: "unsupported_grant_type" }, 400);
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Health check — unauthenticated, used by Railway health probes
+// ─────────────────────────────────────────────────────────────────────────────
+app.get("/health", (c) => c.json({
+    status: "ok",
+    service: "vantage-peers-mcp-http",
+    version: "2.1.0",
+    transport: "streamable-http",
+    oauth: "scoped-tokens",
+}));
+// ─────────────────────────────────────────────────────────────────────────────
+// Admin endpoints — master token only
+// Used by Pi to provision OAuth clients for external users (Marie, VIP).
+// ─────────────────────────────────────────────────────────────────────────────
+const admin = new Hono();
+admin.use("*", masterOnlyMiddleware());
+// POST /admin/oauth/clients  — create client, returns raw secret ONCE
+admin.post("/oauth/clients", async (c) => {
+    const masterToken = process.env.BEARER_SECRET_MASTER;
+    if (!masterToken) {
+        return c.json({ error: "server_misconfigured" }, 500);
+    }
+    let body = {};
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_request" }, 400);
+    }
+    const name = typeof body.name === "string" ? body.name : null;
+    const scopeProfile = typeof body.scope_profile === "string" ? body.scope_profile : null;
+    const redirectUris = Array.isArray(body.redirect_uris)
+        ? body.redirect_uris
+        : [];
+    if (!name || !scopeProfile) {
+        return c.json({
+            error: "invalid_request",
+            error_description: "name and scope_profile are required",
+        }, 400);
+    }
+    const profile = await loadScopeProfile(scopeProfile);
+    if (!profile) {
+        return c.json({ error: "invalid_scope_profile", scopeProfile }, 400);
+    }
+    const clientId = crypto.randomUUID();
+    const clientSecret = randomOpaqueToken();
+    const clientSecretHash = await sha256Hex(clientSecret);
+    try {
+        await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:createClient", {
+            callerToken: masterToken,
+            clientId,
+            clientSecretHash,
+            name,
+            redirectUris,
+            scopeProfile,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error("[admin] createClient failed:", message);
+        return c.json({ error: "server_error", detail: message }, 500);
+    }
+    return c.json({
+        client_id: clientId,
+        client_secret: clientSecret, // RAW — returned once, never again
+        name,
+        scope_profile: scopeProfile,
+        redirect_uris: redirectUris,
+    }, 201);
+});
+// GET /admin/oauth/clients  — list (no secrets)
+admin.get("/oauth/clients", async (c) => {
+    const masterToken = process.env.BEARER_SECRET_MASTER;
+    if (!masterToken)
+        return c.json({ error: "server_misconfigured" }, 500);
+    const rows = await internalClient().query(
+    // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+    "oauth:listClients", { callerToken: masterToken });
+    return c.json({ clients: rows });
+});
+// DELETE /admin/oauth/clients/:clientId  — revoke client + all its tokens
+admin.delete("/oauth/clients/:clientId", async (c) => {
+    const masterToken = process.env.BEARER_SECRET_MASTER;
+    if (!masterToken)
+        return c.json({ error: "server_misconfigured" }, 500);
+    const clientId = c.req.param("clientId");
+    const result = await internalClient().mutation(
+    // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+    "oauth:deleteClient", { callerToken: masterToken, clientId });
+    return c.json(result);
+});
+// POST /admin/oauth/seed-profiles — idempotent; safe to re-run after deploy
+admin.post("/oauth/seed-profiles", async (c) => {
+    const masterToken = process.env.BEARER_SECRET_MASTER;
+    if (!masterToken)
+        return c.json({ error: "server_misconfigured" }, 500);
+    const created = await internalClient().mutation(
+    // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+    "oauth:seedDefaultProfiles", { callerToken: masterToken });
+    return c.json({ created });
+});
+app.route("/admin", admin);
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP endpoint — authenticated, stateless per-request server
+// ─────────────────────────────────────────────────────────────────────────────
+app.all("/mcp", bearerAuthMiddleware(), async (c) => {
+    const tenant = c.get("tenant");
+    const oauthCtx = c.get("oauthContext");
+    // Per-request Convex client bound to the resolved deployment
+    const convex = new ConvexHttpClient(tenant.convexUrl);
+    // Fresh McpServer per request — stateless mode, no session leakage
+    const server = new McpServer({
+        name: "vantage-peers",
+        version: "2.1.0",
+    });
+    registerTools(server, convex, oauthCtx);
+    const transport = new WebStandardStreamableHTTPServerTransport();
+    await server.connect(transport);
+    return transport.handleRequest(c.req.raw);
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Start
+// ─────────────────────────────────────────────────────────────────────────────
+const PORT = Number(process.env.PORT ?? 3000);
+const HOSTNAME = "0.0.0.0";
+// Explicit Bun.serve() — does not rely on default-export auto-detection,
+// which can fail when started via `bun run <file>` (vs `bun <file>`).
+// @ts-expect-error — Bun global available at runtime on Railway
+const server = Bun.serve({
+    port: PORT,
+    hostname: HOSTNAME,
+    fetch: app.fetch,
+});
+console.log(`[vantage-peers-mcp] HTTP transport listening on ${server.hostname}:${server.port}`);
+console.log(`[vantage-peers-mcp] Health: http://${server.hostname}:${server.port}/health`);
+console.log(`[vantage-peers-mcp] MCP:    http://${server.hostname}:${server.port}/mcp`);

package/dist/server.js

@@ -50,11 +50,11 @@ const memoryTypeSchema = z
     .enum(["user", "feedback", "project", "reference", "episode"])
     .describe("Memory classification type");
 // Open string — validated at runtime by the backend (issue #132).
-// Known defaults: pi, tau, phi, sigma, omega, zeta, eta, alpha, lambda, victor, system.
+// Known defaults: pi, tau, phi, sigma, omega, zeta, eta, kappa, alpha, lambda, victor, system.
 // New internal orchestrators use Greek letters (lowercase); external client orchestrators use free lowercase strings.
 const creatorSchema = z
     .string()
-    .describe("Orchestrator role name (e.g. pi, tau, phi, sigma, omega, zeta, eta, alpha, lambda, victor, laurent, or any custom client role (lowercase string)). " +
+    .describe("Orchestrator role name (e.g. pi, tau, phi, sigma, omega, zeta, eta, kappa, alpha, lambda, victor, laurent, or any custom client role (lowercase string)). " +
     "New internal orchestrators use Greek letters (lowercase); external client orchestrators use free lowercase strings.");
 const severitySchema = z
     .enum(["critical", "major", "minor"])
@@ -474,7 +474,7 @@ server.tool("list_memories", "List active memories for a namespace, ordered newe
 server.tool("send_message", "Send a message to one, many, or all orchestrators. " +
     "channel: 'broadcast' = all, 'tau' = role DM, 'pi-vps' = instance DM, 'tau,phi' = multi. " +
     "Creates message + one receipt per recipient. Replaces claude-peers send_message.", {
-    from: creatorSchema.describe("Sender role (e.g. pi, tau, phi, sigma, alpha, lambda, victor, or any custom role)"),
+    from: creatorSchema.describe("Sender role (e.g. pi, tau, phi, sigma, omega, zeta, eta, kappa, alpha, lambda, victor, or any custom role)"),
     fromInstanceId: z
         .string()
         .optional()
@@ -521,7 +521,7 @@ server.tool("send_message", "Send a message to one, many, or all orchestrators.
 server.tool("check_messages", "Check for unread messages. Returns messages with receiptIds for marking as read. " +
     "If recipientInstanceId is provided, returns instance-targeted + role-level messages. " +
     "Replaces claude-peers check_messages.", {
-    recipient: creatorSchema.describe("Orchestrator role (e.g. pi, tau, phi, sigma, alpha, lambda, victor, or any custom role)"),
+    recipient: creatorSchema.describe("Orchestrator role (e.g. pi, tau, phi, sigma, omega, zeta, eta, kappa, alpha, lambda, victor, or any custom role)"),
     recipientInstanceId: z
         .string()
         .optional()
@@ -752,7 +752,7 @@ server.tool("list_broadcast_status", "Show who read a broadcast message and who
 // Open string — validated at runtime by the backend (issue #132).
 const assigneeSchema = z
     .string()
-    .describe("Orchestrator to assign to (e.g. pi, tau, phi, sigma, omega, zeta, eta, alpha, lambda, victor, laurent, or any custom client role (lowercase string)). " +
+    .describe("Orchestrator to assign to (e.g. pi, tau, phi, sigma, omega, zeta, eta, kappa, alpha, lambda, victor, laurent, or any custom client role (lowercase string)). " +
     "New internal orchestrators use Greek letters (lowercase); external client orchestrators use free lowercase strings.");
 const prioritySchema = z
     .enum(["urgent", "high", "medium", "low"])
@@ -1455,6 +1455,60 @@ server.tool("create_briefing_note", "Create a briefing note — a structured rec
     }
 });
 // ─────────────────────────────────────────────────────────────────────────────
+// Tool: update_briefing_note
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("update_briefing_note", "Update an existing briefing note. Partial-update — only provided fields are patched. " +
+    "Arrays (decisions, linkedMemoryIds, participants) are FULL REPLACE, not append. " +
+    "RBAC : caller must be createdBy or 'system'. " +
+    "Sets updatedAt + updatedBy automatically.", {
+    noteId: z
+        .string()
+        .describe("Convex document ID of the briefing note to update"),
+    callerOrchestrator: creatorSchema.describe("Orchestrator role making the update — must match createdBy or be 'system' (RBAC deny-by-default)"),
+    title: z.string().optional().describe("Optional new title — full replace"),
+    topic: z.string().optional().describe("Optional new topic — full replace"),
+    participants: z
+        .array(z.string())
+        .optional()
+        .describe("Optional new participants array — full replace, not append"),
+    content: z
+        .string()
+        .optional()
+        .describe("Optional new content — full replace"),
+    decisions: z
+        .array(z.string())
+        .optional()
+        .describe("Optional new decisions array — full replace, not append"),
+    linkedMemoryIds: z
+        .array(z.string())
+        .optional()
+        .describe("Optional new linkedMemoryIds array — full replace, not append. Each ID must point to memories table."),
+}, async ({ noteId, callerOrchestrator, title, topic, participants, content, decisions, linkedMemoryIds, }) => {
+    try {
+        await convex.mutation("briefingNotes:update", {
+            noteId: noteId,
+            callerOrchestrator,
+            title,
+            topic,
+            participants,
+            content,
+            decisions,
+            linkedMemoryIds: linkedMemoryIds,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ noteId, updated: true }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return mcpError(error.message ?? String(error));
+    }
+});
+// ─────────────────────────────────────────────────────────────────────────────
 // Tool: list_briefing_notes
 // ─────────────────────────────────────────────────────────────────────────────
 server.tool("list_briefing_notes", "List briefing notes, optionally filtered by topic. Returns newest first.", {