The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Type the MCP tool set and validate tools/call params (#28187)
Paul Rastoin24744e2d9cd8
diff --git a/packages/twenty-server/src/engine/api/mcp/dtos/json-rpc.ts b/packages/twenty-server/src/engine/api/mcp/dtos/json-rpc.tsindex 99ed0102da7..34f9cadc560 100644--- a/packages/twenty-server/src/engine/api/mcp/dtos/json-rpc.ts+++ b/packages/twenty-server/src/engine/api/mcp/dtos/json-rpc.ts@@ -22,10 +22,7 @@ export class JsonRpc {@IsOptional()@IsObject()- params?: {- name: string;- arguments: unknown;- };+ params?: Record<string, unknown>;@IsOptional()@Validate(IsNumberOrString)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 9bc127028ca..8f9bcb2ce5f 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,7 @@import { HttpException, HttpStatus, Injectable } from '@nestjs/common';import * as Sentry from '@sentry/node';-import { isNonEmptyString } from '@sniptt/guards';-import { type ToolSet, zodSchema } from 'ai';+import { type ToolSet } from 'ai';import { type ActorMetadata, FieldActorSource } from 'twenty-shared/types';import { isDefined } from 'twenty-shared/utils';@@ -19,16 +18,17 @@ import { McpToolExecutorService } from 'src/engine/api/mcp/services/mcp-tool-exeimport {createListObjectMetadataNamesTool,LIST_OBJECT_METADATA_NAMES_TOOL_NAME,- listObjectMetadataNamesInputSchema,} from 'src/engine/api/mcp/tools/list-object-metadata-names.tool';import {createListSkillsTool,LIST_SKILLS_TOOL_NAME,- listSkillsInputSchema,} from 'src/engine/api/mcp/tools/list-skills.tool';+import { type McpAnnotatedTool } from 'src/engine/api/mcp/types/mcp-annotated-tool.type';import { type McpCoreQueryContext } from 'src/engine/api/mcp/types/mcp-core-query-context.type';import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';+import { type McpToolSet } from 'src/engine/api/mcp/types/mcp-tool-set.type';import { getMcpRegistryToolAnnotations } from 'src/engine/api/mcp/utils/get-mcp-registry-tool-annotations.util';+import { parseMcpToolCallParams } from 'src/engine/api/mcp/utils/parse-mcp-tool-call-params.util';import { wrapJsonRpcResponse } from 'src/engine/api/mcp/utils/wrap-jsonrpc-response.util';import { ApiKeyRoleService } from 'src/engine/core-modules/api-key/services/api-key-role.service';import { type FlatApiKey } from 'src/engine/core-modules/api-key/types/flat-api-key.type';@@ -41,22 +41,18 @@ import { ToolRegistryService } from 'src/engine/core-modules/tool-provider/serviimport {createLearnToolsTool,LEARN_TOOLS_TOOL_NAME,- learnToolsInputSchema,} from 'src/engine/core-modules/tool-provider/tools';import {createExecuteToolTool,EXECUTE_TOOL_TOOL_NAME,- executeToolInputSchema,} from 'src/engine/core-modules/tool-provider/tools/execute-tool.tool';import {createGetToolCatalogTool,GET_TOOL_CATALOG_TOOL_NAME,- getToolCatalogInputSchema,} from 'src/engine/core-modules/tool-provider/tools/get-tool-catalog.tool';import {createLoadSkillTool,LOAD_SKILL_TOOL_NAME,- loadSkillInputSchema,} from 'src/engine/core-modules/tool-provider/tools/load-skill.tool';import { type FlatWorkspace } from 'src/engine/core-modules/workspace/types/flat-workspace.type';import {@@ -72,31 +68,25 @@ import { handleException } from 'src/engine/utils/global-exception-handler.util'import { WorkspaceCacheService } from 'src/engine/workspace-cache/services/workspace-cache.service';import { CustomException } from 'src/utils/custom-exception';-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 =>+const annotatePreloadedMcpTools = (toolSet: ToolSet): McpToolSet =>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}"`);- }+ Object.entries(toolSet).map(+ ([name, toolDefinition]): [string, McpAnnotatedTool] => {+ 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,- ];- }),+ return [name, { ...toolDefinition, annotations }];+ },+ ),);@Injectable()@@ -289,7 +279,7 @@ export class McpProtocolService {application?: FlatApplication;agentId?: string;},- ): Promise<{ toolSet: ToolSet; toolContext: ToolProviderContext }> {+ ): Promise<{ toolSet: McpToolSet; toolContext: ToolProviderContext }> {const actorContext = await this.buildActorContext(workspace.id,options?.userId,@@ -312,7 +302,7 @@ export class McpProtocolService {toolContext,);- const toolSet: ToolSet = {+ const toolSet: McpToolSet = {...annotatePreloadedMcpTools(preloadedTools),[GET_TOOL_CATALOG_TOOL_NAME]: {...createGetToolCatalogTool(this.toolRegistry, workspace.id, {@@ -322,16 +312,14 @@ export class McpProtocolService {excludeTools: MCP_EXCLUDED_TOOL_NAMES,application: options?.application,}),- inputSchema: zodSchema(getToolCatalogInputSchema),annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,- } as McpAnnotatedTool,+ },[EXECUTE_TOOL_TOOL_NAME]: {...createExecuteToolTool(this.toolRegistry, toolContext, {isToolAllowed: (toolName) => !MCP_EXCLUDED_TOOL_NAMES.has(toolName),}),- inputSchema: executeToolInputSchema,annotations: MCP_EXECUTE_TOOL_ANNOTATIONS,- } as McpAnnotatedTool,+ },[LOAD_SKILL_TOOL_NAME]: {...createLoadSkillTool((names) =>@@ -344,29 +332,25 @@ export class McpProtocolService {return allSkills.map((skill) => skill.name);},),- inputSchema: zodSchema(loadSkillInputSchema),annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,- } as McpAnnotatedTool,+ },[LIST_OBJECT_METADATA_NAMES_TOOL_NAME]: {...createListObjectMetadataNamesTool(this.flatEntityMapsCacheService,workspace.id,),- inputSchema: zodSchema(listObjectMetadataNamesInputSchema),annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,- } as McpAnnotatedTool,+ },[LIST_SKILLS_TOOL_NAME]: {...createListSkillsTool(this.skillService, workspace.id),- inputSchema: zodSchema(listSkillsInputSchema),annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,- } as McpAnnotatedTool,+ },[LEARN_TOOLS_TOOL_NAME]: {...createLearnToolsTool(this.toolRegistry, toolContext, {isToolAllowed: (toolName) => !MCP_EXCLUDED_TOOL_NAMES.has(toolName),}),- inputSchema: zodSchema(learnToolsInputSchema),annotations: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,- } as McpAnnotatedTool,+ },};return { toolSet, toolContext };@@ -464,7 +448,9 @@ export class McpProtocolService {);if (method === 'tools/call') {- if (!params) {+ const toolCallParams = parseMcpToolCallParams(params);++ if (!isDefined(toolCallParams)) {return wrapJsonRpcResponse(id, {error: {code: JSON_RPC_ERROR_CODE.INVALID_PARAMS,@@ -473,26 +459,23 @@ export class McpProtocolService {});}+ const { toolName, toolArguments, progressToken } = toolCallParams;+const shouldForwardToExecuteTool =- isDirectMode &&- isNonEmptyString(params.name) &&- !isDefined(toolSet[params.name]);+ isDirectMode && !isDefined(toolSet[toolName]);- return await this.mcpToolExecutorService.handleToolCall(+ return await this.mcpToolExecutorService.handleToolCall({id,toolSet,- shouldForwardToExecuteTool+ ...(shouldForwardToExecuteTool? {- ...params,- name: EXECUTE_TOOL_TOOL_NAME,- arguments: {- toolName: params.name,- arguments: params.arguments ?? {},- },+ toolName: EXECUTE_TOOL_TOOL_NAME,+ toolArguments: { toolName, arguments: toolArguments ?? {} },}- : params,+ : { toolName, toolArguments }),+ progressToken,sseWriter,- );+ });}if (isDirectMode) {@@ -534,13 +517,13 @@ export class McpProtocolService {},);- return this.mcpToolExecutorService.handleToolsListing(id, {+ return await this.mcpToolExecutorService.handleToolsListing(id, {...annotatedRegistryTools,...nativeTools,});}- return this.mcpToolExecutorService.handleToolsListing(id, toolSet);+ return await this.mcpToolExecutorService.handleToolsListing(id, toolSet);} catch (error) {const exception =error instanceof Error ? error : new Error(String(error));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 5fa01a1a434..7672938e69f 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@@ -1,8 +1,7 @@import { Injectable } from '@nestjs/common';-import { isNonEmptyString } from '@sniptt/guards';-import { type ToolExecuteFunction, type ToolSet } from 'ai';-import { isDefined, isPlainObject } from 'twenty-shared/utils';+import { asSchema, type ToolExecuteFunction } from 'ai';+import { isDefined } from 'twenty-shared/utils';import { TOOL_EXECUTION_DURATION_MS_BUCKET_BOUNDARIES } from 'src/engine/core-modules/metrics/constants/tool-execution-duration-ms-bucket-boundaries.constant';import { TOOL_OUTPUT_TOKENS_BUCKET_BOUNDARIES } from 'src/engine/core-modules/metrics/constants/tool-output-tokens-bucket-boundaries.constant';@@ -15,39 +14,28 @@ import { resolveToolName } from 'src/engine/core-modules/tool-provider/utils/resimport { JSON_RPC_ERROR_CODE } from 'src/engine/api/mcp/constants/json-rpc-error-code.const';import { MCP_PROGRESS_NOTIFICATION_METHOD } from 'src/engine/api/mcp/constants/mcp-progress-notification.const';-import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';-import { getProgressToken } from 'src/engine/api/mcp/utils/get-progress-token.util';+import { type McpToolSet } from 'src/engine/api/mcp/types/mcp-tool-set.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 {constructor(private readonly metricsService: MetricsService) {}- async handleToolCall(- id: string | number,- toolSet: ToolSet,- params: Record<string, unknown>,- sseWriter?: (data: Record<string, unknown>) => void,- ) {- if (!isNonEmptyString(params.name)) {- return wrapJsonRpcResponse(id, {- error: {- code: JSON_RPC_ERROR_CODE.INVALID_PARAMS,- message: 'Tool name is required',- },- });- }-- const toolName = params.name;+ async handleToolCall({+ id,+ toolSet,+ toolName,+ toolArguments,+ progressToken,+ sseWriter,+ }: {+ id: string | number;+ toolSet: McpToolSet;+ toolName: string;+ toolArguments: Record<string, unknown> | undefined;+ progressToken: string | number | undefined;+ sseWriter?: (data: Record<string, unknown>) => void;+ }) {const tool = toolSet[toolName];if (!isDefined(tool) || !isDefined(tool.execute)) {@@ -59,8 +47,6 @@ export class McpToolExecutorService {});}- const progressToken = getProgressToken(params);-if (isDefined(sseWriter) && isDefined(progressToken)) {sseWriter({jsonrpc: '2.0',@@ -76,7 +62,7 @@ export class McpToolExecutorService {const metricToolName = getToolMetricName(resolveToolName({toolName,- input: params.arguments,+ input: toolArguments,}),);@@ -89,7 +75,7 @@ export class McpToolExecutorService {unknown,undefined>;- const result = await execute(params.arguments, {+ const result = await execute(toolArguments, {toolCallId: '1',messages: [],context: undefined,@@ -159,30 +145,24 @@ export class McpToolExecutorService {}}- handleToolsListing(id: string | number, toolSet: ToolSet) {- const toolsArray = Object.entries(toolSet)- .filter(([, def]) => !!def.inputSchema)- .map(([name, def]) => {- const toolDefinition = def as McpToolDefinition;- // The AI SDK wraps schemas as { jsonSchema } but MCP expects the bare schema- const inputSchema = unwrapJsonSchema(toolDefinition.inputSchema);-- return {+ async handleToolsListing(id: string | number, toolSet: McpToolSet) {+ const tools = await Promise.all(+ Object.entries(toolSet)+ .filter(([, tool]) => isDefined(tool.inputSchema))+ .map(async ([name, tool]) => ({name,- description: toolDefinition.description,+ description: tool.description,inputSchema: {- ...(isPlainObject(inputSchema) ? inputSchema : {}),+ ...(await asSchema(tool.inputSchema).jsonSchema),type: 'object',},- ...(isDefined(toolDefinition.annotations) && {- annotations: toolDefinition.annotations,- }),- };- });+ annotations: tool.annotations,+ })),+ );return wrapJsonRpcResponse(id, {result: {- tools: toolsArray,+ tools,},});}diff --git a/packages/twenty-server/src/engine/api/mcp/types/mcp-annotated-tool.type.ts b/packages/twenty-server/src/engine/api/mcp/types/mcp-annotated-tool.type.tsnew file mode 100644index 00000000000..f70b0b69d9a--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/types/mcp-annotated-tool.type.ts@@ -0,0 +1,7 @@+import { type ToolSet } from 'ai';++import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';++export type McpAnnotatedTool = ToolSet[string] & {+ annotations: McpToolAnnotations;+};diff --git a/packages/twenty-server/src/engine/api/mcp/types/mcp-tool-set.type.ts b/packages/twenty-server/src/engine/api/mcp/types/mcp-tool-set.type.tsnew file mode 100644index 00000000000..b36237bd61c--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/types/mcp-tool-set.type.ts@@ -0,0 +1,3 @@+import { type McpAnnotatedTool } from 'src/engine/api/mcp/types/mcp-annotated-tool.type';++export type McpToolSet = Record<string, McpAnnotatedTool>;diff --git a/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-progress-token.util.spec.ts b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-progress-token.util.spec.tsdeleted file mode 100644index 7d8189a64b0..00000000000--- a/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-progress-token.util.spec.ts+++ /dev/null@@ -1,43 +0,0 @@-import { getProgressToken } from 'src/engine/api/mcp/utils/get-progress-token.util';--describe('getProgressToken', () => {- it.each([['abc123'], [4], [0], [-7]])(- 'should return the token %p supplied by the client',- (progressToken) => {- expect(getProgressToken({ _meta: { progressToken } })).toBe(- progressToken,- );- },- );-- it('should return undefined when params carry no _meta', () => {- expect(getProgressToken({ name: 'learn_tools' })).toBeUndefined();- });-- it('should return undefined when _meta carries no progressToken', () => {- expect(getProgressToken({ _meta: { other: 'value' } })).toBeUndefined();- });-- it.each([[null], ['abc123']])(- 'should return undefined when _meta is %p',- (meta) => {- expect(getProgressToken({ _meta: meta })).toBeUndefined();- },- );-- it.each([- [true],- [{}],- [[]],- [null],- [1.5],- [-0.25],- [Number.NaN],- [Number.POSITIVE_INFINITY],- ])(- 'should return undefined for the non conformant token %p',- (progressToken) => {- expect(getProgressToken({ _meta: { progressToken } })).toBeUndefined();- },- );-});diff --git a/packages/twenty-server/src/engine/api/mcp/utils/__tests__/parse-mcp-tool-call-params.util.spec.ts b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/parse-mcp-tool-call-params.util.spec.tsnew file mode 100644index 00000000000..7ef988393a9--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/parse-mcp-tool-call-params.util.spec.ts@@ -0,0 +1,89 @@+import { parseMcpToolCallParams } from 'src/engine/api/mcp/utils/parse-mcp-tool-call-params.util';++describe('parseMcpToolCallParams', () => {+ it('should return the tool name and arguments', () => {+ expect(+ parseMcpToolCallParams({+ name: 'learn_tools',+ arguments: { toolNames: ['find_companies'] },+ }),+ ).toEqual({+ toolName: 'learn_tools',+ toolArguments: { toolNames: ['find_companies'] },+ progressToken: undefined,+ });+ });++ it.each([+ ['omitted arguments', { name: 'list_skills' }],+ ['null arguments', { name: 'list_skills', arguments: null }],+ ])('should accept a call with %s as no arguments', (_, params) => {+ expect(parseMcpToolCallParams(params)).toEqual({+ toolName: 'list_skills',+ toolArguments: undefined,+ progressToken: undefined,+ });+ });++ it.each([+ ['missing params', undefined],+ ['a missing name', { arguments: {} }],+ ['an empty name', { name: '', arguments: {} }],+ ['a non string name', { name: 42, arguments: {} }],+ ['array arguments', { name: 'learn_tools', arguments: [] }],+ ['string arguments', { name: 'learn_tools', arguments: 'toolNames' }],+ ])('should reject %s', (_, params) => {+ expect(parseMcpToolCallParams(params)).toBeUndefined();+ });++ it.each([['abc123'], [4], [0], [-7]])(+ 'should return the progress token %p supplied by the client',+ (progressToken) => {+ expect(+ parseMcpToolCallParams({+ name: 'learn_tools',+ _meta: { progressToken },+ })?.progressToken,+ ).toBe(progressToken);+ },+ );++ it.each([+ ['_meta without progressToken', { other: 'value' }],+ ['a null _meta', null],+ ['a string _meta', 'abc123'],+ ])('should ignore %s', (_, meta) => {+ expect(+ parseMcpToolCallParams({ name: 'learn_tools', _meta: meta }),+ ).toEqual({+ toolName: 'learn_tools',+ toolArguments: undefined,+ progressToken: undefined,+ });+ });++ it.each([+ [true],+ [{}],+ [[]],+ [null],+ [1.5],+ [-0.25],+ [Number.NaN],+ [Number.POSITIVE_INFINITY],+ ])(+ 'should ignore the non conformant progress token %p without failing the call',+ (progressToken) => {+ expect(+ parseMcpToolCallParams({+ name: 'learn_tools',+ _meta: { progressToken },+ }),+ ).toEqual({+ toolName: 'learn_tools',+ toolArguments: undefined,+ progressToken: undefined,+ });+ },+ );+});diff --git a/packages/twenty-server/src/engine/api/mcp/utils/get-progress-token.util.ts b/packages/twenty-server/src/engine/api/mcp/utils/get-progress-token.util.tsdeleted file mode 100644index 62bde2e6a4e..00000000000--- a/packages/twenty-server/src/engine/api/mcp/utils/get-progress-token.util.ts+++ /dev/null@@ -1,13 +0,0 @@-import { z } from 'zod';--const progressTokenParamsSchema = z.object({- _meta: z.object({- progressToken: z.union([z.string(), z.number().int()]),- }),-});--export const getProgressToken = (params: Record<string, unknown>) => {- const parsed = progressTokenParamsSchema.safeParse(params);-- return parsed.success ? parsed.data._meta.progressToken : undefined;-};diff --git a/packages/twenty-server/src/engine/api/mcp/utils/parse-mcp-tool-call-params.util.ts b/packages/twenty-server/src/engine/api/mcp/utils/parse-mcp-tool-call-params.util.tsnew file mode 100644index 00000000000..c5a131ed3f1--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/utils/parse-mcp-tool-call-params.util.ts@@ -0,0 +1,29 @@+import { z } from 'zod';++const mcpToolCallParamsSchema = z.object({+ name: z.string().min(1),+ arguments: z.record(z.string(), z.unknown()).nullish(),+ // A malformed progress token only disables progress notifications, it does not fail the call+ _meta: z+ .object({+ progressToken: z.union([z.string(), z.number().int()]).optional(),+ })+ .optional()+ .catch(undefined),+});++export const parseMcpToolCallParams = (+ params: Record<string, unknown> | undefined,+) => {+ const parsed = mcpToolCallParamsSchema.safeParse(params);++ if (!parsed.success) {+ return undefined;+ }++ return {+ toolName: parsed.data.name,+ toolArguments: parsed.data.arguments ?? undefined,+ progressToken: parsed.data._meta?.progressToken,+ };+};