documents

Instructions

Implementation Reference

• src/index.ts:107-115 (schema)

  Schema definition for the 'documents' tool. Defines name, description ('Extract structured data from a URL or text content using LLM analysis. Cost: 3 credits.'), and inputSchema with optional 'url', 'content', and 'extraction_prompt' parameters.

  {
    name: "documents",
    description: "Extract structured data from a URL or text content using LLM analysis. Cost: 3 credits.",
    inputSchema: {
      url: z.string().optional().describe("URL to scrape and extract from"),
      content: z.string().optional().describe("Pre-scraped text to extract from"),
      extraction_prompt: z.string().optional().describe("What to extract, in plain language"),
    },
  },

• src/index.ts:255-257 (handler)

  Handler for the 'documents' tool (and all other tools). Registered via loop using server.registerTool; the handler is an async callback that delegates to callSuprsonic(cap.name, args), where cap.name is 'documents'.

  async (args: any): Promise<CallToolResult> => {
    return callSuprsonic(cap.name, args as Record<string, unknown>);
  },

• src/index.ts:247-259 (registration)

  Registration of the 'documents' tool. All capabilities (including 'documents') are registered in a for-of loop via server.registerTool(cap.name, {description, inputSchema}, async handler).

  for (const cap of CAPABILITIES) {
    // Cast inputSchema to avoid TS2589 (excessively deep type instantiation from Zod chains)
    server.registerTool(
      cap.name,
      {
        description: cap.description,
        inputSchema: cap.inputSchema as any,
      },
      async (args: any): Promise<CallToolResult> => {
        return callSuprsonic(cap.name, args as Record<string, unknown>);
      },
    );
  }

• src/index.ts:183-234 (helper)

  The callSuprsonic helper function that all tool handlers delegate to. Makes an HTTP POST to the Suprsonic REST API with the capability name and params, then parses the response.

  async function callSuprsonic(capability: string, params: Record<string, unknown>): Promise<CallToolResult> {
    if (!API_KEY) {
      return {
        content: [{ type: "text", text: "Error: SUPRSONIC_API_KEY environment variable is not set. Get your key at https://suprsonic.ai/app/apis" }],
        isError: true,
      };
    }
  
    try {
      const resp = await fetch(`${BASE_URL}/v1/agent`, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ capability, params }),
      });
  
      const result = await resp.json() as any;
  
      // Handle non-envelope responses (401, 429, etc. return {"detail": ...})
      if (result.detail && result.success === undefined) {
        const msg = typeof result.detail === "object" ? (result.detail.title || result.detail.detail || JSON.stringify(result.detail)) : String(result.detail);
        return {
          content: [{ type: "text", text: `Error (HTTP ${resp.status}): ${msg}` }],
          isError: true,
        };
      }
  
      if (!result.success) {
        const errMsg = result.error?.detail || result.error?.title || "Request failed";
        return {
          content: [{ type: "text", text: `Error: ${errMsg}` }],
          isError: true,
        };
      }
  
      const text = JSON.stringify(result.data, null, 2);
      const meta = result.metadata
        ? `\n\n[Provider: ${(result.metadata as any).provider_used || "unknown"}, ${(result.metadata as any).response_time_ms || 0}ms, ${result.credits_used || 0} credits]`
        : "";
  
      return {
        content: [{ type: "text", text: text + meta }],
      };
    } catch (err) {
      return {
        content: [{ type: "text", text: `Network error: ${err instanceof Error ? err.message : String(err)}` }],
        isError: true,
      };
    }
  }