dsh-artcraft-plugin-soundcraft 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-artcraft-plugin-soundcraft",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "description": "DSH plugin: drive SoundCraft (audio production) headlessly through its own CLI and MCP server.",

package/src/kit/mcp.js

@@ -14,6 +14,8 @@
 
 import { spawn } from 'node:child_process'
                                                                         
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { killTree } from './exec.js'
                                                            
 
@@ -31,6 +33,33 @@ import { killTree } from './exec.js'
                        
  
 
+/** Extensions for the image types an MCP tool can return. */
+const IMAGE_EXTENSIONS                         = {
+  'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif', 'image/svg+xml': 'svg',
+}
+
+/**
+ * Write one base64 image from a tool result to disk.
+ * @param data - base64 payload.
+ * @param mimeType - media type the server declared.
+ * @param dir - directory to write into.
+ * @param craft - craft id, used in the file name.
+ * @param tool - tool name, used in the file name.
+ * @returns the absolute path, or `undefined` when the payload cannot be written.
+ */
+function saveImage(data        , mimeType                    , dir        , craft        , tool        )                     {
+  try {
+    const extension = IMAGE_EXTENSIONS[mimeType ?? ''] ?? 'png'
+    const safeTool = tool.replace(/[^\w.-]+/g, '-')
+    mkdirSync(dir, { recursive: true })
+    const file = join(dir, `${craft}-${safeTool}-${Date.now()}.${extension}`)
+    writeFileSync(file, Buffer.from(data, 'base64'))
+    return file
+  } catch {
+    return undefined
+  }
+}
+
 /** Default MCP protocol revision; servers negotiate down if they need to. */
 const PROTOCOL_VERSION = '2024-11-05'
 
