evc-spark-mcp

Instructions

Implementation Reference

• src/index.ts:345-373 (handler)

  Registration and handler for the list_categories tool. Fetches AI tags and domains from the Spark API taxonomy endpoints and formats them as a markdown response.

  server.tool(
    "list_categories",
    "List available categories (domains and AI tags) in the Spark marketplace. Useful for filtering searches.",
    {},
    async () => {
      const [ais, domains] = await Promise.all([
        sparkApi<AiTag[]>("/taxonomy/ais"),
        sparkApi<DomainGroup[]>("/taxonomy/domains"),
      ]);
  
      const sections: string[] = ["## AI Tags", ""];
      for (const tag of ais) {
        sections.push(`- ${tag.name} (\`${tag.slug}\`)`);
      }
  
      sections.push("", "## Domains", "");
      for (const group of domains) {
        sections.push(`### ${group.parent_name}`);
        for (const child of group.children) {
          sections.push(`- ${child.child_name} (\`${child.child_slug}\`)`);
        }
        sections.push("");
      }
  
      return {
        content: [{ type: "text" as const, text: sections.join("\n") }],
      };
    }
  );

• src/index.ts:95-98 (schema)

  Type definition for AI tag objects returned by the /taxonomy/ais API endpoint

  interface AiTag {
    slug: string;
    name: string;
  }

• src/index.ts:100-104 (schema)

  Type definition for domain group objects returned by the /taxonomy/domains API endpoint

  interface DomainGroup {
    parent_name: string;
    parent_slug: string;
    children: { child_name: string; child_slug: string }[];
  }

• src/index.ts:43-53 (helper)

  HTTP helper function used by list_categories handler to fetch data from the Spark API endpoints

  async function sparkApi<T = unknown>(path: string): Promise<T> {
    const url = `${SPARK_API}${path}`;
    const res = await fetch(url, {
      headers: { Accept: "application/json" },
    });
    if (!res.ok) {
      const text = await res.text().catch(() => res.statusText);
      throw new Error(`Spark API ${res.status}: ${text}`);
    }
    return res.json() as Promise<T>;
  }