@withpica/mcp-server 2.7.0 → 2.9.0

package/dist/resources/index.js

@@ -1,78 +1,123 @@
 // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
-import { ResourceError } from "../utils/errors.js";
+import { ResourceError } from "@withpica/mcp-utils";
 import { readFileSync } from "fs";
 import { join } from "path";
 import { WITHPICA_PRIMER } from "./llms-primer.js";
+import { UPLOAD_HTML } from "../apps/upload.js";
+import { DOWNLOAD_HTML } from "../apps/download.js";
+import { PICA_STORAGE_CONNECT_DOMAINS } from "../apps/shared.js";
 export class ResourceRegistry {
     pica;
-    constructor(pica) {
+    config;
+    constructor(pica, config) {
         this.pica = pica;
+        this.config = config;
     }
     /**
      * List all available resources
      */
     listResources() {
-        return [
+        const resources = [
             {
-                uri: "llms://primer",
-                name: "PICA Domain Primer",
-                description: "Plain-language description of PICA's domain model, entity relationships, and recommended agent workflows. Read this first.",
+                uri: "pica://welcome",
+                name: "Welcome to PICA",
+                description: "Getting started guide — how to sign in and what you can do",
                 mimeType: "text/markdown",
             },
-            {
-                uri: "works://list",
-                name: "All Works",
-                description: "Complete list of musical works in the catalog",
-                mimeType: "application/json",
-            },
-            {
-                uri: "people://list",
-                name: "All People",
-                description: "Complete list of people (artists, composers, etc.)",
-                mimeType: "application/json",
-            },
-            {
-                uri: "recordings://list",
-                name: "All Recordings",
-                description: "Complete list of recordings",
-                mimeType: "application/json",
-            },
-            {
-                uri: "catalog://stats",
-                name: "Catalog Statistics",
-                description: "Statistics and metrics about the catalog",
-                mimeType: "application/json",
-            },
-            {
-                uri: "catalog://health",
-                name: "Catalog Health (PICA Score)",
-                description: "PICA Score — composite legibility index (0-100) with grade, 4-pillar breakdown, and actionable suggestions",
-                mimeType: "application/json",
-            },
-            {
-                uri: "workspace://context",
-                name: "Workspace Context",
-                description: "Aggregated workspace orientation — org info, catalog stats, health score, and top priorities in one call",
-                mimeType: "application/json",
-            },
-            {
-                uri: "events://recent",
-                name: "Recent Events",
-                description: "Recent webhook delivery events — what happened in this workspace recently",
-                mimeType: "application/json",
-            },
-            {
-                uri: "api://openapi",
-                name: "OpenAPI Specification",
-                description: "OpenAPI 3.1 spec for the top 20 PICA API endpoints — works, people, recordings, agreements, credits, search, health",
-                mimeType: "text/yaml",
-            },
         ];
+        if (this.config?.lobbyMode || !this.pica) {
+            return resources;
+        }
+        resources.push({
+            uri: "llms://primer",
+            name: "PICA Domain Primer",
+            description: "Plain-language description of PICA's domain model, entity relationships, and recommended agent workflows. Read this first.",
+            mimeType: "text/markdown",
+        }, {
+            uri: "works://list",
+            name: "All Works",
+            description: "Complete list of musical works in the catalog",
+            mimeType: "application/json",
+        }, {
+            uri: "people://list",
+            name: "All People",
+            description: "Complete list of people (artists, composers, etc.)",
+            mimeType: "application/json",
+        }, {
+            uri: "recordings://list",
+            name: "All Recordings",
+            description: "Complete list of recordings",
+            mimeType: "application/json",
+        }, {
+            uri: "catalog://stats",
+            name: "Catalog Statistics",
+            description: "Statistics and metrics about the catalog",
+            mimeType: "application/json",
+        }, {
+            uri: "catalog://health",
+            name: "Catalog Health (PICA Score)",
+            description: "PICA Score — composite legibility index (0-100) with grade, 4-pillar breakdown, and actionable suggestions",
+            mimeType: "application/json",
+        }, {
+            uri: "workspace://context",
+            name: "Workspace Context",
+            description: "Aggregated workspace orientation — org info, catalog stats, health score, and top priorities in one call",
+            mimeType: "application/json",
+        }, {
+            uri: "events://recent",
+            name: "Recent Events",
+            description: "Recent webhook delivery events — what happened in this workspace recently",
+            mimeType: "application/json",
+        }, {
+            uri: "api://openapi",
+            name: "OpenAPI Specification",
+            description: "OpenAPI 3.1 spec for the top 20 PICA API endpoints — works, people, recordings, agreements, credits, search, health",
+            mimeType: "text/yaml",
+        }, {
+            uri: "ui://pica/upload",
+            name: "Upload Files",
+            description: "Generic file upload card — drop zone for audio, photos, documents, anything",
+            mimeType: "text/html;profile=mcp-app",
+        }, {
+            uri: "ui://pica/download",
+            name: "Download File",
+            description: "File download card — shows file metadata and a download button",
+            mimeType: "text/html;profile=mcp-app",
+        });
+        return resources;
     }
     /**
      * Read a resource by URI
      */
     async readResource(uri) {
+        switch (uri) {
+            case "pica://welcome":
+                return {
+                    contents: [
+                        {
+                            uri: "pica://welcome",
+                            mimeType: "text/markdown",
+                            text: "# welcome to PICA\n\n" +
+                                "PICA manages your music catalog — works, recordings, credits, agreements, and more.\n\n" +
+                                "## get started\n\n" +
+                                'Say **"sign me in"** and provide your email address. ' +
+                                "You'll receive a magic link — click it, and all tools unlock automatically.\n\n" +
+                                "No API key needed. No config files. Just talk.\n\n" +
+                                "## what you can do after signing in\n\n" +
+                                "- Add and manage works, recordings, and credits\n" +
+                                "- Enrich metadata from Spotify, MusicBrainz, MLC, and more\n" +
+                                "- Generate exports (CSV, NRO, CAR reports)\n" +
+                                "- Track agreements and splits\n" +
+                                "- Search your catalog and get health reports\n",
+                        },
+                    ],
+                };
+            default:
+                break;
+        }
+        if (!this.pica) {
+            throw new ResourceError(`Resource not available in lobby mode: ${uri}`);
+        }
         switch (uri) {
             case "llms://primer":
                 return {
@@ -100,6 +145,40 @@ export class ResourceRegistry {
                 return await this.getRecentEvents();
             case "api://openapi":
                 return this.getOpenAPISpec();
+            case "ui://pica/upload":
+                return {
+                    contents: [
+                        {
+                            uri: "ui://pica/upload",
+                            mimeType: "text/html;profile=mcp-app",
+                            text: UPLOAD_HTML,
+                            _meta: {
+                                ui: {
+                                    csp: {
+                                        connectDomains: PICA_STORAGE_CONNECT_DOMAINS,
+                                    },
+                                },
+                            },
+                        },
+                    ],
+                };
+            case "ui://pica/download":
+                return {
+                    contents: [
+                        {
+                            uri: "ui://pica/download",
+                            mimeType: "text/html;profile=mcp-app",
+                            text: DOWNLOAD_HTML,
+                            _meta: {
+                                ui: {
+                                    csp: {
+                                        connectDomains: PICA_STORAGE_CONNECT_DOMAINS,
+                                    },
+                                },
+                            },
+                        },
+                    ],
+                };
             default:
                 throw new ResourceError(`Resource not found: ${uri}`);
         }

package/dist/resources/index.js.map

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

package/dist/resources/llms-primer.d.ts

@@ -0,0 +1,2 @@
+export declare const WITHPICA_PRIMER = "# PICA \u2014 Music Catalog Management Platform\n\nPICA helps music creators and publishers manage their catalog metadata,\ntrack royalties, and prepare works for registration with collection societies.\n\n## Core Entities\n\n### Work\nA musical composition (song, piece, library track). The central entity.\n- Has: title, ISWC, work_type (song/library/demo), genre, mood, BPM, key\n- Relationships: has many credits (writers/composers), has many recordings,\n  has many agreements, may have audio files, may have multimedia\n- Identifiers: ISWC (global), Tunecode (PRS), CAE/IPI (writer)\n\n### Person\nA human involved in music \u2014 writer, composer, performer, producer, publisher.\n- Has: name, email, IPI number, ISNI, MusicBrainz ID, PRO affiliation\n- Relationships: credited on many works, may have recordings, may have agreements\n- Can be enriched via: ISNI, MusicBrainz, Wikidata\n\n### Recording\nA specific audio capture of a work \u2014 the master/sound recording side.\n- Has: title, ISRC, duration, artist, label\n- Relationships: belongs to one work, has credits (performers/producers)\n- Distinct from the work: a work is the composition, a recording is the performance\n\n### Agreement\nA contract governing rights to works \u2014 publishing, sync, distribution.\n- Has: title, type, parties, dates, territory, terms\n- Relationships: covers many works\n- Types: publishing_admin, co_publishing, master_recording, sub_publishing,\n  admin_only, distribution, library_music, production, artist_contract,\n  termination, report, other\n\n### Import Document\nA canonical representation of an ingested file (royalty statement, CSV import).\n- Has: source (16 formats \u2014 PROs: PRS, ASCAP, BMI, SESAC, SOCAN, APRA, GEMA, SACEM; NROs: PPL, SoundExchange, GVL; Mechanical: MCPS; Distributors: DistroKid, TuneCore, CD Baby; Revenue: YouTube Content ID), period, line items, field mappings, warnings\n- Immutable snapshot of the import event \u2014 not a live view\n- Use pica_import_documents_list to find them, pica_import_documents_get to read\n\n## First Connection\n\nIf you're connecting to this workspace for the first time or don't know where to start,\ninvoke the **workspace-autopilot** prompt. It reads the workspace state and routes you\nto the most valuable workflow automatically.\n\n## Recommended Workflows\n\n1. **Catalog audit**: pica_catalog_stats \u2192 pica_works_query({ health_filter: \"needs_attention\" }) \u2192 pica_works_inspect({ sections: [\"completeness\"] })\n2. **Enrichment**: pica_enrichment_candidates \u2192 pica_enrich_work_spotify/mlc/musicbrainz \u2192 pica_works_inspect (verify)\n3. **Statement reconciliation**: pica_import_documents_query \u2192 pica_import_documents_inspect({ sections: [\"diff\"] })\n4. **Duplicate cleanup**: pica_find_duplicates \u2192 review \u2192 pica_merge_duplicates\n5. **Registration readiness**: pica_works_inspect({ sections: [\"registration\"] }) \u2192 fix gaps \u2192 pica_export_song_registration\n\n## Key Concepts\n\n- **Organisation**: Multi-tenant \u2014 all data scoped to one org. Never cross org boundaries.\n- **PICA Score**: Composite catalog legibility index (0-100, grade A-F). Four pillars:\n  identification, documentation, registration, completeness.\n- **Enrichment cascade**: When an identifier is added, external sources\n  (MusicBrainz, ISNI, MLC) are queried automatically to fill gaps.\n- **Credits**: Work credits (writers/composers with splits) are distinct from\n  recording credits (performers/producers). Different tables, different role enums.\n  Work credit roles: writer, composer, arranger, lyricist, producer, performer.\n  Recording credit roles: Writer, Composer, Producer, Performer (PascalCase).\n";
+//# sourceMappingURL=llms-primer.d.ts.map

package/dist/resources/llms-primer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-primer.d.ts","sourceRoot":"","sources":["../../src/resources/llms-primer.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,eAAe,kpHAiE3B,CAAC"}

package/dist/resources/llms-primer.js

@@ -0,0 +1,68 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+export const WITHPICA_PRIMER = `# PICA — Music Catalog Management Platform
+
+PICA helps music creators and publishers manage their catalog metadata,
+track royalties, and prepare works for registration with collection societies.
+
+## Core Entities
+
+### Work
+A musical composition (song, piece, library track). The central entity.
+- Has: title, ISWC, work_type (song/library/demo), genre, mood, BPM, key
+- Relationships: has many credits (writers/composers), has many recordings,
+  has many agreements, may have audio files, may have multimedia
+- Identifiers: ISWC (global), Tunecode (PRS), CAE/IPI (writer)
+
+### Person
+A human involved in music — writer, composer, performer, producer, publisher.
+- Has: name, email, IPI number, ISNI, MusicBrainz ID, PRO affiliation
+- Relationships: credited on many works, may have recordings, may have agreements
+- Can be enriched via: ISNI, MusicBrainz, Wikidata
+
+### Recording
+A specific audio capture of a work — the master/sound recording side.
+- Has: title, ISRC, duration, artist, label
+- Relationships: belongs to one work, has credits (performers/producers)
+- Distinct from the work: a work is the composition, a recording is the performance
+
+### Agreement
+A contract governing rights to works — publishing, sync, distribution.
+- Has: title, type, parties, dates, territory, terms
+- Relationships: covers many works
+- Types: publishing_admin, co_publishing, master_recording, sub_publishing,
+  admin_only, distribution, library_music, production, artist_contract,
+  termination, report, other
+
+### Import Document
+A canonical representation of an ingested file (royalty statement, CSV import).
+- Has: source (16 formats — PROs: PRS, ASCAP, BMI, SESAC, SOCAN, APRA, GEMA, SACEM; NROs: PPL, SoundExchange, GVL; Mechanical: MCPS; Distributors: DistroKid, TuneCore, CD Baby; Revenue: YouTube Content ID), period, line items, field mappings, warnings
+- Immutable snapshot of the import event — not a live view
+- Use pica_import_documents_list to find them, pica_import_documents_get to read
+
+## First Connection
+
+If you're connecting to this workspace for the first time or don't know where to start,
+invoke the **workspace-autopilot** prompt. It reads the workspace state and routes you
+to the most valuable workflow automatically.
+
+## Recommended Workflows
+
+1. **Catalog audit**: pica_catalog_stats → pica_works_query({ health_filter: "needs_attention" }) → pica_works_inspect({ sections: ["completeness"] })
+2. **Enrichment**: pica_enrichment_candidates → pica_enrich_work_spotify/mlc/musicbrainz → pica_works_inspect (verify)
+3. **Statement reconciliation**: pica_import_documents_query → pica_import_documents_inspect({ sections: ["diff"] })
+4. **Duplicate cleanup**: pica_find_duplicates → review → pica_merge_duplicates
+5. **Registration readiness**: pica_works_inspect({ sections: ["registration"] }) → fix gaps → pica_export_song_registration
+
+## Key Concepts
+
+- **Organisation**: Multi-tenant — all data scoped to one org. Never cross org boundaries.
+- **PICA Score**: Composite catalog legibility index (0-100, grade A-F). Four pillars:
+  identification, documentation, registration, completeness.
+- **Enrichment cascade**: When an identifier is added, external sources
+  (MusicBrainz, ISNI, MLC) are queried automatically to fill gaps.
+- **Credits**: Work credits (writers/composers with splits) are distinct from
+  recording credits (performers/producers). Different tables, different role enums.
+  Work credit roles: writer, composer, arranger, lyricist, producer, performer.
+  Recording credit roles: Writer, Composer, Producer, Performer (PascalCase).
+`;
+//# sourceMappingURL=llms-primer.js.map

package/dist/resources/llms-primer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-primer.js","sourceRoot":"","sources":["../../src/resources/llms-primer.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiE9B,CAAC"}

package/dist/server-instructions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Server-level instructions sent to agents on MCP handshake.
+ * Keep under 2000 chars — this is context budget, not documentation.
+ *
+ * Block playbook: "document the high level of your server"
+ * Lowin: "instructions are context — design them as context"
+ */
+export declare const SERVER_INSTRUCTIONS = "PICA manages music catalog metadata \u2014 works, recordings, people, credits, agreements, and rights.\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\nKey patterns:\n- Read tools are safe to call freely (annotated readOnlyHint=true)\n- Use _inspect tools with sections param for targeted data (e.g., pica_works_inspect with sections: [\"basic\", \"credits\"])\n- Write tools (create/update) confirm what changed after execution\n- Destructive tools (delete/merge) require a two-step confirmation with a token\n- Errors include a \"suggestion\" field with recovery instructions and a \"next_tool\" to try\n\nTool categories: catalog, enrichment, business, discovery, media, comms, settings.\nUse pica_dashboard_attention for items needing action.\nUse pica_works_inspect with sections: [\"health\", \"completeness\"] to check data quality.\nEnrichment tools (pica_enrich_work_*) pull from external sources \u2014 Spotify, MusicBrainz, MLC, ISNI, Discogs, YouTube.\nThe agent orchestrates enrichment \u2014 try sources based on available identifiers, follow recovery hints.\n\nAll query endpoints accept \"limit\" (default 50) and return paginated results.\nIDs are UUIDs. When unsure of an ID, use a _query tool first.\n\nWhen calling write tools: briefly tell the user what you're about to do before calling. After execution, confirm what changed.\nWhen calling destructive tools: describe exactly what will be deleted/merged and get explicit user confirmation before calling.";
+//# 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;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,2nDAwBgG,CAAC"}

package/dist/server-instructions.js

@@ -0,0 +1,34 @@
+// 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.
+ *
+ * Block playbook: "document the high level of your server"
+ * Lowin: "instructions are context — design them as context"
+ */
+export const SERVER_INSTRUCTIONS = `PICA manages music catalog metadata — works, recordings, people, credits, agreements, and rights.
+
+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
+
+Key patterns:
+- Read tools are safe to call freely (annotated readOnlyHint=true)
+- Use _inspect tools with sections param for targeted data (e.g., pica_works_inspect with sections: ["basic", "credits"])
+- Write tools (create/update) confirm what changed after execution
+- Destructive tools (delete/merge) require a two-step confirmation with a token
+- Errors include a "suggestion" field with recovery instructions and a "next_tool" to try
+
+Tool categories: catalog, enrichment, business, discovery, media, comms, settings.
+Use pica_dashboard_attention for items needing action.
+Use pica_works_inspect with sections: ["health", "completeness"] to check data quality.
+Enrichment tools (pica_enrich_work_*) pull from external sources — Spotify, MusicBrainz, MLC, ISNI, Discogs, YouTube.
+The agent orchestrates enrichment — try sources based on available identifiers, follow recovery hints.
+
+All query endpoints accept "limit" (default 50) and return paginated results.
+IDs are UUIDs. When unsure of an ID, use a _query tool first.
+
+When calling write tools: briefly tell the user what you're about to do before calling. After execution, confirm what changed.
+When calling destructive tools: describe exactly what will be deleted/merged and get explicit user confirmation before calling.`;
+//# 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;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;gIAwB6F,CAAC"}

package/dist/server.d.ts

@@ -8,6 +8,23 @@ export declare class PicaMcpServer {
   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)
    */

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM3C,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,IAAI,CAAa;IACzB,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;IAiChC;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAkBd,UAAU;YAKV,SAAS;IAwHvB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA6CxB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAS5B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAY3C,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;IA4DhC;;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;IA6CxB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAS5B"}

package/dist/server.js

@@ -8,11 +8,14 @@ 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 { PicaClient } from "./pica-sdk.js";
+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 "./utils/errors.js";
+import { logError } from "@withpica/mcp-utils";
+import { makeStdioCallerContext, makeHttpAuditFn, McpAuditLogger, } from "@withpica/mcp-utils";
+import { SERVER_INSTRUCTIONS } from "./server-instructions.js";
 export class PicaMcpServer {
     server;
     pica;
@@ -23,29 +26,110 @@ export class PicaMcpServer {
     httpServer;
     constructor(config) {
         this.config = config;
-        // Initialize PICA SDK client
-        this.pica = new PicaClient({
-            apiKey: config.picaApiKey,
-            baseUrl: config.picaApiUrl,
-            debug: config.debug,
-        });
+        // 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
         this.server = new Server({
             name: config.serverName,
             version: config.version,
         }, {
             capabilities: {
-                tools: {},
-                resources: {},
+                // 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: SERVER_INSTRUCTIONS,
         });
-        // Initialize registries
-        this.toolRegistry = new ToolRegistry(this.pica);
-        this.resourceRegistry = new ResourceRegistry(this.pica);
+        // 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)
      */
@@ -70,6 +154,7 @@ export class PicaMcpServer {
         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");
     }
@@ -98,7 +183,11 @@ export class PicaMcpServer {
                 const token = authHeader.startsWith("Bearer ")
                     ? authHeader.slice(7)
                     : "";
-                if (token !== httpSecret) {
+                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;