health_check

Instructions

Implementation Reference

• src/tools/health_check.ts:26-72 (handler)

  The main handler function that probes each chain adapter with a trivial query ('milch') and reports health status, latency, and capabilities. Accepts an AdapterRegistry and HealthCheckInput, returns health results per chain plus a summary.

  export async function healthCheckHandler(
    registry: AdapterRegistry,
    input: HealthCheckInput,
  ): Promise<{ chains: HealthCheckResult[]; summary: { healthy: number; unhealthy: number; unregistered: number } }> {
    const all: Chain[] = ['migros', 'coop', 'aldi', 'denner', 'lidl'];
    const requested = input.chains ?? all;
    const timeout = input.timeoutMs ?? 5000;
  
    const results = await Promise.all(requested.map(async (chain): Promise<HealthCheckResult> => {
      const adapter = registry.get(chain);
      if (!adapter) return { chain, registered: false, ok: false };
      const start = Date.now();
      try {
        const r = await Promise.race([
          adapter.searchProducts({ query: TRIVIAL_QUERY, limit: 1 }),
          new Promise<never>((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout)),
        ]);
        const latencyMs = Date.now() - start;
        if (r.ok) {
          return {
            chain, registered: true, ok: true, latencyMs,
            capabilities: { ...adapter.capabilities },
          };
        }
        return {
          chain, registered: true, ok: false, latencyMs,
          error: { code: r.error.code, reason: 'reason' in r.error ? r.error.reason : undefined },
          capabilities: { ...adapter.capabilities },
        };
      } catch (e) {
        const msg = e instanceof Error ? e.message : String(e);
        return {
          chain, registered: true, ok: false,
          error: { code: msg === 'timeout' ? 'timeout' : 'unavailable', reason: msg },
          capabilities: { ...adapter.capabilities },
        };
      }
    }));
  
    const summary = {
      healthy: results.filter((r) => r.ok).length,
      unhealthy: results.filter((r) => r.registered && !r.ok).length,
      unregistered: results.filter((r) => !r.registered).length,
    };
  
    return { chains: results, summary };
  }

• src/tools/health_check.ts:5-11 (schema)

  Zod schema defining the health_check input: optional 'chains' array (enum of chain names) and optional 'timeoutMs' (1-30000).

  export const healthCheckSchema = z.object({
    chains: z.array(z.enum(['migros', 'coop', 'aldi', 'denner', 'lidl', 'farmy', 'volgshop', 'ottos']))
      .optional()
      .describe('Chains to probe. Default: all configured.'),
    timeoutMs: z.number().int().positive().max(30000).optional()
      .describe('Per-chain timeout in milliseconds. Default 5000.'),
  }).describe('Probe each registered chain adapter with a trivial query and report which are healthy. Useful for diagnosing why a particular chain is missing from search/plan results.');

• src/index.ts:105-110 (registration)

  Registration of the 'health_check' tool in the TOOLS array, mapping name, description, schema (healthCheckSchema), and handler (healthCheckHandler).

  {
    name: 'health_check',
    description: 'Probe each registered chain adapter with a trivial query and report status, latency, and capability flags. Use this when a chain seems missing from results or when debugging adapter problems.',
    schema: healthCheckSchema,
    handler: healthCheckHandler,
  },

• src/index.ts:130-136 (registration)

  The ListToolsRequestSchema handler that exposes tool metadata, including health_check, to the MCP client via zodToJsonSchema conversion.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS.map((t) => ({
      name: t.name,
      description: t.description,
      inputSchema: zodToJsonSchema(t.schema),
    })),
  }));

• scripts/probe-health-check.ts:1-10 (helper)

  Standalone probe script that invokes healthCheckHandler directly with an empty input and prints per-chain status and summary. Useful for CLI debugging.

  import { buildRegistry } from '../src/index.js';
  import { healthCheckHandler } from '../src/tools/health_check.js';
  
  const r = buildRegistry();
  const out = await healthCheckHandler(r, {});
  for (const c of out.chains) {
    const status = !c.registered ? 'UNREGISTERED' : c.ok ? `OK ${c.latencyMs}ms` : `FAIL (${c.error?.code}: ${c.error?.reason ?? ''})`;
    console.log(`${c.chain}: ${status}`);
  }
  console.log('\nSummary:', out.summary);