myinstants-mcp

Instructions

Implementation Reference

• server.js:481-519 (handler)

  The "play_sound" MCP tool is defined and implemented here, handling sound retrieval (via slug, URL, or query) and playback using streamPlay or enqueue, and returning the duration.

  server.tool(
    "play_sound",
    "Play a sound from myinstants.com. Returns the sound duration in seconds so you can plan around async playback.",
    {
      slug: z.string().optional().describe("Sound slug from search results"),
      url: z.string().optional().describe("Direct MP3 URL"),
      query: z.string().optional().describe("Quick search — plays first result"),
      wait: z.boolean().optional().default(defaultWait).describe(`Wait for sound to finish before returning (default: ${defaultWait}). Set true only for dramatic moments where timing matters.`),
    },
    async ({ slug, url, query, wait }) => {
      let soundUrl = url;
      let name = url?.split("/").pop()?.replace(/\.\w+$/, "") || "";
  
      if (query) {
        const results = await search(query);
        if (!results.length) return { content: [{ type: "text", text: `No sounds found for "${query}"` }] };
        const q = query.toLowerCase();
        const best = results.find(r => r.name.toLowerCase() === q) || results[0];
        soundUrl = best.url;
        name = best.name;
      } else if (slug) {
        const html = await httpGet(`${BASE}/en/instant/${encodeURIComponent(slug)}/`);
        soundUrl = html.match(/<meta\s+(?:name|property)=["']og:audio["']\s+content=["']([^"']+)["']/)?.[1] || null;
        if (!soundUrl) return { content: [{ type: "text", text: `Sound "${slug}" not found` }] };
        name = (html.match(/<meta\s+(?:name|property)=["']og:title["']\s+content=["']([^"']+)["']/)?.[1] || "").replace(/\s*-\s*Sound Button$/i, "") || slug.replace(/-\d+$/, "").replace(/-/g, " ");
      }
  
      if (!soundUrl) return { content: [{ type: "text", text: "Provide slug, url, or query." }] };
  
      const [duration] = await Promise.all([
        getMp3Duration(soundUrl),
        wait ? streamPlay(soundUrl) : Promise.resolve(enqueue(soundUrl)),
      ]);
      const lines = [`🔊 ${name}`];
      if (duration) lines.push(`Duration: ${duration}s`);
      if (!wait && duration) lines.push(`Sound is playing in the background and will finish in ~${duration} seconds.`);
      return { content: [{ type: "text", text: lines.join("\n") }] };
    }
  );