check_url

Instructions

Implementation Reference

• src/tools/check.ts:40-51 (handler)

  The check_url tool handler function. Validates API key, calls api.check(url, profile), and returns the result or an error. This is the core execution logic for the check_url tool.

    async ({ url, profile }) => {
      if (!api.hasApiKey) return authError();
  
      try {
        const result = await api.check(url, profile);
        return successResult(result);
      } catch (err) {
        if (err instanceof ApiRequestError) return apiErrorToResult(err);
        return errorResult(err instanceof Error ? err.message : "Unknown error");
      }
    }
  );

• src/tools/check.ts:30-38 (schema)

  Input schema for check_url: requires a URL string (max 2048 chars) and an optional profile name string.

  inputSchema: {
    url: z.string().url().max(2048).describe("The URL to check (must be http:// or https://)"),
    profile: z
      .string()
      .optional()
      .describe(
        "Name of a custom scoring profile to use (optional). If omitted, default weights are used."
      ),
  },

• src/tools/check.ts:15-17 (registration)

  Registration of the check_url tool via server.registerTool() with the name 'check_url', called from src/index.ts line 35.

  export function registerCheckTool(server: McpServer, api: UnphurlAPI): void {
    server.registerTool(
      "check_url",

• src/api.ts:129-133 (helper)

  The api.check() method that check_url's handler delegates to. Makes a GET request to /v1/check with the URL and optional profile parameter.

  async check(urlToCheck: string, profile?: string): Promise<CheckResponse> {
    let path = `/v1/check?url=${encodeURIComponent(urlToCheck)}`;
    if (profile) path += `&profile=${encodeURIComponent(profile)}`;
    return this.doRequest<CheckResponse>("GET", path);
  }

• src/tools/helpers.ts:1-76 (helper)

  Shared helper utilities used by the check_url handler: successResult, errorResult, authError, and apiErrorToResult for consistent MCP tool result formatting.

  // Shared utilities for MCP tool handlers
  // Provides consistent success/error formatting across all tools
  
  import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
  import { ApiRequestError } from "../api.js";
  
  // Wrap any data as a successful MCP tool result
  export function successResult(data: unknown): CallToolResult {
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
  
  // Return a plain error message as an MCP tool error
  export function errorResult(message: string): CallToolResult {
    return {
      content: [{ type: "text", text: JSON.stringify({ error: message }) }],
      isError: true,
    };
  }
  
  // Standard error for tools that require an API key but none is configured
  export function authError(): CallToolResult {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            error: "auth_required",
            message:
              "API key is missing. Set UNPHURL_API_KEY in your MCP server configuration, or use the signup tool to create an account first.",
          }),
        },
      ],
      isError: true,
    };
  }
  
  // Convert an API error into an MCP tool error
  // Special-cases 402 (insufficient credits) to prompt the agent toward the purchase tool
  export function apiErrorToResult(err: ApiRequestError): CallToolResult {
    const body = err.apiError;
  
    if (err.status === 402) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                ...body,
                _hint:
                  "Use the purchase tool to buy more credits, or get_pricing to see available packages.",
              },
              null,
              2
            ),
          },
        ],
        isError: true,
      };
    }
  
    return {
      content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
      isError: true,
    };
  }
  
  // Promise-based sleep for polling loops
  export function sleep(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }