Skip to content

The open alternative to Salesforce, designed for AI.

feat: add create/complete file upload action tools for MCP (#25503)

Lakshay Manchanda96609b97ae4b
diff --git a/packages/twenty-server/src/engine/api/mcp/services/mcp-instruction-builder.service.ts b/packages/twenty-server/src/engine/api/mcp/services/mcp-instruction-builder.service.ts
index 909afcf0190..b5a11febc2e 100644
--- a/packages/twenty-server/src/engine/api/mcp/services/mcp-instruction-builder.service.ts
+++ b/packages/twenty-server/src/engine/api/mcp/services/mcp-instruction-builder.service.ts
@@ -1,8 +1,11 @@
import { Injectable } from '@nestjs/common';
+import { ToolCategory } from 'twenty-shared/ai';
import { camelToSnakeCase } from 'twenty-shared/utils';
+import { MCP_EXCLUDED_TOOL_NAMES } from 'src/engine/api/mcp/constants/mcp-excluded-tool-names.const';
import { buildMcpServerInstructions } from 'src/engine/api/mcp/utils/build-mcp-server-instructions.util';
+import { ToolRegistryService } from 'src/engine/core-modules/tool-provider/services/tool-registry.service';
import { getDatabaseCrudToolFlatObjects } from 'src/engine/metadata-modules/ai/ai-agent/utils/get-database-crud-tool-flat-objects.util';
import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
import { SkillService } from 'src/engine/metadata-modules/skill/skill.service';
@@ -12,16 +15,27 @@ export class McpInstructionBuilderService {
constructor(
private readonly flatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
private readonly skillService: SkillService,
+ private readonly toolRegistry: ToolRegistryService,
) {}
- async buildInstructions(workspaceId: string): Promise<string> {
- const [{ flatObjectMetadataMaps }, allSkills] = await Promise.all([
- this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps({
- workspaceId,
- flatMapsKeys: ['flatObjectMetadataMaps'],
- }),
- this.skillService.findAllFlatSkills(workspaceId),
- ]);
+ async buildInstructions({
+ workspaceId,
+ roleId,
+ }: {
+ workspaceId: string;
+ roleId: string;
+ }): Promise<string> {
+ const [{ flatObjectMetadataMaps }, allSkills, actionToolCatalog] =
+ await Promise.all([
+ this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps({
+ workspaceId,
+ flatMapsKeys: ['flatObjectMetadataMaps'],
+ }),
+ this.skillService.findAllFlatSkills(workspaceId),
+ this.toolRegistry.buildToolIndex(workspaceId, roleId, {
+ categories: [ToolCategory.ACTION],
+ }),
+ ]);
const objectNames = getDatabaseCrudToolFlatObjects(
flatObjectMetadataMaps.byUniversalIdentifier,
@@ -30,11 +44,19 @@ export class McpInstructionBuilderService {
.sort()
.join(', ');
+ const actionToolNames = actionToolCatalog
+ .map((entry) => entry.name)
+ .filter((name) => !MCP_EXCLUDED_TOOL_NAMES.has(name));
+
const skillNames =
allSkills.length > 0
? allSkills.map((skill) => skill.name).join(', ')
: undefined;
- return buildMcpServerInstructions(objectNames, skillNames);
+ return buildMcpServerInstructions({
+ objectNames,
+ actionToolNames,
+ skillNames,
+ });
}
}
diff --git a/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts b/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts
index e4b4e870312..e60054ab116 100644
--- a/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts
+++ b/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts
@@ -1,8 +1,8 @@
import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
import { type ToolSet, zodSchema } from 'ai';
-import { isDefined } from 'twenty-shared/utils';
import { type ActorMetadata, FieldActorSource } from 'twenty-shared/types';
+import { isDefined } from 'twenty-shared/utils';
import { JSON_RPC_ERROR_CODE } from 'src/engine/api/mcp/constants/json-rpc-error-code.const';
import { MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-closed-world-read-only-tool-annotations.const';
@@ -55,8 +55,8 @@ import {
import { type FlatWorkspace } from 'src/engine/core-modules/workspace/types/flat-workspace.type';
import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
import { SkillService } from 'src/engine/metadata-modules/skill/skill.service';
-import { WorkspaceCacheService } from 'src/engine/workspace-cache/services/workspace-cache.service';
import { UserRoleService } from 'src/engine/metadata-modules/user-role/user-role.service';
+import { WorkspaceCacheService } from 'src/engine/workspace-cache/services/workspace-cache.service';
type McpAnnotatedTool = ToolSet[string] & {
annotations: McpToolAnnotations;
@@ -98,9 +98,15 @@ export class McpProtocolService {
private readonly workspaceCacheService: WorkspaceCacheService,
) {}
- async handleInitialize(requestId: string | number, workspaceId: string) {
+ async handleInitialize(
+ requestId: string | number,
+ { workspaceId, roleId }: { workspaceId: string; roleId: string },
+ ) {
const instructions =
- await this.mcpInstructionBuilderService.buildInstructions(workspaceId);
+ await this.mcpInstructionBuilderService.buildInstructions({
+ workspaceId,
+ roleId,
+ });
return wrapJsonRpcResponse(requestId, {
result: {
@@ -300,7 +306,10 @@ export class McpProtocolService {
}
if (method === 'initialize') {
- return this.handleInitialize(id, workspace.id);
+ return this.handleInitialize(id, {
+ workspaceId: workspace.id,
+ roleId: await this.getRoleId(workspace.id, userWorkspaceId, apiKey),
+ });
}
if (method === 'ping') {
diff --git a/packages/twenty-server/src/engine/api/mcp/utils/__tests__/build-mcp-server-instructions.util.spec.ts b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/build-mcp-server-instructions.util.spec.ts
new file mode 100644
index 00000000000..65224f8b17a
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/build-mcp-server-instructions.util.spec.ts
@@ -0,0 +1,60 @@
+import { buildMcpServerInstructions } from 'src/engine/api/mcp/utils/build-mcp-server-instructions.util';
+
+const getActionLine = (instructions: string): string =>
+ instructions.split('\n').find((line) => line.includes('ACTION:')) ?? '';
+
+describe('buildMcpServerInstructions', () => {
+ it('should render the ACTION line from the tools the caller can reach', () => {
+ const instructions = buildMcpServerInstructions({
+ objectNames: 'companies, people',
+ actionToolNames: ['send_email', 'search_help_center'],
+ });
+
+ expect(getActionLine(instructions)).toContain(
+ 'send_email | search_help_center',
+ );
+ expect(instructions).not.toContain('create_file_upload');
+ expect(instructions).not.toContain('http_request');
+ });
+
+ it('should add the upload recipe only when the upload tools are reachable', () => {
+ const withUpload = buildMcpServerInstructions({
+ objectNames: 'companies',
+ actionToolNames: ['create_file_upload', 'complete_file_upload'],
+ });
+
+ expect(withUpload).toContain('To attach a file: create_file_upload');
+
+ const withoutUpload = buildMcpServerInstructions({
+ objectNames: 'companies',
+ actionToolNames: ['send_email'],
+ });
+
+ expect(withoutUpload).not.toContain('To attach a file');
+ });
+
+ it('should add the http_request guidance only when http_request is reachable', () => {
+ const withHttp = buildMcpServerInstructions({
+ objectNames: 'companies',
+ actionToolNames: ['http_request'],
+ });
+
+ expect(withHttp).toContain('http_request is ONLY for external');
+
+ const withoutHttp = buildMcpServerInstructions({
+ objectNames: 'companies',
+ actionToolNames: ['send_email'],
+ });
+
+ expect(withoutHttp).not.toContain('http_request is ONLY for external');
+ });
+
+ it('should omit the skills line when the workspace has no skills', () => {
+ const instructions = buildMcpServerInstructions({
+ objectNames: 'companies',
+ actionToolNames: ['send_email'],
+ });
+
+ expect(instructions).not.toContain('Available skills');
+ });
+});
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 a2a036796d3..f97e7ca3ad8 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
@@ -1,8 +1,17 @@
-export const buildMcpServerInstructions = (
- objectNames: string,
- skillNames?: string,
-): string =>
- [
+import { settings } from 'src/engine/constants/settings';
+
+export const buildMcpServerInstructions = ({
+ objectNames,
+ actionToolNames,
+ skillNames,
+}: {
+ objectNames: string;
+ actionToolNames: string[];
+ skillNames?: string;
+}): string => {
+ const availableActionTools = new Set(actionToolNames);
+
+ return [
`You are an AI assistant for a Twenty CRM workspace.`,
`Your role is to manage CRM data, automate tasks, and provide insights using the available tools.`,
``,
@@ -23,7 +32,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 | find_connected_accounts | navigate_app | code_interpreter | search_help_center`,
+ ` ACTION: ${actionToolNames.join(' | ')}`,
` 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`,
@@ -70,9 +79,19 @@ export const buildMcpServerInstructions = (
`Twenty primitives:`,
` Favorites are navigation menu items. To favorite something, call create_navigation_menu_item with scope: 'user'.`,
` A default OBJECT navigation item is auto-created with create_object_metadata — do not add another.`,
- ` http_request is ONLY for external third-party APIs, never for Twenty's own data.`,
+ ...(availableActionTools.has('http_request')
+ ? [
+ ` http_request is ONLY for external third-party APIs, never for Twenty's own data.`,
+ ]
+ : []),
+ ...(availableActionTools.has('create_file_upload')
+ ? [
+ ` To attach a file: create_file_upload ({ filename, size }), PUT the bytes to uploadUrl with Content-Type contentType (max ${settings.storage.maxDirectUploadFileSize}), then complete_file_upload ({ fileId }). Use that fileId in a FILES value (create_one_attachment file: [{ fileId, label }] and the target*Id, or a FILES field on create_one_* / update_one_*) or in code_interpreter.files. update_many does not copy FILES values; update_one replaces the whole FILES list.`,
+ ]
+ : []),
``,
`On tool failure: read the error message, do not retry silently, report to user.`,
`Present results as readable summaries, not raw JSON.`,
`For large result sets, show count + first N records and offer to paginate.`,
].join('\n');
+};
diff --git a/packages/twenty-server/src/engine/core-modules/file/file-upload/services/file-upload.service.ts b/packages/twenty-server/src/engine/core-modules/file/file-upload/services/file-upload.service.ts
index 3e1196d41f8..4882f375918 100644
--- a/packages/twenty-server/src/engine/core-modules/file/file-upload/services/file-upload.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/file/file-upload/services/file-upload.service.ts
@@ -16,11 +16,11 @@ import { settings } from 'src/engine/constants/settings';
import { ApplicationEntity } from 'src/engine/core-modules/application/application.entity';
import { ApplicationService } from 'src/engine/core-modules/application/application.service';
import { FileStorageService } from 'src/engine/core-modules/file-storage/services/file-storage.service';
-import { FileWithSignedUrlDTO } from 'src/engine/core-modules/file/dtos/file-with-sign-url.dto';
import { FileEntity } from 'src/engine/core-modules/file/entities/file.entity';
import { COMPLETE_FILE_UPLOAD_DEADLINE_MS } from 'src/engine/core-modules/file/file-upload/constants/complete-file-upload-deadline.constant';
import { MAX_SANITIZABLE_SVG_BYTES } from 'src/engine/core-modules/file/file-upload/constants/max-sanitizable-svg-size.constant';
import { FileUploadTargetDTO } from 'src/engine/core-modules/file/file-upload/dtos/file-upload-target.dto';
+import { type CompletedFileUpload } from 'src/engine/core-modules/file/file-upload/types/completed-file-upload.type';
import {
FileUploadException,
FileUploadExceptionCode,
@@ -250,7 +250,7 @@ export class FileUploadService {
}: {
workspaceId: string;
fileId: string;
- }): Promise<FileWithSignedUrlDTO> {
+ }): Promise<CompletedFileUpload> {
const file = await this.findFileOrThrow({ workspaceId, fileId });
const [fileFolder] = file.path.split('/');
@@ -451,7 +451,7 @@ export class FileUploadService {
file: FileEntity;
fileFolder: FileFolder;
workspaceId: string;
- }): Promise<FileWithSignedUrlDTO> {
+ }): Promise<CompletedFileUpload> {
return {
...file,
url: await this.fileUrlService.signFileByIdUrl({
diff --git a/packages/twenty-server/src/engine/core-modules/file/file-upload/types/completed-file-upload.type.ts b/packages/twenty-server/src/engine/core-modules/file/file-upload/types/completed-file-upload.type.ts
new file mode 100644
index 00000000000..bf23209e182
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/file/file-upload/types/completed-file-upload.type.ts
@@ -0,0 +1,5 @@
+import { type FileWithSignedUrlDTO } from 'src/engine/core-modules/file/dtos/file-with-sign-url.dto';
+import { type FileEntity } from 'src/engine/core-modules/file/entities/file.entity';
+
+export type CompletedFileUpload = FileWithSignedUrlDTO &
+ Pick<FileEntity, 'mimeType'>;
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 ea03e74e047..0b76996f57a 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
@@ -13,6 +13,8 @@ export const ACTION_TOOL_IDS = [
'code_interpreter',
'navigate_app',
'save_campaign',
+ 'create_file_upload',
+ 'complete_file_upload',
] as const;
export type ActionToolId = (typeof ACTION_TOOL_IDS)[number];
@@ -45,4 +47,10 @@ export const ACTION_TOOL_LABELS: Record<ActionToolId, ActionToolLabel> = {
save_campaign: {
label: i18nLabel(msg`Save Campaign`),
},
+ create_file_upload: {
+ label: i18nLabel(msg`Create File Upload`),
+ },
+ complete_file_upload: {
+ label: i18nLabel(msg`Complete File Upload`),
+ },
};
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 d1180aba35c..d2974180039 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
@@ -26,6 +26,8 @@ import { CodeInterpreterTool } from 'src/engine/core-modules/tool/tools/code-int
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 { CompleteFileUploadTool } from 'src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool';
+import { CreateFileUploadTool } from 'src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-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';
import { ExtractJsonPathsTool } from 'src/engine/core-modules/tool/tools/output-navigation-tool/extract-json-paths-tool';
@@ -49,6 +51,8 @@ export class ActionToolProvider implements ToolProvider {
private readonly findConnectedAccountsTool: FindConnectedAccountsTool,
private readonly createCalendarEventTool: CreateCalendarEventTool,
private readonly searchHelpCenterTool: SearchHelpCenterTool,
+ private readonly createFileUploadTool: CreateFileUploadTool,
+ private readonly completeFileUploadTool: CompleteFileUploadTool,
private readonly codeInterpreterTool: CodeInterpreterTool,
private readonly navigateAppTool: NavigateAppTool,
private readonly extractJsonPathsTool: ExtractJsonPathsTool,
@@ -65,6 +69,8 @@ export class ActionToolProvider implements ToolProvider {
['find_connected_accounts', this.findConnectedAccountsTool],
['create_calendar_event', this.createCalendarEventTool],
['search_help_center', this.searchHelpCenterTool],
+ ['create_file_upload', this.createFileUploadTool],
+ ['complete_file_upload', this.completeFileUploadTool],
['code_interpreter', this.codeInterpreterTool],
['navigate_app', this.navigateAppTool],
['extract_json_paths', this.extractJsonPathsTool],
@@ -152,6 +158,32 @@ export class ActionToolProvider implements ToolProvider {
);
}
+ const hasUploadFilePermission =
+ await this.permissionsService.hasToolPermission(
+ context.rolePermissionConfig,
+ context.workspaceId,
+ PermissionFlagType.UPLOAD_FILE,
+ );
+
+ if (hasUploadFilePermission) {
+ descriptors.push(
+ this.buildDescriptor(
+ 'create_file_upload',
+ this.createFileUploadTool,
+ includeSchemas,
+ context.locale,
+ ),
+ );
+ descriptors.push(
+ this.buildDescriptor(
+ 'complete_file_upload',
+ this.completeFileUploadTool,
+ includeSchemas,
+ context.locale,
+ ),
+ );
+ }
+
descriptors.push(
this.buildDescriptor(
'search_help_center',
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts
index 9e29859db71..b5df4e8f859 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts
@@ -1,6 +1,7 @@
import { Inject, Injectable, Logger } from '@nestjs/common';
import { type ToolSet, jsonSchema } from 'ai';
+import { type ToolCategory } from 'twenty-shared/ai';
import { type APP_LOCALES } from 'twenty-shared/translations';
import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
@@ -31,9 +32,20 @@ export class ToolRegistryService {
private readonly toolOutputSpillService: ToolOutputSpillService,
) {}
- async getCatalog(context: ToolProviderContext): Promise<ToolIndexEntry[]> {
+ async getCatalog(
+ context: ToolProviderContext,
+ options?: { categories?: ToolCategory[]; excludeTools?: Set<string> },
+ ): Promise<ToolIndexEntry[]> {
+ const categorySet = options?.categories
+ ? new Set(options.categories)
+ : undefined;
+
const results = await Promise.all(
this.providers.map(async (provider) => {
+ if (categorySet && !categorySet.has(provider.category)) {
+ return [];
+ }
+
if (await provider.isAvailable(context)) {
return provider.generateDescriptors(context, {
includeSchemas: false,
@@ -44,7 +56,9 @@ export class ToolRegistryService {
}),
);
- return results.flat();
+ const excludeTools = options?.excludeTools;
+
+ return results.flat().filter((entry) => !excludeTools?.has(entry.name));
}
async resolveSchemas({
@@ -159,6 +173,8 @@ export class ToolRegistryService {
userWorkspaceId?: string;
locale?: keyof typeof APP_LOCALES;
rolePermissionConfig?: RolePermissionConfig;
+ categories?: ToolCategory[];
+ excludeTools?: Set<string>;
},
): Promise<ToolIndexEntry[]> {
const context = this.buildContextFromToolContext({
@@ -170,7 +186,10 @@ export class ToolRegistryService {
locale: options?.locale,
});
- return this.getCatalog(context);
+ return this.getCatalog(context, {
+ categories: options?.categories,
+ excludeTools: options?.excludeTools,
+ });
}
async getToolsByName(
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 36d481d7d35..b09e42ac386 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
@@ -13,6 +13,8 @@ import { DraftEmailTool } from 'src/engine/core-modules/tool/tools/email-tool/dr
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 { CompleteFileUploadTool } from 'src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool';
+import { CreateFileUploadTool } from 'src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-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';
import { ExtractJsonPathsTool } from 'src/engine/core-modules/tool/tools/output-navigation-tool/extract-json-paths-tool';
@@ -54,6 +56,8 @@ import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspac
CreateCalendarEventTool,
EmailComposerService,
SearchHelpCenterTool,
+ CreateFileUploadTool,
+ CompleteFileUploadTool,
CodeInterpreterTool,
NavigateAppTool,
ExtractJsonPathsTool,
@@ -69,6 +73,8 @@ import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspac
CreateCalendarEventTool,
EmailComposerService,
SearchHelpCenterTool,
+ CreateFileUploadTool,
+ CompleteFileUploadTool,
CodeInterpreterTool,
NavigateAppTool,
ExtractJsonPathsTool,
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool.ts
new file mode 100644
index 00000000000..aecc67da2fe
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool.ts
@@ -0,0 +1,83 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { FileUploadException } from 'src/engine/core-modules/file/file-upload/file-upload.exception';
+import { FileUploadService } from 'src/engine/core-modules/file/file-upload/services/file-upload.service';
+import { CompleteFileUploadToolInputZodSchema } from 'src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema';
+import { type ToolInput } from 'src/engine/core-modules/tool/types/tool-input.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { type ToolExecutionContext } from 'src/engine/core-modules/tool/types/tool-execution-context.type';
+import { type Tool } from 'src/engine/core-modules/tool/types/tool.type';
+
+@Injectable()
+export class CompleteFileUploadTool implements Tool {
+ private readonly logger = new Logger(CompleteFileUploadTool.name);
+
+ description =
+ 'Confirm a direct upload after the client has PUT bytes to the uploadUrl from create_file_upload. Returns a fileId for FILES fields or code_interpreter.files. Requires UPLOAD_FILE permission.';
+ inputSchema = CompleteFileUploadToolInputZodSchema;
+
+ constructor(private readonly fileUploadService: FileUploadService) {}
+
+ async execute(
+ parameters: ToolInput,
+ context: ToolExecutionContext,
+ ): Promise<ToolOutput> {
+ const parseResult =
+ CompleteFileUploadToolInputZodSchema.safeParse(parameters);
+
+ if (!parseResult.success) {
+ return {
+ success: false,
+ message: 'Invalid input for complete file upload',
+ error: parseResult.error.issues
+ .map(
+ (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,
+ )
+ .join('; '),
+ };
+ }
+
+ const { fileId } = parseResult.data;
+
+ try {
+ const completedFile = await this.fileUploadService.completeFileUpload({
+ workspaceId: context.workspaceId,
+ fileId,
+ });
+
+ this.logger.log(
+ `Completed file upload ${completedFile.id} for workspace ${context.workspaceId}`,
+ );
+
+ return {
+ success: true,
+ message: 'File upload completed',
+ result: {
+ fileId: completedFile.id,
+ path: completedFile.path,
+ mimeType: completedFile.mimeType,
+ size: Number(completedFile.size),
+ },
+ };
+ } catch (error) {
+ if (error instanceof FileUploadException) {
+ return {
+ success: false,
+ message: 'Failed to complete file upload',
+ error: error.message,
+ };
+ }
+
+ this.logger.error(`Failed to complete file upload: ${error}`);
+
+ return {
+ success: false,
+ message: 'Failed to complete file upload',
+ error:
+ error instanceof Error
+ ? error.message
+ : 'Failed to complete file upload',
+ };
+ }
+ }
+}
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-tool.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-tool.ts
new file mode 100644
index 00000000000..68ac6ab0da1
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-tool.ts
@@ -0,0 +1,87 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { FileFolder } from 'twenty-shared/types';
+
+import { settings } from 'src/engine/constants/settings';
+import { FileUploadException } from 'src/engine/core-modules/file/file-upload/file-upload.exception';
+import { FileUploadService } from 'src/engine/core-modules/file/file-upload/services/file-upload.service';
+import { CreateFileUploadToolInputZodSchema } from 'src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema';
+import { type ToolInput } from 'src/engine/core-modules/tool/types/tool-input.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { type ToolExecutionContext } from 'src/engine/core-modules/tool/types/tool-execution-context.type';
+import { type Tool } from 'src/engine/core-modules/tool/types/tool.type';
+
+@Injectable()
+export class CreateFileUploadTool implements Tool {
+ private readonly logger = new Logger(CreateFileUploadTool.name);
+
+ description = `Create an upload URL for a file in agent-chat storage. PUT the bytes to uploadUrl with the returned Content-Type, then call complete_file_upload. Requires UPLOAD_FILE permission. Maximum size ${settings.storage.maxDirectUploadFileSize}.`;
+ inputSchema = CreateFileUploadToolInputZodSchema;
+
+ constructor(private readonly fileUploadService: FileUploadService) {}
+
+ async execute(
+ parameters: ToolInput,
+ context: ToolExecutionContext,
+ ): Promise<ToolOutput> {
+ const parseResult =
+ CreateFileUploadToolInputZodSchema.safeParse(parameters);
+
+ if (!parseResult.success) {
+ return {
+ success: false,
+ message: 'Invalid input for create file upload',
+ error: parseResult.error.issues
+ .map(
+ (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,
+ )
+ .join('; '),
+ };
+ }
+
+ const { filename, size } = parseResult.data;
+
+ try {
+ const uploadTarget = await this.fileUploadService.createFileUpload({
+ workspaceId: context.workspaceId,
+ filename,
+ size,
+ fileFolder: FileFolder.AgentChat,
+ });
+
+ this.logger.log(
+ `Created file upload ${uploadTarget.fileId} (${filename}) for workspace ${context.workspaceId}`,
+ );
+
+ return {
+ success: true,
+ message: 'Upload URL created.',
+ result: {
+ fileId: uploadTarget.fileId,
+ uploadUrl: uploadTarget.uploadUrl,
+ contentType: uploadTarget.contentType,
+ expiresAt: uploadTarget.expiresAt,
+ },
+ };
+ } catch (error) {
+ if (error instanceof FileUploadException) {
+ return {
+ success: false,
+ message: 'Failed to create file upload',
+ error: error.message,
+ };
+ }
+
+ this.logger.error(`Failed to create file upload: ${error}`);
+
+ return {
+ success: false,
+ message: 'Failed to create file upload',
+ error:
+ error instanceof Error
+ ? error.message
+ : 'Failed to create file upload',
+ };
+ }
+ }
+}
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema.ts
new file mode 100644
index 00000000000..b2f383c7a6e
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema.ts
@@ -0,0 +1,26 @@
+import { isValidUuid } from 'twenty-shared/utils';
+import { z } from 'zod';
+
+export const CreateFileUploadToolInputZodSchema = z.object({
+ filename: z
+ .string()
+ .describe(
+ 'Original filename including extension (e.g. protokol-2026-001.pdf).',
+ ),
+ size: z
+ .number()
+ .int()
+ .positive()
+ .describe('Exact byte length of the file being uploaded.'),
+});
+
+export const CompleteFileUploadToolInputZodSchema = z.object({
+ fileId: z
+ .string()
+ .refine((fileId) => isValidUuid(fileId), {
+ message: 'fileId must be a valid UUID',
+ })
+ .describe(
+ 'fileId returned by create_file_upload after the bytes have been PUT to uploadUrl.',
+ ),
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const.ts
index db8dc6154ca..94f4beb8bd6 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const.ts
@@ -3,4 +3,6 @@ import { type ActionToolId } from 'src/engine/core-modules/tool-provider/constan
export const WORKFLOW_AGENT_EXCLUDED_TOOL_NAMES = [
'search_help_center',
'navigate_app',
+ 'create_file_upload',
+ 'complete_file_upload',
] as const satisfies readonly ActionToolId[];
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts
index e49a1b6b753..d795ee1b436 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts
@@ -44,6 +44,7 @@ import { OUTPUT_NAVIGATION_TOOL_NAMES } from 'src/engine/core-modules/tool/tools
import { UsageOperationType } from 'src/engine/core-modules/usage/enums/usage-operation-type.enum';
import { WorkspaceEntity } from 'src/engine/core-modules/workspace/workspace.entity';
import { OPEN_ENDED_AGENT_REGISTRY_TOOL_CATEGORIES } from 'src/engine/metadata-modules/ai/ai-agent-execution/constants/open-ended-agent-registry-tool-categories.const';
+import { WORKFLOW_AGENT_EXCLUDED_TOOL_NAMES } from 'src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const';
import { WORKFLOW_AGENT_REGISTRY_TOOL_CATEGORIES } from 'src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-registry-tool-categories.const';
import { type AgentExecutionResult } from 'src/engine/metadata-modules/ai/ai-agent-execution/types/agent-execution-result.type';
import { type AgentToolLoadingStrategy } from 'src/engine/metadata-modules/ai/ai-agent-execution/types/agent-tool-loading-strategy.type';
@@ -172,7 +173,10 @@ export class AgentAsyncExecutorService {
return this.toolRegistry.getToolsByCategories(toolProviderContext, {
categories: WORKFLOW_AGENT_REGISTRY_TOOL_CATEGORIES,
- excludeTools: [...OUTPUT_NAVIGATION_TOOL_NAMES],
+ excludeTools: [
+ ...OUTPUT_NAVIGATION_TOOL_NAMES,
+ ...WORKFLOW_AGENT_EXCLUDED_TOOL_NAMES,
+ ],
wrapWithErrorContext: false,
});
}
@@ -219,7 +223,10 @@ export class AgentAsyncExecutorService {
const allowedCategories = new Set(
OPEN_ENDED_AGENT_REGISTRY_TOOL_CATEGORIES,
);
- const excludedToolNames = new Set<string>(OUTPUT_NAVIGATION_TOOL_NAMES);
+ const excludedToolNames = new Set<string>([
+ ...OUTPUT_NAVIGATION_TOOL_NAMES,
+ ...WORKFLOW_AGENT_EXCLUDED_TOOL_NAMES,
+ ]);
const catalog = fullCatalog.filter(
(entry) =>
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const.ts
new file mode 100644
index 00000000000..1d710633981
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const.ts
@@ -0,0 +1,4 @@
+export const AI_CHAT_EXCLUDED_TOOL_NAMES = new Set([
+ 'create_file_upload',
+ 'complete_file_upload',
+]);
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts
index fae956d6833..3a0d2bcfc27 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts
@@ -55,6 +55,7 @@ import {
extractCacheCreationTokens,
extractCacheCreationTokensFromSteps,
} from 'src/engine/metadata-modules/ai/ai-billing/utils/extract-cache-creation-tokens.util';
+import { AI_CHAT_EXCLUDED_TOOL_NAMES } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const';
import { AI_CHAT_STREAM_FUNCTION_ID } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-stream-function-id.constant';
import { AI_CHAT_TOOL_NAMES_TO_PRELOAD } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-tool-names-to-preload.const';
import { AI_CHAT_WORKSPACE_SETUP_STREAM_FUNCTION_ID } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-workspace-setup-stream-function-id.constant';
@@ -172,7 +173,12 @@ export class ChatExecutionService {
const toolCatalog = await this.toolRegistry.buildToolIndex(
workspace.id,
roleId,
- { userId, userWorkspaceId, locale },
+ {
+ userId,
+ userWorkspaceId,
+ locale,
+ excludeTools: AI_CHAT_EXCLUDED_TOOL_NAMES,
+ },
);
const skillCatalog = await this.skillService.findAllFlatSkills(
@@ -244,6 +250,9 @@ export class ChatExecutionService {
...(isWorkspaceSetupThread ? [COMPLETE_WORKSPACE_SETUP_TOOL_NAME] : []),
];
+ const isToolAllowed = (toolName: string) =>
+ !AI_CHAT_EXCLUDED_TOOL_NAMES.has(toolName);
+
// ToolSet is constant for the entire conversation — no mutation.
// learn_tools returns schemas as text; execute_tool dispatches via the registry.
const activeTools: ToolSet = {
@@ -260,12 +269,19 @@ export class ChatExecutionService {
[LEARN_TOOLS_TOOL_NAME]: createLearnToolsTool(
this.toolRegistry,
toolContext,
- { spillLargeOutput: true },
+ {
+ spillLargeOutput: true,
+ isToolAllowed,
+ },
),
[EXECUTE_TOOL_TOOL_NAME]: createExecuteToolTool(
this.toolRegistry,
toolContext,
- { compactOutput: true, spillLargeOutput: true },
+ {
+ compactOutput: true,
+ spillLargeOutput: true,
+ isToolAllowed,
+ },
),
[LOAD_SKILL_TOOL_NAME]: createLoadSkillTool(
(skillNames) =>
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/system-prompt-builder.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/system-prompt-builder.service.ts
index 045e7eb4f0c..58c4cbb734a 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/system-prompt-builder.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/system-prompt-builder.service.ts
@@ -6,6 +6,7 @@ import { COMMON_PRELOAD_TOOLS } from 'src/engine/core-modules/tool-provider/cons
import { ToolRegistryService } from 'src/engine/core-modules/tool-provider/services/tool-registry.service';
import { buildToolCatalogSection } from 'src/engine/core-modules/tool-provider/utils/build-tool-catalog-section.util';
import { AgentActorContextService } from 'src/engine/metadata-modules/ai/ai-agent-execution/services/agent-actor-context.service';
+import { AI_CHAT_EXCLUDED_TOOL_NAMES } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const';
import { CHAT_SYSTEM_PROMPTS } from 'src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const';
import { buildSkillCatalogSection } from 'src/engine/metadata-modules/ai/ai-chat/utils/build-skill-catalog-section.util';
import { buildUserContextSection } from 'src/engine/metadata-modules/ai/ai-chat/utils/build-user-context-section.util';
@@ -48,7 +49,11 @@ export class SystemPromptBuilderService {
const toolCatalog = await this.toolRegistry.buildToolIndex(
workspaceId,
roleId,
- { userId, userWorkspaceId },
+ {
+ userId,
+ userWorkspaceId,
+ excludeTools: AI_CHAT_EXCLUDED_TOOL_NAMES,
+ },
);
const skillCatalog = await this.skillService.findAllFlatSkills(workspaceId);