strale-mcp

Instructions

Implementation Reference

• packages/mcp-server/src/tools.ts:219-285 (handler)

  The executeCapability function handles the execution logic for Strale capabilities, including authentication checks, free-tier verification, and calling the Strale API.

  export async function executeCapability(
    slug: string,
    inputs: Record<string, unknown>,
    opts: StraleClientOptions,
    capabilities?: Capability[],
  ): Promise<{ content: Array<{ type: "text"; text: string }> }> {
    // Determine if this is a free-tier capability
    const cap = capabilities?.find((c) => c.slug === slug);
    const isFreeTier = cap?.is_free_tier ?? FREE_TIER_SLUGS.includes(slug);
  
    if (!opts.apiKey) {
      if (!isFreeTier) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                error: "Authentication required for paid capabilities.",
                fix: "Get a free API key at https://strale.dev/signup — includes €2 free credits, no card needed. Then reconnect with Authorization: Bearer sk_live_YOUR_KEY",
                tip: "Try a free capability first: email-validate, dns-lookup, json-repair, url-to-markdown, or iban-validate — no API key needed.",
              }),
            },
          ],
        };
      }
    }
  
    const { data, status } = await stralePost<Record<string, unknown>>(
      "/v1/do",
      {
        capability_slug: slug,
        inputs,
        max_price_cents: opts.maxPriceCents,
      },
      opts,
    );
  
    if (status === 202) {
      const txId = (data as any).transaction_id;
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              status: "executing",
              message: `Capability '${slug}' is running asynchronously.`,
              transaction_id: txId,
              poll_url: `${opts.baseUrl}/v1/transactions/${txId}`,
              note: "Poll the transaction endpoint until status is 'completed' or 'failed'.",
            }),
          },
        ],
      };
    }
  
    if (status === 429) {
      const retryAfter = (data as any).retry_after_seconds;
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: "Free tier rate limit reached (10 executions/day).",
              fix: "Sign up at https://strale.dev/signup for unlimited access with €2 free credits.",
              ...(retryAfter != null ? { retry_after_seconds: retryAfter } : {}),
            }),
          },

• packages/mcp-server/src/tools.ts:524-562 (registration)

  The 'strale_execute' tool is registered in the MCP server, defining the input schema and calling 'executeCapability'.

  server.registerTool(
    "strale_execute",
    {
      description:
        "Run a Strale capability by slug — validate an IBAN, look up a company in 27 countries, screen against sanctions/PEP lists, extract data from a URL or PDF, check VAT numbers, verify email deliverability, and 250+ more. Returns structured JSON output with SQS quality score, latency, and data provenance. Free capabilities (email-validate, dns-lookup, json-repair, url-to-markdown, iban-validate) work without an API key. Use strale_search first to find the right slug and required inputs.",
      inputSchema: z.object({
        slug: z
          .string()
          .describe(
            "Capability slug from strale_search results, e.g. 'swedish-company-data', 'vat-validate', 'iban-validate'",
          ),
        inputs: z
          .record(z.unknown())
          .describe(
            "Input parameters matching the capability's required fields. Check strale_search results for the expected input_fields.",
          ),
        max_price_cents: z
          .number()
          .optional()
          .describe(
            "Maximum price in EUR cents. Default: 200 (€2.00). Execution fails if capability costs more.",
          ),
      }),
    },
    async ({ slug, inputs, max_price_cents }) => {
      return executeCapability(
        slug,
        inputs as Record<string, unknown>,
        { ...opts, maxPriceCents: max_price_cents ?? opts.maxPriceCents },
        capabilities,
      );
    },
  );
  
  // Meta-tool: strale_search (works without API key)
  server.registerTool(
    "strale_search",
    {
      description: