@withpica/mcp-server 1.3.0

package/README.md

@@ -0,0 +1,304 @@
+# PICA MCP Server
+
+Model Context Protocol (MCP) server for the PICA Platform. Enables **any MCP-compatible AI assistant** to interact with your PICA music catalog.
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely access external data and functionality. With this MCP server, any MCP-compatible AI can interact with your PICA catalog.
+
+## Compatible AI Assistants
+
+- **Claude Desktop** - Anthropic's desktop AI assistant
+- **ChatGPT** - OpenAI's assistant (when MCP support is available)
+- **Custom AI tools** - Any application that implements the MCP protocol
+- **Future AI assistants** - As more tools adopt MCP
+
+## Features
+
+### 24 AI-Callable Tools
+
+**Works Management (8 tools)**
+
+- `pica_works_list` - List musical works
+- `pica_works_get` - Get work details
+- `pica_works_create` - Create new work
+- `pica_works_update` - Update work
+- `pica_works_delete` - Delete work
+- `pica_works_verify` - Verify work
+- `pica_works_search` - Search works
+- `pica_works_bulk_delete` - Delete multiple works
+
+**People Management (8 tools)**
+
+- `pica_people_list` - List people
+- `pica_people_get` - Get person details
+- `pica_people_create` - Create new person
+- `pica_people_update` - Update person
+- `pica_people_delete` - Delete person
+- `pica_people_search` - Search people
+- `pica_people_enrich_isni` - Enrich from ISNI
+- `pica_people_enrich_musicbrainz` - Enrich from MusicBrainz
+
+**Recordings Management (5 tools)**
+
+- `pica_recordings_query` - List/search recordings; filter by `work_id` (replaces removed `pica_recordings_by_work`)
+- `pica_recordings_inspect` - Get recording details (sections-based)
+- `pica_recordings_create` - Create new recording
+- `pica_recordings_update` - Update recording
+- `pica_recordings_delete` - Delete recording
+
+**Search & Analytics (2 tools)**
+
+- `pica_search_all` - Search across all entities
+- `pica_catalog_stats` - Get catalog statistics
+
+### 4 Data Resources
+
+Read-only access to catalog data:
+
+- `works://list` - All works
+- `people://list` - All people
+- `recordings://list` - All recordings
+- `catalog://stats` - Catalog statistics
+
+### 4 Workflow Prompts
+
+Pre-configured prompts for common tasks:
+
+- `analyze-catalog` - Comprehensive catalog analysis
+- `find-duplicates` - Find duplicate entries
+- `enrich-metadata` - Identify enrichment opportunities
+- `verify-works` - Review unverified works
+
+## Installation
+
+### NPM (Recommended)
+
+```bash
+npm install -g @withpica/mcp-server
+```
+
+### From Source
+
+```bash
+cd mcp-server
+npm install
+npm run build
+npm link
+```
+
+## Configuration
+
+### Get Your PICA API Key
+
+1. Log into PICA at https://withpica.com
+2. Go to Settings → API Keys
+3. Generate a new API key
+4. Copy the key for use below
+
+### Claude Desktop Setup
+
+Add to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pica": {
+      "command": "npx",
+      "args": ["-y", "@withpica/mcp-server"],
+      "env": {
+        "PICA_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Other MCP-Compatible AI Assistants
+
+The setup process is similar for any MCP-compatible tool:
+
+1. Configure the MCP server command: `npx -y @withpica/mcp-server`
+2. Set the `PICA_API_KEY` environment variable
+3. The AI can now access all PICA tools and resources
+
+## Usage Examples
+
+### Example 1: List Your Works
+
+**User**: "Show me my musical works"
+
+**AI** uses: `pica_works_list`
+
+**Result**: List of works with titles, ISWCs, verification status, etc.
+
+### Example 2: Create a Work
+
+**User**: "Create a new composition called 'Moonlight Sonata No. 2'"
+
+**AI** uses: `pica_works_create` with appropriate parameters
+
+**Result**: New work created with generated ID
+
+### Example 3: Analyze Catalog
+
+**User**: "Analyze my catalog"
+
+**AI** uses: `analyze-catalog` prompt
+
+**AI calls**:
+
+- `pica_catalog_stats` - Get statistics
+- `pica_works_list` - Review works
+- `pica_people_list` - Review people
+
+**Result**: Comprehensive analysis with insights and recommendations
+
+### Example 4: Find Duplicates
+
+**User**: "Find duplicate entries"
+
+**AI** uses: `find-duplicates` prompt
+
+**AI calls**:
+
+- `pica_works_list` - Get all works
+- `pica_people_list` - Get all people
+
+**Result**: List of potential duplicates with merge recommendations
+
+### Example 5: Enrich Metadata
+
+**User**: "Enrich Mozart's profile from ISNI"
+
+**AI** uses: `pica_people_enrich_isni` with person ID and ISNI
+
+**Result**: Person record updated with enriched data from ISNI
+
+## Use Cases
+
+### For Catalog Managers
+
+- "Show me all unverified works"
+- "Find duplicate entries"
+- "List works missing ISWC codes"
+- "Enrich all people from ISNI"
+
+### For Data Analysis
+
+- "What's the average duration of my compositions?"
+- "Who are my most prolific composers?"
+- "Which works have the most recordings?"
+- "Show me catalog statistics"
+
+### For Enrichment
+
+- "Find all people that could be enriched from MusicBrainz"
+- "Suggest ISNI matches for unverified artists"
+- "Which works are missing metadata?"
+
+### For Bulk Operations
+
+- "Create works from this list"
+- "Verify all completed works"
+- "Delete test entries"
+
+## Environment Variables
+
+- `PICA_API_KEY` (required) - Your PICA API key
+- `PICA_API_URL` (optional) - API base URL (default: https://withpica.com/api)
+- `DEBUG` (optional) - Enable debug logging (set to 'true' or '1')
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Development Mode
+
+```bash
+npm run dev
+```
+
+### Local Testing
+
+```bash
+PICA_API_KEY=your-key npm run dev
+```
+
+## Troubleshooting
+
+### "PICA_API_KEY environment variable is required"
+
+Make sure you've set the API key in your MCP server configuration:
+
+```json
+{
+  "env": {
+    "PICA_API_KEY": "your-actual-api-key"
+  }
+}
+```
+
+### "Authentication failed"
+
+- Verify your API key is correct
+- Check that the API key hasn't been revoked
+- Generate a new API key if needed
+
+### Tools Not Showing Up
+
+1. Restart your AI assistant after configuring the MCP server
+2. Check the MCP server logs for errors
+3. Verify the configuration file syntax is correct
+
+### Connection Issues
+
+- Ensure you have an internet connection
+- Check that https://withpica.com is accessible
+- Verify no firewall is blocking the connection
+
+## Architecture
+
+```
+MCP Server for PICA
+├── Protocol Handler (MCP standard)
+├── Authentication (API key)
+├── Tools (24 AI-callable functions)
+│   ├── Works Management (8)
+│   ├── People Management (8)
+│   ├── Recordings Management (6)
+│   └── Search & Analytics (2)
+├── Resources (4 data providers)
+└── Prompts (4 workflows)
+```
+
+## Security
+
+- All requests require a valid PICA API key
+- API keys are transmitted securely over HTTPS
+- Data access is scoped to your organization
+- No data is stored by the MCP server
+
+## Support
+
+- **Documentation**: https://docs.withpica.com
+- **Issues**: https://github.com/withpica/pica/issues
+- **Email**: support@withpica.com
+
+## License
+
+MIT
+
+## Credits
+
+Built with:
+
+- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP SDK
+- [@withpica/sdk](https://www.npmjs.com/package/@withpica/sdk) - PICA TypeScript SDK

package/dist/apps/download.d.ts

@@ -0,0 +1,2 @@
+export declare const DOWNLOAD_HTML: string;
+//# sourceMappingURL=download.d.ts.map

package/dist/apps/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/apps/download.ts"],"names":[],"mappings":"AAgIA,eAAO,MAAM,aAAa,QAIzB,CAAC"}

package/dist/apps/download.js

@@ -0,0 +1,125 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/**
+ * pica_download MCP App card — file delivery.
+ *
+ * Shows filename, mime_type, size, and an optional description, then a copper
+ * "download" button wired to app.downloadFile(). After dispatch the button
+ * flips to a "downloaded" state with a secondary "download again" action.
+ *
+ * DOM API only — never innerHTML.
+ */
+import { buildAppHtml } from "./shared.js";
+const DOWNLOAD_BODY = `
+<div class="stack gap-6">
+  <header>
+    <h1 class="heading heading-lg">download ready</h1>
+    <p class="text-secondary">your file is ready to save</p>
+  </header>
+
+  <div class="card-flat dl-file">
+    <div class="dl-icon" id="dl-icon">\u25CF</div>
+    <div class="dl-meta">
+      <div class="heading heading-sm" id="dl-filename">file</div>
+      <div class="text-tertiary" id="dl-sub" style="font-size: 12px; margin-top: 4px;"></div>
+      <div class="text-secondary" id="dl-description" style="font-size: 13px; margin-top: 8px; display: none;"></div>
+      <div class="text-tertiary" id="dl-expires" style="font-size: 11px; margin-top: 6px; display: none;"></div>
+    </div>
+  </div>
+
+  <div class="row" style="gap: 12px;">
+    <button class="btn-copper" id="dl-button">download</button>
+    <a class="btn-ghost" id="dl-fallback" href="#" target="_blank" rel="noopener">or open in browser</a>
+  </div>
+</div>
+
+<style>
+.dl-file {
+  display: flex;
+  gap: 16px;
+  align-items: flex-start;
+}
+.dl-icon {
+  font-size: 32px;
+  color: var(--accent);
+  flex: 0 0 auto;
+  line-height: 1;
+  padding-top: 4px;
+}
+.dl-meta { flex: 1 1 auto; min-width: 0; }
+#dl-filename { word-break: break-all; }
+</style>
+`;
+const DOWNLOAD_JS = `
+var dlState = { file: null };
+
+function dlFormatBytes(bytes) {
+  if (bytes == null || isNaN(bytes)) return "";
+  if (bytes < 1024) return bytes + " B";
+  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + " KB";
+  if (bytes < 1024 * 1024 * 1024) return (bytes / (1024 * 1024)).toFixed(1) + " MB";
+  return (bytes / (1024 * 1024 * 1024)).toFixed(2) + " GB";
+}
+
+function dlRender() {
+  var f = dlState.file;
+  if (!f) return;
+
+  var filenameEl = document.getElementById("dl-filename");
+  if (filenameEl) filenameEl.textContent = f.filename;
+
+  var subParts = [];
+  if (f.mime_type) subParts.push(f.mime_type);
+  if (f.size) subParts.push(dlFormatBytes(f.size));
+  var subEl = document.getElementById("dl-sub");
+  if (subEl) subEl.textContent = subParts.join(" \u00B7 ");
+
+  if (f.description) {
+    var descEl = document.getElementById("dl-description");
+    if (descEl) {
+      descEl.textContent = f.description;
+      descEl.style.display = "block";
+    }
+  }
+
+  if (f.expires_at) {
+    var expEl = document.getElementById("dl-expires");
+    if (expEl) {
+      expEl.textContent = "link expires " + f.expires_at;
+      expEl.style.display = "block";
+    }
+  }
+
+  var fallback = document.getElementById("dl-fallback");
+  if (fallback) fallback.setAttribute("href", f.url);
+}
+
+function dlTriggerDownload() {
+  var f = dlState.file;
+  if (!f) return;
+  var btn = document.getElementById("dl-button");
+
+  if (app && typeof app.downloadFile === "function") {
+    try {
+      app.downloadFile({ url: f.url, filename: f.filename });
+      if (btn) {
+        btn.textContent = "download again";
+        btn.classList.remove("btn-copper");
+        btn.classList.add("btn-ghost");
+      }
+      return;
+    } catch (err) {
+      console.warn("[pica_download] downloadFile failed:", err);
+    }
+  }
+}
+
+window.onPicaToolResult = function (data) {
+  if (!data || !data.file) return;
+  dlState.file = data.file;
+  dlRender();
+  var btn = document.getElementById("dl-button");
+  if (btn) btn.addEventListener("click", dlTriggerDownload);
+};
+`;
+export const DOWNLOAD_HTML = buildAppHtml("pica \u2014 download", DOWNLOAD_BODY, DOWNLOAD_JS);
+//# sourceMappingURL=download.js.map

package/dist/apps/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../../src/apps/download.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCrB,CAAC;AAEF,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuEnB,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CACvC,sBAAsB,EACtB,aAAa,EACb,WAAW,CACZ,CAAC"}