aaa-health-check

Instructions

Implementation Reference

• packages/core/src/tools/handlers.ts:303-324 (handler)

  Core handler function implementing aaa-health-check tool logic. Detects runtime environment, echoes input, returns formatted JSON health status.

  export async function handleHealthCheck(params: {
    echo?: string;
  }): Promise<ToolResult> {
    const payload = {
      ok: true,
      name: 'attio-mcp-core',
      version: '0.1.0',
      echo: params.echo,
      timestamp: new Date().toISOString(),
      runtime:
        typeof (globalThis as Record<string, unknown>).Deno !== 'undefined'
          ? 'deno'
          : typeof (globalThis as Record<string, unknown>).Bun !== 'undefined'
            ? 'bun'
            : typeof (globalThis as Record<string, unknown>).caches !==
                'undefined'
              ? 'cloudflare-workers'
              : 'node',
    };
  
    return successResult(JSON.stringify(payload, null, 2));
  }

• packages/core/src/tools/definitions.ts:88-113 (schema)

  Tool schema definition including name, description, input schema (optional echo string), and annotations for read-only/idempotent usage.

  export const healthCheckDefinition: ToolDefinition = {
    name: 'aaa-health-check',
    description: formatDescription({
      capability:
        'Run a lightweight health probe that echoes deployment metadata.',
      boundaries: 'query Attio APIs, mutate data, or require credentials.',
      constraints:
        'Accepts optional echo text; returns JSON payload as text for MCP clients.',
      recoveryHint:
        'If unavailable, review server logs or restart the server process.',
    }),
    inputSchema: {
      type: 'object',
      properties: {
        echo: {
          type: 'string',
          description: 'Optional text to echo back in the response',
        },
      },
      additionalProperties: true,
    },
    annotations: {
      readOnlyHint: true,
      idempotentHint: true,
    },
  };

• packages/core/src/tools/handlers.ts:1000-1001 (registration)

  Registration of aaa-health-check in the core tool handler dispatcher map, delegating to handleHealthCheck function.

  'aaa-health-check': async (_client, params) =>
    handleHealthCheck(params as { echo?: string }),

• packages/core/src/tools/registry.ts:44-45 (registration)

  Inclusion of aaa-health-check in read-only tools set for search-only mode filtering.

  const READ_ONLY_TOOLS = new Set([
    'aaa-health-check',

• src/handlers/tool-configs/universal/index.ts:58-104 (handler)

  Alternative/server-specific handler configuration for aaa-health-check with Node.js environment detection and MCP-compliant response formatting.

  export const healthCheckConfig = {
    name: 'aaa-health-check',
    handler: async (params: { [key: string]: unknown }) => {
      const payload = {
        ok: true,
        name: 'attio-mcp',
        echo:
          typeof params?.echo === 'string' ? (params.echo as string) : undefined,
        timestamp: new Date().toISOString(),
        environment: process.env.NODE_ENV || 'production',
        needs_api_key: true,
      } as const;
  
      // Return MCP-compliant text response (not JSON type)
      // MCP SDK expects content type to be 'text', not 'json'
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(payload, null, 2),
          },
        ],
        isError: false,
      };
    },
    formatResult: (res: Record<string, unknown>): string => {
      const content = res?.content as Array<Record<string, unknown>> | undefined;
      const textContent = content?.[0]?.text as string | undefined;
  
      // Parse JSON from text content if available
      let data: Record<string, unknown>;
      if (textContent) {
        try {
          data = JSON.parse(textContent) as Record<string, unknown>;
        } catch {
          data = res;
        }
      } else {
        data = res;
      }
  
      const parts: string[] = ['✅ Server healthy'];
      if (data?.echo) parts.push(`echo: ${String(data.echo)}`);
      if (data?.environment) parts.push(`env: ${String(data.environment)}`);
      return parts.join(' | ');
    },
  };