mcp-music-studio 0.1.1 → 0.1.2

package/README.md

@@ -8,7 +8,7 @@ Forked from [`@modelcontextprotocol/server-sheet-music`](https://github.com/mode
 
 - **8 style presets** — rock, jazz, bossa, waltz, march, reggae, folk, classical. One parameter adds drums + bass + chord accompaniment.
 - **30 instruments** — selectable from UI or via tool parameter, with fuzzy matching
-- **Browser fallback** — `openInBrowser: true` launches a standalone player for CLI environments (Claude Code, Codex, Gemini CLI) that don't support ext-apps UI
+- **Three rendering modes** — ext-apps inline UI for Claude Desktop/VS Code, browser fallback for CLI environments, configurable via `--render-mode`
 - **`get-music-guide` tool** — on-demand reference for AI systems (instruments, drums, ABC syntax, arrangements, genre templates, MIDI directives)
 - **7 `music://guide/*` resources** — same content for resource-capable clients
 - **Note highlighting** — currently playing notes light up during playback
@@ -148,7 +148,6 @@ Creates and plays music with visual sheet music and multi-instrument audio.
 | `tempo` | number? | BPM (40-240) |
 | `swing` | number? | Swing feel (0-100) |
 | `transpose` | number? | Semitones (-12 to 12) |
-| `openInBrowser` | boolean? | Open standalone browser player (for CLI environments without UI) |
 
 **Example — jazz arrangement:**
 ```json
@@ -174,6 +173,31 @@ Returns reference material for composition. Topics:
 | `styles` | What each style preset does and when to use it |
 | `midi-directives` | Full `%%MIDI` reference for ABCJS |
 
+## Render Modes
+
+The server auto-detects whether the client supports ext-apps UI. For clients that don't, use `--render-mode` to control how music is delivered:
+
+| Mode | Flag | Behavior |
+|------|------|----------|
+| `auto` | (default) | Inline ext-apps UI for Claude Desktop, VS Code |
+| `browser` | `--render-mode browser` | Saves HTML player and opens in system browser |
+| `html` | `--render-mode html` | Returns HTML as embedded resource in response |
+
+Use `--output-dir` to control where HTML player files are saved (default: `~/Desktop/mcp-music-studio`).
+
+**Example — Cherry Studio, CLI environments, or other non-ext-apps clients:**
+
+```json
+{
+  "mcpServers": {
+    "music-studio": {
+      "command": "npx",
+      "args": ["-y", "mcp-music-studio", "--stdio", "--render-mode", "browser", "--output-dir", "/path/to/output"]
+    }
+  }
+}
+```
+
 ## Development
 
 ```bash

package/dist/index.js

@@ -30624,13 +30624,13 @@ async function startStreamableHTTPServer(createServer2) {
       }
     }
   });
