{"_id":"@damsarabi/jambot-mcp","_rev":"2-4c6c011e7b8da34047ad68b04be49a64","name":"@damsarabi/jambot-mcp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@damsarabi/jambot-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","music","ai","llm","jamprovise","claude"],"author":{"name":"damsarabi"},"license":"MIT","_id":"@damsarabi/jambot-mcp@0.1.0","maintainers":[{"name":"damsarabi","email":"sam.darabi@gmail.com"}],"homepage":"https://github.com/damsarabi/jambot-mcp","bugs":{"url":"https://github.com/damsarabi/jambot-mcp/issues"},"bin":{"jambot-mcp":"dist/index.js"},"dist":{"shasum":"6b7bc0347ee85c61d3495f2548c94872d31b0bb1","tarball":"https://registry.npmjs.org/@damsarabi/jambot-mcp/-/jambot-mcp-0.1.0.tgz","fileCount":19,"integrity":"sha512-QzhAy5QcPJAuxQ9G2mjB8C4swsXUvIyX+t2BqCPXW7/D/fGKGo42gbFaWo0ONrm7sFgN0z9xkPG5yQuarRmkCw==","signatures":[{"sig":"MEQCIDt+x5RvHSi51mGERUBmlElD5OCvBSgxP+SLta0qEficAiAuBiQSN5JJvR/v44VMTz0Knbpo4DoTNxJx2pJBfbdy1A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":71076},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"61d53fcb5e9578090dbadff3d5dc41175bde8bcc","scripts":{"dev":"tsx src/index.ts","test":"vitest run --coverage","build":"tsc","start":"node dist/index.js","coverage":"vitest run --coverage","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"damsarabi","email":"sam.darabi@gmail.com"},"repository":{"url":"git+https://github.com/damsarabi/jambot-mcp.git","type":"git"},"_npmVersion":"10.9.4","description":"MCP Server for domain-constrained AI control of the Jamprovise music app. Exposes typed tools for sequence generation and transport control via the Model Context Protocol.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^4.6.2","@modelcontextprotocol/server":"^2.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^2.0.0","typescript":"^5.0.0","@types/node":"^22.0.0","@vitest/coverage-v8":"^2.1.9"},"_npmOperationalInternal":{"tmp":"tmp/jambot-mcp_0.1.0_1789102026255_0.7142847892955406","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"_id":"@damsarabi/jambot-mcp@0.1.1","bin":{"jambot-mcp":"dist/index.js"},"bugs":{"url":"https://github.com/damsarabi/jambot-mcp/issues"},"dist":{"shasum":"8a9d3a47a3e5104cc0034af1727831134d1ad99c","tarball":"https://registry.npmjs.org/@damsarabi/jambot-mcp/-/jambot-mcp-0.1.1.tgz","fileCount":19,"integrity":"sha512-Zey53NIiQWVev+6mDr4Qcl/20VjkRPUqFM0say7AtbYc/oNWBJeg2LxHb0LDWuynyvvqC6Zj0qSRnrdthpmXcQ==","signatures":[{"sig":"MEYCIQDMFZFSxfZu/9cPXtrPs1d5GMMxdJcTaOEfYWXtpPb2EAIhANrL8M9MLmZ9VpX4KEEEb2sHBKbAmhk5BsLrrkitbs2s","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCXC/B2hX1LtFSMrUxVbskwuVDtLP7fE7CSDrdyCwAG/gIgThYM+PvAufQkZii0LDgk98Kp/9UdaYZwdULtYSz+V+8="}],"unpackedSize":71117},"main":"./dist/index.js","name":"@damsarabi/jambot-mcp","type":"module","types":"./dist/index.d.ts","author":{"name":"damsarabi"},"engines":{"node":">=20.0.0"},"gitHead":"eb87c0c35f2903be6aedc0cbe9725112d4b6bf74","license":"MIT","scripts":{"dev":"tsx src/index.ts","test":"vitest run --coverage","build":"tsc","start":"node dist/index.js","coverage":"vitest run --coverage","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build && npm test"},"version":"0.1.1","_npmUser":{"name":"damsarabi","email":"sam.darabi@gmail.com"},"homepage":"https://github.com/damsarabi/jambot-mcp","keywords":["mcp","model-context-protocol","music","ai","llm","jamprovise","claude"],"repository":{"url":"git+https://github.com/damsarabi/jambot-mcp.git","type":"git"},"_npmVersion":"10.9.4","description":"MCP Server for domain-constrained AI control of the Jamprovise music app. Exposes typed tools for sequence generation and transport control via the Model Context Protocol.","directories":{},"maintainers":[{"name":"damsarabi","email":"sam.darabi@gmail.com"}],"_nodeVersion":"22.22.0","dependencies":{"zod":"^4.6.2","@modelcontextprotocol/server":"^2.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^2.0.0","typescript":"^5.0.0","@types/node":"^22.0.0","@vitest/coverage-v8":"^2.1.9"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/jambot-mcp_0.1.1_1789102703148_0.06718460263868464"}}},"time":{"created":"2026-09-11T04:47:06.040Z","modified":"2026-09-11T04:58:23.383Z","0.1.0":"2026-09-11T04:47:06.403Z","0.1.1":"2026-09-11T04:58:23.226Z"},"bugs":{"url":"https://github.com/damsarabi/jambot-mcp/issues"},"author":{"name":"damsarabi"},"license":"MIT","homepage":"https://github.com/damsarabi/jambot-mcp","keywords":["mcp","model-context-protocol","music","ai","llm","jamprovise","claude"],"repository":{"url":"git+https://github.com/damsarabi/jambot-mcp.git","type":"git"},"description":"MCP Server for domain-constrained AI control of the Jamprovise music app. Exposes typed tools for sequence generation and transport control via the Model Context Protocol.","maintainers":[{"name":"damsarabi","email":"sam.darabi@gmail.com"}],"readme":"# Jambot MCP Server\n\n> A type-safe Model Context Protocol (MCP) server that provides Large Language Models (LLMs) with domain-constrained, side-effect-safe control over the Jamprovise music synthesis engine.\n\n[![npm version](https://img.shields.io/npm/v/@damsarabi/jambot-mcp.svg)](https://npmjs.org/package/@damsarabi/jambot-mcp)\n[![Coverage](https://img.shields.io/badge/Coverage-100%25%20%28Schemas%29-brightgreen.svg)](https://github.com/damsarabi/jambot-mcp/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Overview\n\nJambot MCP is the orchestration layer that bridges conversational AI with real-time music generation. It extracts complex intent routing and state mutation logic into a standalone, verifiable protocol boundary. \n\nInstead of relying on fragile prompt engineering to output raw JSON, this server uses **Zod v4** to enforce strict musical constraints (e.g., chord duration limits, flat-to-sharp enharmonic normalization, track availability) *before* the command ever reaches the Jamprovise backend. If an LLM hallucinates an invalid chord quality or exceeds global bar limits, the MCP server rejects it immediately with a typed error, allowing the model to self-correct in a tight feedback loop.\n\n### Why this exists\n\nThis repository extracts the orchestration layer of Jamprovise into an independent, open standard. By decoupling the AI control plane from the core application, we achieve:\n1. **Agentic Control Boundaries**: Safely exposing complex domain logic to LLMs using the Model Context Protocol (MCP), ensuring strict separation of concerns.\n2. **Deterministic Fallbacks**: Using Zod to enforce schema adherence at the protocol boundary, eliminating the need for legacy string-repair heuristics.\n3. **Context Hydration via Resources**: Dynamically supplying the LLM with read-only state (e.g., available instruments, style presets) to reduce context window bloat and eliminate hallucinations.\n\n---\n\n## 🛠️ Tools (State Mutators)\n\nThe server exposes four tools that Claude (or any MCP client) can use to manipulate the Jamprovise environment:\n\n- **`play_sequence`**: The core creative engine. Generates and plays a new chord sequence. Enforces a strict `MAX_GLOBAL_BARS` limit and validates musical sections.\n- **`modify_transport`**: Adjusts tempo, key signature, and playback state. Includes **Pro-tier gating** (e.g., Drone Mode requires `JAMPROVISE_IS_PRO=true`).\n- **`query_state`**: Reads a specific field from the live app state using dot-notation (e.g., `tracks.harmony.instrument`).\n- **`get_available_instruments`**: Resolves aliases (e.g., \"piano\" → \"harmony\") and returns the valid instrument manifest for a given track.\n\n## 📚 Resources (Read-Only Context)\n\nResources provide the LLM with the context it needs to construct valid tool calls:\n\n- **`jamprovise://styles`**: The current manifest of available musical style presets (e.g., Jazz, Cinematic, Bossa Nova).\n- **`jamprovise://instruments`**: The valid instrument names categorized by track (Harmony, Bass, Percussion).\n- **`jamprovise://schema`**: The full domain constraints (voicing indexes, enharmonic rules) provided as markdown.\n\n---\n\n## 🚀 Installation & Usage with Claude Desktop\n\nTo use this server with Claude Desktop, you need a running instance of the Jamprovise backend (or you can point it to production if you have an API key).\n\n### Option 1: Run directly via NPX (Recommended)\nYou can run the published NPM package directly without cloning the repository. Add the following to your Claude Desktop configuration file:\n\n- **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"jambot\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@damsarabi/jambot-mcp\"\n      ],\n      \"env\": {\n        \"JAMPROVISE_API_URL\": \"http://localhost:8000\",\n        \"JAMPROVISE_API_KEY\": \"your-dev-api-key\",\n        \"JAMPROVISE_IS_PRO\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### Option 2: Build from Source\nIf you want to modify the server or run it locally from source:\n\n1. Clone and build the project:\n   ```bash\n   git clone https://github.com/damsarabi/jambot-mcp.git\n   cd jambot-mcp\n   npm install\n   npm run build\n   ```\n\n2. Update your Claude Desktop config to point to the local build:\n```json\n{\n  \"mcpServers\": {\n    \"jambot\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/absolute/path/to/jambot-mcp/dist/index.js\"\n      ],\n      \"env\": {\n        \"JAMPROVISE_API_URL\": \"http://localhost:8000\",\n        \"JAMPROVISE_API_KEY\": \"your-dev-api-key\",\n        \"JAMPROVISE_IS_PRO\": \"true\"\n      }\n    }\n  }\n}\n```\n\n3. Restart Claude Desktop. You will now see the tools are available.\n\n## 🎥 Demo\n\n*[Loom Video Placeholder: Insert a 2-minute demo showing Claude Desktop communicating with the local Jamprovise UI via the MCP Stdio transport]*\n\n## Architecture\n\n```mermaid\ngraph TD\n    A[Claude Desktop] -->|Stdio Transport| B(Jambot MCP Server)\n    B -->|Zod Validation| B\n    B -->|HTTP POST /mcp/command| C{Jamprovise Python API}\n    B -->|HTTP GET /mcp/state| C\n    C -->|Zustand Update| D[Jamprovise React UI]\n    C -->|Audio Engine| E[Tone.js]\n```\n\n## License\nMIT\n","readmeFilename":"README.md"}