Attio MCP Server

Instructions

Implementation Reference

• src/handlers/tool-configs/universal/operations/batch-operations.ts:17-67 (handler)

  Core handler implementation for the records_batch tool (target of batch-operations alias). Handles input validation, routes to new operations array executor or legacy batch handler, and formats results.

  export const batchOperationsConfig: UniversalToolConfig<
    Record<string, unknown>,
    Record<string, unknown> | Record<string, unknown>[]
  > = {
    name: 'records_batch',
    handler: async (
      params: Record<string, unknown>
    ): Promise<Record<string, unknown> | Record<string, unknown>[]> => {
      try {
        const sanitizedParams = validateUniversalToolParams(
          'records_batch',
          params
        ) as JsonObject;
  
        const resourceType =
          sanitizedParams.resource_type as UniversalResourceType;
        const operations = sanitizedParams.operations as JsonObject[] | undefined;
  
        if (operations && operations.length > 0) {
          return executeOperationsArray(resourceType, operations);
        }
  
        return executeLegacyBatch({
          resourceType,
          params: sanitizedParams,
        });
      } catch (error: unknown) {
        const typedParams = params as Record<string, unknown>;
        throw ErrorService.createUniversalError(
          'records_batch',
          `${typedParams?.resource_type}:${typedParams?.operation_type}`,
          error
        );
      }
    },
    formatResult: (
      results: Record<string, unknown> | Record<string, unknown>[],
      ...args: unknown[]
    ) => {
      const operationType = args[0] as BatchOperationType | undefined;
      const resourceType = args[1] as UniversalResourceType | undefined;
      return formatBatchResult(
        results as
          | Record<string, unknown>
          | Record<string, unknown>[]
          | undefined,
        operationType,
        resourceType
      );
    },
  };

• src/handlers/tool-configs/universal/schemas/advanced-schemas.ts:192-248 (schema)

  Input schema for batch-operations tool, defining properties for resource_type, operations array (modern format), and legacy operation_type/records/record_ids.

  export const batchOperationsSchema = {
    type: 'object' as const,
    properties: {
      resource_type: resourceTypeProperty,
      // New flexible format: operations array
      operations: {
        type: 'array' as const,
        items: {
          type: 'object' as const,
          properties: {
            operation: {
              type: 'string' as const,
              enum: ['create', 'update', 'delete'],
              description: 'Operation type for this specific operation',
            },
            record_data: {
              type: 'object' as const,
              additionalProperties: true,
              description: 'Record data for the operation',
            },
          },
          required: ['operation', 'record_data'],
          additionalProperties: false,
        },
        description: 'Array of operations to perform',
      },
      // Legacy format: single operation type applied to multiple records
      operation_type: {
        type: 'string' as const,
        enum: Object.values(BatchOperationType),
        description: 'Batch operation type (legacy format)',
      },
      records: {
        type: 'array' as const,
        items: { type: 'object' as const, additionalProperties: true },
        description: 'Record data for create/update (legacy format)',
      },
      record_ids: {
        type: 'array' as const,
        items: { type: 'string' as const },
        description: 'Record IDs for delete/get (legacy format)',
      },
      ...paginationProperties,
    },
    required: ['resource_type' as const],
    additionalProperties: false,
    examples: [
      {
        resource_type: 'companies',
        operation_type: BatchOperationType.CREATE,
        records: [
          { name: 'Example Ltd.', domain: 'example.com' },
          { name: 'Sample Inc.', domain: 'sample.io' },
        ],
      },
    ],
  };

• src/handlers/tool-configs/universal/operations/index.ts:21-27 (registration)

  Registration of batchOperationsConfig as 'records_batch' in advancedOperationsToolConfigs, which is merged into universalToolConfigs.

  export const advancedOperationsToolConfigs = {
    records_search_advanced: advancedSearchConfig,
    records_search_by_relationship: searchByRelationshipConfig,
    records_search_by_content: searchByContentConfig,
    records_search_by_timeframe: searchByTimeframeConfig,
    records_batch: batchOperationsConfig,
  };

• src/config/tool-aliases.ts:73-78 (registration)

  Alias registration mapping the tool name 'batch-operations' to the canonical target 'records_batch'.

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

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

  Final registration where advancedOperationsToolConfigs (including records_batch) is spread into the universalToolConfigs registry.

  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,
  };