Attio MCP Server

Instructions

Implementation Reference

• src/handlers/tool-configs/universal/batch-search.ts:44-82 (handler)

  Core handler function for batch search operations, aliased as 'batch-search'. Performs validation and calls universalBatchSearch API.

  handler: async (
    params: BatchSearchParams
  ): Promise<UniversalBatchSearchResult[]> => {
    try {
      const sanitizedParams = validateUniversalToolParams(
        'records_search_batch',
        params
      );
  
      const { resource_type, queries, limit, offset } = sanitizedParams;
  
      if (!queries || !Array.isArray(queries) || queries.length === 0) {
        throw new Error('Queries array is required and must not be empty');
      }
  
      // Validate batch operation with comprehensive checks
      const searchValidation = validateBatchOperation({
        items: queries,
        operationType: 'search',
        resourceType: resource_type,
        checkPayload: false, // Queries don't need payload size check
      });
      if (!searchValidation.isValid) {
        throw new Error(searchValidation.error);
      }
  
      // Use optimized universal batch search API (Issue #471)
      return await universalBatchSearch(resource_type, queries, {
        limit,
        offset,
      });
    } catch (error: unknown) {
      throw ErrorService.createUniversalError(
        'records_search_batch',
        params.resource_type,
        error
      );
    }
  },

• src/handlers/tool-configs/universal/batch-search.ts:167-203 (schema)

  Input schema definition for the batch-search tool, defining parameters like resource_type, queries array, limit, and offset.

  export const batchSearchSchema = {
    type: 'object' as const,
    properties: {
      resource_type: {
        type: 'string' as const,
        enum: Object.values(UniversalResourceType),
        description:
          'Resource type to search (companies, people, records, tasks, deals)',
      },
      queries: {
        type: 'array' as const,
        items: { type: 'string' as const },
        description: 'Array of search query strings',
        minItems: 1,
      },
      limit: {
        type: 'number' as const,
        minimum: 1,
        maximum: 100,
        description: 'Maximum number of results per query (default: 20)',
      },
      offset: {
        type: 'number' as const,
        minimum: 0,
        description: 'Number of results to skip per query (default: 0)',
      },
    },
    required: ['resource_type' as const, 'queries' as const],
    additionalProperties: false,
    examples: [
      {
        resource_type: 'companies',
        queries: ['Acme', 'Globex'],
        limit: 10,
      },
    ],
  };

• src/config/tool-aliases.ts:79-84 (registration)

  Tool alias registration mapping 'batch-search' to the canonical 'records_search_batch' tool.

  'batch-search': {
    target: 'records_search_batch',
    reason: 'Phase 1 search tool rename (#776)',
    since: SINCE_PHASE_1,
    removal: 'v1.x (TBD)',
  },

• src/handlers/tool-configs/universal/index.ts:136-142 (registration)

  Registration of the 'records_search_batch' tool definition (target of batch-search alias) in universal tools.

  export const universalToolDefinitions = {
    // Ensure health-check is listed first alphabetically for best-guess scanners
    'aaa-health-check': healthCheckToolDefinition,
    'smithery-debug-config': smitheryDiagnosticsToolDefinition,
    ...coreOperationsToolDefinitions,
    ...advancedOperationsToolDefinitions,
    records_search_batch: batchSearchToolDefinition,

• src/handlers/tool-configs/universal/index.ts:123-131 (registration)

  Registration of the 'records_search_batch' tool config/handler (target of batch-search alias) in universal tools.

  export const universalToolConfigs = {
    // Ensure health-check is listed first alphabetically for best-guess scanners
    'aaa-health-check': healthCheckConfig,
    'smithery-debug-config': smitheryDiagnosticsConfig,
    ...coreOperationsToolConfigs,
    ...advancedOperationsToolConfigs,
    records_search_batch: batchSearchConfig,
    ...openAiToolConfigs,
  };