Hatch MCP Server

Instructions

Implementation Reference

• src/index.ts:373-406 (handler)

  Handler for the hatch_find_phone tool: validates arguments using isFindPhoneParams type guard, calls the Hatch API endpoint '/v1/findPhone' with retry logic, returns the JSON response or an error message.

  case 'hatch_find_phone': {
    if (!isFindPhoneParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for hatch_find_phone'
      );
    }
  
    try {
      const response = await withRetry(
        async () => apiClient.post('/v1/findPhone', args),
        'find phone'
      );
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
        isError: false,
      };
    } catch (error) {
      const errorMessage = axios.isAxiosError(error)
        ? `API Error: ${error.response?.data?.message || error.message}`
        : `Error: ${error instanceof Error ? error.message : String(error)}`;
  
      return {
        content: [{ type: 'text', text: errorMessage }],
        isError: true,
      };
    }
  }

• src/index.ts:41-54 (schema)

  Input schema and metadata definition for the hatch_find_phone tool, specifying the required 'linkedInUrl' parameter.

  const FIND_PHONE_TOOL: Tool = {
    name: 'hatch_find_phone',
    description: 'Find a phone number using LinkedIn profile URL.',
    inputSchema: {
      type: 'object',
      properties: {
        linkedInUrl: {
          type: 'string',
          description: 'LinkedIn profile URL of the person',
        },
      },
      required: ['linkedInUrl'],
    },
  };

• src/index.ts:312-320 (registration)

  Tool registration via the ListToolsRequestSchema handler, which advertises the hatch_find_phone tool among others.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      FIND_EMAIL_TOOL,
      FIND_PHONE_TOOL,
      VERIFY_EMAIL_TOOL,
      FIND_COMPANY_DATA_TOOL,
      GET_LINKEDIN_URL_TOOL,
    ],
  }));

• src/index.ts:148-155 (helper)

  Type guard function to validate that tool arguments match the expected FindPhoneParams shape for hatch_find_phone.

  function isFindPhoneParams(args: unknown): args is FindPhoneParams {
    return (
      typeof args === 'object' &&
      args !== null &&
      'linkedInUrl' in args &&
      typeof (args as { linkedInUrl: unknown }).linkedInUrl === 'string'
    );
  }

• src/index.ts:116-118 (schema)

  TypeScript interface defining the input parameters for the hatch_find_phone tool.

  interface FindPhoneParams {
    linkedInUrl: string;
  }