Skip to content

The open alternative to Salesforce, designed for AI.

fix(mcp): list connected accounts from the core schema (#25658)

Hermi94125d0780dfda2
diff --git a/packages/twenty-front/src/modules/ai/constants/action-tool-status-labels.constant.ts b/packages/twenty-front/src/modules/ai/constants/action-tool-status-labels.constant.ts
index 0fff676f358..3e95d494052 100644
--- a/packages/twenty-front/src/modules/ai/constants/action-tool-status-labels.constant.ts
+++ b/packages/twenty-front/src/modules/ai/constants/action-tool-status-labels.constant.ts
@@ -11,6 +11,10 @@ export const ACTION_TOOL_STATUS_LABELS: Record<string, ToolStatusLabels> = {
loading: msg`Drafting email`,
completed: msg`Drafted email`,
},
+ find_connected_accounts: {
+ loading: msg`Finding connected accounts`,
+ completed: msg`Found connected accounts`,
+ },
search_help_center: {
loading: msg`Searching the help center`,
completed: msg`Searched the help center`,
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 2acbea5e939..a2a036796d3 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
@@ -23,7 +23,7 @@ export const buildMcpServerInstructions = (
` 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.`,
``,
`Non-CRUD tools — use learn_tools for schemas:`,
- ` ACTION: http_request | send_email | draft_email | navigate_app | code_interpreter | search_help_center`,
+ ` ACTION: http_request | send_email | draft_email | find_connected_accounts | navigate_app | code_interpreter | search_help_center`,
` WORKFLOW: list_workflows | create_complete_workflow | create/update/delete_workflow_version_step | activate/deactivate_workflow_version | list_workflow_runs | get_workflow_run | get_workflow_current_version`,
` METADATA: get/create/update/delete_object_metadata | get/create/update/delete_field_metadata`,
` Both GET tools return system items as compact summaries by default — keep that default for listing/inspecting; only set includeFullSystemObjects / includeFullSystemFields=true when you specifically need a system item's full configuration`,
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/constants/action-tool-label.constant.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/constants/action-tool-label.constant.ts
index bc001bdeb06..ea03e74e047 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/constants/action-tool-label.constant.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/constants/action-tool-label.constant.ts
@@ -7,6 +7,7 @@ export const ACTION_TOOL_IDS = [
'http_request',
'send_email',
'draft_email',
+ 'find_connected_accounts',
'create_calendar_event',
'search_help_center',
'code_interpreter',
@@ -26,6 +27,9 @@ export const ACTION_TOOL_LABELS: Record<ActionToolId, ActionToolLabel> = {
draft_email: {
label: i18nLabel(msg`Draft Email`),
},
+ find_connected_accounts: {
+ label: i18nLabel(msg`Find Connected Accounts`),
+ },
create_calendar_event: {
label: i18nLabel(msg`Create Calendar Event`),
},
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/action-tool.provider.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/action-tool.provider.ts
index 3f3b854ba79..d1180aba35c 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/action-tool.provider.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/action-tool.provider.ts
@@ -24,6 +24,7 @@ import { CodeInterpreterService } from 'src/engine/core-modules/code-interpreter
import { CreateCalendarEventTool } from 'src/engine/core-modules/tool/tools/calendar-tool/create-calendar-event-tool';
import { CodeInterpreterTool } from 'src/engine/core-modules/tool/tools/code-interpreter-tool/code-interpreter-tool';
import { DraftEmailTool } from 'src/engine/core-modules/tool/tools/email-tool/draft-email-tool';
+import { FindConnectedAccountsTool } from 'src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool';
import { SendEmailTool } from 'src/engine/core-modules/tool/tools/email-tool/send-email-tool';
import { HttpTool } from 'src/engine/core-modules/tool/tools/http-tool/http-tool';
import { NavigateAppTool } from 'src/engine/core-modules/tool/tools/navigate-tool/navigate-app-tool';
@@ -45,6 +46,7 @@ export class ActionToolProvider implements ToolProvider {
private readonly httpTool: HttpTool,
private readonly sendEmailTool: SendEmailTool,
private readonly draftEmailTool: DraftEmailTool,
+ private readonly findConnectedAccountsTool: FindConnectedAccountsTool,
private readonly createCalendarEventTool: CreateCalendarEventTool,
private readonly searchHelpCenterTool: SearchHelpCenterTool,
private readonly codeInterpreterTool: CodeInterpreterTool,
@@ -60,6 +62,7 @@ export class ActionToolProvider implements ToolProvider {
['http_request', this.httpTool],
['send_email', this.sendEmailTool],
['draft_email', this.draftEmailTool],
+ ['find_connected_accounts', this.findConnectedAccountsTool],
['create_calendar_event', this.createCalendarEventTool],
['search_help_center', this.searchHelpCenterTool],
['code_interpreter', this.codeInterpreterTool],
@@ -121,6 +124,14 @@ export class ActionToolProvider implements ToolProvider {
context.locale,
),
);
+ descriptors.push(
+ this.buildDescriptor(
+ 'find_connected_accounts',
+ this.findConnectedAccountsTool,
+ includeSchemas,
+ context.locale,
+ ),
+ );
}
const hasCreateCalendarEventPermission =
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tool.module.ts b/packages/twenty-server/src/engine/core-modules/tool/tool.module.ts
index fe1e93a403f..36d481d7d35 100644
--- a/packages/twenty-server/src/engine/core-modules/tool/tool.module.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool/tool.module.ts
@@ -11,6 +11,7 @@ import { CreateCalendarEventTool } from 'src/engine/core-modules/tool/tools/cale
import { CodeInterpreterTool } from 'src/engine/core-modules/tool/tools/code-interpreter-tool/code-interpreter-tool';
import { DraftEmailTool } from 'src/engine/core-modules/tool/tools/email-tool/draft-email-tool';
import { EmailComposerService } from 'src/engine/core-modules/tool/tools/email-tool/email-composer.service';
+import { FindConnectedAccountsTool } from 'src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool';
import { SendEmailTool } from 'src/engine/core-modules/tool/tools/email-tool/send-email-tool';
import { HttpTool } from 'src/engine/core-modules/tool/tools/http-tool/http-tool';
import { NavigateAppTool } from 'src/engine/core-modules/tool/tools/navigate-tool/navigate-app-tool';
@@ -19,6 +20,7 @@ import { SearchOutputTool } from 'src/engine/core-modules/tool/tools/output-navi
import { SearchHelpCenterTool } from 'src/engine/core-modules/tool/tools/search-help-center-tool/search-help-center-tool';
import { ToolOutputSpillService } from 'src/engine/core-modules/tool/services/tool-output-spill.service';
import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
+import { ConnectedAccountMetadataModule } from 'src/engine/metadata-modules/connected-account/connected-account-metadata.module';
import { ConnectedAccountEntity } from 'src/engine/metadata-modules/connected-account/entities/connected-account.entity';
import { NavigationMenuItemModule } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.module';
import { ObjectMetadataModule } from 'src/engine/metadata-modules/object-metadata/object-metadata.module';
@@ -33,6 +35,7 @@ import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspac
MessagingSendManagerModule,
CalendarEventCreationManagerModule,
TypeOrmModule.forFeature([FileEntity, ConnectedAccountEntity]),
+ ConnectedAccountMetadataModule,
ApplicationModule,
FeatureFlagModule,
FileModule,
@@ -47,6 +50,7 @@ import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspac
HttpTool,
SendEmailTool,
DraftEmailTool,
+ FindConnectedAccountsTool,
CreateCalendarEventTool,
EmailComposerService,
SearchHelpCenterTool,
@@ -61,6 +65,7 @@ import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspac
HttpTool,
SendEmailTool,
DraftEmailTool,
+ FindConnectedAccountsTool,
CreateCalendarEventTool,
EmailComposerService,
SearchHelpCenterTool,
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool.schema.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool.schema.ts
new file mode 100644
index 00000000000..bcb9dde8190
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool.schema.ts
@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+export const FindConnectedAccountsToolInputZodSchema = z.object({
+ handle: z
+ .string()
+ .describe(
+ 'Optional email handle to match against the connected account handle or aliases. Case-insensitive.',
+ )
+ .optional(),
+});
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool.ts
new file mode 100644
index 00000000000..0446db9b16a
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool.ts
@@ -0,0 +1,58 @@
+import { Injectable } from '@nestjs/common';
+
+import { isNonEmptyString } from '@sniptt/guards';
+
+import { FindConnectedAccountsToolInputZodSchema } from 'src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool.schema';
+import { type FindConnectedAccountsToolInput } from 'src/engine/core-modules/tool/tools/email-tool/types/find-connected-accounts-tool-input.type';
+import { filterConnectedAccountsByHandle } from 'src/engine/core-modules/tool/tools/email-tool/utils/filter-connected-accounts-by-handle.util';
+import { type ToolExecutionContext } from 'src/engine/core-modules/tool/types/tool-execution-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { type Tool } from 'src/engine/core-modules/tool/types/tool.type';
+import { ConnectedAccountMetadataService } from 'src/engine/metadata-modules/connected-account/connected-account-metadata.service';
+
+@Injectable()
+export class FindConnectedAccountsTool implements Tool {
+ description =
+ 'List connected email accounts the caller can use with draft_email and send_email. Returns id, handle, provider, visibility and aliases. Use a returned id as connectedAccountId.';
+ inputSchema = FindConnectedAccountsToolInputZodSchema;
+
+ constructor(
+ private readonly connectedAccountMetadataService: ConnectedAccountMetadataService,
+ ) {}
+
+ async execute(
+ { handle }: FindConnectedAccountsToolInput,
+ { workspaceId, userWorkspaceId }: ToolExecutionContext,
+ ): Promise<ToolOutput> {
+ const usableAccounts =
+ await this.connectedAccountMetadataService.findUsableByCaller({
+ workspaceId,
+ userWorkspaceId,
+ });
+
+ const matchingAccounts = isNonEmptyString(handle)
+ ? filterConnectedAccountsByHandle({
+ connectedAccounts: usableAccounts,
+ handle,
+ })
+ : usableAccounts;
+
+ const records = matchingAccounts.map((connectedAccount) => ({
+ id: connectedAccount.id,
+ handle: connectedAccount.handle,
+ handleAliases: connectedAccount.handleAliases,
+ provider: connectedAccount.provider,
+ name: connectedAccount.name,
+ visibility: connectedAccount.visibility,
+ }));
+
+ return {
+ success: true,
+ message: `Found ${records.length} connectedAccount record${records.length === 1 ? '' : 's'}`,
+ result: {
+ records,
+ count: String(records.length),
+ },
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/types/find-connected-accounts-tool-input.type.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/types/find-connected-accounts-tool-input.type.ts
new file mode 100644
index 00000000000..c85d2829391
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/types/find-connected-accounts-tool-input.type.ts
@@ -0,0 +1,7 @@
+import { type z } from 'zod';
+
+import { type FindConnectedAccountsToolInputZodSchema } from 'src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool.schema';
+
+export type FindConnectedAccountsToolInput = z.infer<
+ typeof FindConnectedAccountsToolInputZodSchema
+>;
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/utils/__tests__/filter-connected-accounts-by-handle.util.spec.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/utils/__tests__/filter-connected-accounts-by-handle.util.spec.ts
new file mode 100644
index 00000000000..a9e780258ca
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/utils/__tests__/filter-connected-accounts-by-handle.util.spec.ts
@@ -0,0 +1,62 @@
+import { filterConnectedAccountsByHandle } from 'src/engine/core-modules/tool/tools/email-tool/utils/filter-connected-accounts-by-handle.util';
+
+const ownAccount = {
+ id: 'own-account-id',
+ handle: '[email protected]',
+ handleAliases: ['[email protected]'],
+};
+
+const sharedAccount = {
+ id: 'shared-account-id',
+ handle: '[email protected]',
+ handleAliases: null,
+};
+
+const connectedAccounts = [ownAccount, sharedAccount];
+
+describe('filterConnectedAccountsByHandle', () => {
+ it('matches the primary handle regardless of case and surrounding spaces', () => {
+ expect(
+ filterConnectedAccountsByHandle({
+ connectedAccounts,
+ handle: ' [email protected] ',
+ }),
+ ).toEqual([ownAccount]);
+ });
+
+ it('matches a verified alias', () => {
+ expect(
+ filterConnectedAccountsByHandle({
+ connectedAccounts,
+ handle: '[email protected]',
+ }),
+ ).toEqual([ownAccount]);
+ });
+
+ it('matches an account without aliases', () => {
+ expect(
+ filterConnectedAccountsByHandle({
+ connectedAccounts,
+ handle: '[email protected]',
+ }),
+ ).toEqual([sharedAccount]);
+ });
+
+ it('returns no account when the handle only partially matches', () => {
+ expect(
+ filterConnectedAccountsByHandle({
+ connectedAccounts,
+ handle: 'me@example',
+ }),
+ ).toEqual([]);
+ });
+
+ it('returns no account when nothing matches', () => {
+ expect(
+ filterConnectedAccountsByHandle({
+ connectedAccounts,
+ handle: '[email protected]',
+ }),
+ ).toEqual([]);
+ });
+});
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/utils/filter-connected-accounts-by-handle.util.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/utils/filter-connected-accounts-by-handle.util.ts
new file mode 100644
index 00000000000..0e62c3c870c
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/email-tool/utils/filter-connected-accounts-by-handle.util.ts
@@ -0,0 +1,21 @@
+import { getSendableEmailHandles } from 'twenty-shared/utils';
+
+const normalizeHandle = (handle: string): string => handle.trim().toLowerCase();
+
+export const filterConnectedAccountsByHandle = <
+ TConnectedAccount extends { handle: string; handleAliases: string[] | null },
+>({
+ connectedAccounts,
+ handle,
+}: {
+ connectedAccounts: TConnectedAccount[];
+ handle: string;
+}): TConnectedAccount[] => {
+ const normalizedHandle = normalizeHandle(handle);
+
+ return connectedAccounts.filter((connectedAccount) =>
+ getSendableEmailHandles(connectedAccount).some(
+ (sendableHandle) => normalizeHandle(sendableHandle) === normalizedHandle,
+ ),
+ );
+};
diff --git a/packages/twenty-server/src/engine/metadata-modules/connected-account/connected-account-metadata.service.ts b/packages/twenty-server/src/engine/metadata-modules/connected-account/connected-account-metadata.service.ts
index 2aeb0faa24f..58b28b05164 100644
--- a/packages/twenty-server/src/engine/metadata-modules/connected-account/connected-account-metadata.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/connected-account/connected-account-metadata.service.ts
@@ -17,6 +17,7 @@ import {
} from 'src/engine/metadata-modules/connected-account/connected-account.exception';
import { ConnectedAccountEntity } from 'src/engine/metadata-modules/connected-account/entities/connected-account.entity';
import { type ConnectedAccountDeletedEvent } from 'src/engine/metadata-modules/connected-account/types/connected-account-deleted.type';
+import { type ConnectedAccountWithoutCredentials } from 'src/engine/metadata-modules/connected-account/types/connected-account-without-credentials.type';
import { isConnectedAccountUsableByCaller } from 'src/engine/metadata-modules/connected-account/utils/is-connected-account-usable-by-caller.util';
import { MESSAGE_CHANNEL_DELETED_EVENT } from 'src/engine/metadata-modules/message-channel/constants/message-channel-deleted.constant';
import { MessageChannelEntity } from 'src/engine/metadata-modules/message-channel/entities/message-channel.entity';
@@ -39,6 +40,38 @@ export class ConnectedAccountMetadataService {
private readonly workspaceEventEmitter: WorkspaceEventEmitter,
) {}
+ async findUsableByCaller({
+ workspaceId,
+ userWorkspaceId,
+ }: {
+ workspaceId: string;
+ userWorkspaceId?: string;
+ }): Promise<ConnectedAccountWithoutCredentials[]> {
+ const connectedAccounts = await this.repository.find({
+ where: { workspaceId, archivedAt: IsNull() },
+ order: { createdAt: 'ASC', id: 'ASC' },
+ select: {
+ id: true,
+ handle: true,
+ handleAliases: true,
+ provider: true,
+ name: true,
+ visibility: true,
+ userWorkspaceId: true,
+ },
+ });
+
+ if (!isDefined(userWorkspaceId)) {
+ return connectedAccounts.filter(
+ (connectedAccount) => connectedAccount.visibility === 'workspace',
+ );
+ }
+
+ return connectedAccounts.filter((connectedAccount) =>
+ isConnectedAccountUsableByCaller({ connectedAccount, userWorkspaceId }),
+ );
+ }
+
async findByUserWorkspaceId({
userWorkspaceId,
workspaceId,
diff --git a/packages/twenty-server/src/engine/metadata-modules/connected-account/types/connected-account-without-credentials.type.ts b/packages/twenty-server/src/engine/metadata-modules/connected-account/types/connected-account-without-credentials.type.ts
new file mode 100644
index 00000000000..19bbce43ac0
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/connected-account/types/connected-account-without-credentials.type.ts
@@ -0,0 +1,12 @@
+import { type ConnectedAccountEntity } from 'src/engine/metadata-modules/connected-account/entities/connected-account.entity';
+
+export type ConnectedAccountWithoutCredentials = Pick<
+ ConnectedAccountEntity,
+ | 'id'
+ | 'handle'
+ | 'handleAliases'
+ | 'provider'
+ | 'name'
+ | 'visibility'
+ | 'userWorkspaceId'
+>;