ShieldAPI MCP

Instructions

Implementation Reference

• src/index.ts:179-187 (registration)

  The shieldapi.check_email tool is registered dynamically within a loop that iterates over the TOOLS configuration object. The tool handler uses the `callShieldApi` function to fetch data from the ShieldAPI.

  for (const [name, def] of Object.entries(TOOLS)) {
    server.tool(
      name,
      def.description,
      { [def.param]: z.string().describe(def.paramDesc) },
      { ...readOnlyAnnotations, title: TOOL_TITLES[name] || name },
      async (params) => formatResult(await callShieldApi(def.endpoint, params as Record<string, string>))
    );
  }

• src/index.ts:101-116 (handler)

  The handler function `callShieldApi` performs the actual API request to the ShieldAPI backend. It handles parameter serialization, demo mode injection, and payment-enabled fetching.

  async function callShieldApi(endpoint: string, params: Record<string, string>): Promise<unknown> {
    const url = new URL(`${SHIELDAPI_URL}/api/${endpoint}`);
    for (const [key, value] of Object.entries(params)) {
      url.searchParams.set(key, value);
    }
    if (demoMode) {
      url.searchParams.set('demo', 'true');
    }
  
    const response = await paymentFetch(url.toString());
    if (!response.ok) {
      const body = await response.text();
      throw new Error(`ShieldAPI ${endpoint} failed (${response.status}): ${body.substring(0, 200)}`);
    }
    return response.json();
  }

• src/index.ts:62-68 (schema)

  The schema and configuration for the `shieldapi.check_email` tool, defining the endpoint path and parameter requirements.

    'shieldapi.check_email': {
      description: 'Check if an email address has been exposed in known data breaches via HIBP.',
      param: 'email',
      paramDesc: 'Email address to check',
      endpoint: 'check-email',
    },
  };