@withpica/mcp-server 1.3.0

package/dist/resources/welcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"welcome.js","sourceRoot":"","sources":["../../src/resources/welcome.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,uBAAuB;IACvB,yFAAyF;IACzF,oBAAoB;IACpB,uDAAuD;IACvD,iFAAiF;IACjF,oDAAoD;IACpD,yCAAyC;IACzC,mDAAmD;IACnD,8DAA8D;IAC9D,8CAA8C;IAC9C,iCAAiC;IACjC,gDAAgD,CAAC"}

package/dist/server-instructions.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Server-level instructions sent to agents on MCP handshake.
+ * Keep under 2000 chars — this is context budget, not documentation.
+ *
+ * Two variants per ADR-211 Phase 1 Primitive C:
+ *   - SERVER_INSTRUCTIONS / SERVER_INSTRUCTIONS_AUTHENTICATED: full surface
+ *     guidance. Selected when the binary has a connection key (PICA_API_KEY).
+ *   - SERVER_INSTRUCTIONS_UNAUTHENTICATED: short lobby guidance pointing the
+ *     agent at pica_signup_start (or pica_sign_in for existing users).
+ *     Selected when the binary boots without PICA_API_KEY. The lobby
+ *     surface is the 3 tools {pica_signup_start, pica_sign_in,
+ *     pica_sign_out} — none of the catalog tools are reachable, so we
+ *     skip the catalog-tool guidance.
+ *
+ * Block playbook: "document the high level of your server"
+ * Lowin: "instructions are context — design them as context"
+ */
+export declare const SERVER_INSTRUCTIONS = "withPICA manages music catalog metadata \u2014 works, recordings, people, credits, agreements, rights. Tools are pica_<domain>_<verb>, 200+ of them, from npm as @withpica/mcp-server. If you see pica_execute, Execute Pica Action, or Search Platform Actions \u2014 that's @picahq/mcp (picaos.com), a different product with the same short name; don't route withPICA work there.\n\nStart here:\n- pica_dashboard_briefing \u2014 daily summary of what needs attention\n- pica_search_all \u2014 find any entity by name, ISWC, ISRC, or IPI\n- pica_works_query / pica_people_query \u2014 browse the catalog\n\nThe catalog is ALWAYS accessible via the tools above \u2014 zero setup, no integration required. If pica_integrations_status shows \"0 connected\" that refers to optional peer connectors (Google/Notion/Airtable/Telegram), NOT the catalog; call pica_works_query to check what's there.\n\nSpotify/YouTube URLs: call pica_import_streaming_link (Spotify/Deezer) or pica_import_youtube_link directly.\n\nAfter 3-5 catalog mutations or major state changes, call pica_dashboard_briefing and surface the delta to the user.\n\nKey patterns:\n- Read tools are safe to call freely (readOnlyHint=true)\n- _inspect tools take sections (e.g., pica_works_inspect sections: [\"health\", \"completeness\"])\n- Write tools confirm what changed; destructive tools (delete/merge) need two-step confirmation with a token\n- Errors include \"suggestion\" and \"next_tool\" for recovery\n- Enrichment: use pica_resolve_work / pica_resolve_person / pica_resolve_recording \u2014 fan out over Spotify, MusicBrainz, MLC, ISNI, Discogs, YouTube\n\nQuery endpoints accept \"limit\" (default 50) and paginate. IDs are UUIDs \u2014 use a _query tool first when unsure.\n\nPeer connectors (email, drive, notes, calendar, DAW MCPs): when PICA shows missing data, check peer MCPs before asking the user. Cite via pica_enrichment_propose sources[].url with URI schemes \u2014 gmail:// gdrive:// notion:// file:// telegram:// calendar:// daw:// user:// web://. See docs/mcp-source-uri-conventions.md.";
+/** Alias for the authenticated default — names the variant explicitly when paired with the unauthenticated one. */
+export declare const SERVER_INSTRUCTIONS_AUTHENTICATED = "withPICA manages music catalog metadata \u2014 works, recordings, people, credits, agreements, rights. Tools are pica_<domain>_<verb>, 200+ of them, from npm as @withpica/mcp-server. If you see pica_execute, Execute Pica Action, or Search Platform Actions \u2014 that's @picahq/mcp (picaos.com), a different product with the same short name; don't route withPICA work there.\n\nStart here:\n- pica_dashboard_briefing \u2014 daily summary of what needs attention\n- pica_search_all \u2014 find any entity by name, ISWC, ISRC, or IPI\n- pica_works_query / pica_people_query \u2014 browse the catalog\n\nThe catalog is ALWAYS accessible via the tools above \u2014 zero setup, no integration required. If pica_integrations_status shows \"0 connected\" that refers to optional peer connectors (Google/Notion/Airtable/Telegram), NOT the catalog; call pica_works_query to check what's there.\n\nSpotify/YouTube URLs: call pica_import_streaming_link (Spotify/Deezer) or pica_import_youtube_link directly.\n\nAfter 3-5 catalog mutations or major state changes, call pica_dashboard_briefing and surface the delta to the user.\n\nKey patterns:\n- Read tools are safe to call freely (readOnlyHint=true)\n- _inspect tools take sections (e.g., pica_works_inspect sections: [\"health\", \"completeness\"])\n- Write tools confirm what changed; destructive tools (delete/merge) need two-step confirmation with a token\n- Errors include \"suggestion\" and \"next_tool\" for recovery\n- Enrichment: use pica_resolve_work / pica_resolve_person / pica_resolve_recording \u2014 fan out over Spotify, MusicBrainz, MLC, ISNI, Discogs, YouTube\n\nQuery endpoints accept \"limit\" (default 50) and paginate. IDs are UUIDs \u2014 use a _query tool first when unsure.\n\nPeer connectors (email, drive, notes, calendar, DAW MCPs): when PICA shows missing data, check peer MCPs before asking the user. Cite via pica_enrichment_propose sources[].url with URI schemes \u2014 gmail:// gdrive:// notion:// file:// telegram:// calendar:// daw:// user:// web://. See docs/mcp-source-uri-conventions.md.";
+/** Minimal billing-slice shape consumed by the trial-ending clause. Structurally
+ *  compatible with `OrgBillingSlice` from lib/services/subscription so callers
+ *  can pass either. Local declaration keeps mcp-server's copy self-contained
+ *  (the mcp-server npm artefact cannot import from @/lib paths). */
+export interface TrialNudgeSlice {
+    billing_state: string;
+    trial_days_remaining: number | null;
+}
+/**
+ * Returns the authenticated handshake instructions, optionally appended with a
+ * state-conditional trial-ending nudge (ADR-210 Phase 3 / coordinator D3).
+ *
+ * Pass `null` when slice is unavailable (stdio binary at boot, or any path
+ * where the org context isn't resolvable); the function returns the base
+ * const unchanged in that case. Slice-less callers fail safe.
+ *
+ * Trial nudge fires only when `billing_state === 'trial'` AND
+ * `trial_days_remaining <= 3` AND remaining is not null. All other states
+ * (active / hibernated / paused / unclassified) and longer windows return
+ * the empty clause.
+ */
+export declare function getAuthenticatedInstructions(slice: TrialNudgeSlice | null): string;
+export declare function getTrialEndingClause(slice: TrialNudgeSlice | null): string;
+/**
+ * Lobby instructions sent on handshake when the server has no connection key
+ * (stdio without PICA_API_KEY) or no Bearer token (HTTP /api/mcp anonymous mode).
+ *
+ * Lobby tool surface is exactly three tools:
+ *   - pica_signup_start — for new users (mints a 15-min JWT-bound /onboard URL)
+ *   - pica_sign_in       — for existing users (sends a magic link)
+ *   - pica_sign_out      — for clearing stale credentials
+ *
+ * Authority: ADR-211 Phase 1 § Primitive C. Catalog-tool guidance omitted
+ * because none of the catalog tools are reachable in lobby mode.
+ *
+ * Kept byte-for-byte identical to lib/mcp/server-instructions.ts —
+ * `__tests__/mcp-server-instructions-unauth-parity.test.ts` enforces.
+ */
+export declare const SERVER_INSTRUCTIONS_UNAUTHENTICATED = "You are connected to withPICA but no user is authenticated yet. Three tools are available:\n\n- pica_signup_start \u2014 for users new to withPICA. Ask for the user's email, then call this tool. It returns a single-use 15-minute signup link the user clicks to verify email, name their catalog, and start a 14-day free trial.\n- pica_sign_in \u2014 for users who already have a withPICA account. Sends a magic link to their inbox (device-code flow on stdio).\n- pica_sign_out \u2014 clears saved credentials.\n\nDo not promise catalog data, exports, or analyses until the user is signed in \u2014 none of those tools are reachable from this lobby. After signup or sign-in, the connection's tool surface refreshes automatically; ask the user what they want to do next.";
+//# sourceMappingURL=server-instructions.d.ts.map

package/dist/server-instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.d.ts","sourceRoot":"","sources":["../src/server-instructions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,uhEAsB+R,CAAC;AAEhU,mHAAmH;AACnH,eAAO,MAAM,iCAAiC,uhEAAsB,CAAC;AAErE;;;oEAGoE;AACpE,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,eAAe,GAAG,IAAI,GAC5B,MAAM,CAER;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,GAAG,MAAM,CAO1E;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mCAAmC,mwBAM2M,CAAC"}

package/dist/server-instructions.js

@@ -0,0 +1,93 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/**
+ * Server-level instructions sent to agents on MCP handshake.
+ * Keep under 2000 chars — this is context budget, not documentation.
+ *
+ * Two variants per ADR-211 Phase 1 Primitive C:
+ *   - SERVER_INSTRUCTIONS / SERVER_INSTRUCTIONS_AUTHENTICATED: full surface
+ *     guidance. Selected when the binary has a connection key (PICA_API_KEY).
+ *   - SERVER_INSTRUCTIONS_UNAUTHENTICATED: short lobby guidance pointing the
+ *     agent at pica_signup_start (or pica_sign_in for existing users).
+ *     Selected when the binary boots without PICA_API_KEY. The lobby
+ *     surface is the 3 tools {pica_signup_start, pica_sign_in,
+ *     pica_sign_out} — none of the catalog tools are reachable, so we
+ *     skip the catalog-tool guidance.
+ *
+ * Block playbook: "document the high level of your server"
+ * Lowin: "instructions are context — design them as context"
+ */
+export const SERVER_INSTRUCTIONS = `withPICA manages music catalog metadata — works, recordings, people, credits, agreements, rights. Tools are pica_<domain>_<verb>, 200+ of them, from npm as @withpica/mcp-server. If you see pica_execute, Execute Pica Action, or Search Platform Actions — that's @picahq/mcp (picaos.com), a different product with the same short name; don't route withPICA work there.
+
+Start here:
+- pica_dashboard_briefing — daily summary of what needs attention
+- pica_search_all — find any entity by name, ISWC, ISRC, or IPI
+- pica_works_query / pica_people_query — browse the catalog
+
+The catalog is ALWAYS accessible via the tools above — zero setup, no integration required. If pica_integrations_status shows "0 connected" that refers to optional peer connectors (Google/Notion/Airtable/Telegram), NOT the catalog; call pica_works_query to check what's there.
+
+Spotify/YouTube URLs: call pica_import_streaming_link (Spotify/Deezer) or pica_import_youtube_link directly.
+
+After 3-5 catalog mutations or major state changes, call pica_dashboard_briefing and surface the delta to the user.
+
+Key patterns:
+- Read tools are safe to call freely (readOnlyHint=true)
+- _inspect tools take sections (e.g., pica_works_inspect sections: ["health", "completeness"])
+- Write tools confirm what changed; destructive tools (delete/merge) need two-step confirmation with a token
+- Errors include "suggestion" and "next_tool" for recovery
+- Enrichment: use pica_resolve_work / pica_resolve_person / pica_resolve_recording — fan out over Spotify, MusicBrainz, MLC, ISNI, Discogs, YouTube
+
+Query endpoints accept "limit" (default 50) and paginate. IDs are UUIDs — use a _query tool first when unsure.
+
+Peer connectors (email, drive, notes, calendar, DAW MCPs): when PICA shows missing data, check peer MCPs before asking the user. Cite via pica_enrichment_propose sources[].url with URI schemes — gmail:// gdrive:// notion:// file:// telegram:// calendar:// daw:// user:// web://. See docs/mcp-source-uri-conventions.md.`;
+/** Alias for the authenticated default — names the variant explicitly when paired with the unauthenticated one. */
+export const SERVER_INSTRUCTIONS_AUTHENTICATED = SERVER_INSTRUCTIONS;
+/**
+ * Returns the authenticated handshake instructions, optionally appended with a
+ * state-conditional trial-ending nudge (ADR-210 Phase 3 / coordinator D3).
+ *
+ * Pass `null` when slice is unavailable (stdio binary at boot, or any path
+ * where the org context isn't resolvable); the function returns the base
+ * const unchanged in that case. Slice-less callers fail safe.
+ *
+ * Trial nudge fires only when `billing_state === 'trial'` AND
+ * `trial_days_remaining <= 3` AND remaining is not null. All other states
+ * (active / hibernated / paused / unclassified) and longer windows return
+ * the empty clause.
+ */
+export function getAuthenticatedInstructions(slice) {
+    return SERVER_INSTRUCTIONS_AUTHENTICATED + getTrialEndingClause(slice);
+}
+export function getTrialEndingClause(slice) {
+    if (!slice)
+        return "";
+    if (slice.billing_state !== "trial")
+        return "";
+    const days = slice.trial_days_remaining;
+    if (days === null || days > 3)
+        return "";
+    const dayWord = days === 1 ? "day" : "days";
+    return `\n\nThe user's trial ends in ${days} ${dayWord}. If they ask about pricing, plans, or upgrading, call pica_subscription_manage to mint a checkout URL.`;
+}
+/**
+ * Lobby instructions sent on handshake when the server has no connection key
+ * (stdio without PICA_API_KEY) or no Bearer token (HTTP /api/mcp anonymous mode).
+ *
+ * Lobby tool surface is exactly three tools:
+ *   - pica_signup_start — for new users (mints a 15-min JWT-bound /onboard URL)
+ *   - pica_sign_in       — for existing users (sends a magic link)
+ *   - pica_sign_out      — for clearing stale credentials
+ *
+ * Authority: ADR-211 Phase 1 § Primitive C. Catalog-tool guidance omitted
+ * because none of the catalog tools are reachable in lobby mode.
+ *
+ * Kept byte-for-byte identical to lib/mcp/server-instructions.ts —
+ * `__tests__/mcp-server-instructions-unauth-parity.test.ts` enforces.
+ */
+export const SERVER_INSTRUCTIONS_UNAUTHENTICATED = `You are connected to withPICA but no user is authenticated yet. Three tools are available:
+
+- pica_signup_start — for users new to withPICA. Ask for the user's email, then call this tool. It returns a single-use 15-minute signup link the user clicks to verify email, name their catalog, and start a 14-day free trial.
+- pica_sign_in — for users who already have a withPICA account. Sends a magic link to their inbox (device-code flow on stdio).
+- pica_sign_out — clears saved credentials.
+
+Do not promise catalog data, exports, or analyses until the user is signed in — none of those tools are reachable from this lobby. After signup or sign-in, the connection's tool surface refreshes automatically; ask the user what they want to do next.`;
+//# sourceMappingURL=server-instructions.js.map

