evc-spark-mcp

Instructions

Implementation Reference

• src/index.ts:262-274 (handler)

  Tool registration and handler function for 'get_asset'. Takes a slug parameter, fetches asset details from the Spark API, and returns formatted full asset information including description, content, files, ratings, and metadata.

  server.tool(
    "get_asset",
    "Get full details of a Spark asset by its slug. Returns description, content, files, ratings, and more.",
    {
      slug: z.string().describe("Asset slug (e.g. 'vb-seo-expert', 'vb-python-expert')"),
    },
    async ({ slug }) => {
      const asset = await sparkApi<Asset>(`/assets/${slug}`);
      return {
        content: [{ type: "text" as const, text: formatAssetFull(asset) }],
      };
    }
  );

• src/index.ts:265-267 (schema)

  Input schema validation using zod. Defines the single 'slug' parameter as a required string used to identify the asset (e.g., 'vb-seo-expert').

  {
    slug: z.string().describe("Asset slug (e.g. 'vb-seo-expert', 'vb-python-expert')"),
  },

• src/index.ts:77-86 (schema)

  Type definition for the Asset interface. Extends AssetListItem with additional fields like description_md, inline_content, version, files, bundle_items, chain_steps, and external_source information.

  interface Asset extends AssetListItem {
    description_md: string;
    inline_content?: string | null;
    version: string;
    files: { filename: string; size_bytes: number }[];
    bundle_items?: { asset_title: string; asset_slug: string; asset_type: string; role: string }[];
    chain_steps?: { title: string; content: string; order: number }[];
    external_source_name?: string | null;
    external_source_url?: string | null;
  }

• src/index.ts:139-193 (helper)

  Formatting helper function formatAssetFull that transforms an Asset object into a formatted markdown string with sections for title, type, rating, downloads, price, version, URL, AI models, domains, source, description, content, prompt chain steps, bundle contents, and files.

  function formatAssetFull(a: Asset): string {
    const sections: string[] = [
      `# ${a.title}`,
      "",
      `**Type:** ${a.type}`,
      `**Rating:** ${a.rating_avg.toFixed(1)}/5 (${a.rating_count} ratings)`,
      `**Downloads:** ${a.downloads_count}`,
      `**Price:** ${a.pricing_type === "free" ? "Free" : `${a.price_credits} EVC`}`,
      `**Version:** ${a.version}`,
      `**URL:** ${assetUrl(a)}`,
    ];
  
    if (a.ai_tags.length) {
      sections.push(`**AI Models:** ${a.ai_tags.join(", ")}`);
    }
    if (a.domain_tags.length) {
      sections.push(
        `**Domains:** ${a.domain_tags.map((d) => d.child_name).join(", ")}`
      );
    }
    if (a.external_source_name) {
      sections.push(
        `**Source:** ${a.external_source_name}${a.external_source_url ? ` (${a.external_source_url})` : ""}`
      );
    }
  
    sections.push("", "## Description", "", a.description_md);
  
    if (a.inline_content) {
      sections.push("", "## Content", "", a.inline_content);
    }
  
    if (a.chain_steps?.length) {
      sections.push("", "## Prompt Chain Steps");
      for (const step of a.chain_steps.sort((x, y) => x.order - y.order)) {
        sections.push("", `### Step ${step.order}: ${step.title}`, "", step.content);
      }
    }
  
    if (a.bundle_items?.length) {
      sections.push("", "## Bundle Contents");
      for (const item of a.bundle_items) {
        sections.push(`- **${item.asset_title}** (${item.asset_type}) — ${item.role}`);
      }
    }
  
    if (a.files?.length) {
      sections.push("", "## Files");
      for (const f of a.files) {
        sections.push(`- ${f.filename} (${(f.size_bytes / 1024).toFixed(1)} KB)`);
      }
    }
  
    return sections.join("\n");
  }

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

  HTTP helper function sparkApi that makes authenticated fetch requests to the Spark API endpoint. Handles JSON parsing and error responses, throwing descriptive errors for non-OK responses.

  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>;
  }