Skip to content

The open alternative to Salesforce, designed for AI.

feat(ai): add merge_many database tool for duplicate records (#29115)

Etienned06bf84ce6bd
diff --git a/packages/twenty-front/src/modules/ai/constants/CrudToolOperationVerbs.ts b/packages/twenty-front/src/modules/ai/constants/CrudToolOperationVerbs.ts
index 585950a5735..39c48b82f7f 100644
--- a/packages/twenty-front/src/modules/ai/constants/CrudToolOperationVerbs.ts
+++ b/packages/twenty-front/src/modules/ai/constants/CrudToolOperationVerbs.ts
@@ -47,4 +47,8 @@ export const CRUD_TOOL_OPERATION_VERBS: Record<
loading: msg`Deleting {objectLabel}`,
completed: msg`Deleted {objectLabel}`,
},
+ merge_many: {
+ loading: msg`Merging {objectLabel}`,
+ completed: msg`Merged {objectLabel}`,
+ },
};
diff --git a/packages/twenty-server/src/engine/api/mcp/constants/mcp-database-crud-tool-annotations.constant.ts b/packages/twenty-server/src/engine/api/mcp/constants/mcp-database-crud-tool-annotations.constant.ts
index 37d7dcc83ec..daa0291c76b 100644
--- a/packages/twenty-server/src/engine/api/mcp/constants/mcp-database-crud-tool-annotations.constant.ts
+++ b/packages/twenty-server/src/engine/api/mcp/constants/mcp-database-crud-tool-annotations.constant.ts
@@ -17,4 +17,5 @@ export const MCP_DATABASE_CRUD_TOOL_ANNOTATIONS: Record<
upsert_many: MCP_EXECUTE_TOOL_ANNOTATIONS,
delete_one: MCP_EXECUTE_TOOL_ANNOTATIONS,
delete_many: MCP_EXECUTE_TOOL_ANNOTATIONS,
+ merge_many: MCP_EXECUTE_TOOL_ANNOTATIONS,
};
diff --git a/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-registry-tool-annotations.util.spec.ts b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-registry-tool-annotations.util.spec.ts
index 33892720571..c7b797997c9 100644
--- a/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-registry-tool-annotations.util.spec.ts
+++ b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-registry-tool-annotations.util.spec.ts
@@ -26,6 +26,7 @@ describe('getMcpRegistryToolAnnotations', () => {
['upsert_many'],
['delete_one'],
['delete_many'],
+ ['merge_many'],
])(
'should return execute annotations for the database write operation %p',
(operation) => {
diff --git a/packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts b/packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts
index d29d398cd15..4cee3779ae6 100644
--- a/packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts
+++ b/packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts
@@ -45,7 +45,7 @@ export const buildMcpServerInstructions = ({
...(skillNames ? [`Available skills: ${skillNames}.`, ``] : []),
`CRUD tool name grammar — construct names directly without prior discovery:`,
` Read: find_many_{objects} | find_one_{object} | group_by_{objects}`,
- ` Write: create_one_{object} | create_many_{objects} | update_one_{object} | update_many_{objects} | delete_one_{object} | delete_many_{objects} | upsert_many_{objects}. Use upsert_many_{objects} instead of update_many_{objects} when each record has its own individual data.`,
+ ` Write: create_one_{object} | create_many_{objects} | update_one_{object} | update_many_{objects} | delete_one_{object} | delete_many_{objects} | upsert_many_{objects} | merge_many_{objects}. Use upsert_many_{objects} instead of update_many_{objects} when each record has its own individual data.`,
...(isDirectMode
? []
: [
@@ -93,6 +93,7 @@ export const buildMcpServerInstructions = ({
` Multiple metrics → run parallel group_by calls, merge results`,
` Per-record updates (different data per record) → find_many_{objects} first, then upsert_many_{objects} with each record's id (or other unique identifier) and new values`,
` Bulk update (same data for all) → update_many_{objects}`,
+ ` Merge duplicate records → find_many_{objects} to get their ids, merge_many_{objects} with dryRun: true to preview, ask the user which record to keep when values conflict, then merge_many_{objects}. Never copy fields and delete a record: that loses its linked records`,
isDirectMode
? ` Non-CRUD task → call the matching tool directly`
: ` Non-CRUD task → use tool name from the list above + learn_tools for schema`,
diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/json-schemas/merge-many-tool.json-schema.ts b/packages/twenty-server/src/engine/core-modules/record-crud/json-schemas/merge-many-tool.json-schema.ts
new file mode 100644
index 00000000000..854eae14b4b
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/record-crud/json-schemas/merge-many-tool.json-schema.ts
@@ -0,0 +1,27 @@
+import { type JSONSchema7 } from 'json-schema';
+import { MUTATION_MAX_MERGE_RECORDS } from 'twenty-shared/constants';
+
+export const MERGE_MANY_TOOL_INPUT_SCHEMA: JSONSchema7 = {
+ type: 'object',
+ properties: {
+ ids: {
+ description: 'The UUIDs of the duplicate records to merge into one',
+ type: 'array',
+ items: { type: 'string', format: 'uuid' },
+ minItems: 2,
+ maxItems: MUTATION_MAX_MERGE_RECORDS,
+ },
+ conflictPriorityIndex: {
+ description:
+ 'The position in ids of the record to keep. Its values win when the records have conflicting values',
+ type: 'integer',
+ minimum: 0,
+ },
+ dryRun: {
+ description:
+ 'When true, returns the merged record as it would be saved without changing any data',
+ type: 'boolean',
+ },
+ },
+ required: ['ids', 'conflictPriorityIndex'],
+};
diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/record-crud.module.ts b/packages/twenty-server/src/engine/core-modules/record-crud/record-crud.module.ts
index 225d576cf93..df19e4f1819 100644
--- a/packages/twenty-server/src/engine/core-modules/record-crud/record-crud.module.ts
+++ b/packages/twenty-server/src/engine/core-modules/record-crud/record-crud.module.ts
@@ -9,6 +9,7 @@ import { DeleteManyRecordsService } from 'src/engine/core-modules/record-crud/se
import { DeleteRecordService } from 'src/engine/core-modules/record-crud/services/delete-record.service';
import { FindRecordsService } from 'src/engine/core-modules/record-crud/services/find-records.service';
import { GroupByRecordsService } from 'src/engine/core-modules/record-crud/services/group-by-records.service';
+import { MergeManyRecordsService } from 'src/engine/core-modules/record-crud/services/merge-many-records.service';
import { UpdateManyRecordsService } from 'src/engine/core-modules/record-crud/services/update-many-records.service';
import { UpdateRecordService } from 'src/engine/core-modules/record-crud/services/update-record.service';
import { UpsertManyRecordsService } from 'src/engine/core-modules/record-crud/services/upsert-many-records.service';
@@ -33,6 +34,7 @@ import { WorkspaceCacheModule } from 'src/engine/workspace-cache/workspace-cache
UpdateManyRecordsService,
DeleteRecordService,
DeleteManyRecordsService,
+ MergeManyRecordsService,
FindRecordsService,
GroupByRecordsService,
UpsertRecordService,
@@ -46,6 +48,7 @@ import { WorkspaceCacheModule } from 'src/engine/workspace-cache/workspace-cache
UpdateManyRecordsService,
DeleteRecordService,
DeleteManyRecordsService,
+ MergeManyRecordsService,
FindRecordsService,
GroupByRecordsService,
UpsertRecordService,
diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/services/merge-many-records.service.ts b/packages/twenty-server/src/engine/core-modules/record-crud/services/merge-many-records.service.ts
new file mode 100644
index 00000000000..a0f33ed7fbf
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/record-crud/services/merge-many-records.service.ts
@@ -0,0 +1,112 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { canObjectBeManagedByAutomation } from 'twenty-shared/workflow';
+
+import { CommonMergeManyQueryRunnerService } from 'src/engine/api/common/common-query-runners/common-merge-many-query-runner.service';
+import {
+ RecordCrudException,
+ RecordCrudExceptionCode,
+} from 'src/engine/core-modules/record-crud/exceptions/record-crud.exception';
+import { CommonApiContextBuilderService } from 'src/engine/core-modules/record-crud/services/common-api-context-builder.service';
+import { type MergeManyRecordsParams } from 'src/engine/core-modules/record-crud/types/merge-many-records-params.type';
+import { getRecordDisplayName } from 'src/engine/core-modules/record-crud/utils/get-record-display-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+
+@Injectable()
+export class MergeManyRecordsService {
+ private readonly logger = new Logger(MergeManyRecordsService.name);
+
+ constructor(
+ private readonly commonMergeManyRunner: CommonMergeManyQueryRunnerService,
+ private readonly commonApiContextBuilder: CommonApiContextBuilderService,
+ ) {}
+
+ async execute(params: MergeManyRecordsParams): Promise<ToolOutput> {
+ const {
+ objectName,
+ ids,
+ conflictPriorityIndex,
+ dryRun,
+ authContext,
+ rolePermissionConfig,
+ } = params;
+
+ try {
+ const {
+ queryRunnerContext,
+ selectedFields,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ } = await this.commonApiContextBuilder.build({
+ authContext,
+ objectName,
+ rolePermissionConfig,
+ });
+
+ if (
+ !canObjectBeManagedByAutomation({
+ nameSingular: flatObjectMetadata.nameSingular,
+ })
+ ) {
+ throw new RecordCrudException(
+ 'Failed to merge: Object cannot be merged by automation',
+ RecordCrudExceptionCode.INVALID_REQUEST,
+ );
+ }
+
+ const { results: mergedRecord } =
+ await this.commonMergeManyRunner.execute(
+ { ids, conflictPriorityIndex, dryRun, selectedFields },
+ queryRunnerContext,
+ );
+
+ const keptRecordId = ids[conflictPriorityIndex];
+
+ if (dryRun) {
+ return {
+ success: true,
+ message: `Preview of merging ${ids.length} records from ${objectName} into ${keptRecordId}. Nothing was changed. Records linked to the other records will be moved to the kept record.`,
+ result: { ...mergedRecord, id: keptRecordId, deletedAt: null },
+ };
+ }
+
+ this.logger.log(
+ `Merged ${ids.length} records from ${objectName} into ${keptRecordId}`,
+ );
+
+ return {
+ success: true,
+ message: `Merged ${ids.length} records from ${objectName} into ${keptRecordId}`,
+ result: mergedRecord,
+ recordReferences: [
+ {
+ objectNameSingular: objectName,
+ recordId: mergedRecord.id,
+ displayName: getRecordDisplayName(
+ mergedRecord,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ ),
+ },
+ ],
+ };
+ } catch (error) {
+ if (error instanceof RecordCrudException) {
+ return {
+ success: false,
+ message: `Failed to merge records from ${objectName}`,
+ error: error.message,
+ };
+ }
+
+ this.logger.error(`Failed to merge records: ${error}`);
+
+ return {
+ success: false,
+ message: `Failed to merge records from ${objectName}`,
+ error:
+ error instanceof Error ? error.message : 'Failed to merge records',
+ };
+ }
+ }
+}
diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/types/merge-many-records-params.type.ts b/packages/twenty-server/src/engine/core-modules/record-crud/types/merge-many-records-params.type.ts
new file mode 100644
index 00000000000..9f7a83c561e
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/record-crud/types/merge-many-records-params.type.ts
@@ -0,0 +1,7 @@
+import { type MergeManyQueryArgs } from 'src/engine/api/common/types/common-query-args.type';
+import { type RecordCrudExecutionContext } from 'src/engine/core-modules/record-crud/types/record-crud-execution-context.type';
+
+export type MergeManyRecordsParams = MergeManyQueryArgs &
+ RecordCrudExecutionContext & {
+ objectName: string;
+ };
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/__tests__/database-tool.provider.spec.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/__tests__/database-tool.provider.spec.ts
index 91704433a1e..38dd1ac0b40 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/__tests__/database-tool.provider.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/__tests__/database-tool.provider.spec.ts
@@ -281,6 +281,34 @@ describe('DatabaseToolProvider', () => {
expect(labelByName.get('upsert_many_companies')).toBe('Upsert companies');
expect(labelByName.get('delete_one_company')).toBe('Delete company');
expect(labelByName.get('delete_many_companies')).toBe('Delete companies');
+ expect(labelByName.get('merge_many_companies')).toBe('Merge companies');
+ });
+
+ it('advertises merge only on the objects the Merge action is available on', async () => {
+ const descriptorNames = await generateDescriptorNames([
+ createFlatObject({ nameSingular: 'company', namePlural: 'companies' }),
+ createFlatObject({
+ nameSingular: 'noteTarget',
+ namePlural: 'noteTargets',
+ isSystem: true,
+ }),
+ createFlatObject({ nameSingular: 'dashboard', namePlural: 'dashboards' }),
+ ]);
+
+ expect(descriptorNames).toContain('merge_many_companies');
+ expect(descriptorNames).toContain('update_many_note_targets');
+ expect(descriptorNames).not.toContain('merge_many_note_targets');
+ expect(descriptorNames).not.toContain('merge_many_dashboards');
+ });
+
+ it('does not advertise merge without the destroy permission', async () => {
+ const descriptorNames = await generateDescriptorNames(
+ [createFlatObject({ nameSingular: 'company', namePlural: 'companies' })],
+ { composedObjectPermissions: { canDestroyObjectRecords: false } },
+ );
+
+ expect(descriptorNames).toContain('delete_one_company');
+ expect(descriptorNames).not.toContain('merge_many_companies');
});
it('uses the object labelSingular/labelPlural from metadata, not the programmatic name', async () => {
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts
index 463893b1e5c..47c44b0afec 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts
@@ -1,6 +1,7 @@
import { type I18n } from '@lingui/core';
import { Injectable } from '@nestjs/common';
+import { MUTATION_MAX_MERGE_RECORDS } from 'twenty-shared/constants';
import { SOURCE_LOCALE } from 'twenty-shared/translations';
import { camelToSnakeCase, isDefined } from 'twenty-shared/utils';
import { canObjectBeManagedByAutomation } from 'twenty-shared/workflow';
@@ -23,6 +24,7 @@ import { DELETE_TOOL_INPUT_SCHEMA } from 'src/engine/core-modules/record-crud/js
import { FIND_ONE_TOOL_INPUT_SCHEMA } from 'src/engine/core-modules/record-crud/json-schemas/find-one-tool.json-schema';
import { generateFindToolInputSchema } from 'src/engine/core-modules/record-crud/json-schemas/find-tool.json-schema';
import { generateGroupByToolInputSchema } from 'src/engine/core-modules/record-crud/json-schemas/group-by-tool.json-schema';
+import { MERGE_MANY_TOOL_INPUT_SCHEMA } from 'src/engine/core-modules/record-crud/json-schemas/merge-many-tool.json-schema';
import { type ToolDescriptor } from 'src/engine/core-modules/tool-provider/types/tool-descriptor.type';
import { type ToolIndexEntry } from 'src/engine/core-modules/tool-provider/types/tool-index-entry.type';
import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
@@ -160,6 +162,10 @@ export class DatabaseToolProvider implements ToolProvider {
permission.canSoftDeleteObjectRecords &&
(!requireExplicitObjectGrants ||
explicitPermission?.canSoftDeleteObjectRecords === true);
+ const canDestroyRecords =
+ permission.canDestroyObjectRecords &&
+ (!requireExplicitObjectGrants ||
+ explicitPermission?.canDestroyObjectRecords === true);
const snakePlural = camelToSnakeCase(flatObject.namePlural);
const snakeSingular = camelToSnakeCase(flatObject.nameSingular);
@@ -448,6 +454,36 @@ export class DatabaseToolProvider implements ToolProvider {
operation: 'delete_many',
});
}
+
+ if (
+ canUpdateRecords &&
+ canDestroyRecords &&
+ canBeManagedByAutomation &&
+ !flatObject.isSystem
+ ) {
+ descriptors.push({
+ name: `merge_many_${snakePlural}`,
+ ...getCrudToolLabels(
+ 'merge_many',
+ flatObject.labelPlural,
+ this.i18nService,
+ context.locale,
+ ),
+ description: `Merge 2 to ${MUTATION_MAX_MERGE_RECORDS} duplicate ${objectMetadata.labelPlural} records into one, like the Merge action in the app. The record at conflictPriorityIndex is kept: its empty fields are filled from the other records, its values win on conflicting values, multi-value fields (emails, phones, links, arrays) are combined, and every record linked to the other records (notes, tasks, related records) is moved to it. The other records are then permanently deleted, which cannot be undone. Use this instead of copying fields and deleting a record, which loses the linked records. Call it with dryRun: true first to preview the merged record.`,
+ category: ToolCategory.DATABASE_CRUD,
+ ...(shouldIncludeSchema(`merge_many_${snakePlural}`) && {
+ inputSchema: MERGE_MANY_TOOL_INPUT_SCHEMA,
+ }),
+ executionRef: {
+ kind: 'database_crud',
+ objectNameSingular: objectMetadata.nameSingular,
+ operation: 'merge_many',
+ },
+ objectName: objectMetadata.nameSingular,
+ icon: flatObject.icon ?? undefined,
+ operation: 'merge_many',
+ });
+ }
}
// group_by answers with aggregates, not the recordReferences the records widget links.
@@ -505,7 +541,8 @@ export class DatabaseToolProvider implements ToolProvider {
toolNames.has(`update_many_${snakePlural}`) ||
toolNames.has(`delete_one_${snakeSingular}`) ||
toolNames.has(`delete_many_${snakePlural}`) ||
- toolNames.has(`upsert_many_${snakePlural}`)
+ toolNames.has(`upsert_many_${snakePlural}`) ||
+ toolNames.has(`merge_many_${snakePlural}`)
);
}
}
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-executor.service.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-executor.service.ts
index 53deb8c9d63..22816c921da 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-executor.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-executor.service.ts
@@ -17,6 +17,7 @@ import { DeleteManyRecordsService } from 'src/engine/core-modules/record-crud/se
import { DeleteRecordService } from 'src/engine/core-modules/record-crud/services/delete-record.service';
import { FindRecordsService } from 'src/engine/core-modules/record-crud/services/find-records.service';
import { GroupByRecordsService } from 'src/engine/core-modules/record-crud/services/group-by-records.service';
+import { MergeManyRecordsService } from 'src/engine/core-modules/record-crud/services/merge-many-records.service';
import { UpdateManyRecordsService } from 'src/engine/core-modules/record-crud/services/update-many-records.service';
import { UpdateRecordService } from 'src/engine/core-modules/record-crud/services/update-record.service';
import { UpsertManyRecordsService } from 'src/engine/core-modules/record-crud/services/upsert-many-records.service';
@@ -51,6 +52,7 @@ export class ToolExecutorService {
private readonly upsertManyRecordsService: UpsertManyRecordsService,
private readonly deleteRecordService: DeleteRecordService,
private readonly deleteManyRecordsService: DeleteManyRecordsService,
+ private readonly mergeManyRecordsService: MergeManyRecordsService,
private readonly logicFunctionExecutorService: LogicFunctionExecutorService,
private readonly recordFilesResolverService: RecordFilesResolverService,
private readonly workspaceCacheService: WorkspaceCacheService,
@@ -272,6 +274,16 @@ export class ToolExecutorService {
rolePermissionConfig: context.rolePermissionConfig,
});
+ case 'merge_many':
+ return this.mergeManyRecordsService.execute({
+ objectName: ref.objectNameSingular,
+ ids: args.ids as string[],
+ conflictPriorityIndex: args.conflictPriorityIndex as number,
+ dryRun: args.dryRun as boolean | undefined,
+ authContext,
+ rolePermissionConfig: context.rolePermissionConfig,
+ });
+
case 'group_by': {
const {
groupBy,
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/get-crud-tool-label.util.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/get-crud-tool-label.util.ts
index 7d47c80adb6..3406aca6bc6 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/get-crud-tool-label.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/get-crud-tool-label.util.ts
@@ -17,6 +17,7 @@ const OPERATION_VERBS: Record<DatabaseCrudOperation, MessageDescriptor> = {
upsert_many: msg`Upsert`,
delete_one: msg`Delete`,
delete_many: msg`Delete`,
+ merge_many: msg`Merge`,
};
type CrudToolLabel = {
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts
index aa9d2d4dd37..596cf07c46f 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts
@@ -34,12 +34,13 @@ Intent gate: purely informational dashboard questions (e.g. "what is a dashboard
## Database vs HTTP Tools
-- Use database tools (find_many_*, find_one_*, create_one_*, create_many_*, update_one_*, update_many_*, upsert_many_*, delete_one_*, delete_many_*) for ALL Twenty CRM data operations
+- Use database tools (find_many_*, find_one_*, create_one_*, create_many_*, update_one_*, update_many_*, upsert_many_*, delete_one_*, delete_many_*, merge_many_*) for ALL Twenty CRM data operations
- NEVER guess or construct API URLs — always use the appropriate database tool
- The \`http_request\` tool is ONLY for external third-party APIs (not for Twenty's own data)
- If you need to look up a record by ID, use find_one_*; to search with filters, use find_many_*
- For comparative/grouped analytics questions (by/per/top/most/least/average/total/ranking), use \`group_by_*\` instead of \`find_many_*\`; if multiple metrics are needed, run multiple \`group_by_*\` calls with the same dimensions and merge results.
- **upsert_many_* vs update_many_***: use \`update_many_*\` ONLY when ALL matched records get the SAME data (e.g. mark all as closed). Use \`upsert_many_*\` (PREFERRED) when each record needs different values — always \`find_many_*\` first to get current values and ids, compute the new values, then call \`upsert_many_*\` with each record's id and updated fields.
+- **Merging duplicates**: use \`merge_many_*\` to merge duplicate records. NEVER copy fields onto one record and delete the other: that loses the records linked to the deleted one. Find the records with \`find_many_*\`, call \`merge_many_*\` with \`dryRun: true\` to preview the result, and when the records have conflicting values ask the user which record to keep. Then call \`merge_many_*\` without \`dryRun\`, with the kept record's position in \`ids\` as \`conflictPriorityIndex\`.
## Data Efficiency
diff --git a/packages/twenty-server/test/integration/ai/suites/mcp-tool-execution.integration-spec.ts b/packages/twenty-server/test/integration/ai/suites/mcp-tool-execution.integration-spec.ts
index 7b4ff0acea5..29cdd9ac773 100644
--- a/packages/twenty-server/test/integration/ai/suites/mcp-tool-execution.integration-spec.ts
+++ b/packages/twenty-server/test/integration/ai/suites/mcp-tool-execution.integration-spec.ts
@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto';
import request from 'supertest';
import { deleteRecordsByIds } from 'test/integration/utils/delete-records-by-ids';
+import { waitForTimelineActivities } from 'test/integration/utils/wait-for-timeline-activities.util';
const TEST_WORKSPACE_SCHEMA = 'workspace_1wgvd1injqtife6y4rvfbu3h5';
@@ -10,6 +11,8 @@ const TOOL_NAMES = {
createCompany: 'create_one_company',
createNote: 'create_one_note',
createNoteTarget: 'create_one_note_target',
+ createPerson: 'create_one_person',
+ mergeCompanies: 'merge_many_companies',
groupByNoteTargets: 'group_by_note_targets',
groupByCompanies: 'group_by_companies',
} as const;
@@ -454,4 +457,102 @@ describe('MCP tool execution (integration)', () => {
]);
});
});
+
+ describe('merge_many_companies', () => {
+ const keptCompanyName = `mcp-merge-kept-${randomUUID()}`;
+ let keptCompanyId: string;
+ let duplicateCompanyId: string;
+ let relatedPersonId: string;
+
+ type MergedCompany = { id: string; name: string; employees: number };
+
+ beforeAll(async () => {
+ const keptCompany = await executeWorkspaceTool<CreatedRecord>(
+ TOOL_NAMES.createCompany,
+ { name: keptCompanyName },
+ );
+
+ keptCompanyId = keptCompany.id;
+
+ const duplicateCompany = await executeWorkspaceTool<CreatedRecord>(
+ TOOL_NAMES.createCompany,
+ { name: `mcp-merge-duplicate-${randomUUID()}`, employees: 42 },
+ );
+
+ duplicateCompanyId = duplicateCompany.id;
+
+ const relatedPerson = await executeWorkspaceTool<CreatedRecord>(
+ TOOL_NAMES.createPerson,
+ {
+ name: { firstName: 'Merge', lastName: 'Contact' },
+ companyId: duplicateCompanyId,
+ },
+ );
+
+ relatedPersonId = relatedPerson.id;
+
+ await waitForTimelineActivities('targetCompanyId', [
+ keptCompanyId,
+ duplicateCompanyId,
+ ]);
+ await waitForTimelineActivities('targetPersonId', [relatedPersonId]);
+ });
+
+ afterAll(async () => {
+ await deleteRecordsByIds('person', [relatedPersonId]);
+ await deleteRecordsByIds('company', [keptCompanyId, duplicateCompanyId]);
+ });
+
+ const findCompanyIds = async (): Promise<string[]> => {
+ const rows = (await global.testDataSource.query(
+ `SELECT id FROM "${TEST_WORKSPACE_SCHEMA}"."company" WHERE id = ANY($1)`,
+ [[keptCompanyId, duplicateCompanyId]],
+ )) as Array<{ id: string }>;
+
+ return rows.map(({ id }) => id);
+ };
+
+ const findRelatedPersonCompanyId = async (): Promise<string> => {
+ const [person] = (await global.testDataSource.query(
+ `SELECT "companyId" FROM "${TEST_WORKSPACE_SCHEMA}"."person" WHERE id = $1`,
+ [relatedPersonId],
+ )) as Array<{ companyId: string }>;
+
+ return person.companyId;
+ };
+
+ it('should preview the merged company with dryRun without changing any data', async () => {
+ const preview = await executeWorkspaceTool<MergedCompany>(
+ TOOL_NAMES.mergeCompanies,
+ {
+ ids: [keptCompanyId, duplicateCompanyId],
+ conflictPriorityIndex: 0,
+ dryRun: true,
+ },
+ );
+
+ expect(preview).toMatchObject({
+ id: keptCompanyId,
+ name: keptCompanyName,
+ employees: 42,
+ });
+ expect(await findCompanyIds()).toHaveLength(2);
+ expect(await findRelatedPersonCompanyId()).toBe(duplicateCompanyId);
+ });
+
+ it('should move the related person to the kept company and delete the duplicate', async () => {
+ const mergedCompany = await executeWorkspaceTool<MergedCompany>(
+ TOOL_NAMES.mergeCompanies,
+ { ids: [keptCompanyId, duplicateCompanyId], conflictPriorityIndex: 0 },
+ );
+
+ expect(mergedCompany).toMatchObject({
+ id: keptCompanyId,
+ name: keptCompanyName,
+ employees: 42,
+ });
+ expect(await findCompanyIds()).toEqual([keptCompanyId]);
+ expect(await findRelatedPersonCompanyId()).toBe(keptCompanyId);
+ });
+ });
});
diff --git a/packages/twenty-shared/src/ai/constants/database-crud-operation.const.ts b/packages/twenty-shared/src/ai/constants/database-crud-operation.const.ts
index d7ca6e2bd5c..c164b9ffb67 100644
--- a/packages/twenty-shared/src/ai/constants/database-crud-operation.const.ts
+++ b/packages/twenty-shared/src/ai/constants/database-crud-operation.const.ts
@@ -9,6 +9,7 @@ export const DATABASE_CRUD_OPERATIONS = [
'upsert_many',
'delete_one',
'delete_many',
+ 'merge_many',
] as const;
export type DatabaseCrudOperation = (typeof DATABASE_CRUD_OPERATIONS)[number];