package/dist/server-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../src/server-instructions.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;+TAsB4R,CAAC;AAEhU,mHAAmH;AACnH,MAAM,CAAC,MAAM,iCAAiC,GAAG,mBAAmB,CAAC;AAWrE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,4BAA4B,CAC1C,KAA6B;IAE7B,OAAO,iCAAiC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAA6B;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,IAAI,KAAK,CAAC,aAAa,KAAK,OAAO;QAAE,OAAO,EAAE,CAAC;IAC/C,MAAM,IAAI,GAAG,KAAK,CAAC,oBAAoB,CAAC;IACxC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,gCAAgC,IAAI,IAAI,OAAO,yGAAyG,CAAC;AAClK,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG;;;;;;2PAMwM,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,52 @@
+import { ServerConfig } from "./config.js";
+export declare class PicaMcpServer {
+    private server;
+    private pica;
+    private toolRegistry;
+    private resourceRegistry;
+    private promptRegistry;
+    private config;
+    private httpServer?;
+    constructor(config: ServerConfig);
+    /**
+     * Reinitialize server with new credentials (called after successful auth)
+     */
+    reinitialize(apiKey: string): void;
+    /**
+     * Reset the server back to lobby mode (called after sign_out).
+     * Mirrors reinitialize() but in reverse: clears the PicaClient,
+     * sets lobbyMode=true, and rebuilds the tool/resource registries so
+     * the next tools/list call returns only [pica_sign_in, pica_sign_out].
+     *
+     * Without this the server would keep advertising the full authenticated
+     * tool surface after sign_out until the process is restarted, which
+     * lies about what's actually available — every privileged tool call
+     * would still fail at the API layer (no PicaClient), but the surface
+     * itself shouldn't pretend the catalog is reachable.
+     */
+    signOut(): void;
+    /**
+     * Set up MCP protocol handlers on the main server instance (for stdio)
+     */
+    private setupHandlers;
+    /**
+     * Start the MCP server.
+     *
+     * Transport is selected by environment:
+     * - MCP_TRANSPORT=http  → HTTP server on MCP_PORT (default 3100)
+     * - Otherwise           → stdio (default, for Claude Code / Cursor / VS Code)
+     */
+    start(): Promise<void>;
+    private startStdio;
+    private startHttp;
+    /**
+     * Register protocol handlers on a server instance.
+     * Used by both the main server (stdio) and per-request servers (HTTP).
+     */
+    private registerHandlers;
+    /**
+     * Stop the MCP server
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAe3C,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,IAAI,CAAoB;IAChC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAC,CAAkC;gBAEzC,MAAM,EAAE,YAAY;IAqEhC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAgDlC;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,IAAI;IAqCf;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAqBd,UAAU;YAKV,SAAS;IA6HvB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAkDxB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAS5B"}

package/dist/server.js

@@ -0,0 +1,334 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/**
+ * MCP Server for PICA Platform
+ * Enables AI assistants to interact with PICA via the Model Context Protocol
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolRegistry } from "./tools/index.js";
+import { ResourceRegistry } from "./resources/index.js";
+import { PromptRegistry } from "./prompts/index.js";
+import { logError } from "@withpica/mcp-utils";
+import { makeStdioCallerContext, makeHttpAuditFn, McpAuditLogger, } from "@withpica/mcp-utils";
+import { SERVER_INSTRUCTIONS_AUTHENTICATED, SERVER_INSTRUCTIONS_UNAUTHENTICATED, } from "./server-instructions.js";
+export class PicaMcpServer {
+    server;
+    pica;
+    toolRegistry;
+    resourceRegistry;
+    promptRegistry;
+    config;
+    httpServer;
+    constructor(config) {
+        this.config = config;
+        // Initialize PICA SDK client (null in lobby mode)
+        if (config.picaApiKey) {
+            this.pica = new PicaClient({
+                apiKey: config.picaApiKey,
+                baseUrl: config.picaApiUrl,
+                debug: config.debug,
+            });
+        }
+        else {
+            this.pica = null;
+        }
+        // Initialize MCP server
+        // ADR-211 Phase 1 Primitive C: select the lobby variant of
+        // server-instructions when the binary boots without a connection key.
+        // The authenticated variant covers 200+ catalog tools; the lobby
+        // variant points at the 3 lobby tools (pica_signup_start +
+        // pica_sign_in + pica_sign_out) since none of the catalog surface
+        // is reachable yet.
+        const handshakeInstructions = config.lobbyMode
+            ? SERVER_INSTRUCTIONS_UNAUTHENTICATED
+            : SERVER_INSTRUCTIONS_AUTHENTICATED;
+        this.server = new Server({
+            name: config.serverName,
+            version: config.version,
+        }, {
+            capabilities: {
+                // listChanged: true on tools + resources tells the client we
+                // may emit `notifications/tools/list_changed` and
+                // `notifications/resources/list_changed` after sign-in or
+                // sign-out hot-swaps the registries. Without this declaration
+                // the client won't subscribe to those notifications, and the
+                // tool surface stays frozen at the lobby pair forever.
+                tools: { listChanged: true },
+                resources: { listChanged: true },
+                prompts: {},
+            },
+            instructions: handshakeInstructions,
+        });
+        // Initialize registries with stdio caller context (api key hash)
+        this.toolRegistry = new ToolRegistry(this.pica, config, (apiKey) => this.reinitialize(apiKey), makeStdioCallerContext(config.picaApiKey), () => this.signOut());
+        this.resourceRegistry = new ResourceRegistry(this.pica, config);
+        this.promptRegistry = new PromptRegistry();
+        // Wire audit logger — fire-and-forget POST to /api/mcp/audit
+        this.toolRegistry.setAuditLogger(new McpAuditLogger(makeHttpAuditFn({
+            baseUrl: config.picaApiUrl,
+            apiKey: config.picaApiKey,
+        })));
+        this.setupHandlers();
+    }
+    /**
+     * Reinitialize server with new credentials (called after successful auth)
+     */
+    reinitialize(apiKey) {
+        this.pica = new PicaClient({
+            apiKey,
+            baseUrl: this.config.picaApiUrl,
+            debug: this.config.debug,
+        });
+        this.config = { ...this.config, picaApiKey: apiKey, lobbyMode: false };
+        this.toolRegistry = new ToolRegistry(this.pica, this.config, (key) => this.reinitialize(key), makeStdioCallerContext(apiKey), () => this.signOut());
+        this.toolRegistry.setAuditLogger(new McpAuditLogger(makeHttpAuditFn({ baseUrl: this.config.picaApiUrl, apiKey })));
+        this.resourceRegistry = new ResourceRegistry(this.pica, this.config);
+        console.error("[MCP Server] Reinitialized with new credentials");
+        // Tell the client the tool + resource lists have changed so it
+        // re-fetches and discovers the full authenticated surface. Without
+        // these notifications the client keeps showing the lobby pair
+        // (sign_in/sign_out) even though sign-in succeeded — the in-memory
+        // registries on the server know about the 168 catalog tools but
+        // the client never asks for them again.
+        //
+        // Fire-and-forget: a failure to notify is a soft error (the user
+        // can manually trigger another tool call which will work since the
+        // server's internal state is correct), so we log and continue
+        // rather than throwing inside the callback path that just rebuilt
+        // the registries.
+        this.server.sendToolListChanged().catch((err) => {
+            console.error("[MCP Server] Failed to send tools/list_changed notification:", err);
+        });
+        this.server.sendResourceListChanged().catch((err) => {
+            console.error("[MCP Server] Failed to send resources/list_changed notification:", err);
+        });
+    }
+    /**
+     * Reset the server back to lobby mode (called after sign_out).
+     * Mirrors reinitialize() but in reverse: clears the PicaClient,
+     * sets lobbyMode=true, and rebuilds the tool/resource registries so
+     * the next tools/list call returns only [pica_sign_in, pica_sign_out].
+     *
+     * Without this the server would keep advertising the full authenticated
+     * tool surface after sign_out until the process is restarted, which
+     * lies about what's actually available — every privileged tool call
+     * would still fail at the API layer (no PicaClient), but the surface
+     * itself shouldn't pretend the catalog is reachable.
+     */
+    signOut() {
+        this.pica = null;
+        this.config = { ...this.config, picaApiKey: "", lobbyMode: true };
+        this.toolRegistry = new ToolRegistry(this.pica, this.config, (key) => this.reinitialize(key), makeStdioCallerContext(""), () => this.signOut());
+        this.toolRegistry.setAuditLogger(new McpAuditLogger(makeHttpAuditFn({ baseUrl: this.config.picaApiUrl, apiKey: "" })));
+        this.resourceRegistry = new ResourceRegistry(this.pica, this.config);
+        console.error("[MCP Server] Reset to lobby mode after sign_out");
+        // Same listChanged story as reinitialize() — without these the
+        // client keeps advertising the full authenticated surface to the
+        // model after sign-out, and any tool call would fail at the API
+        // layer with a confusing "no credentials" error instead of the
+        // model saying "you need to sign in first."
+        this.server.sendToolListChanged().catch((err) => {
+            console.error("[MCP Server] Failed to send tools/list_changed notification (signOut):", err);
+        });
+        this.server.sendResourceListChanged().catch((err) => {
+            console.error("[MCP Server] Failed to send resources/list_changed notification (signOut):", err);
+        });
+    }
+    /**
+     * Set up MCP protocol handlers on the main server instance (for stdio)
+     */
+    setupHandlers() {
+        this.registerHandlers(this.server);
+    }
+    /**
+     * Start the MCP server.
+     *
+     * Transport is selected by environment:
+     * - MCP_TRANSPORT=http  → HTTP server on MCP_PORT (default 3100)
+     * - Otherwise           → stdio (default, for Claude Code / Cursor / VS Code)
+     */
+    async start() {
+        const mode = process.env.MCP_TRANSPORT;
+        if (mode === "http") {
+            await this.startHttp();
+        }
+        else {
+            await this.startStdio();
+        }
+        console.error("[MCP Server] PICA MCP Server started");
+        console.error(`[MCP Server] Version: ${this.config.version}`);
+        console.error(`[MCP Server] Transport: ${mode === "http" ? "HTTP" : "stdio"}`);
+        console.error(`[MCP Server] Mode: ${this.config.lobbyMode ? "lobby (sign in to connect)" : "authenticated"}`);
+        console.error(`[MCP Server] API URL: ${this.config.picaApiUrl}`);
+        console.error("[MCP Server] Ready to accept connections");
+    }
+    async startStdio() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+    }
+    async startHttp() {
+        const port = parseInt(process.env.MCP_PORT || "3100", 10);
+        // Each HTTP request gets its own transport instance (stateless sessions)
+        const httpServer = createServer(async (req, res) => {
+            // CORS headers for browser-based clients
+            res.setHeader("Access-Control-Allow-Origin", "*");
+            res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS, DELETE");
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, Mcp-Session-Id");
+            res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+            if (req.method === "OPTIONS") {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            // Auth check — require MCP_HTTP_SECRET or PICA_API_KEY as Bearer token
+            const httpSecret = process.env.MCP_HTTP_SECRET || process.env.PICA_API_KEY;
+            if (httpSecret) {
+                const authHeader = req.headers["authorization"] ?? "";
+                const token = authHeader.startsWith("Bearer ")
+                    ? authHeader.slice(7)
+                    : "";
+                const tokenBuf = Buffer.from(token);
+                const secretBuf = Buffer.from(httpSecret);
+                const isValid = tokenBuf.length === secretBuf.length &&
+                    timingSafeEqual(tokenBuf, secretBuf);
+                if (!isValid) {
+                    res.writeHead(401, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Unauthorized" }));
+                    return;
+                }
+            }
+            // Health check
+            if (req.method === "GET" && req.url === "/health") {
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    status: "ok",
+                    server: this.config.serverName,
+                    version: this.config.version,
+                    tools: this.toolRegistry.listTools().length,
+                }));
+                return;
+            }
+            // MCP endpoint — create per-request transport
+            if (req.url === "/mcp" || req.url === "/") {
+                try {
+                    // Read body
+                    const chunks = [];
+                    for await (const chunk of req) {
+                        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+                    }
+                    const body = Buffer.concat(chunks).toString("utf-8");
+                    const parsedBody = body ? JSON.parse(body) : undefined;
+                    const transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: undefined, // stateless
+                    });
+                    // Connect a fresh server instance for this request
+                    const requestServer = new Server({
+                        name: this.config.serverName,
+                        version: this.config.version,
+                    }, {
+                        capabilities: {
+                            tools: {},
+                            resources: {},
+                            prompts: {},
+                        },
+                    });
+                    // Re-register handlers on the request-scoped server
+                    this.registerHandlers(requestServer);
+                    await requestServer.connect(transport);
+                    await transport.handleRequest(req, res, parsedBody);
+                }
+                catch (err) {
+                    if (this.config.debug) {
+                        console.error("[MCP Server] HTTP request error:", err);
+                    }
+                    if (!res.headersSent) {
+                        res.writeHead(500, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "Internal server error" }));
+                    }
+                }
+                return;
+            }
+            // 404
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Not found" }));
+        });
+        this.httpServer = httpServer;
+        await new Promise((resolve) => {
+            httpServer.listen(port, () => {
+                console.error(`[MCP Server] HTTP listening on port ${port}`);
+                console.error(`[MCP Server] Endpoint: http://localhost:${port}/mcp`);
+                console.error(`[MCP Server] Health: http://localhost:${port}/health`);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Register protocol handlers on a server instance.
+     * Used by both the main server (stdio) and per-request servers (HTTP).
+     */
+    registerHandlers(server) {
+        server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: this.toolRegistry.listTools(),
+        }));
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args, _meta } = request.params;
+            const toolArgs = _meta ? { ...(args || {}), _meta } : args || {};
+            try {
+                // ADR-200 Phase 1: pass the per-request `Server` so executors can
+                // call `server.elicitInput()` / `server.getClientCapabilities()`
+                // when issuing an elicitation/create request. Each per-request
+                // HTTP server is a different instance; positional context
+                // avoids registry-level state that would race across calls.
+                return await this.toolRegistry.executeTool(name, toolArgs, { server });
+            }
+            catch (error) {
+                logError(`Tool execution: ${name}`, error);
+                throw error;
+            }
+        });
+        server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+            resources: this.resourceRegistry.listResources(),
+        }));
+        server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            const { uri } = request.params;
+            try {
+                return await this.resourceRegistry.readResource(uri);
+            }
+            catch (error) {
+                logError(`Resource read: ${uri}`, error);
+                throw error;
+            }
+        });
+        server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+            prompts: this.promptRegistry.listPrompts(),
+        }));
+        server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            try {
+                return await this.promptRegistry.getPrompt(name, args);
+            }
+            catch (error) {
+                logError(`Prompt get: ${name}`, error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Stop the MCP server
+     */
+    async stop() {
+        if (this.httpServer) {
+            await new Promise((resolve) => {
+                this.httpServer.close(() => resolve());
+            });
+        }
+        await this.server.close();
+        console.error("[MCP Server] Server stopped");
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools/access-simulate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Access Simulate MCP Tool
+ *
+ * Read-only "who would see what?" simulator. Given an entity + an
+ * action + a hypothetical recipient, returns the field-level
+ * visibility matrix and the chain of rules that produced the answer.
+ *
+ * v1 implements share_link_preview for works with real logic; other
+ * actions and entity types return a structured `not_yet_supported`
+ * scaffold so agents can iterate against the stable shape.
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import type { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class AccessSimulateTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private simulate;
+}
+//# sourceMappingURL=access-simulate.d.ts.map

package/dist/tools/access-simulate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-simulate.d.ts","sourceRoot":"","sources":["../../src/tools/access-simulate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAO3E,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA+I3D,QAAQ;CAoCvB"}