Skip to content

The open alternative to Salesforce, designed for AI.

Migrate the navigation menu item tools to @DefineTool (#28477)

Paul Rastoinfedf59e1758d
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/__tests__/define-tool.decorator.spec.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/__tests__/define-tool.decorator.spec.ts
index cc0c4201331..470be36ae34 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/__tests__/define-tool.decorator.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/__tests__/define-tool.decorator.spec.ts
@@ -105,6 +105,22 @@ describe('DefineTool', () => {
}
}
+ const plainUnionInputSchema = z.union([
+ z.object({ link: z.url() }),
+ z.object({ name: z.string() }),
+ ]);
+
+ class ToolWithPlainUnionInput extends BaseTool<
+ // @ts-expect-error a plain union has no discriminator to tell its variants apart
+ typeof plainUnionInputSchema
+ > {
+ readonly inputSchema = plainUnionInputSchema;
+
+ async execute(): Promise<ToolOutput> {
+ return { success: true, message: 'Done' };
+ }
+ }
+
expect([
ToolWithoutPermissionFlag,
NotATool,
@@ -113,6 +129,32 @@ describe('DefineTool', () => {
ToolWithoutExecute,
ToolWithMismatchedInput,
ToolWithScalarInput,
- ]).toHaveLength(7);
+ ToolWithPlainUnionInput,
+ ]).toHaveLength(8);
+ });
+
+ it('should accept a discriminated union of objects as input', () => {
+ const pinItemInputSchema = z.discriminatedUnion('type', [
+ z.object({ type: z.literal('LINK'), link: z.url() }),
+ z.object({ type: z.literal('FOLDER'), name: z.string() }),
+ ]);
+
+ @DefineTool({ ...RENAME_WEBHOOK_OPTIONS, name: 'pin_item' })
+ class PinItemTool extends BaseTool<typeof pinItemInputSchema> {
+ readonly inputSchema = pinItemInputSchema;
+
+ async execute(
+ input: z.infer<typeof pinItemInputSchema>,
+ ): Promise<ToolOutput> {
+ return {
+ success: true,
+ message: input.type === 'LINK' ? input.link : input.name,
+ };
+ }
+ }
+
+ expect(
+ Reflect.getMetadata(DEFINE_TOOL_METADATA_KEY, PinItemTool),
+ ).toMatchObject({ name: 'pin_item' });
});
});
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/interfaces/base-tool.interface.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/interfaces/base-tool.interface.ts
index 95ff6e7e1d4..d028ebd4cae 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/interfaces/base-tool.interface.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/interfaces/base-tool.interface.ts
@@ -1,9 +1,12 @@
import { type z } from 'zod';
import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolInputSchema } from 'src/engine/core-modules/tool-provider/types/tool-input-schema.type';
import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
-export abstract class BaseTool<TInputSchema extends z.ZodObject = z.ZodObject> {
+export abstract class BaseTool<
+ TInputSchema extends ToolInputSchema = ToolInputSchema,
+> {
// Makes the type nominal: @DefineTool rejects look-alike classes that would fail instanceof at boot
protected readonly isBaseTool = true;
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/navigation-menu-item-tool.provider.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/navigation-menu-item-tool.provider.ts
deleted file mode 100644
index b850f42983b..00000000000
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/navigation-menu-item-tool.provider.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-import { Injectable } from '@nestjs/common';
-
-import { type ToolSet } from 'ai';
-import { ToolCategory } from 'twenty-shared/ai';
-
-import { type GenerateDescriptorOptions } from 'src/engine/core-modules/tool-provider/interfaces/generate-descriptor-options.type';
-import { type ToolProvider } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider.interface';
-import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
-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 { executeToolFromToolSet } from 'src/engine/core-modules/tool-provider/utils/execute-tool-from-tool-set.util';
-import { toolSetToDescriptors } from 'src/engine/core-modules/tool-provider/utils/tool-set-to-descriptors.util';
-import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
-import { NavigationMenuItemToolWorkspaceService } from 'src/engine/metadata-modules/navigation-menu-item/tools/services/navigation-menu-item-tool.workspace-service';
-
-@Injectable()
-export class NavigationMenuItemToolProvider implements ToolProvider {
- readonly category = ToolCategory.NAVIGATION_MENU_ITEM;
-
- constructor(
- private readonly navigationMenuItemToolService: NavigationMenuItemToolWorkspaceService,
- ) {}
-
- async isAvailable(_context: ToolProviderContext): Promise<boolean> {
- return true;
- }
-
- async generateDescriptors(
- context: ToolProviderContext,
- options?: GenerateDescriptorOptions,
- ): Promise<(ToolIndexEntry | ToolDescriptor)[]> {
- return toolSetToDescriptors(
- this.buildToolSet(context),
- ToolCategory.NAVIGATION_MENU_ITEM,
- { includeSchemas: options?.includeSchemas ?? true },
- );
- }
-
- async executeStaticTool(
- toolName: string,
- args: Record<string, unknown>,
- context: ToolProviderContext,
- ): Promise<ToolOutput> {
- return executeToolFromToolSet(
- this.buildToolSet(context),
- toolName,
- args,
- ToolCategory.NAVIGATION_MENU_ITEM,
- );
- }
-
- private buildToolSet(context: ToolProviderContext): ToolSet {
- return this.navigationMenuItemToolService.generateNavigationMenuItemTools({
- workspaceId: context.workspaceId,
- userWorkspaceId: context.userWorkspaceId,
- applicationId: context.application?.id,
- agentId: context.agentId,
- });
- }
-}
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
index 81b81e8486f..44e449e9aca 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
@@ -13,7 +13,6 @@ import { DashboardToolProvider } from 'src/engine/core-modules/tool-provider/pro
import { DatabaseToolProvider } from 'src/engine/core-modules/tool-provider/providers/database-tool.provider';
import { LogicFunctionToolProvider } from 'src/engine/core-modules/tool-provider/providers/logic-function-tool.provider';
import { MetadataToolProvider } from 'src/engine/core-modules/tool-provider/providers/metadata-tool.provider';
-import { NavigationMenuItemToolProvider } from 'src/engine/core-modules/tool-provider/providers/navigation-menu-item-tool.provider';
import { ViewToolProvider } from 'src/engine/core-modules/tool-provider/providers/view-tool.provider';
import { WorkflowToolProvider } from 'src/engine/core-modules/tool-provider/providers/workflow-tool.provider';
import { DefinedToolRegistryService } from 'src/engine/core-modules/tool-provider/services/defined-tool-registry.service';
@@ -25,7 +24,7 @@ import { AiAgentModule } from 'src/engine/metadata-modules/ai/ai-agent/ai-agent.
import { ApplicationTranslationCatalogModule } from 'src/engine/metadata-modules/application-translation-catalog/application-translation-catalog.module';
import { FieldMetadataModule } from 'src/engine/metadata-modules/field-metadata/field-metadata.module';
import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
-import { NavigationMenuItemModule } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.module';
+import { NavigationMenuItemToolsModule } from 'src/engine/metadata-modules/navigation-menu-item/tools/navigation-menu-item-tools.module';
import { ObjectMetadataModule } from 'src/engine/metadata-modules/object-metadata/object-metadata.module';
import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permissions.module';
import { RoleToolsModule } from 'src/engine/metadata-modules/role/tools/role-tools.module';
@@ -64,7 +63,7 @@ import { ToolRegistryService } from './services/tool-registry.service';
ViewSortModule,
WorkspaceCacheModule,
WorkspaceManyOrAllFlatEntityMapsCacheModule,
- NavigationMenuItemModule,
+ NavigationMenuItemToolsModule,
WebhookToolsModule,
RoleToolsModule,
UserRoleModule,
@@ -83,7 +82,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
DashboardToolProvider,
DatabaseToolProvider,
MetadataToolProvider,
- NavigationMenuItemToolProvider,
LogicFunctionToolProvider,
ViewToolProvider,
WorkflowToolProvider,
@@ -94,7 +92,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
databaseProvider: DatabaseToolProvider,
metadataProvider: MetadataToolProvider,
logicFunctionProvider: LogicFunctionToolProvider,
- navigationMenuItemProvider: NavigationMenuItemToolProvider,
viewProvider: ViewToolProvider,
workflowProvider: WorkflowToolProvider,
dashboardProvider: DashboardToolProvider,
@@ -104,7 +101,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
databaseProvider,
metadataProvider,
logicFunctionProvider,
- navigationMenuItemProvider,
viewProvider,
workflowProvider,
dashboardProvider,
@@ -115,7 +111,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
DatabaseToolProvider,
MetadataToolProvider,
LogicFunctionToolProvider,
- NavigationMenuItemToolProvider,
ViewToolProvider,
WorkflowToolProvider,
DashboardToolProvider,
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/types/tool-input-schema.type.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/types/tool-input-schema.type.ts
new file mode 100644
index 00000000000..e3c0385b1ab
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/types/tool-input-schema.type.ts
@@ -0,0 +1,6 @@
+import { type z } from 'zod';
+
+// A discriminated union lets one tool take several object variants, e.g. one per item type
+export type ToolInputSchema =
+ | z.ZodObject
+ | z.ZodDiscriminatedUnion<readonly z.ZodObject[]>;
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-tool-input-json-schema-or-throw.util.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-tool-input-json-schema-or-throw.util.ts
index bd588983250..c52fbbc489c 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-tool-input-json-schema-or-throw.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-tool-input-json-schema-or-throw.util.ts
@@ -1,13 +1,12 @@
-import { type z } from 'zod';
-
import { toToolJsonSchema } from 'src/engine/core-modules/record-crud/utils/to-tool-json-schema.util';
+import { type ToolInputSchema } from 'src/engine/core-modules/tool-provider/types/tool-input-schema.type';
export const buildToolInputJsonSchemaOrThrow = ({
toolName,
inputSchema,
}: {
toolName: string;
- inputSchema: z.ZodObject;
+ inputSchema: ToolInputSchema;
}): object => {
try {
return toToolJsonSchema(inputSchema);
diff --git a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.module.ts b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.module.ts
index 6ec1d2258e6..259f6f16978 100644
--- a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.module.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.module.ts
@@ -11,7 +11,6 @@ import { NavigationMenuItemService } from 'src/engine/metadata-modules/navigatio
import { NavigationMenuItemAccessService } from 'src/engine/metadata-modules/navigation-menu-item/services/navigation-menu-item-access.service';
import { NavigationMenuItemDeletionService } from 'src/engine/metadata-modules/navigation-menu-item/services/navigation-menu-item-deletion.service';
import { NavigationMenuItemRecordIdentifierService } from 'src/engine/metadata-modules/navigation-menu-item/services/navigation-menu-item-record-identifier.service';
-import { NavigationMenuItemToolWorkspaceService } from 'src/engine/metadata-modules/navigation-menu-item/tools/services/navigation-menu-item-tool.workspace-service';
import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permissions.module';
import { WorkspaceMigrationModule } from 'src/engine/workspace-manager/workspace-migration/workspace-migration.module';
import { ApplicationTranslationCatalogModule } from 'src/engine/metadata-modules/application-translation-catalog/application-translation-catalog.module';
@@ -34,11 +33,10 @@ import { ApplicationTranslationCatalogModule } from 'src/engine/metadata-modules
NavigationMenuItemDeletionJob,
NavigationMenuItemResolver,
NavigationMenuItemRecordIdentifierService,
- NavigationMenuItemToolWorkspaceService,
],
exports: [
+ NavigationMenuItemService,
NavigationMenuItemRecordIdentifierService,
- NavigationMenuItemToolWorkspaceService,
],
})
export class NavigationMenuItemModule {}
diff --git a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/create-navigation-menu-item.tool.ts b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/create-navigation-menu-item.tool.ts
index 4cb7d9c9440..d112a963cc3 100644
--- a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/create-navigation-menu-item.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/create-navigation-menu-item.tool.ts
@@ -1,11 +1,14 @@
-import { z } from 'zod';
-
+import { ToolCategory } from 'twenty-shared/ai';
import { NavigationMenuItemType } from 'twenty-shared/types';
+import { z } from 'zod';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
import { type CreateNavigationMenuItemInput } from 'src/engine/metadata-modules/navigation-menu-item/dtos/create-navigation-menu-item.input';
+import { NavigationMenuItemService } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.service';
import { navigationMenuItemScopeSchema } from 'src/engine/metadata-modules/navigation-menu-item/tools/schemas/navigation-menu-item-scope.schema';
-import { type NavigationMenuItemToolContext } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-context.type';
-import { type NavigationMenuItemToolDependencies } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-dependencies.type';
const commonOptionalFields = {
icon: z
@@ -38,7 +41,7 @@ const derivedNameField = z
"Optional custom label. If omitted, the sidebar shows the target's own name (object's plural label / view name / record identifier). Only pass this if the user explicitly wants a different label.",
);
-const createNavigationMenuItemSchema = z.discriminatedUnion('type', [
+const createNavigationMenuItemInputSchema = z.discriminatedUnion('type', [
z.object({
type: z.literal(NavigationMenuItemType.FOLDER),
scope: navigationMenuItemScopeSchema,
@@ -90,7 +93,7 @@ const createNavigationMenuItemSchema = z.discriminatedUnion('type', [
]);
type CreateNavigationMenuItemParams = z.infer<
- typeof createNavigationMenuItemSchema
+ typeof createNavigationMenuItemInputSchema
>;
const toServiceInput = (
@@ -137,11 +140,10 @@ const toServiceInput = (
}
};
-export const createCreateNavigationMenuItemTool = (
- deps: Pick<NavigationMenuItemToolDependencies, 'navigationMenuItemService'>,
- context: NavigationMenuItemToolContext,
-) => ({
- name: 'create_navigation_menu_item' as const,
+@DefineTool({
+ name: 'create_navigation_menu_item',
+ category: ToolCategory.NAVIGATION_MENU_ITEM,
+ requiredPermissionFlags: [],
description: `Create a navigation menu item. With scope='user' it becomes a personal favorite for the current user; with scope='workspace' it is shared with everyone (requires LAYOUTS permission).
Type chooses the variant:
@@ -153,10 +155,24 @@ Type chooses the variant:
- PAGE_LAYOUT: pins a standalone page layout (name required — no auto-derivation). The referenced page layout must be of type STANDALONE_PAGE; dashboards and record/index page layouts are not reachable this way.
Note: creating a new custom object via create_object_metadata already auto-creates an OBJECT navigation menu item — do not double-create.`,
- inputSchema: createNavigationMenuItemSchema,
- execute: async (parameters: CreateNavigationMenuItemParams) => {
+})
+export class CreateNavigationMenuItemTool extends BaseTool<
+ typeof createNavigationMenuItemInputSchema
+> {
+ readonly inputSchema = createNavigationMenuItemInputSchema;
+
+ constructor(
+ private readonly navigationMenuItemService: NavigationMenuItemService,
+ ) {
+ super();
+ }
+
+ async execute(
+ parameters: CreateNavigationMenuItemParams,
+ { workspaceId, userWorkspaceId, application, agentId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
try {
- if (parameters.scope === 'user' && !context.userWorkspaceId) {
+ if (parameters.scope === 'user' && !userWorkspaceId) {
return {
success: false,
message:
@@ -165,12 +181,12 @@ Note: creating a new custom object via create_object_metadata already auto-creat
};
}
- const created = await deps.navigationMenuItemService.create({
- input: toServiceInput(parameters, context.userWorkspaceId),
- workspaceId: context.workspaceId,
- authUserWorkspaceId: context.userWorkspaceId,
- authApplicationId: context.applicationId,
- authAgentId: context.agentId,
+ const created = await this.navigationMenuItemService.create({
+ input: toServiceInput(parameters, userWorkspaceId),
+ workspaceId,
+ authUserWorkspaceId: userWorkspaceId,
+ authApplicationId: application?.id,
+ authAgentId: agentId,
});
return {
@@ -194,5 +210,5 @@ Note: creating a new custom object via create_object_metadata already auto-creat
error: message,
};
}
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/delete-navigation-menu-item.tool.ts b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/delete-navigation-menu-item.tool.ts
index f57bdc88e6a..a539837155e 100644
--- a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/delete-navigation-menu-item.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/delete-navigation-menu-item.tool.ts
@@ -1,31 +1,44 @@
+import { ToolCategory } from 'twenty-shared/ai';
import { z } from 'zod';
-import { type NavigationMenuItemToolContext } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-context.type';
-import { type NavigationMenuItemToolDependencies } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-dependencies.type';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { NavigationMenuItemService } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.service';
-const deleteNavigationMenuItemSchema = z.object({
+const deleteNavigationMenuItemInputSchema = z.object({
id: z.uuid().describe('Id of the navigation menu item to delete'),
});
-type DeleteNavigationMenuItemParams = z.infer<
- typeof deleteNavigationMenuItemSchema
->;
-
-export const createDeleteNavigationMenuItemTool = (
- deps: Pick<NavigationMenuItemToolDependencies, 'navigationMenuItemService'>,
- context: NavigationMenuItemToolContext,
-) => ({
- name: 'delete_navigation_menu_item' as const,
+@DefineTool({
+ name: 'delete_navigation_menu_item',
+ category: ToolCategory.NAVIGATION_MENU_ITEM,
+ requiredPermissionFlags: [],
description: `Delete a navigation menu item. Deleting a folder also deletes everything inside it.`,
- inputSchema: deleteNavigationMenuItemSchema,
- execute: async (parameters: DeleteNavigationMenuItemParams) => {
+})
+export class DeleteNavigationMenuItemTool extends BaseTool<
+ typeof deleteNavigationMenuItemInputSchema
+> {
+ readonly inputSchema = deleteNavigationMenuItemInputSchema;
+
+ constructor(
+ private readonly navigationMenuItemService: NavigationMenuItemService,
+ ) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof deleteNavigationMenuItemInputSchema>,
+ { workspaceId, userWorkspaceId, application, agentId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
try {
- const deleted = await deps.navigationMenuItemService.delete({
+ const deleted = await this.navigationMenuItemService.delete({
id: parameters.id,
- workspaceId: context.workspaceId,
- authUserWorkspaceId: context.userWorkspaceId,
- authApplicationId: context.applicationId,
- authAgentId: context.agentId,
+ workspaceId,
+ authUserWorkspaceId: userWorkspaceId,
+ authApplicationId: application?.id,
+ authAgentId: agentId,
});
return {
@@ -46,5 +59,5 @@ export const createDeleteNavigationMenuItemTool = (
error: message,
};
}
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/list-navigation-menu-items.tool.ts b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/list-navigation-menu-items.tool.ts
index 39f1397ebd4..fbf8139299f 100644
--- a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/list-navigation-menu-items.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/list-navigation-menu-items.tool.ts
@@ -1,13 +1,16 @@
-import { z } from 'zod';
-
+import { ToolCategory } from 'twenty-shared/ai';
import { NavigationMenuItemType } from 'twenty-shared/types';
import { isDefined } from 'twenty-shared/utils';
+import { z } from 'zod';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { NavigationMenuItemService } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.service';
import { navigationMenuItemTypeSchema } from 'src/engine/metadata-modules/navigation-menu-item/tools/schemas/navigation-menu-item-type.schema';
-import { type NavigationMenuItemToolContext } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-context.type';
-import { type NavigationMenuItemToolDependencies } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-dependencies.type';
-const listNavigationMenuItemsSchema = z.object({
+const listNavigationMenuItemsInputSchema = z.object({
scope: z
.enum(['workspace', 'user', 'all'])
.optional()
@@ -34,22 +37,31 @@ const listNavigationMenuItemsSchema = z.object({
.describe('Max number of items to return.'),
});
-type ListNavigationMenuItemsParams = z.infer<
- typeof listNavigationMenuItemsSchema
->;
-
-export const createListNavigationMenuItemsTool = (
- deps: Pick<NavigationMenuItemToolDependencies, 'navigationMenuItemService'>,
- context: NavigationMenuItemToolContext,
-) => ({
- name: 'list_navigation_menu_items' as const,
+@DefineTool({
+ name: 'list_navigation_menu_items',
+ category: ToolCategory.NAVIGATION_MENU_ITEM,
+ requiredPermissionFlags: [],
description: `List navigation menu items (shared workspace navigation and/or the current user's personal favorites). Returns items sorted by position.`,
- inputSchema: listNavigationMenuItemsSchema,
- execute: async (parameters: ListNavigationMenuItemsParams) => {
+})
+export class ListNavigationMenuItemsTool extends BaseTool<
+ typeof listNavigationMenuItemsInputSchema
+> {
+ readonly inputSchema = listNavigationMenuItemsInputSchema;
+
+ constructor(
+ private readonly navigationMenuItemService: NavigationMenuItemService,
+ ) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof listNavigationMenuItemsInputSchema>,
+ { workspaceId, userWorkspaceId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
try {
- const items = await deps.navigationMenuItemService.findAll({
- workspaceId: context.workspaceId,
- userWorkspaceId: context.userWorkspaceId,
+ const items = await this.navigationMenuItemService.findAll({
+ workspaceId,
+ userWorkspaceId,
scope: parameters.scope,
folderId: parameters.folderId,
type: parameters.type as NavigationMenuItemType | undefined,
@@ -87,5 +99,5 @@ export const createListNavigationMenuItemsTool = (
error: message,
};
}
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/navigation-menu-item-tools.module.ts b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/navigation-menu-item-tools.module.ts
new file mode 100644
index 00000000000..26fedd50c15
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/navigation-menu-item-tools.module.ts
@@ -0,0 +1,18 @@
+import { Module } from '@nestjs/common';
+
+import { NavigationMenuItemModule } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.module';
+import { CreateNavigationMenuItemTool } from 'src/engine/metadata-modules/navigation-menu-item/tools/create-navigation-menu-item.tool';
+import { DeleteNavigationMenuItemTool } from 'src/engine/metadata-modules/navigation-menu-item/tools/delete-navigation-menu-item.tool';
+import { ListNavigationMenuItemsTool } from 'src/engine/metadata-modules/navigation-menu-item/tools/list-navigation-menu-items.tool';
+import { UpdateNavigationMenuItemTool } from 'src/engine/metadata-modules/navigation-menu-item/tools/update-navigation-menu-item.tool';
+
+@Module({
+ imports: [NavigationMenuItemModule],
+ providers: [
+ ListNavigationMenuItemsTool,
+ CreateNavigationMenuItemTool,
+ UpdateNavigationMenuItemTool,
+ DeleteNavigationMenuItemTool,
+ ],
+})
+export class NavigationMenuItemToolsModule {}
diff --git a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/services/navigation-menu-item-tool.workspace-service.ts b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/services/navigation-menu-item-tool.workspace-service.ts
deleted file mode 100644
index c22f41ee7a5..00000000000
--- a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/services/navigation-menu-item-tool.workspace-service.ts
+++ /dev/null
@@ -1,48 +0,0 @@
-import { Injectable } from '@nestjs/common';
-
-import { type ToolSet } from 'ai';
-
-import { NavigationMenuItemService } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.service';
-import { createCreateNavigationMenuItemTool } from 'src/engine/metadata-modules/navigation-menu-item/tools/create-navigation-menu-item.tool';
-import { createDeleteNavigationMenuItemTool } from 'src/engine/metadata-modules/navigation-menu-item/tools/delete-navigation-menu-item.tool';
-import { createListNavigationMenuItemsTool } from 'src/engine/metadata-modules/navigation-menu-item/tools/list-navigation-menu-items.tool';
-import { type NavigationMenuItemToolContext } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-context.type';
-import { type NavigationMenuItemToolDependencies } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-dependencies.type';
-import { createUpdateNavigationMenuItemTool } from 'src/engine/metadata-modules/navigation-menu-item/tools/update-navigation-menu-item.tool';
-
-@Injectable()
-export class NavigationMenuItemToolWorkspaceService {
- private readonly deps: NavigationMenuItemToolDependencies;
-
- constructor(navigationMenuItemService: NavigationMenuItemService) {
- this.deps = { navigationMenuItemService };
- }
-
- generateNavigationMenuItemTools(
- context: NavigationMenuItemToolContext,
- ): ToolSet {
- const listNavigationMenuItems = createListNavigationMenuItemsTool(
- this.deps,
- context,
- );
- const createNavigationMenuItem = createCreateNavigationMenuItemTool(
- this.deps,
- context,
- );
- const updateNavigationMenuItem = createUpdateNavigationMenuItemTool(
- this.deps,
- context,
- );
- const deleteNavigationMenuItem = createDeleteNavigationMenuItemTool(
- this.deps,
- context,
- );
-
- return {
- [listNavigationMenuItems.name]: listNavigationMenuItems,
- [createNavigationMenuItem.name]: createNavigationMenuItem,
- [updateNavigationMenuItem.name]: updateNavigationMenuItem,
- [deleteNavigationMenuItem.name]: deleteNavigationMenuItem,
- };
- }
-}
diff --git a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-context.type.ts b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-context.type.ts
deleted file mode 100644
index 089b85c7c0d..00000000000
--- a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-context.type.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-export type NavigationMenuItemToolContext = {
- workspaceId: string;
- userWorkspaceId?: string;
- applicationId?: string;
- agentId?: string;
-};
diff --git a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-dependencies.type.ts b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-dependencies.type.ts
deleted file mode 100644
index 6d14615b4f1..00000000000
--- a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-dependencies.type.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import type { NavigationMenuItemService } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.service';
-
-export type NavigationMenuItemToolDependencies = {
- navigationMenuItemService: NavigationMenuItemService;
-};
diff --git a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/update-navigation-menu-item.tool.ts b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/update-navigation-menu-item.tool.ts
index 19ee7bd4836..bb20911e342 100644
--- a/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/update-navigation-menu-item.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/navigation-menu-item/tools/update-navigation-menu-item.tool.ts
@@ -1,10 +1,14 @@
+import { ToolCategory } from 'twenty-shared/ai';
import { z } from 'zod';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
import { type UpdateNavigationMenuItemInput } from 'src/engine/metadata-modules/navigation-menu-item/dtos/update-navigation-menu-item.input';
-import { type NavigationMenuItemToolContext } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-context.type';
-import { type NavigationMenuItemToolDependencies } from 'src/engine/metadata-modules/navigation-menu-item/tools/types/navigation-menu-item-tool-dependencies.type';
+import { NavigationMenuItemService } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.service';
-const updateNavigationMenuItemSchema = z.object({
+const updateNavigationMenuItemInputSchema = z.object({
id: z.uuid().describe('Id of the navigation menu item to update'),
name: z
.string()
@@ -35,18 +39,27 @@ const updateNavigationMenuItemSchema = z.object({
.describe('New page layout id (only meaningful for PAGE_LAYOUT items)'),
});
-type UpdateNavigationMenuItemParams = z.infer<
- typeof updateNavigationMenuItemSchema
->;
-
-export const createUpdateNavigationMenuItemTool = (
- deps: Pick<NavigationMenuItemToolDependencies, 'navigationMenuItemService'>,
- context: NavigationMenuItemToolContext,
-) => ({
- name: 'update_navigation_menu_item' as const,
+@DefineTool({
+ name: 'update_navigation_menu_item',
+ category: ToolCategory.NAVIGATION_MENU_ITEM,
+ requiredPermissionFlags: [],
description: `Update a navigation menu item (rename, recolor, move between folders, reorder). Type and target ids are immutable — delete and recreate to convert one variant into another.`,
- inputSchema: updateNavigationMenuItemSchema,
- execute: async (parameters: UpdateNavigationMenuItemParams) => {
+})
+export class UpdateNavigationMenuItemTool extends BaseTool<
+ typeof updateNavigationMenuItemInputSchema
+> {
+ readonly inputSchema = updateNavigationMenuItemInputSchema;
+
+ constructor(
+ private readonly navigationMenuItemService: NavigationMenuItemService,
+ ) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof updateNavigationMenuItemInputSchema>,
+ { workspaceId, userWorkspaceId, application, agentId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
try {
const update: Partial<UpdateNavigationMenuItemInput> = {};
@@ -61,12 +74,12 @@ export const createUpdateNavigationMenuItemTool = (
if (parameters.pageLayoutId !== undefined)
update.pageLayoutId = parameters.pageLayoutId;
- const updated = await deps.navigationMenuItemService.update({
+ const updated = await this.navigationMenuItemService.update({
input: { id: parameters.id, ...update },
- workspaceId: context.workspaceId,
- authUserWorkspaceId: context.userWorkspaceId,
- authApplicationId: context.applicationId,
- authAgentId: context.agentId,
+ workspaceId,
+ authUserWorkspaceId: userWorkspaceId,
+ authApplicationId: application?.id,
+ authAgentId: agentId,
});
return {
@@ -89,5 +102,5 @@ export const createUpdateNavigationMenuItemTool = (
error: message,
};
}
- },
-});
+ }
+}
diff --git a/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-navigation-menu-item-tools.integration-spec.ts.snap b/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-navigation-menu-item-tools.integration-spec.ts.snap
new file mode 100644
index 00000000000..1acc87911dd
--- /dev/null
+++ b/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-navigation-menu-item-tools.integration-spec.ts.snap
@@ -0,0 +1,397 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`MCP navigation menu item tools (integration) should describe the navigation menu item tools to the model 1`] = `
+[
+ {
+ "description": "List navigation menu items (shared workspace navigation and/or the current user's personal favorites). Returns items sorted by position.",
+ "inputSchema": {
+ "properties": {
+ "folderId": {
+ "description": "Only return items inside this folder.",
+ "format": "uuid",
+ "type": "string",
+ },
+ "limit": {
+ "default": 100,
+ "description": "Max number of items to return.",
+ "type": "integer",
+ },
+ "scope": {
+ "default": "all",
+ "description": "'workspace' = shared navigation, 'user' = current user's favorites, 'all' = both merged (default).",
+ "enum": [
+ "workspace",
+ "user",
+ "all",
+ ],
+ "type": "string",
+ },
+ "type": {
+ "description": "Filter by item type (FOLDER, LINK, OBJECT, VIEW, RECORD, PAGE_LAYOUT).",
+ "enum": [
+ "FOLDER",
+ "LINK",
+ "OBJECT",
+ "VIEW",
+ "RECORD",
+ "PAGE_LAYOUT",
+ ],
+ "type": "string",
+ },
+ },
+ "type": "object",
+ },
+ "name": "list_navigation_menu_items",
+ },
+ {
+ "description": "Create a navigation menu item. With scope='user' it becomes a personal favorite for the current user; with scope='workspace' it is shared with everyone (requires LAYOUTS permission).
+
+Type chooses the variant:
+- FOLDER: a group to nest other items into (name required).
+- LINK: an external URL pinned in the sidebar (name + link required).
+- OBJECT: pins an object's standard view (label auto-derived from the object's plural name; only pass 'name' if the user wants a custom label).
+- VIEW: pins a saved view (label auto-derived from the view's name; only pass 'name' for a custom label).
+- RECORD: pins a single record (label auto-derived from the record's identifier; only pass 'name' for a custom label).
+- PAGE_LAYOUT: pins a standalone page layout (name required — no auto-derivation). The referenced page layout must be of type STANDALONE_PAGE; dashboards and record/index page layouts are not reachable this way.
+
+Note: creating a new custom object via create_object_metadata already auto-creates an OBJECT navigation menu item — do not double-create.",
+ "inputSchema": {
+ "$defs": {
+ "__schema0": {
+ "description": "'user' creates a personal favorite, visible only to the current user. 'workspace' creates a shared navigation menu item visible to everyone (requires the LAYOUTS permission). Twenty has no separate Favorites concept — favorites are just navigation menu items with scope=user.",
+ "enum": [
+ "workspace",
+ "user",
+ ],
+ "type": "string",
+ },
+ "__schema1": {
+ "description": "Label shown in the sidebar.",
+ "minLength": 1,
+ "type": "string",
+ },
+ "__schema2": {
+ "description": "Icon identifier (e.g. "IconStar", "IconFolder")",
+ "type": "string",
+ },
+ "__schema3": {
+ "description": "Optional hex colour",
+ "type": "string",
+ },
+ "__schema4": {
+ "description": "Position among siblings; defaults to the end.",
+ "type": "number",
+ },
+ "__schema5": {
+ "description": "Parent folder id, if the item should live inside a folder.",
+ "format": "uuid",
+ "type": "string",
+ },
+ "__schema6": {
+ "description": "Optional custom label. If omitted, the sidebar shows the target's own name (object's plural label / view name / record identifier). Only pass this if the user explicitly wants a different label.",
+ "minLength": 1,
+ "type": "string",
+ },
+ },
+ "anyOf": [
+ {
+ "properties": {
+ "color": {
+ "$ref": "#/$defs/__schema3",
+ },
+ "folderId": {
+ "$ref": "#/$defs/__schema5",
+ },
+ "icon": {
+ "$ref": "#/$defs/__schema2",
+ },
+ "name": {
+ "$ref": "#/$defs/__schema1",
+ },
+ "position": {
+ "$ref": "#/$defs/__schema4",
+ },
+ "scope": {
+ "$ref": "#/$defs/__schema0",
+ },
+ "type": {
+ "const": "FOLDER",
+ "type": "string",
+ },
+ },
+ "required": [
+ "type",
+ "scope",
+ "name",
+ ],
+ "type": "object",
+ },
+ {
+ "properties": {
+ "color": {
+ "$ref": "#/$defs/__schema3",
+ },
+ "folderId": {
+ "$ref": "#/$defs/__schema5",
+ },
+ "icon": {
+ "$ref": "#/$defs/__schema2",
+ },
+ "link": {
+ "description": "Target URL",
+ "format": "uri",
+ "type": "string",
+ },
+ "name": {
+ "$ref": "#/$defs/__schema1",
+ },
+ "position": {
+ "$ref": "#/$defs/__schema4",
+ },
+ "scope": {
+ "$ref": "#/$defs/__schema0",
+ },
+ "type": {
+ "const": "LINK",
+ "type": "string",
+ },
+ },
+ "required": [
+ "type",
+ "scope",
+ "name",
+ "link",
+ ],
+ "type": "object",
+ },
+ {
+ "properties": {
+ "color": {
+ "$ref": "#/$defs/__schema3",
+ },
+ "folderId": {
+ "$ref": "#/$defs/__schema5",
+ },
+ "icon": {
+ "$ref": "#/$defs/__schema2",
+ },
+ "name": {
+ "$ref": "#/$defs/__schema6",
+ },
+ "position": {
+ "$ref": "#/$defs/__schema4",
+ },
+ "scope": {
+ "$ref": "#/$defs/__schema0",
+ },
+ "targetObjectMetadataId": {
+ "description": "Id of the object to pin",
+ "format": "uuid",
+ "type": "string",
+ },
+ "type": {
+ "const": "OBJECT",
+ "type": "string",
+ },
+ },
+ "required": [
+ "type",
+ "scope",
+ "targetObjectMetadataId",
+ ],
+ "type": "object",
+ },
+ {
+ "properties": {
+ "color": {
+ "$ref": "#/$defs/__schema3",
+ },
+ "folderId": {
+ "$ref": "#/$defs/__schema5",
+ },
+ "icon": {
+ "$ref": "#/$defs/__schema2",
+ },
+ "name": {
+ "$ref": "#/$defs/__schema6",
+ },
+ "position": {
+ "$ref": "#/$defs/__schema4",
+ },
+ "scope": {
+ "$ref": "#/$defs/__schema0",
+ },
+ "type": {
+ "const": "VIEW",
+ "type": "string",
+ },
+ "viewId": {
+ "description": "Id of the view to pin",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "type",
+ "scope",
+ "viewId",
+ ],
+ "type": "object",
+ },
+ {
+ "properties": {
+ "color": {
+ "$ref": "#/$defs/__schema3",
+ },
+ "folderId": {
+ "$ref": "#/$defs/__schema5",
+ },
+ "icon": {
+ "$ref": "#/$defs/__schema2",
+ },
+ "name": {
+ "$ref": "#/$defs/__schema6",
+ },
+ "position": {
+ "$ref": "#/$defs/__schema4",
+ },
+ "scope": {
+ "$ref": "#/$defs/__schema0",
+ },
+ "targetObjectMetadataId": {
+ "description": "Id of the record's object metadata",
+ "format": "uuid",
+ "type": "string",
+ },
+ "targetRecordId": {
+ "description": "Id of the record to pin",
+ "format": "uuid",
+ "type": "string",
+ },
+ "type": {
+ "const": "RECORD",
+ "type": "string",
+ },
+ },
+ "required": [
+ "type",
+ "scope",
+ "targetRecordId",
+ "targetObjectMetadataId",
+ ],
+ "type": "object",
+ },
+ {
+ "properties": {
+ "color": {
+ "$ref": "#/$defs/__schema3",
+ },
+ "folderId": {
+ "$ref": "#/$defs/__schema5",
+ },
+ "icon": {
+ "$ref": "#/$defs/__schema2",
+ },
+ "name": {
+ "$ref": "#/$defs/__schema1",
+ },
+ "pageLayoutId": {
+ "description": "Id of the page layout to pin",
+ "type": "string",
+ },
+ "position": {
+ "$ref": "#/$defs/__schema4",
+ },
+ "scope": {
+ "$ref": "#/$defs/__schema0",
+ },
+ "type": {
+ "const": "PAGE_LAYOUT",
+ "type": "string",
+ },
+ },
+ "required": [
+ "type",
+ "scope",
+ "pageLayoutId",
+ "name",
+ ],
+ "type": "object",
+ },
+ ],
+ },
+ "name": "create_navigation_menu_item",
+ },
+ {
+ "description": "Update a navigation menu item (rename, recolor, move between folders, reorder). Type and target ids are immutable — delete and recreate to convert one variant into another.",
+ "inputSchema": {
+ "properties": {
+ "color": {
+ "description": "New hex colour",
+ "type": "string",
+ },
+ "folderId": {
+ "anyOf": [
+ {
+ "type": "string",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "Move into a different folder. Pass null to move to the top level.",
+ },
+ "icon": {
+ "description": "New icon identifier",
+ "type": "string",
+ },
+ "id": {
+ "description": "Id of the navigation menu item to update",
+ "format": "uuid",
+ "type": "string",
+ },
+ "link": {
+ "description": "New URL (only meaningful for LINK items)",
+ "format": "uri",
+ "type": "string",
+ },
+ "name": {
+ "description": "New display name. For OBJECT/VIEW/RECORD items the sidebar normally shows the target entity's own name — only set this if the user wants a custom label.",
+ "minLength": 1,
+ "type": "string",
+ },
+ "pageLayoutId": {
+ "description": "New page layout id (only meaningful for PAGE_LAYOUT items)",
+ "type": "string",
+ },
+ "position": {
+ "description": "New position among siblings",
+ "type": "number",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "name": "update_navigation_menu_item",
+ },
+ {
+ "description": "Delete a navigation menu item. Deleting a folder also deletes everything inside it.",
+ "inputSchema": {
+ "properties": {
+ "id": {
+ "description": "Id of the navigation menu item to delete",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "name": "delete_navigation_menu_item",
+ },
+]
+`;
diff --git a/packages/twenty-server/test/integration/ai/suites/mcp-navigation-menu-item-tools.integration-spec.ts b/packages/twenty-server/test/integration/ai/suites/mcp-navigation-menu-item-tools.integration-spec.ts
new file mode 100644
index 00000000000..e11911749ae
--- /dev/null
+++ b/packages/twenty-server/test/integration/ai/suites/mcp-navigation-menu-item-tools.integration-spec.ts
@@ -0,0 +1,221 @@
+import { executeToolThroughMcp } from 'test/integration/ai/utils/execute-tool-through-mcp.util';
+import { callMcpTool } from 'test/integration/graphql/suites/application-role-intersection/utils/call-mcp-tool.util';
+import { jestExpectToBeDefined } from 'test/utils/jest-expect-to-be-defined.util.test';
+
+const NAVIGATION_MENU_ITEM_TOOL_NAMES = [
+ 'list_navigation_menu_items',
+ 'create_navigation_menu_item',
+ 'update_navigation_menu_item',
+ 'delete_navigation_menu_item',
+];
+
+const ITEM_NAME_PREFIX = 'MCP navigation tools';
+
+type NavigationMenuItemSummary = {
+ id: string;
+ name: string | null;
+ scope: 'user' | 'workspace';
+ folderId: string | null;
+};
+
+const listItemsThroughMcp = async ({
+ token,
+ folderId,
+}: {
+ token: string;
+ folderId?: string;
+}): Promise<NavigationMenuItemSummary[]> => {
+ const output = await executeToolThroughMcp<{
+ items: NavigationMenuItemSummary[];
+ }>({
+ toolName: 'list_navigation_menu_items',
+ toolArguments: { folderId },
+ token,
+ });
+
+ expect(output.success).toBe(true);
+
+ return output.result?.items ?? [];
+};
+
+const createItemThroughMcp = (
+ token: string,
+ toolArguments: Record<string, unknown>,
+) =>
+ executeToolThroughMcp<NavigationMenuItemSummary>({
+ toolName: 'create_navigation_menu_item',
+ toolArguments,
+ token,
+ });
+
+const deleteItemThroughMcp = (token: string, id: string) =>
+ executeToolThroughMcp({
+ toolName: 'delete_navigation_menu_item',
+ toolArguments: { id },
+ token,
+ });
+
+describe('MCP navigation menu item tools (integration)', () => {
+ afterAll(async () => {
+ for (const token of [
+ APPLE_JANE_ADMIN_ACCESS_TOKEN,
+ APPLE_JONY_MEMBER_ACCESS_TOKEN,
+ ]) {
+ const leakedItems = (await listItemsThroughMcp({ token })).filter(
+ ({ name }) => name?.startsWith(ITEM_NAME_PREFIX),
+ );
+
+ for (const { id } of leakedItems) {
+ await deleteItemThroughMcp(token, id);
+ }
+ }
+ });
+
+ it('should describe the navigation menu item tools to the model', async () => {
+ const result = await callMcpTool({
+ toolName: 'learn_tools',
+ toolArguments: { toolNames: NAVIGATION_MENU_ITEM_TOOL_NAMES },
+ token: API_KEY_ACCESS_TOKEN,
+ });
+
+ expect(result.isError).toBe(false);
+
+ const payload = JSON.parse(result.content[0].text);
+
+ expect(payload.notFound).toEqual([]);
+ expect(payload.tools).toMatchSnapshot();
+ });
+
+ it('should create, move and delete workspace items', async () => {
+ const folder = await createItemThroughMcp(APPLE_JANE_ADMIN_ACCESS_TOKEN, {
+ type: 'FOLDER',
+ scope: 'workspace',
+ name: `${ITEM_NAME_PREFIX} folder`,
+ });
+
+ expect(folder).toMatchObject({
+ success: true,
+ result: { name: `${ITEM_NAME_PREFIX} folder`, scope: 'workspace' },
+ });
+
+ const folderId = folder.result?.id;
+
+ jestExpectToBeDefined(folderId);
+
+ const link = await createItemThroughMcp(APPLE_JANE_ADMIN_ACCESS_TOKEN, {
+ type: 'LINK',
+ scope: 'workspace',
+ name: `${ITEM_NAME_PREFIX} link`,
+ link: 'https://twenty.com',
+ folderId,
+ });
+
+ expect(link).toMatchObject({
+ success: true,
+ result: { name: `${ITEM_NAME_PREFIX} link`, folderId },
+ });
+
+ const linkId = link.result?.id;
+
+ jestExpectToBeDefined(linkId);
+ expect(
+ (
+ await listItemsThroughMcp({
+ token: APPLE_JANE_ADMIN_ACCESS_TOKEN,
+ folderId,
+ })
+ ).map(({ id }) => id),
+ ).toEqual([linkId]);
+
+ const moved = await executeToolThroughMcp({
+ toolName: 'update_navigation_menu_item',
+ toolArguments: {
+ id: linkId,
+ name: `${ITEM_NAME_PREFIX} moved link`,
+ folderId: null,
+ },
+ token: APPLE_JANE_ADMIN_ACCESS_TOKEN,
+ });
+
+ expect(moved).toMatchObject({
+ success: true,
+ message: `Navigation menu item ${linkId} updated`,
+ result: { id: linkId, name: `${ITEM_NAME_PREFIX} moved link` },
+ });
+
+ for (const id of [linkId, folderId]) {
+ expect(
+ await deleteItemThroughMcp(APPLE_JANE_ADMIN_ACCESS_TOKEN, id),
+ ).toMatchObject({
+ success: true,
+ message: `Navigation menu item ${id} deleted`,
+ });
+ }
+
+ const remainingIds = (
+ await listItemsThroughMcp({ token: APPLE_JANE_ADMIN_ACCESS_TOKEN })
+ ).map(({ id }) => id);
+
+ expect(remainingIds).not.toContain(linkId);
+ expect(remainingIds).not.toContain(folderId);
+ });
+
+ it('should refuse a personal favorite to a caller without a user', async () => {
+ const output = await createItemThroughMcp(API_KEY_ACCESS_TOKEN, {
+ type: 'FOLDER',
+ scope: 'user',
+ name: `${ITEM_NAME_PREFIX} api key favorite`,
+ });
+
+ expect(output).toEqual({
+ success: false,
+ message:
+ 'Cannot create a user-scoped favorite without an authenticated user context.',
+ error: 'missing_user_workspace_id',
+ });
+ });
+
+ // The seeded member role holds no settings flag, so it lacks LAYOUTS
+ describe('for a member without LAYOUTS', () => {
+ it('should create and delete a personal favorite', async () => {
+ const favorite = await createItemThroughMcp(
+ APPLE_JONY_MEMBER_ACCESS_TOKEN,
+ {
+ type: 'FOLDER',
+ scope: 'user',
+ name: `${ITEM_NAME_PREFIX} member favorite`,
+ },
+ );
+
+ expect(favorite).toMatchObject({
+ success: true,
+ result: { scope: 'user' },
+ });
+
+ const favoriteId = favorite.result?.id;
+
+ jestExpectToBeDefined(favoriteId);
+ expect(
+ await deleteItemThroughMcp(APPLE_JONY_MEMBER_ACCESS_TOKEN, favoriteId),
+ ).toMatchObject({ success: true });
+ });
+
+ it('should refuse a workspace item', async () => {
+ const output = await createItemThroughMcp(
+ APPLE_JONY_MEMBER_ACCESS_TOKEN,
+ {
+ type: 'FOLDER',
+ scope: 'workspace',
+ name: `${ITEM_NAME_PREFIX} member workspace folder`,
+ },
+ );
+
+ expect(output).toMatchObject({
+ success: false,
+ message: expect.stringMatching(
+ /^Failed to create navigation menu item: /,
+ ),
+ });
+ });
+ });
+});
diff --git a/packages/twenty-server/test/integration/ai/utils/execute-tool-through-mcp.util.ts b/packages/twenty-server/test/integration/ai/utils/execute-tool-through-mcp.util.ts
index e6c7800cbb7..0c6ad706074 100644
--- a/packages/twenty-server/test/integration/ai/utils/execute-tool-through-mcp.util.ts
+++ b/packages/twenty-server/test/integration/ai/utils/execute-tool-through-mcp.util.ts
@@ -8,13 +8,15 @@ import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.
export const executeToolThroughMcp = async <TResult = object>({
toolName,
toolArguments,
+ token = API_KEY_ACCESS_TOKEN,
}: {
toolName: string;
toolArguments: Record<string, unknown>;
+ token?: string;
}): Promise<ToolOutput<TResult>> => {
const response = await request(`http://localhost:${APP_PORT}`)
.post('/mcp')
- .set('Authorization', `Bearer ${API_KEY_ACCESS_TOKEN}`)
+ .set('Authorization', `Bearer ${token}`)
.set('Content-Type', 'application/json')
.set('Accept', 'application/json')
.send(