The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Add MCP tool annotations (#20672)
Thomas des Francsd5e65c563e2b
diff --git a/packages/twenty-server/src/engine/api/mcp/constants/mcp-closed-world-read-only-tool-annotations.const.ts b/packages/twenty-server/src/engine/api/mcp/constants/mcp-closed-world-read-only-tool-annotations.const.tsnew file mode 100644index 00000000000..0471a8ab7cb--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/constants/mcp-closed-world-read-only-tool-annotations.const.ts@@ -0,0 +1,7 @@+import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';++export const MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS: McpToolAnnotations = {+ readOnlyHint: true,+ openWorldHint: false,+ destructiveHint: false,+};diff --git a/packages/twenty-server/src/engine/api/mcp/constants/mcp-execute-tool-annotations.const.ts b/packages/twenty-server/src/engine/api/mcp/constants/mcp-execute-tool-annotations.const.tsnew file mode 100644index 00000000000..6a6fb577a28--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/constants/mcp-execute-tool-annotations.const.ts@@ -0,0 +1,7 @@+import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';++export const MCP_EXECUTE_TOOL_ANNOTATIONS: McpToolAnnotations = {+ readOnlyHint: false,+ openWorldHint: true,+ destructiveHint: true,+};diff --git a/packages/twenty-server/src/engine/api/mcp/constants/mcp-open-world-read-only-tool-annotations.const.ts b/packages/twenty-server/src/engine/api/mcp/constants/mcp-open-world-read-only-tool-annotations.const.tsnew file mode 100644index 00000000000..47de680fe43--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/constants/mcp-open-world-read-only-tool-annotations.const.ts@@ -0,0 +1,7 @@+import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';++export const MCP_OPEN_WORLD_READ_ONLY_TOOL_ANNOTATIONS: McpToolAnnotations = {+ readOnlyHint: true,+ openWorldHint: true,+ destructiveHint: false,+};diff --git a/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-protocol.service.spec.ts b/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-protocol.service.spec.tsindex fc2e9c41991..b0d9fe8f5b4 100644--- a/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-protocol.service.spec.ts+++ b/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-protocol.service.spec.ts@@ -2,12 +2,16 @@ import { HttpException, HttpStatus } from '@nestjs/common';import { Test, type TestingModule } from '@nestjs/testing';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';+import { MCP_EXECUTE_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-execute-tool-annotations.const';+import { MCP_OPEN_WORLD_READ_ONLY_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-open-world-read-only-tool-annotations.const';import { MCP_PROTOCOL_VERSION } from 'src/engine/api/mcp/constants/mcp-protocol-version.const';import { MCP_SERVER_INFO } from 'src/engine/api/mcp/constants/mcp-server-info.const';import { MCP_SERVER_INSTRUCTIONS } from 'src/engine/api/mcp/constants/mcp-server-instructions.const';import { type JsonRpc } from 'src/engine/api/mcp/dtos/json-rpc';import { McpProtocolService } from 'src/engine/api/mcp/services/mcp-protocol.service';import { McpToolExecutorService } from 'src/engine/api/mcp/services/mcp-tool-executor.service';+import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';import { type FlatApiKey } from 'src/engine/core-modules/api-key/types/flat-api-key.type';import { ApiKeyRoleService } from 'src/engine/core-modules/api-key/services/api-key-role.service';import { EXECUTE_TOOL_TOOL_NAME } from 'src/engine/core-modules/tool-provider/tools/execute-tool.tool';@@ -41,7 +45,18 @@ describe('McpProtocolService', () => {EXECUTE_TOOL_TOOL_NAME,LOAD_SKILL_TOOL_NAME,'search_help_center',- ];+ ] as const;++ const EXPECTED_MCP_TOOL_ANNOTATIONS: Record<+ (typeof EXPECTED_MCP_TOOL_NAMES)[number],+ McpToolAnnotations+ > = {+ [GET_TOOL_CATALOG_TOOL_NAME]: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,+ [LEARN_TOOLS_TOOL_NAME]: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,+ [EXECUTE_TOOL_TOOL_NAME]: MCP_EXECUTE_TOOL_ANNOTATIONS,+ [LOAD_SKILL_TOOL_NAME]: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,+ search_help_center: MCP_OPEN_WORLD_READ_ONLY_TOOL_ANNOTATIONS,+ };beforeEach(async () => {const mockSearchHelpCenterTool = {@@ -255,6 +270,7 @@ describe('McpProtocolService', () => {name,expect.objectContaining({description: expect.any(String),+ annotations: EXPECTED_MCP_TOOL_ANNOTATIONS[name],execute: expect.any(Function),}),]),@@ -294,6 +310,7 @@ describe('McpProtocolService', () => {name,expect.objectContaining({description: expect.any(String),+ annotations: EXPECTED_MCP_TOOL_ANNOTATIONS[name],}),]),),diff --git a/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-tool-executor.service.spec.ts b/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-tool-executor.service.spec.tsindex ef6a13a3922..a05e1e9c1ef 100644--- a/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-tool-executor.service.spec.ts+++ b/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-tool-executor.service.spec.ts@@ -1,4 +1,5 @@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';import {MCP_PROGRESS_NOTIFICATION_METHOD,TOOL_CALL_PROGRESS_TOKEN_PREFIX,@@ -24,6 +25,7 @@ describe('McpToolExecutorService', () => {required: ['query'],},},+ annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,},} as any;@@ -42,6 +44,7 @@ describe('McpToolExecutorService', () => {properties: { query: { type: 'string' } },required: ['query'],},+ annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,},],},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.tsindex e2f958a4a00..b43c2b8251d 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@@ -4,12 +4,16 @@ import { type ToolSet, zodSchema } from 'ai';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';import { MCP_EXCLUDED_TOOL_NAMES } from 'src/engine/api/mcp/constants/mcp-excluded-tool-names.const';+import { MCP_EXECUTE_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-execute-tool-annotations.const';+import { MCP_OPEN_WORLD_READ_ONLY_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-open-world-read-only-tool-annotations.const';import { MCP_PROTOCOL_VERSION } from 'src/engine/api/mcp/constants/mcp-protocol-version.const';import { MCP_SERVER_INFO } from 'src/engine/api/mcp/constants/mcp-server-info.const';import { MCP_SERVER_INSTRUCTIONS } from 'src/engine/api/mcp/constants/mcp-server-instructions.const';import { type JsonRpc } from 'src/engine/api/mcp/dtos/json-rpc';import { McpToolExecutorService } from 'src/engine/api/mcp/services/mcp-tool-executor.service';+import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';import { wrapJsonRpcResponse } from 'src/engine/api/mcp/utils/wrap-jsonrpc-response.util';import { type FlatApiKey } from 'src/engine/core-modules/api-key/types/flat-api-key.type';import { ApiKeyRoleService } from 'src/engine/core-modules/api-key/services/api-key-role.service';@@ -41,6 +45,33 @@ import { type FlatWorkspace } from 'src/engine/core-modules/workspace/types/flatimport { SkillService } from 'src/engine/metadata-modules/skill/skill.service';import { UserRoleService } from 'src/engine/metadata-modules/user-role/user-role.service';+type McpAnnotatedTool = ToolSet[string] & {+ annotations: McpToolAnnotations;+};++const MCP_PRELOADED_TOOL_ANNOTATIONS: Record<string, McpToolAnnotations> = {+ search_help_center: MCP_OPEN_WORLD_READ_ONLY_TOOL_ANNOTATIONS,+};++const annotatePreloadedMcpTools = (toolSet: ToolSet): ToolSet =>+ Object.fromEntries(+ Object.entries(toolSet).map(([name, toolDefinition]) => {+ const annotations = MCP_PRELOADED_TOOL_ANNOTATIONS[name];++ if (!isDefined(annotations)) {+ throw new Error(`Missing MCP annotations for preloaded tool "${name}"`);+ }++ return [+ name,+ {+ ...toolDefinition,+ annotations,+ } as McpAnnotatedTool,+ ];+ }),+ );+@Injectable()export class McpProtocolService {constructor(@@ -121,7 +152,7 @@ export class McpProtocolService {);return {- ...preloadedTools,+ ...annotatePreloadedMcpTools(preloadedTools),[GET_TOOL_CATALOG_TOOL_NAME]: {...createGetToolCatalogTool(this.toolRegistry, workspace.id, roleId, {userId: options?.userId,@@ -129,7 +160,8 @@ export class McpProtocolService {excludeTools: MCP_EXCLUDED_TOOL_NAMES,}),inputSchema: zodSchema(getToolCatalogInputSchema),- },+ annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,+ } as McpAnnotatedTool,[LEARN_TOOLS_TOOL_NAME]: {...createLearnToolsTool(this.toolRegistry,@@ -137,13 +169,15 @@ export class McpProtocolService {MCP_EXCLUDED_TOOL_NAMES,),inputSchema: zodSchema(learnToolsInputSchema),- },+ annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,+ } as McpAnnotatedTool,[EXECUTE_TOOL_TOOL_NAME]: {...createExecuteToolTool(this.toolRegistry, toolContext, {excludeTools: MCP_EXCLUDED_TOOL_NAMES,}),inputSchema: executeToolInputSchema,- },+ annotations: MCP_EXECUTE_TOOL_ANNOTATIONS,+ } as McpAnnotatedTool,[LOAD_SKILL_TOOL_NAME]: {...createLoadSkillTool((names) =>@@ -157,7 +191,8 @@ export class McpProtocolService {},),inputSchema: zodSchema(loadSkillInputSchema),- },+ annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,+ } as McpAnnotatedTool,};}diff --git a/packages/twenty-server/src/engine/api/mcp/services/mcp-tool-executor.service.ts b/packages/twenty-server/src/engine/api/mcp/services/mcp-tool-executor.service.tsindex 59e3ce52eb1..0078b47b655 100644--- a/packages/twenty-server/src/engine/api/mcp/services/mcp-tool-executor.service.ts+++ b/packages/twenty-server/src/engine/api/mcp/services/mcp-tool-executor.service.ts@@ -8,8 +8,18 @@ import {MCP_PROGRESS_NOTIFICATION_METHOD,TOOL_CALL_PROGRESS_TOKEN_PREFIX,} from 'src/engine/api/mcp/constants/mcp-progress-notification.const';+import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';import { wrapJsonRpcResponse } from 'src/engine/api/mcp/utils/wrap-jsonrpc-response.util';+type McpToolDefinition = ToolSet[string] & {+ annotations?: McpToolAnnotations;+};++const unwrapJsonSchema = (schema: unknown) =>+ schema && typeof schema === 'object' && 'jsonSchema' in schema+ ? schema.jsonSchema+ : schema;+@Injectable()export class McpToolExecutorService {async handleToolCall(@@ -76,20 +86,18 @@ export class McpToolExecutorService {const toolsArray = Object.entries(toolSet).filter(([, def]) => !!def.inputSchema).map(([name, def]) => {+ const toolDefinition = def as McpToolDefinition;// Unwrap the AI SDK's jsonSchema wrapper if present// The AI SDK serializes schemas as { jsonSchema: {...} } but MCP expects {...} directly- const inputSchema = def.inputSchema;- const unwrappedSchema =- inputSchema &&- typeof inputSchema === 'object' &&- 'jsonSchema' in inputSchema- ? inputSchema.jsonSchema- : inputSchema;+ const inputSchema = unwrapJsonSchema(toolDefinition.inputSchema);return {name,- description: def.description,- inputSchema: unwrappedSchema,+ description: toolDefinition.description,+ inputSchema,+ ...(isDefined(toolDefinition.annotations) && {+ annotations: toolDefinition.annotations,+ }),};});diff --git a/packages/twenty-server/src/engine/api/mcp/types/mcp-tool-annotations.type.ts b/packages/twenty-server/src/engine/api/mcp/types/mcp-tool-annotations.type.tsnew file mode 100644index 00000000000..80c8751307c--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/types/mcp-tool-annotations.type.ts@@ -0,0 +1,5 @@+export type McpToolAnnotations = {+ readOnlyHint: boolean;+ openWorldHint: boolean;+ destructiveHint: boolean;+};