-  const httpServer = app.listen(port, (err) => {
-    if (err) {
-      console.error("Failed to start server:", err);
-      process.exit(1);
-    }
+  const httpServer = app.listen(port, () => {
     console.log(`MCP server listening on http://localhost:${port}/mcp`);
   });
+  httpServer.on("error", (err) => {
+    console.error("Failed to start server:", err);
+    process.exit(1);
+  });
   const shutdown = () => {
     console.log(`
 Shutting down...`);
@@ -30642,11 +30642,38 @@ Shutting down...`);
 async function startStdioServer(createServer2) {
   await createServer2().connect(new StdioServerTransport);
 }
+function parseArg(name) {
+  for (let i = 0;i < process.argv.length; i++) {
+    const arg = process.argv[i].trim();
+    if (arg === name && i + 1 < process.argv.length)
+      return process.argv[i + 1].trim();
+    if (arg.startsWith(name + "="))
+      return arg.slice(name.length + 1).trim();
+    if (arg.startsWith(name + " "))
+      return arg.slice(name.length).trim();
+  }
+  return;
+}
+function parseRenderMode() {
+  const val = parseArg("--render-mode");
+  if (!val)
+    return "auto";
+  if (val === "html" || val === "browser" || val === "auto")
+    return val;
+  console.error(`Unknown render mode "${val}", using "auto"`);
+  return "auto";
+}
+function parseOutputDir() {
+  return parseArg("--output-dir");
+}
 async function main() {
+  const defaultRenderMode = parseRenderMode();
+  const outputDir = parseOutputDir();
+  const factory = () => createServer({ defaultRenderMode, outputDir });
   if (process.argv.includes("--stdio")) {
-    await startStdioServer(createServer);
+    await startStdioServer(factory);
   } else {
-    await startStreamableHTTPServer(createServer);
+    await startStreamableHTTPServer(factory);
   }
 }
 main().catch((e) => {

package/dist/mcp-app.html

@@ -228,7 +228,7 @@ X:`),l=o.length;return l===0&&(l=1),l};var r=a.TuneBook=function(s){var o=t(s);t
 `)}
 `):`${a.join(`
 `)}
-${n}`}function f3(e){const t=u3(e),n={};return e.swing!==void 0&&(n.swing=e.swing),{...t,abcNotation:e.abcNotation?h3(e.abcNotation,e):void 0,synthOptions:n}}const ye={visualObj:null,synthControl:null,currentInstrument:ou,currentStyle:"",currentAbc:null,highlightedEls:[]},nr=document.querySelector(".main"),Tc=document.getElementById("status"),At=document.getElementById("sheet-music"),pa=document.getElementById("audio-controls"),lu=document.getElementById("instrument-selector"),uu=document.getElementById("style-selector"),hu=document.getElementById("toolbar");"audioSession"in navigator&&(navigator.audioSession.type="playback");const d3={onEvent(e){if(ye.highlightedEls.forEach(t=>t.classList.remove("note-playing")),ye.highlightedEls=[],!!e.elements){for(const t of e.elements)for(const n of t)n.classList.add("note-playing"),ye.highlightedEls.push(n);ye.highlightedEls.length>0&&ye.highlightedEls[0].scrollIntoView({behavior:"smooth",block:"nearest"})}},onFinished(){ye.highlightedEls.forEach(e=>e.classList.remove("note-playing")),ye.highlightedEls=[]}},_t=document.createElement("select");_t.id="instrument-select";_t.className="control-select";for(const e of Object.keys($t)){const t=document.createElement("option");t.value=e,t.textContent=e,e===ye.currentInstrument&&(t.selected=!0),_t.appendChild(t)}_t.addEventListener("change",()=>{ye.currentInstrument=_t.value,ye.visualObj&&ye.synthControl&&p3()});async function p3(){var e;if(!(!ye.synthControl||!((e=ye.visualObj)!=null&&e[0])))try{const n={program:$t[ye.currentInstrument]??0};await ye.synthControl.setTune(ye.visualObj[0],!1,n)}catch(t){console.error("Failed to apply settings:",t)}}const kr=document.createElement("label");kr.className="control-label";kr.htmlFor="instrument-select";kr.textContent="Instrument";lu.appendChild(kr);lu.appendChild(_t);const ot=document.createElement("select");ot.id="style-select";ot.className="control-select";const hi=document.createElement("option");hi.value="";hi.textContent="No style (melody only)";ot.appendChild(hi);for(const e of Object.keys(li)){const t=document.createElement("option");t.value=e,t.textContent=e.charAt(0).toUpperCase()+e.slice(1),ot.appendChild(t)}ot.addEventListener("change",()=>{ye.currentStyle=ot.value,ye.currentAbc&&fu(ye.currentAbc)});const xr=document.createElement("label");xr.className="control-label";xr.htmlFor="style-select";xr.textContent="Style";uu.appendChild(xr);uu.appendChild(ot);let ir=null;const Jt=document.createElement("button");Jt.className="toolbar-btn";Jt.textContent="⛶";Jt.title="Toggle fullscreen";Jt.addEventListener("click",()=>{ir==null||ir.requestDisplayMode({mode:"fullscreen"})});hu.appendChild(Jt);function It(e,t=!1){Tc.textContent=e,Tc.classList.toggle("error",t)}async function fu(e,t){try{It("Rendering..."),ye.synthControl&&ye.synthControl.pause(),ye.currentAbc=e,At.innerHTML="",pa.innerHTML="";const n=cu(e,ye.currentStyle);if(ye.visualObj=ar.renderAbc(At,n,{responsive:"resize",add_classes:!0}),!ye.visualObj||ye.visualObj.length===0)throw new Error("Failed to parse music notation");if(!ar.synth.supportsAudio())throw new Error("Audio not supported in this browser");ye.synthControl=new ar.synth.SynthController,ye.synthControl.load(pa,d3,{displayLoop:!0,displayPlay:!0,displayProgress:!0,displayWarp:!0});const r={program:$t[ye.currentInstrument]??0,...t};await ye.synthControl.setTune(ye.visualObj[0],!1,r),hu.classList.add("visible"),It("Ready to play!")}catch(n){console.error("Render error:",n),It(`Error: ${n.message}`,!0),pa.innerHTML=""}}const kt=new yg({name:"Music Studio",version:"0.1.0"});ir=kt;kt.ontoolinput=e=>{console.info("Received tool input:",e);const t=f3(e.arguments??{});ye.currentInstrument=t.instrument,_t.value=t.instrument,ye.currentStyle=t.style,ot.value=t.style,t.abcNotation?fu(t.abcNotation,t.synthOptions).catch(console.error):It("No ABC notation provided",!0)};let ga=null,Ec="";kt.ontoolinputpartial=e=>{var a,r;const t=(a=e.arguments)==null?void 0:a.abcNotation;if(!t)return;ye.currentAbc=t;const n=(r=e.arguments)==null?void 0:r.style;if(n&&ui(n)&&ye.currentStyle!==n&&(ye.currentStyle=n,ot.value=n),!t.match(/K:[^\n]+/)){It("Composing...");return}t!==Ec&&(Ec=t,ga&&clearTimeout(ga),ga=setTimeout(()=>{try{const s=cu(t,ye.currentStyle);ar.renderAbc(At,s,{responsive:"resize",add_classes:!0}),At.scrollTop=At.scrollHeight;const o=At.closest(".sheet-section");o&&(o.scrollTop=o.scrollHeight),It("Composing...")}catch{}},150))};kt.onerror=console.error;function du(e){e.safeAreaInsets&&(nr.style.paddingTop=`${e.safeAreaInsets.top}px`,nr.style.paddingRight=`${e.safeAreaInsets.right}px`,nr.style.paddingBottom=`${e.safeAreaInsets.bottom}px`,nr.style.paddingLeft=`${e.safeAreaInsets.left}px`)}kt.onhostcontextchanged=du;kt.connect().then(()=>{const e=kt.getHostContext();e&&du(e)});</script>
+${n}`}function f3(e){const t=u3(e),n={};return e.swing!==void 0&&(n.swing=e.swing),{...t,abcNotation:e.abcNotation?h3(e.abcNotation,e):void 0,synthOptions:n}}const ye={visualObj:null,synthControl:null,currentInstrument:ou,currentStyle:"",currentAbc:null,highlightedEls:[]},nr=document.querySelector(".main"),Tc=document.getElementById("status"),At=document.getElementById("sheet-music"),pa=document.getElementById("audio-controls"),lu=document.getElementById("instrument-selector"),uu=document.getElementById("style-selector"),hu=document.getElementById("toolbar");"audioSession"in navigator&&(navigator.audioSession.type="playback");const d3={onEvent(e){if(ye.highlightedEls.forEach(t=>t.classList.remove("note-playing")),ye.highlightedEls=[],!!e.elements){for(const t of e.elements)for(const n of t)n.classList.add("note-playing"),ye.highlightedEls.push(n);ye.highlightedEls.length>0&&ye.highlightedEls[0].scrollIntoView({behavior:"smooth",block:"nearest"})}},onFinished(){ye.highlightedEls.forEach(e=>e.classList.remove("note-playing")),ye.highlightedEls=[]}},_t=document.createElement("select");_t.id="instrument-select";_t.className="control-select";for(const e of Object.keys($t)){const t=document.createElement("option");t.value=e,t.textContent=e,e===ye.currentInstrument&&(t.selected=!0),_t.appendChild(t)}_t.addEventListener("change",()=>{ye.currentInstrument=_t.value,ye.visualObj&&ye.synthControl&&p3()});async function p3(){var e;if(!(!ye.synthControl||!((e=ye.visualObj)!=null&&e[0])))try{const n={program:$t[ye.currentInstrument]??0};await ye.synthControl.setTune(ye.visualObj[0],!1,n)}catch(t){console.error("Failed to apply settings:",t)}}const kr=document.createElement("label");kr.className="control-label";kr.htmlFor="instrument-select";kr.textContent="Instrument";lu.appendChild(kr);lu.appendChild(_t);const ot=document.createElement("select");ot.id="style-select";ot.className="control-select";const hi=document.createElement("option");hi.value="";hi.textContent="No style (melody only)";ot.appendChild(hi);for(const e of Object.keys(li)){const t=document.createElement("option");t.value=e,t.textContent=e.charAt(0).toUpperCase()+e.slice(1),ot.appendChild(t)}ot.addEventListener("change",()=>{ye.currentStyle=ot.value,ye.currentAbc&&fu(ye.currentAbc)});const xr=document.createElement("label");xr.className="control-label";xr.htmlFor="style-select";xr.textContent="Style";uu.appendChild(xr);uu.appendChild(ot);let ir=null;const Jt=document.createElement("button");Jt.className="toolbar-btn";Jt.textContent="⛶";Jt.title="Toggle fullscreen";Jt.addEventListener("click",()=>{ir==null||ir.requestDisplayMode({mode:"fullscreen"})});hu.appendChild(Jt);function It(e,t=!1){Tc.textContent=e,Tc.classList.toggle("error",t)}async function fu(e,t){try{It("Rendering..."),ye.synthControl&&ye.synthControl.pause(),ye.currentAbc=e,At.innerHTML="",pa.innerHTML="";const n=cu(e,ye.currentStyle);if(ye.visualObj=ar.renderAbc(At,n,{responsive:"resize",add_classes:!0}),!ye.visualObj||ye.visualObj.length===0)throw new Error("Failed to parse music notation");if(!ar.synth.supportsAudio())throw new Error("Audio not supported in this browser");ye.synthControl=new ar.synth.SynthController,ye.synthControl.load(pa,d3,{displayLoop:!0,displayPlay:!0,displayProgress:!0,displayWarp:!0});const r={program:$t[ye.currentInstrument]??0,...t};await ye.synthControl.setTune(ye.visualObj[0],!1,r),hu.classList.add("visible"),It("Ready to play!")}catch(n){console.error("Render error:",n),It(`Error: ${n.message}`,!0),pa.innerHTML=""}}const kt=new yg({name:"Music Studio",version:"0.1.2"});ir=kt;kt.ontoolinput=e=>{console.info("Received tool input:",e);const t=f3(e.arguments??{});ye.currentInstrument=t.instrument,_t.value=t.instrument,ye.currentStyle=t.style,ot.value=t.style,t.abcNotation?fu(t.abcNotation,t.synthOptions).catch(console.error):It("No ABC notation provided",!0)};let ga=null,Ec="";kt.ontoolinputpartial=e=>{var a,r;const t=(a=e.arguments)==null?void 0:a.abcNotation;if(!t)return;ye.currentAbc=t;const n=(r=e.arguments)==null?void 0:r.style;if(n&&ui(n)&&ye.currentStyle!==n&&(ye.currentStyle=n,ot.value=n),!t.match(/K:[^\n]+/)){It("Composing...");return}t!==Ec&&(Ec=t,ga&&clearTimeout(ga),ga=setTimeout(()=>{try{const s=cu(t,ye.currentStyle);ar.renderAbc(At,s,{responsive:"resize",add_classes:!0}),At.scrollTop=At.scrollHeight;const o=At.closest(".sheet-section");o&&(o.scrollTop=o.scrollHeight),It("Composing...")}catch{}},150))};kt.onerror=console.error;function du(e){e.safeAreaInsets&&(nr.style.paddingTop=`${e.safeAreaInsets.top}px`,nr.style.paddingRight=`${e.safeAreaInsets.right}px`,nr.style.paddingBottom=`${e.safeAreaInsets.bottom}px`,nr.style.paddingLeft=`${e.safeAreaInsets.left}px`)}kt.onhostcontextchanged=du;kt.connect().then(()=>{const e=kt.getHostContext();e&&du(e)});</script>
   <style rel="stylesheet" crossorigin>.abcjs-inline-audio{height:26px;padding:0 5px;border-radius:3px;background-color:#424242;display:flex;align-items:center;box-sizing:border-box}.abcjs-inline-audio.abcjs-disabled{opacity:.5}.abcjs-inline-audio .abcjs-btn{display:block;width:28px;height:34px;margin-right:2px;padding:7px 4px;background:none!important;border:1px solid transparent;box-sizing:border-box;line-height:1}.abcjs-btn g{fill:#f4f4f4;stroke:#f4f4f4}.abcjs-inline-audio .abcjs-btn:hover g{fill:#ccc;stroke:#ccc}.abcjs-inline-audio .abcjs-midi-selection.abcjs-pushed,.abcjs-inline-audio .abcjs-midi-loop.abcjs-pushed,.abcjs-inline-audio .abcjs-midi-reset.abcjs-pushed{border:1px solid #cccccc;background-color:#666;box-sizing:border-box}.abcjs-inline-audio .abcjs-midi-start .abcjs-pause-svg,.abcjs-inline-audio .abcjs-midi-start .abcjs-loading-svg,.abcjs-inline-audio .abcjs-midi-start.abcjs-pushed .abcjs-play-svg,.abcjs-inline-audio .abcjs-midi-start.abcjs-loading .abcjs-play-svg{display:none}.abcjs-inline-audio .abcjs-midi-start.abcjs-pushed .abcjs-pause-svg{display:block}.abcjs-inline-audio .abcjs-midi-progress-background{background-color:#424242;height:10px;border-radius:5px;border:2px solid #cccccc;margin:0 8px 0 15px;position:relative;flex:1;padding:0;box-sizing:border-box}.abcjs-inline-audio .abcjs-midi-progress-indicator{width:20px;margin-left:-10px;height:14px;background-color:#f4f4f4;position:absolute;display:inline-block;border-radius:6px;top:-4px;left:0;box-sizing:border-box}.abcjs-inline-audio .abcjs-midi-clock{margin-left:4px;margin-top:1px;margin-right:2px;display:inline-block;font-family:sans-serif;font-size:16px;box-sizing:border-box;color:#f4f4f4}.abcjs-inline-audio .abcjs-tempo-wrapper{font-size:10px;color:#f4f4f4;box-sizing:border-box;display:flex;align-items:center}.abcjs-inline-audio .abcjs-midi-tempo{border-radius:2px;border:none;margin:0 2px 0 4px;width:42px;padding-left:2px;box-sizing:border-box}.abcjs-inline-audio .abcjs-loading .abcjs-loading-svg{display:inherit}.abcjs-inline-audio .abcjs-loading{outline:none;animation-name:abcjs-spin;animation-duration:1s;animation-iteration-count:infinite;animation-timing-function:linear}.abcjs-inline-audio .abcjs-loading-svg circle{stroke:#f4f4f4}@keyframes abcjs-spin{0%{transform:rotate(0)}to{transform:rotate(360deg)}}.abcjs-large .abcjs-inline-audio{height:52px}.abcjs-large .abcjs-btn{width:56px;height:52px;font-size:28px;padding:6px 8px}.abcjs-large .abcjs-midi-progress-background{height:20px;border:4px solid #cccccc}.abcjs-large .abcjs-midi-progress-indicator{height:28px;top:-8px;width:40px}.abcjs-large .abcjs-midi-clock{font-size:32px;margin-right:10px;margin-left:10px;margin-top:-1px}.abcjs-large .abcjs-midi-tempo{font-size:20px;width:50px}.abcjs-large .abcjs-tempo-wrapper{font-size:20px}.abcjs-css-warning{display:none}*{box-sizing:border-box}html,body{font-family:system-ui,-apple-system,sans-serif;font-size:1rem}code{font-size:1em}:root{--color-bg: #ffffff;--color-text: #1f2937;--color-text-muted: #6b7280;--color-primary: #2563eb;--color-success: #10b981;--color-danger: #ef4444;--color-card-bg: #f9fafb;--color-border: #e5e7eb}@media(prefers-color-scheme:dark){:root{--color-bg: #111827;--color-text: #f9fafb;--color-text-muted: #9ca3af;--color-primary: #3b82f6;--color-success: #34d399;--color-danger: #f87171;--color-card-bg: #1f2937;--color-border: #374151}}html,body{margin:0;padding:0;background:var(--color-bg);color:var(--color-text)}.main{width:100%;margin:0 auto;padding:8px;display:flex;flex-direction:column;gap:8px}.header{display:flex;flex-direction:column;gap:6px}#audio-controls:empty{display:none}#audio-controls:not(:empty)~#status{display:none}.audio-controls{width:100%}.audio-controls .abcjs-inline-audio{border-radius:8px}.audio-controls .abcjs-inline-audio .abcjs-midi-loop.abcjs-pushed{background-color:var(--color-success)!important;border-color:var(--color-success)!important}.status{font-size:.875rem;color:var(--color-text-muted)}.status.error{color:var(--color-danger)}.toolbar{display:none;flex-wrap:wrap;gap:8px}.toolbar.visible{display:flex}.toolbar-group{display:flex;align-items:center;gap:6px;flex:1;min-width:140px}.control-label{font-size:.75rem;color:var(--color-text-muted);white-space:nowrap;text-transform:uppercase;letter-spacing:.05em}.control-select{flex:1;padding:5px 8px;border:1px solid var(--color-border);border-radius:6px;background:var(--color-card-bg);color:var(--color-text);font-size:.8125rem;cursor:pointer;min-width:0}.control-select:focus{outline:2px solid var(--color-primary);outline-offset:-1px}.toolbar-btn{padding:5px 10px;border:1px solid var(--color-border);border-radius:6px;background:var(--color-card-bg);color:var(--color-text);font-size:1rem;cursor:pointer;line-height:1}.toolbar-btn:hover{background:var(--color-border)}.note-playing path,.note-playing circle,.note-playing ellipse,.note-playing polygon{fill:var(--color-primary)!important;transition:fill .08s ease}.note-playing path[stroke]{stroke:var(--color-primary)!important}.sheet-section{background:var(--color-card-bg);border-radius:8px;padding:16px;border:1px solid var(--color-border);min-height:200px;max-height:80vh;overflow-y:auto;scroll-behavior:smooth}.sheet-section .sheet-music-container{width:100%;overflow-x:auto}</style>
 </head>
 <body>

package/dist/server.d.ts

@@ -8,5 +8,10 @@ export declare function handlePlaySheetMusic({ abcNotation, }: {
 export declare function handleGetMusicGuide({ topic, }: {
     topic: (typeof GUIDE_TOPICS)[number];
 }): Promise<CallToolResult>;
-export declare function createServer(): McpServer;
+export type RenderMode = "auto" | "html" | "browser";
+export interface ServerOptions {
+    defaultRenderMode?: RenderMode;
+    outputDir?: string;
+}
+export declare function createServer(options?: ServerOptions): McpServer;
 export {};

package/dist/server.js

@@ -52118,6 +52118,12 @@ function uZ(Z, $, J, X) {
 function fZ(Z, $, J, X, D) {
   return Z.registerResource($, J, { mimeType: d, ...X }, D);
 }
+var OQ = "io.modelcontextprotocol/ui";
+function dZ(Z) {
+  if (!Z)
+    return;
+  return Z.extensions?.[OQ];
+}
 
 // src/music-logic.ts
 var INSTRUMENTS = {
@@ -52343,8 +52349,11 @@ function formatKey(raw) {
     return "";
   return raw.replace(/([A-G])b/g, "$1♭").replace(/([A-G])#/g, "$1♯");
 }
+function stripVoiceNameQuotes(abc) {
+  return abc.replace(/^(V:\S+.*?\bname=)"([^"]*)"(.*)$/gm, "$1$2$3");
+}
 function generatePlayerHtml(options) {
-  let abc = options.abcNotation;
+  let abc = stripVoiceNameQuotes(options.abcNotation);
   if (options.tempo !== undefined || options.transpose !== undefined) {
     abc = injectTempoAndTranspose(abc, {
       tempo: options.tempo,
@@ -52673,12 +52682,12 @@ function generatePlayerHtml(options) {
 </body>
 </html>`;
 }
