Skip to content

The open alternative to Salesforce, designed for AI.

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.ts
index 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.ts
index 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-exe
import {
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/servi
import {
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.ts
index 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/res
import { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
new file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
new file mode 100644
index 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,
+ };
+};