@withpica/mcp-server 2.1.0

package/README.md

@@ -0,0 +1,305 @@
+# 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 (6 tools)**
+
+- `pica_recordings_list` - List recordings
+- `pica_recordings_get` - Get recording details
+- `pica_recordings_create` - Create new recording
+- `pica_recordings_update` - Update recording
+- `pica_recordings_delete` - Delete recording
+- `pica_recordings_by_work` - Get recordings of a work
+
+**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/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP Server Configuration
+ */
+export interface ServerConfig {
+    /**
+     * PICA API key for authentication
+     */
+    picaApiKey: string;
+    /**
+     * PICA API base URL
+     */
+    picaApiUrl: string;
+    /**
+     * Server name shown to AI assistants
+     */
+    serverName: string;
+    /**
+     * Server version
+     */
+    version: string;
+    /**
+     * Enable debug logging
+     */
+    debug: boolean;
+}
+/**
+ * Load configuration from environment variables
+ */
+export declare function loadConfig(): ServerConfig;
+/**
+ * Validate configuration
+ */
+export declare function validateConfig(config: ServerConfig): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,YAAY,CAkBzC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAQzD"}

package/dist/config.js

@@ -0,0 +1,33 @@
+/**
+ * MCP Server Configuration
+ */
+/**
+ * Load configuration from environment variables
+ */
+export function loadConfig() {
+    const picaApiKey = process.env.PICA_API_KEY;
+    if (!picaApiKey) {
+        throw new Error("PICA_API_KEY environment variable is required.\n" +
+            "Please set it to your PICA API key:\n" +
+            'export PICA_API_KEY="your-api-key-here"');
+    }
+    return {
+        picaApiKey,
+        picaApiUrl: process.env.PICA_API_URL || "https://withpica.com/api",
+        serverName: "pica-mcp-server",
+        version: "2.1.0",
+        debug: process.env.DEBUG === "true" || process.env.DEBUG === "1",
+    };
+}
+/**
+ * Validate configuration
+ */
+export function validateConfig(config) {
+    if (!config.picaApiKey || config.picaApiKey.trim() === "") {
+        throw new Error("PICA API key cannot be empty");
+    }
+    if (!config.picaApiUrl || !config.picaApiUrl.startsWith("http")) {
+        throw new Error("Invalid PICA API URL");
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AA6BH;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAE5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,kDAAkD;YAChD,uCAAuC;YACvC,yCAAyC,CAC5C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU;QACV,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,0BAA0B;QAClE,UAAU,EAAE,iBAAiB;QAC7B,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,GAAG;KACjE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAoB;IACjD,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * PICA MCP Server
+ * Entry point for the Model Context Protocol server
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * PICA MCP Server
+ * Entry point for the Model Context Protocol server
+ */
+import { loadConfig, validateConfig } from "./config.js";
+import { PicaMcpServer } from "./server.js";
+async function main() {
+    try {
+        // Load and validate configuration
+        const config = loadConfig();
+        validateConfig(config);
+        // Create and start server
+        const server = new PicaMcpServer(config);
+        await server.start();
+        // Handle graceful shutdown
+        process.on("SIGINT", async () => {
+            console.error("[MCP Server] Shutting down...");
+            await server.stop();
+            process.exit(0);
+        });
+        process.on("SIGTERM", async () => {
+            console.error("[MCP Server] Shutting down...");
+            await server.stop();
+            process.exit(0);
+        });
+    }
+    catch (error) {
+        console.error("[MCP Server] Fatal error:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,kCAAkC;QAClC,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAC5B,cAAc,CAAC,MAAM,CAAC,CAAC;QAEvB,0BAA0B;QAC1B,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QAErB,2BAA2B;QAC3B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YAC9B,OAAO,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;YAC/C,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;YAC/B,OAAO,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;YAC/C,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CACX,2BAA2B,EAC3B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}