-async function openPlayerInBrowser(options) {
+async function openPlayerInBrowser(options, outputDir) {
   const html = generatePlayerHtml(options);
-  const tmpDir = path.join(os.tmpdir(), "mcp-music-studio");
-  await fs.mkdir(tmpDir, { recursive: true });
+  const outDir = outputDir ?? path.join(os.homedir(), "Desktop", "mcp-music-studio");
+  await fs.mkdir(outDir, { recursive: true });
   const filename = `player-${Date.now()}.html`;
-  const filepath = path.join(tmpDir, filename);
+  const filepath = path.join(outDir, filename);
   await fs.writeFile(filepath, html, "utf-8");
   const platform = process.platform;
   let cmd;
@@ -53180,62 +53189,90 @@ async function handleGetMusicGuide({
     content: [{ type: "text", text: GUIDES[topic] }]
   };
 }
-function createServer() {
+function createServer(options) {
+  const defaultRenderMode = options?.defaultRenderMode ?? "auto";
+  const outputDir = options?.outputDir;
+  let clientSupportsExtApps = false;
   const server = new McpServer({
     name: "Music Studio",
-    version: "0.1.0"
+    version: "0.1.2"
   });
   const resourceUri = "ui://sheet-music/mcp-app.html";
-  uZ(server, "play-sheet-music", {
-    title: "Play Sheet Music",
-    description: "Creates and plays music with visual sheet music and multi-instrument audio. " + "Use this to compose original songs, demonstrate music theory, set a mood, " + `celebrate occasions, or play well-known tunes.
+  const playInputSchema = exports_external.object({
+    abcNotation: exports_external.string().default(DEFAULT_ABC_NOTATION_INPUT).describe('ABC notation string. Include chord symbols ("C", "Am7") above notes for auto-accompaniment with style presets.'),
+    instrument: exports_external.string().optional().describe("Default instrument. Options: Acoustic Grand Piano, Electric Piano, Harpsichord, " + "Music Box, Vibraphone, Marimba, Xylophone, Church Organ, Accordion, Harmonica, " + "Acoustic Guitar (Nylon), Acoustic Guitar (Steel), Electric Guitar (Clean), " + "Acoustic Bass, Violin, Viola, Cello, String Ensemble, Trumpet, Trombone, " + "French Horn, Alto Sax, Tenor Sax, Oboe, Clarinet, Flute, Pan Flute, Steel Drums."),
+    style: exports_external.enum(STYLE_NAMES).optional().describe("Accompaniment style. Adds drums, bass, and chord patterns automatically. " + 'Your ABC needs chord symbols ("C", "Am") for accompaniment to work. ' + "Options: rock, jazz, bossa, waltz, march, reggae, folk, classical."),
+    tempo: exports_external.number().min(40).max(240).optional().describe("Tempo in BPM (40-240). Overrides Q: in ABC notation."),
+    swing: exports_external.number().min(0).max(100).optional().describe("Swing percentage (0-100). 0=straight, 33=light swing, 66=heavy swing. Great for jazz and blues."),
+    transpose: exports_external.number().min(-12).max(12).optional().describe("Transpose by semitones (-12 to 12). Positive=higher, negative=lower.")
+  });
+  const BASE_DESCRIPTION = "Creates and plays music with visual sheet music and multi-instrument audio. " + "Use this to compose original songs, demonstrate music theory, set a mood, " + `celebrate occasions, or play well-known tunes.
 
-` + `WHAT YOU CAN CREATE:
-` + `- Original compositions for any occasion (birthdays, lullabies, celebrations)
-` + `- Genre pieces: set the style parameter for automatic drums + bass + chord accompaniment
-` + `- Educational demos: scales, modes, chord progressions, rhythms
-` + `- Multi-voice arrangements with different instruments per voice
+` + "BEFORE COMPOSING: Call get-music-guide first to learn available instruments, " + "styles, drum patterns, and ABC syntax. Start with topic 'genres' for complete " + `examples, 'styles' for preset details, or 'instruments' for the full list.
 
 ` + `HOW IT WORKS:
-` + 'Write ABC notation with chord symbols ("C", "Am7", "G7") above the melody. ' + "Set a style to get automatic accompaniment. For known tunes, look up ABC from " + `abcnotation.com or thesession.org.
+` + 'Write ABC notation with chord symbols ("C", "Am7", "G7") above the melody. ' + "Set a style to get automatic drums + bass + chord accompaniment. " + `For known tunes, look up ABC from abcnotation.com or thesession.org.
 
 ` + `QUICK ABC REFERENCE:
 ` + `Notes: C D E F G A B c d e (lowercase=octave up) | Rests: z z2 z4
 ` + `Lengths: C2(half) C/2(eighth) C3/2(dotted) | Bars: | |: :| [1 [2
 ` + `Chords: [CEG](simultaneous) "Am"(guitar chord) | Ties: C-C | Slurs: (CDE)
 ` + `Multi-voice: V:1 ... V:2 ... with %%MIDI program N per voice
-` + `Dynamics: !p! !f! !ff! !mf! | Tempo: Q:1/4=120
+` + "Dynamics: !p! !f! !ff! !mf! | Tempo: Q:1/4=120";
+  const EXT_APPS_SUFFIX = `
 
-` + "Use the get-music-guide tool for detailed reference on instruments, drums, genres, and arrangements.",
-    inputSchema: exports_external.object({
-      abcNotation: exports_external.string().default(DEFAULT_ABC_NOTATION_INPUT).describe('ABC notation string. Include chord symbols ("C", "Am7") above notes for auto-accompaniment with style presets.'),
-      instrument: exports_external.string().optional().describe("Default instrument. Options: Acoustic Grand Piano, Electric Piano, Harpsichord, " + "Music Box, Vibraphone, Marimba, Xylophone, Church Organ, Accordion, Harmonica, " + "Acoustic Guitar (Nylon), Acoustic Guitar (Steel), Electric Guitar (Clean), " + "Acoustic Bass, Violin, Viola, Cello, String Ensemble, Trumpet, Trombone, " + "French Horn, Alto Sax, Tenor Sax, Oboe, Clarinet, Flute, Pan Flute, Steel Drums."),
-      style: exports_external.enum(STYLE_NAMES).optional().describe("Accompaniment style. Adds drums, bass, and chord patterns automatically. " + 'Your ABC needs chord symbols ("C", "Am") for accompaniment to work. ' + "Options: rock, jazz, bossa, waltz, march, reggae, folk, classical."),
-      tempo: exports_external.number().min(40).max(240).optional().describe("Tempo in BPM (40-240). Overrides Q: in ABC notation."),
-      swing: exports_external.number().min(0).max(100).optional().describe("Swing percentage (0-100). 0=straight, 33=light swing, 66=heavy swing. Great for jazz and blues."),
-      transpose: exports_external.number().min(-12).max(12).optional().describe("Transpose by semitones (-12 to 12). Positive=higher, negative=lower."),
-      openInBrowser: exports_external.boolean().optional().describe("Open a standalone browser player with full playback, note highlighting, and controls. " + "Use this in CLI environments (Claude Code, Codex, Gemini CLI) where the MCP client doesn't render UI.")
-    }),
-    _meta: { ui: { resourceUri } }
-  }, async (args) => {
+The music player renders inline with interactive playback controls.`;
+  const FALLBACK_SUFFIX = `
+
+The music player is delivered as HTML or opened in the browser automatically.`;
+  const playHandler = async (args) => {
     const result = await handlePlaySheetMusic(args);
-    if (args.openInBrowser && !result.isError) {
+    if (result.isError)
+      return result;
+    if (defaultRenderMode === "auto")
+      return result;
+    const playerOpts = {
+      abcNotation: args.abcNotation,
+      style: args.style,
+      instrument: args.instrument,
+      tempo: args.tempo,
+      swing: args.swing,
+      transpose: args.transpose
+    };
+    if (defaultRenderMode === "html") {
       try {
-        const filepath = await openPlayerInBrowser({
-          abcNotation: args.abcNotation,
-          style: args.style,
-          instrument: args.instrument,
-          tempo: args.tempo,
-          swing: args.swing,
-          transpose: args.transpose
+        const html = generatePlayerHtml(playerOpts);
+        const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+        result.content = [
+          { type: "text", text },
+          {
+            type: "resource",
+            resource: {
+              uri: `music://player/${Date.now()}.html`,
+              mimeType: "text/html",
+              text: html
+            }
+          }
+        ];
+      } catch (err) {
+        result.content.push({
+          type: "text",
+          text: `
+Failed to generate HTML player: ${err.message}`
         });
+      }
+    } else if (defaultRenderMode === "browser") {
+      try {
+        const filepath = await openPlayerInBrowser(playerOpts, outputDir);
+        const fileUrl = `file://${filepath}`;
         const text = result.content[0]?.type === "text" ? result.content[0].text : "";
         result.content = [
           {
             type: "text",
             text: `${text}
 
-Opened music player in browser: ${filepath}`
+Music player saved and opening in browser.
+File: ${fileUrl}`
           }
         ];
       } catch (err) {
@@ -53247,7 +53284,26 @@ Failed to open browser: ${err.message}`
       }
     }
     return result;
-  });
+  };
+  uZ(server, "play-sheet-music", {
+    title: "Play Sheet Music",
+    description: BASE_DESCRIPTION + FALLBACK_SUFFIX,
+    inputSchema: playInputSchema,
+    _meta: { ui: { resourceUri } }
+  }, playHandler);
+  server.server.oninitialized = () => {
+    const caps = server.server.getClientCapabilities();
+    const uiCap = dZ(caps);
+    clientSupportsExtApps = !!uiCap?.mimeTypes?.includes(d);
+    if (clientSupportsExtApps) {
+      uZ(server, "play-sheet-music", {
+        title: "Play Sheet Music",
+        description: BASE_DESCRIPTION + EXT_APPS_SUFFIX,
+        inputSchema: playInputSchema,
+        _meta: { ui: { resourceUri } }
+      }, playHandler);
+    }
+  };
   server.registerTool("get-music-guide", {
     title: "Music Reference Guide",
     description: "Returns detailed reference material for music composition. " + "Topics: instruments (GM instrument list + combos), drums (patterns + percussion notes), " + "abc-syntax (notation reference), arrangements (multi-voice patterns), " + "genres (complete ABC templates for jazz/blues/folk/rock/bossa/classical), " + "styles (what each style preset does), midi-directives (%%MIDI reference).",

package/dist/src/browser-fallback.d.ts

@@ -7,4 +7,4 @@ export interface BrowserPlayerOptions {
     transpose?: number;
 }
 export declare function generatePlayerHtml(options: BrowserPlayerOptions): string;
-export declare function openPlayerInBrowser(options: BrowserPlayerOptions): Promise<string>;
+export declare function openPlayerInBrowser(options: BrowserPlayerOptions, outputDir?: string): Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-music-studio",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "MCP music composition server — multi-instrument playback, style presets, note highlighting, and AI-friendly reference guides. Fork of @modelcontextprotocol/server-sheet-music.",
   "keywords": [