@@ -52,6 +81,8 @@ export class CraftMcpClient {
   #idleTimer                            
   #handshake                                                          
   #tools                       
+  /** Last stderr lines, so a failed attach can say why the app refused. */
+  #stderrTail           = []
   #closed = false
 
   constructor(profile              , binary             , args                    = []) {
@@ -91,17 +122,26 @@ export class CraftMcpClient {
     child.stdout.on('data', (chunk        ) => { this.#onData(chunk) })
     child.stderr.setEncoding('utf8')
     // Craft servers announce themselves on stderr; it is not an error stream.
+    // The tail is kept so a refused attach can repeat the app's own reason
+    // ("no control token", "cannot connect to 127.0.0.1:7979") instead of a
+    // bare "server exited".
     child.stderr.on('data', (chunk        ) => {
       const text = chunk.trim()
-      if (text.length > 0 && process.env.DSH_ARTCRAFT_TRACE !== undefined) {
+      if (text.length === 0) return
+      for (const line of text.split('\n')) {
+        this.#stderrTail.push(line.trim())
+        if (this.#stderrTail.length > 8) this.#stderrTail.shift()
+      }
+      if (process.env.DSH_ARTCRAFT_TRACE !== undefined) {
         process.stderr.write(`[${this.#profile.id} mcp] ${text}\n`)
       }
     })
     child.on('exit', () => {
       this.#child = undefined
+      const reason = this.#stderrTail.filter(line => line.length > 0).slice(-2).join(' ')
       for (const [, pending] of this.#pending) {
         clearTimeout(pending.timer)
-        pending.reject(new Error(`${this.#profile.product}: MCP server exited`))
+        pending.reject(new Error(`${this.#profile.product}: MCP server exited${reason.length > 0 ? ` (${reason})` : ''}`))
       }
       this.#pending.clear()
     })
@@ -134,22 +174,60 @@ export class CraftMcpClient {
 
   /**
    * Call one tool.
+   *
+   * Image results — a render, a screenshot, a page thumbnail — are written to
+   * `artifactsDir` and referenced by path instead of being dropped: the caller
+   * can then look at them with `read_image`, which is the only way an agent
+   * verifies what it drew.
    * @param name - tool name as declared by the server.
    * @param args - the tool's JSON arguments.
-   * @returns the concatenated text content of the result.
+   * @param artifactsDir - directory for returned images, when one is configured.
+   * @returns the text content, with any images saved and named by path.
    */
-  async callTool(name        , args                         )                  {
+  async callTool(name        , args                         , artifactsDir         )                  {
     const result = await this.#request('tools/call', { name, arguments: args })     
-                                                  
+                                                                                    
                        
      
-    const text = (result.content ?? [])
-      .map(block => (block.type === 'text' ? block.text ?? '' : `[${block.type ?? 'unknown'} content]`))
-      .join('\n')
-      .trim()
+    const parts           = []
+    for (const block of result.content ?? []) {
+      if (block.type === 'text') {
+        parts.push(block.text ?? '')
+        continue
+      }
+      if (block.type === 'image' && typeof block.data === 'string' && artifactsDir !== undefined) {
+        const saved = saveImage(block.data, block.mimeType, artifactsDir, this.#profile.id, name)
+        parts.push(saved === undefined
+          ? '[image content]'
+          : `[image] ${saved}\nUse read_image on that path to look at it.`)
+        continue
+      }
+      parts.push(`[${block.type ?? 'unknown'} content]`)
+    }
+    const text = parts.join('\n').trim()
     return `${text.length > 0 ? text : '(no content)'}${result.isError === true ? '\n[mcp: tool reported an error]' : ''}`
   }
 
+  /** List the resources the server advertises (documents, command catalogues). */
+  async listResources()                                                                   {
+    try {
+      const result = await this.#request('resources/list', {})                                                                           
+      return Array.isArray(result.resources) ? result.resources : []
+    } catch {
+      return []
+    }
+  }
+
+  /** List the prompts the server advertises (curated multi-step workflows). */
+  async listPrompts()                                                     {
+    try {
+      const result = await this.#request('prompts/list', {})                                                           
+      return Array.isArray(result.prompts) ? result.prompts : []
+    } catch {
+      return []
+    }
+  }
+
   /** Terminate the server process now. */
   close()       {
     this.#closed = true

package/src/kit/profiles.mjs

@@ -54,6 +54,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'hostPort' },
   },
   {
     id: 'gridcraft',
@@ -80,6 +81,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'port' },
   },
   {
     id: 'soundcraft',
@@ -107,6 +109,7 @@ export const CRAFT_PROFILES = [
     describeArgs: ['describe'],
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'port' },
   },
   {
     id: 'deckcraft',
@@ -133,6 +136,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'port' },
   },
   {
     id: 'wordcraft',
@@ -158,6 +162,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'hostPort' },
   },
   {
     id: 'photocraft',
@@ -186,6 +191,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--bridge', format: 'hostPort' },
   },
   {
     id: 'lightcraft',
@@ -272,6 +278,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'hostPort' },
   },
   {
     id: 'effectcraft',
@@ -297,6 +304,7 @@ export const CRAFT_PROFILES = [
     catalogJson: false,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--bridge', format: 'port' },
   },
   {
     id: 'filmcraft',
@@ -334,6 +342,7 @@ export const CRAFT_PROFILES = [
     describeArgs: ['describe'],
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--bridge', format: 'hostPort' },
   },
   {
     id: 'designcraft',
@@ -358,6 +367,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'port' },
   },
   {
     id: 'figcraft',
@@ -385,6 +395,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--attach', format: 'port' },
   },
   {
     id: 'texturecraft',
@@ -415,6 +426,7 @@ export const CRAFT_PROFILES = [
     catalogJson: false,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--bridge', format: 'port' },
   },
 ]
 

package/src/kit/tools.js

@@ -157,23 +157,37 @@ function craftWorkDir(profile              )         {
  */
 export function createRuntime(profile              , packageRoot        , config                    = {})               {
   let catalogCache                                                                                                          
-  let mcpClient                            
+  const mcpClients = new Map                        ()
+  const artifacts = config.artifactsDir ?? join(tmpdir(), 'dsh-artcraft', profile.id)
   return {
+    artifactsDir()         {
+      return artifacts
+    },
     profile,
     config,
-    mcp()                             {
+    mcp(attach         )                             {
       if (config.enableMcp === false) return undefined
       if (profile.mcpArgs === undefined) return undefined
+      if (attach !== undefined && profile.mcpAttach === undefined) {
+        throw new Error(`${profile.product} cannot attach to a running app: its MCP server is headless only`)
+      }
       const binary = this.binary()
       if (binary === undefined) return undefined
+      const args = [...profile.mcpSessionArgs ?? []]
+      if (attach !== undefined && profile.mcpAttach !== undefined) {
+        args.push(profile.mcpAttach.flag, profile.mcpAttach.format === 'hostPort' ? `127.0.0.1:${attach}` : String(attach))
+      }
+      const key = String(attach ?? '')
+      const existing = mcpClients.get(key)
       // A CLI upgrade mid-session invalidates the running server.
-      if (mcpClient !== undefined && !mcpClient.running && mcpClient.cachedTools !== undefined) mcpClient = undefined
-      mcpClient ??= new CraftMcpClient(profile, binary, profile.mcpSessionArgs ?? [])
-      return mcpClient
+      if (existing !== undefined && !existing.running && existing.cachedTools !== undefined) mcpClients.delete(key)
+      const fresh = mcpClients.get(key) ?? new CraftMcpClient(profile, binary, args)
+      mcpClients.set(key, fresh)
+      return fresh
     },
     dispose()       {
-      mcpClient?.close()
-      mcpClient = undefined
+      for (const client of mcpClients.values()) client.close()
+      mcpClients.clear()
     },
     binary()                          {
       const found = discoverCraft(profile, config.path, packageRoot)
@@ -666,13 +680,19 @@ export function createToolSet(runtime              )               {
       `${profile.product}'s own MCP server tools, each with a real JSON Schema. `
       + `These are the modelled operations (think \`write_range\`, \`render\`), whereas \`${profile.id}_run\` takes generic `
       + `command strings. Use this to discover them, then call one with \`${profile.id}_mcp_call\`. `
-      + `Search by name or description; omit \`search\` to list everything.`,
+      + `Search by name or description, page with \`offset\`/\`limit\` (large servers declare hundreds). `
+      + `Also lists the server's MCP resources and prompts when it has them.`,
     parameters: {
       search: { type: 'string', description: 'Case-insensitive filter over tool names and descriptions.' },
-      limit: { type: 'number', description: 'Maximum tools to describe (default 30).' },
+      limit: { type: 'number', description: 'Maximum tools to describe (default 30, at most 200).' },
+      offset: { type: 'number', description: 'Skip this many matches, to page through a long list.' },
+      ...profile.mcpAttach !== undefined
+        ? { attach: { type: 'number', description: `Control-channel port of a running ${profile.product} app, to drive the user's open document instead of a headless one.` } }
+        : {},
     },
     async execute(args) {
-      const client = runtime.mcp()
+      const attach = typeof args.attach === 'number' ? Math.floor(args.attach) : undefined
+      const client = runtime.mcp(attach)
       if (client === undefined) throw new Error(`${profile.product} has no MCP server configured`)
       await client.start(idleMs)
       const all = await client.listTools()
@@ -681,10 +701,11 @@ export function createToolSet(runtime              )               {
         ? all
         : all.filter(tool => tool.name.toLowerCase().includes(needle) || (tool.description ?? '').toLowerCase().includes(needle))
       const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(Math.floor(args.limit), 200) : 30
-      const shown = matched.slice(0, limit)
+      const offset = typeof args.offset === 'number' && args.offset > 0 ? Math.floor(args.offset) : 0
+      const shown = matched.slice(offset, offset + limit)
       const lines = [
         `${profile.product} MCP server — ${matched.length} tool(s)${needle.length > 0 ? ` matching ${JSON.stringify(args.search)}` : ''}`
-        + (matched.length > shown.length ? `, showing ${shown.length}` : ''),
+        + (matched.length > offset + shown.length ? `, showing ${offset}–${offset + shown.length}` : ''),
         `server: ${client.describe()}`,
         '',
       ]
@@ -693,6 +714,17 @@ export function createToolSet(runtime              )               {
         lines.push(renderSchema(tool.inputSchema))
       }
       if (shown.length === 0) lines.push('(no matching tools)')
+      // Resources and prompts are the parts a tool-only bridge would miss: the
+      // document, the command catalogue, and curated multi-step workflows.
+      const [resources, prompts] = await Promise.all([client.listResources(), client.listPrompts()])
+      if (resources.length > 0) {
+        lines.push('', 'resources:')
+        for (const resource of resources) lines.push(`  ${resource.uri}${resource.name !== undefined ? ` — ${resource.name}` : ''}`)
+      }
+      if (prompts.length > 0) {
+        lines.push('', 'prompts:')
+        for (const prompt of prompts) lines.push(`  ${prompt.name}${prompt.description !== undefined ? ` — ${prompt.description}` : ''}`)
+      }
       return lines.join('\n')
     },
   }
@@ -703,13 +735,18 @@ export function createToolSet(runtime              )               {
     description:
       `Call one tool on ${profile.product}'s MCP server with JSON arguments. `
       + `Discover names and schemas with \`${profile.id}_mcp_tools\` first. `
-      + `Use this for modelled operations; use \`${profile.id}_run\` for arbitrary command ids.`,
+      + `Use this for modelled operations; use \`${profile.id}_run\` for arbitrary command ids. `
+      + `Images a tool returns (render, screenshot) are saved to disk and named by path — look at them with \`read_image\`.`,
     parameters: {
       tool: { type: 'string', required: true, description: 'MCP tool name, exactly as listed.' },
       arguments: { type: 'object', additionalProperties: true, description: "The tool's arguments object; see its schema in the listing." },
+      ...profile.mcpAttach !== undefined
+        ? { attach: { type: 'number', description: `Control-channel port of a running ${profile.product} app, to drive the user's open document instead of a headless one.` } }
+        : {},
     },
     async execute(args) {
-      const client = runtime.mcp()
+      const attach = typeof args.attach === 'number' ? Math.floor(args.attach) : undefined
+      const client = runtime.mcp(attach)
       if (client === undefined) throw new Error(`${profile.product} has no MCP server configured`)
       const name = String(args.tool ?? '').trim()
       if (name.length === 0) throw new Error('tool is required')
@@ -722,7 +759,7 @@ export function createToolSet(runtime              )               {
       }
       const raw = args.arguments
       const params = typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw                            : {}
-      return await client.callTool(name, params)
+      return await client.callTool(name, params, runtime.artifactsDir())
     },
   }
 
@@ -739,6 +776,9 @@ export function createToolSet(runtime              )               {
         `command: ${client.describe()}`,
         `running: ${client.running}`,
         `tools cached: ${client.cachedTools === undefined ? 'no' : client.cachedTools.length}`,
+        profile.mcpAttach === undefined
+          ? 'attach: not supported (headless MCP server only)'
+          : `attach: pass \`attach: <port>\` to drive a running app (it must be started with its control channel, e.g. \`${profile.bin.replace(/-cli$/, '')} --control <port>\`)`,
       ].join('\n')
     },
   }
@@ -825,11 +865,17 @@ export function applyCraftPlugin(
   }
   ctx.systemPrompt.section({
     name: `artcraft:${profile.id}`,
-    text: `${profile.product} is available through the ${profile.id}_* tools. `
-      + `Documents are ${profile.extensions.join('/')}. `
-      + `Discover operations with \`${profile.id}_commands\` (generic command ids) or `
-      + `\`${profile.id}_mcp_tools\` (modelled operations with JSON schemas), read them back with `
-      + `\`${profile.id}_inspect\`, and apply them with \`${profile.id}_run\` or \`${profile.id}_mcp_call\`.`,
+    text:
+      `${profile.product} is available through the ${profile.id}_* tools; documents are ${profile.extensions.join('/')}. `
+      + `Two surfaces reach the same engine. Use \`${profile.id}_commands\` for the full command registry `
+      + `(every menu action; fetch exact parameter grammar with \`${profile.id}_describe\`) and \`${profile.id}_run\` to apply `
+      + `an ordered list. Use \`${profile.id}_mcp_tools\` for the app's modelled operations with JSON Schemas when you want `
+      + `a safer first call, then \`${profile.id}_mcp_call\`. `
+      + `Read a document back with \`${profile.id}_inspect\` before editing it. `
+      + (profile.mcpAttach === undefined
+        ? ''
+        : `When the user has ${profile.product} open, pass \`attach: <control port>\` to an mcp call to work in their window instead of a headless copy. `)
+      + `Images returned by a render or screenshot are saved and named by path; look at them with \`read_image\`.`,
     order: CRAFT_SECTION_ORDER,
   })
   return () => {