The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
fix: return method-specific MCP responses (#18671)
Sri Hari Haran Sharmaa07337fea0be
diff --git a/packages/twenty-server/src/engine/api/mcp/constants/json-rpc-error-code.const.ts b/packages/twenty-server/src/engine/api/mcp/constants/json-rpc-error-code.const.tsnew file mode 100644index 00000000000..8b4fc5743dd--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/constants/json-rpc-error-code.const.ts@@ -0,0 +1,9 @@+export const JSON_RPC_ERROR_CODE = {+ PARSE_ERROR: -32700,+ INVALID_REQUEST: -32600,+ METHOD_NOT_FOUND: -32601,+ INVALID_PARAMS: -32602,+ INTERNAL_ERROR: -32603,+ // -32000 to -32099: reserved for implementation-defined server errors+ SERVER_ERROR: -32000,+} as const;diff --git a/packages/twenty-server/src/engine/api/mcp/constants/mcp-protocol-version.const.ts b/packages/twenty-server/src/engine/api/mcp/constants/mcp-protocol-version.const.tsnew file mode 100644index 00000000000..f41cb83a6c0--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/constants/mcp-protocol-version.const.ts@@ -0,0 +1 @@+export const MCP_PROTOCOL_VERSION = '2024-11-05';diff --git a/packages/twenty-server/src/engine/api/mcp/constants/mcp-server-info.const.ts b/packages/twenty-server/src/engine/api/mcp/constants/mcp-server-info.const.tsnew file mode 100644index 00000000000..db9fffb5bf2--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/constants/mcp-server-info.const.ts@@ -0,0 +1,4 @@+export const MCP_SERVER_INFO = {+ name: 'Twenty MCP Server',+ version: '0.1.0',+};diff --git a/packages/twenty-server/src/engine/api/mcp/constants/mcp-server-instructions.const.ts b/packages/twenty-server/src/engine/api/mcp/constants/mcp-server-instructions.const.tsnew file mode 100644index 00000000000..e69c4bc4513--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/constants/mcp-server-instructions.const.ts@@ -0,0 +1,2 @@+export const MCP_SERVER_INSTRUCTIONS =+ 'Twenty CRM MCP Server. Follow this workflow: (1) get_tool_catalog to discover tools, (2) learn_tools to get input schemas, (3) execute_tool to run them. Never guess tool names — always start with get_tool_catalog. Use load_skills for guidance on complex tasks like workflow or dashboard building.';diff --git a/packages/twenty-server/src/engine/api/mcp/constants/mcp.const.ts b/packages/twenty-server/src/engine/api/mcp/constants/mcp.const.tsdeleted file mode 100644index a3d48ae56b3..00000000000--- a/packages/twenty-server/src/engine/api/mcp/constants/mcp.const.ts+++ /dev/null@@ -1,10 +0,0 @@-export const MCP_SERVER_METADATA = {- metadata: {- info: 'Twenty CRM MCP Server. Follow this workflow: (1) get_tool_catalog to discover tools, (2) learn_tools to get input schemas, (3) execute_tool to run them. Never guess tool names — always start with get_tool_catalog. Use load_skills for guidance on complex tasks like workflow or dashboard building.',- },- protocolVersion: '2024-11-05',- serverInfo: {- name: 'Twenty MCP Server',- version: '0.1.0',- },-};diff --git a/packages/twenty-server/src/engine/api/mcp/controllers/__tests__/mcp-core.controller.spec.ts b/packages/twenty-server/src/engine/api/mcp/controllers/__tests__/mcp-core.controller.spec.tsindex 96fe5d0bee7..e216d9281d5 100644--- a/packages/twenty-server/src/engine/api/mcp/controllers/__tests__/mcp-core.controller.spec.ts+++ b/packages/twenty-server/src/engine/api/mcp/controllers/__tests__/mcp-core.controller.spec.ts@@ -2,7 +2,9 @@ import { Test, type TestingModule } from '@nestjs/testing';import { DEFAULT_TOOL_INPUT_SCHEMA } from 'twenty-shared/logic-function';-import { MCP_SERVER_METADATA } from 'src/engine/api/mcp/constants/mcp.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 { McpCoreController } from 'src/engine/api/mcp/controllers/mcp-core.controller';import { type JsonRpc } from 'src/engine/api/mcp/dtos/json-rpc';import { McpAuthGuard } from 'src/engine/api/mcp/guards/mcp-auth.guard';@@ -71,6 +73,13 @@ describe('McpCoreController', () => {const mockUser = { id: 'user-1' } as UserEntity;const mockUserWorkspaceId = 'user-workspace-1';const mockApiKey = { id: 'api-key-1' } as ApiKeyEntity;+ const mockRes = {+ status: jest.fn().mockReturnThis(),+ } as unknown as import('express').Response;++ beforeEach(() => {+ (mockRes.status as jest.Mock).mockClear();+ });it('should call mcpProtocolService.handleMCPCoreQuery with correct parameters', async () => {const mockRequest: JsonRpc = {@@ -97,6 +106,7 @@ describe('McpCoreController', () => {mockApiKey,mockUser,mockUserWorkspaceId,+ mockRes,);expect(mcpProtocolService.handleMCPCoreQuery).toHaveBeenCalledWith(@@ -122,12 +132,14 @@ describe('McpCoreController', () => {id: '123',jsonrpc: '2.0',result: {- ...MCP_SERVER_METADATA,+ protocolVersion: MCP_PROTOCOL_VERSION,capabilities: {tools: { listChanged: false },resources: { listChanged: false },prompts: { listChanged: false },},+ serverInfo: MCP_SERVER_INFO,+ instructions: MCP_SERVER_INSTRUCTIONS,},};@@ -139,6 +151,7 @@ describe('McpCoreController', () => {mockApiKey,mockUser,mockUserWorkspaceId,+ mockRes,);expect(mcpProtocolService.handleMCPCoreQuery).toHaveBeenCalledWith(@@ -164,10 +177,6 @@ describe('McpCoreController', () => {id: '123',jsonrpc: '2.0',result: {- ...MCP_SERVER_METADATA,- capabilities: {- tools: { listChanged: false },- },tools: [{name: 'testTool',@@ -186,6 +195,7 @@ describe('McpCoreController', () => {mockApiKey,mockUser,mockUserWorkspaceId,+ mockRes,);expect(mcpProtocolService.handleMCPCoreQuery).toHaveBeenCalledWith(@@ -200,6 +210,27 @@ describe('McpCoreController', () => {expect(result).toEqual(mockResponse);});+ it('should return 202 with no body for notifications', async () => {+ const mockRequest: JsonRpc = {+ jsonrpc: '2.0',+ method: 'notifications/initialized',+ };++ mcpProtocolService.handleMCPCoreQuery.mockResolvedValue(null);++ const result = await controller.handleMcpCore(+ mockRequest,+ mockWorkspace,+ mockApiKey,+ mockUser,+ mockUserWorkspaceId,+ mockRes,+ );++ expect(result).toBeUndefined();+ expect(mockRes.status).toHaveBeenCalledWith(202);+ });+it('should handle API key auth without user', async () => {const mockRequest: JsonRpc = {jsonrpc: '2.0',@@ -225,6 +256,7 @@ describe('McpCoreController', () => {mockApiKey,undefined,undefined,+ mockRes,);expect(mcpProtocolService.handleMCPCoreQuery).toHaveBeenCalledWith(diff --git a/packages/twenty-server/src/engine/api/mcp/controllers/mcp-core.controller.ts b/packages/twenty-server/src/engine/api/mcp/controllers/mcp-core.controller.tsindex a32709c7ef0..5b1060dfc64 100644--- a/packages/twenty-server/src/engine/api/mcp/controllers/mcp-core.controller.ts+++ b/packages/twenty-server/src/engine/api/mcp/controllers/mcp-core.controller.ts@@ -1,13 +1,19 @@import {Body,Controller,+ HttpCode,+ HttpStatus,Post,+ Res,UseFilters,UseGuards,UsePipes,ValidationPipe,} from '@nestjs/common';+import { type Response } from 'express';+import { isDefined } from 'twenty-shared/utils';+import { JsonRpc } from 'src/engine/api/mcp/dtos/json-rpc';import { McpAuthGuard } from 'src/engine/api/mcp/guards/mcp-auth.guard';import { McpProtocolService } from 'src/engine/api/mcp/services/mcp-protocol.service';@@ -16,8 +22,8 @@ import { ApiKeyEntity } from 'src/engine/core-modules/api-key/api-key.entity';import { UserEntity } from 'src/engine/core-modules/user/user.entity';import { WorkspaceEntity } from 'src/engine/core-modules/workspace/workspace.entity';import { AuthApiKey } from 'src/engine/decorators/auth/auth-api-key.decorator';-import { AuthUser } from 'src/engine/decorators/auth/auth-user.decorator';import { AuthUserWorkspaceId } from 'src/engine/decorators/auth/auth-user-workspace-id.decorator';+import { AuthUser } from 'src/engine/decorators/auth/auth-user.decorator';import { AuthWorkspace } from 'src/engine/decorators/auth/auth-workspace.decorator';import { NoPermissionGuard } from 'src/engine/guards/no-permission.guard';import { WorkspaceAuthGuard } from 'src/engine/guards/workspace-auth.guard';@@ -29,6 +35,7 @@ export class McpCoreController {constructor(private readonly mcpProtocolService: McpProtocolService) {}@Post()+ @HttpCode(HttpStatus.OK)@UsePipes(new ValidationPipe({transform: true,@@ -42,12 +49,22 @@ export class McpCoreController {@AuthApiKey() apiKey: ApiKeyEntity | undefined,@AuthUser({ allowUndefined: true }) user: UserEntity | undefined,@AuthUserWorkspaceId() userWorkspaceId: string | undefined,+ @Res({ passthrough: true }) res: Response,) {- return await this.mcpProtocolService.handleMCPCoreQuery(body, {+ const result = await this.mcpProtocolService.handleMCPCoreQuery(body, {workspace,userId: user?.id,userWorkspaceId,apiKey,});++ // JSON-RPC notifications (no id) expect no response body+ if (!isDefined(result)) {+ res.status(HttpStatus.ACCEPTED);++ return;+ }++ return result;}}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 ad9eb9526e6..99ed0102da7 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@@ -29,5 +29,5 @@ export class JsonRpc {@IsOptional()@Validate(IsNumberOrString)- id: string | number;+ id?: string | number;}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 53906ff923b..dd235901bda 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@@ -1,7 +1,10 @@import { HttpException, HttpStatus } from '@nestjs/common';import { Test, type TestingModule } from '@nestjs/testing';-import { MCP_SERVER_METADATA } from 'src/engine/api/mcp/constants/mcp.const';+import { JSON_RPC_ERROR_CODE } from 'src/engine/api/mcp/constants/json-rpc-error-code.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';@@ -97,21 +100,23 @@ describe('McpProtocolService', () => {});describe('handleInitialize', () => {- it('should return correct initialization response', () => {+ it('should return spec-compliant initialization response', () => {const requestId = '123';const result = service.handleInitialize(requestId);- expect(result).toMatchObject({+ expect(result).toEqual({id: requestId,jsonrpc: '2.0',- result: expect.objectContaining({- ...MCP_SERVER_METADATA,+ result: {+ protocolVersion: MCP_PROTOCOL_VERSION,capabilities: {tools: { listChanged: false },resources: { listChanged: false },prompts: { listChanged: false },},- }),+ serverInfo: MCP_SERVER_INFO,+ instructions: MCP_SERVER_INSTRUCTIONS,+ },});});});@@ -176,18 +181,35 @@ describe('McpProtocolService', () => {apiKey: undefined,});- expect(result).toMatchObject({+ expect(result).toEqual({id: '123',jsonrpc: '2.0',- result: expect.objectContaining({- ...MCP_SERVER_METADATA,+ result: {+ protocolVersion: MCP_PROTOCOL_VERSION,capabilities: {tools: { listChanged: false },resources: { listChanged: false },prompts: { listChanged: false },},- }),+ serverInfo: MCP_SERVER_INFO,+ instructions: MCP_SERVER_INSTRUCTIONS,+ },+ });+ });++ it('should return null for notifications (no id)', async () => {+ const mockRequest: JsonRpc = {+ jsonrpc: '2.0',+ method: 'notifications/initialized',+ };++ const result = await service.handleMCPCoreQuery(mockRequest, {+ workspace: mockWorkspace,+ userWorkspaceId: mockUserWorkspaceId,+ apiKey: undefined,});++ expect(result).toBeNull();});it('should build a ToolSet with exactly 5 tools and pass it to executor for tools/call', async () => {@@ -197,7 +219,6 @@ describe('McpProtocolService', () => {id: '123',jsonrpc: '2.0',result: {- ...MCP_SERVER_METADATA,content: [{ type: 'text', text: '{}' }],isError: false,},@@ -276,6 +297,71 @@ describe('McpProtocolService', () => {);});+ it('should return prompts list without role resolution', async () => {+ const mockRequest: JsonRpc = {+ jsonrpc: '2.0',+ method: 'prompts/list',+ id: '123',+ };++ const result = await service.handleMCPCoreQuery(mockRequest, {+ workspace: mockWorkspace,+ userWorkspaceId: mockUserWorkspaceId,+ apiKey: undefined,+ });++ expect(result).toEqual({+ id: '123',+ jsonrpc: '2.0',+ result: { prompts: [] },+ });+ expect(userRoleService.getRoleIdForUserWorkspace).not.toHaveBeenCalled();+ });++ it('should return resources list without role resolution', async () => {+ const mockRequest: JsonRpc = {+ jsonrpc: '2.0',+ method: 'resources/list',+ id: '123',+ };++ const result = await service.handleMCPCoreQuery(mockRequest, {+ workspace: mockWorkspace,+ userWorkspaceId: mockUserWorkspaceId,+ apiKey: undefined,+ });++ expect(result).toEqual({+ id: '123',+ jsonrpc: '2.0',+ result: { resources: [] },+ });+ expect(userRoleService.getRoleIdForUserWorkspace).not.toHaveBeenCalled();+ });++ it('should return method not found for unknown methods', async () => {+ const mockRequest: JsonRpc = {+ jsonrpc: '2.0',+ method: 'unknown/method',+ id: '123',+ };++ const result = await service.handleMCPCoreQuery(mockRequest, {+ workspace: mockWorkspace,+ userWorkspaceId: mockUserWorkspaceId,+ apiKey: undefined,+ });++ expect(result).toEqual({+ id: '123',+ jsonrpc: '2.0',+ error: {+ code: JSON_RPC_ERROR_CODE.METHOD_NOT_FOUND,+ message: "Method 'unknown/method' not found",+ },+ });+ });+it('should handle tools/call with apiKey authentication', async () => {const mockToolCallResponse = {id: '123',@@ -306,20 +392,45 @@ describe('McpProtocolService', () => {);});- it('should handle error when tool execution fails', async () => {+ it('should wrap unexpected errors with INTERNAL_ERROR code', async () => {userRoleService.getRoleIdForUserWorkspace.mockResolvedValue(mockRoleId);mcpToolExecutorService.handleToolCall.mockRejectedValue(- new HttpException(- "Tool 'nonExistentTool' not found",- HttpStatus.NOT_FOUND,- ),+ new Error('Something went wrong'),+ );++ const mockRequest: JsonRpc = {+ jsonrpc: '2.0',+ method: 'tools/call',+ params: { name: 'execute_tool', arguments: {} },+ id: '123',+ };++ const result = await service.handleMCPCoreQuery(mockRequest, {+ workspace: mockWorkspace,+ userWorkspaceId: mockUserWorkspaceId,+ apiKey: undefined,+ });++ expect(result).toEqual({+ id: '123',+ jsonrpc: '2.0',+ error: {+ code: JSON_RPC_ERROR_CODE.INTERNAL_ERROR,+ message: 'Something went wrong',+ },+ });+ });++ it('should wrap HttpException errors with SERVER_ERROR code', async () => {+ userRoleService.getRoleIdForUserWorkspace.mockRejectedValue(+ new HttpException('Role ID missing', HttpStatus.FORBIDDEN),);const mockRequest: JsonRpc = {jsonrpc: '2.0',method: 'tools/call',- params: { name: 'nonExistentTool', arguments: {} },+ params: { name: 'execute_tool', arguments: {} },id: '123',};@@ -333,9 +444,8 @@ describe('McpProtocolService', () => {id: '123',jsonrpc: '2.0',error: {- ...MCP_SERVER_METADATA,- code: HttpStatus.NOT_FOUND,- message: "Tool 'nonExistentTool' not found",+ code: JSON_RPC_ERROR_CODE.SERVER_ERROR,+ message: 'Role ID missing',},});});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.tsnew file mode 100644index 00000000000..b65fa4626e1--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-tool-executor.service.spec.ts@@ -0,0 +1,146 @@+import { JSON_RPC_ERROR_CODE } from 'src/engine/api/mcp/constants/json-rpc-error-code.const';+import { McpToolExecutorService } from 'src/engine/api/mcp/services/mcp-tool-executor.service';++describe('McpToolExecutorService', () => {+ let service: McpToolExecutorService;++ beforeEach(() => {+ service = new McpToolExecutorService();+ });++ describe('handleToolsListing', () => {+ it('should return only tools array in result', () => {+ const toolSet = {+ test_tool: {+ description: 'A test tool',+ inputSchema: {+ jsonSchema: {+ type: 'object',+ properties: { query: { type: 'string' } },+ required: ['query'],+ },+ },+ },+ } as any;++ const result = service.handleToolsListing('123', toolSet);++ expect(result).toEqual({+ id: '123',+ jsonrpc: '2.0',+ result: {+ tools: [+ {+ name: 'test_tool',+ description: 'A test tool',+ inputSchema: {+ type: 'object',+ properties: { query: { type: 'string' } },+ required: ['query'],+ },+ },+ ],+ },+ });+ });++ it('should keep inputSchema unchanged when it is already a plain schema', () => {+ const toolSet = {+ plain_tool: {+ description: 'A plain schema tool',+ inputSchema: {+ type: 'object',+ properties: { name: { type: 'string' } },+ },+ },+ } as any;++ const result = service.handleToolsListing('456', toolSet);++ expect(result).toEqual({+ id: '456',+ jsonrpc: '2.0',+ result: {+ tools: [+ {+ name: 'plain_tool',+ description: 'A plain schema tool',+ inputSchema: {+ type: 'object',+ properties: { name: { type: 'string' } },+ },+ },+ ],+ },+ });+ });+ });++ describe('handleToolCall', () => {+ it('should return JSON-RPC error with INVALID_PARAMS for unknown tools', async () => {+ const toolSet = {} as any;++ const result = await service.handleToolCall('123', toolSet, {+ name: 'nonexistent_tool',+ arguments: {},+ });++ expect(result).toEqual({+ id: '123',+ jsonrpc: '2.0',+ error: {+ code: JSON_RPC_ERROR_CODE.INVALID_PARAMS,+ message: 'Unknown tool: nonexistent_tool',+ },+ });+ });++ it('should return result with isError: false on success', async () => {+ const toolSet = {+ my_tool: {+ execute: jest.fn().mockResolvedValue({ data: 'ok' }),+ description: 'My tool',+ inputSchema: { type: 'object' },+ },+ } as any;++ const result = await service.handleToolCall('123', toolSet, {+ name: 'my_tool',+ arguments: {},+ });++ expect(result).toEqual({+ id: '123',+ jsonrpc: '2.0',+ result: {+ content: [{ type: 'text', text: '{"data":"ok"}' }],+ isError: false,+ },+ });+ });++ it('should return result with isError: true when tool execution throws', async () => {+ const toolSet = {+ failing_tool: {+ execute: jest.fn().mockRejectedValue(new Error('API rate limited')),+ description: 'A tool that fails',+ inputSchema: { type: 'object' },+ },+ } as any;++ const result = await service.handleToolCall('123', toolSet, {+ name: 'failing_tool',+ arguments: {},+ });++ expect(result).toEqual({+ id: '123',+ jsonrpc: '2.0',+ result: {+ content: [{ type: 'text', text: 'API rate limited' }],+ isError: true,+ },+ });+ });+ });+});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 b6b0586bf07..aba1a312781 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@@ -3,6 +3,10 @@ import { HttpException, HttpStatus, Injectable } from '@nestjs/common';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_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 { wrapJsonRpcResponse } from 'src/engine/api/mcp/utils/wrap-jsonrpc-response.util';@@ -51,14 +55,14 @@ export class McpProtocolService {handleInitialize(requestId: string | number) {return wrapJsonRpcResponse(requestId, {result: {+ protocolVersion: MCP_PROTOCOL_VERSION,capabilities: {tools: { listChanged: false },resources: { listChanged: false },prompts: { listChanged: false },},- tools: [],- resources: [],- prompts: [],+ serverInfo: MCP_SERVER_INFO,+ instructions: MCP_SERVER_INSTRUCTIONS,},});}@@ -152,6 +156,7 @@ export class McpProtocolService {};}+ // Returns null for JSON-RPC notifications (no id), which require no response bodyasync handleMCPCoreQuery({ id, method, params }: JsonRpc,{@@ -165,20 +170,40 @@ export class McpProtocolService {userWorkspaceId?: string;apiKey: ApiKeyEntity | undefined;},- ): Promise<Record<string, unknown>> {+ ): Promise<Record<string, unknown> | null> {try {+ // JSON-RPC notifications have no id and expect no response+ if (!isDefined(id)) {+ return null;+ }+if (method === 'initialize') {return this.handleInitialize(id);}if (method === 'ping') {- return wrapJsonRpcResponse(- id,- {- result: {},+ return wrapJsonRpcResponse(id, { result: {} });+ }++ if (method === 'prompts/list') {+ return wrapJsonRpcResponse(id, {+ result: { prompts: [] },+ });+ }++ if (method === 'resources/list') {+ return wrapJsonRpcResponse(id, {+ result: { resources: [] },+ });+ }++ if (method !== 'tools/list' && method !== 'tools/call') {+ return wrapJsonRpcResponse(id, {+ error: {+ code: JSON_RPC_ERROR_CODE.METHOD_NOT_FOUND,+ message: `Method '${method}' not found`,},- true,- );+ });}const roleId = await this.getRoleId(@@ -197,7 +222,16 @@ export class McpProtocolService {userWorkspaceId,});- if (method === 'tools/call' && params) {+ if (method === 'tools/call') {+ if (!params) {+ return wrapJsonRpcResponse(id, {+ error: {+ code: JSON_RPC_ERROR_CODE.INVALID_PARAMS,+ message: 'tools/call requires params with name and arguments',+ },+ });+ }+return await this.mcpToolExecutorService.handleToolCall(id,toolSet,@@ -205,40 +239,22 @@ export class McpProtocolService {);}- if (method === 'tools/list') {- return this.mcpToolExecutorService.handleToolsListing(id, toolSet);- }-- if (method === 'prompts/list') {- return wrapJsonRpcResponse(id, {- result: {- capabilities: {- prompts: { listChanged: false },- },- prompts: [],- },- });- }-- if (method === 'resources/list') {- return wrapJsonRpcResponse(id, {- result: {- capabilities: {- resources: { listChanged: false },- },- resources: [],+ return this.mcpToolExecutorService.handleToolsListing(id, toolSet);+ } catch (error) {+ if (error instanceof HttpException) {+ return wrapJsonRpcResponse(id ?? 0, {+ error: {+ code: JSON_RPC_ERROR_CODE.SERVER_ERROR,+ message: error.message || 'Request failed',},});}- return wrapJsonRpcResponse(id, {- result: {},- });- } catch (error) {- return wrapJsonRpcResponse(id, {+ return wrapJsonRpcResponse(id ?? 0, {error: {- code: error.status || HttpStatus.INTERNAL_SERVER_ERROR,- message: error.message || 'Failed to execute tool',+ code: JSON_RPC_ERROR_CODE.INTERNAL_ERROR,+ message:+ error instanceof Error ? error.message : 'Internal server 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 297361f63eb..bc14645ce3b 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,9 @@-import { HttpException, HttpStatus, Injectable } from '@nestjs/common';+import { Injectable } from '@nestjs/common';import { type ToolSet } 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 { wrapJsonRpcResponse } from 'src/engine/api/mcp/utils/wrap-jsonrpc-response.util';@Injectable()@@ -15,29 +16,43 @@ export class McpToolExecutorService {const toolName = params.name as keyof typeof toolSet;const tool = toolSet[toolName];- if (isDefined(tool) && isDefined(tool.execute)) {+ if (!isDefined(tool) || !isDefined(tool.execute)) {+ return wrapJsonRpcResponse(id, {+ error: {+ code: JSON_RPC_ERROR_CODE.INVALID_PARAMS,+ message: `Unknown tool: ${String(params.name)}`,+ },+ });+ }++ try {+ const result = await tool.execute(params.arguments, {+ toolCallId: '1',+ messages: [],+ });++ return wrapJsonRpcResponse(id, {+ result: {+ content: [{ type: 'text', text: JSON.stringify(result) }],+ isError: false,+ },+ });+ } catch (executionError) {return wrapJsonRpcResponse(id, {result: {content: [{type: 'text',- text: JSON.stringify(- await tool.execute(params.arguments, {- toolCallId: '1',- messages: [],- }),- ),+ text:+ executionError instanceof Error+ ? executionError.message+ : 'Tool execution failed',},],- isError: false,+ isError: true,},});}-- throw new HttpException(- `Tool '${params.name}' not found`,- HttpStatus.NOT_FOUND,- );}handleToolsListing(id: string | number, toolSet: ToolSet) {@@ -63,12 +78,7 @@ export class McpToolExecutorService {return wrapJsonRpcResponse(id, {result: {- capabilities: {- tools: { listChanged: false },- },tools: toolsArray,- resources: [],- prompts: [],},});}diff --git a/packages/twenty-server/src/engine/api/mcp/utils/wrap-jsonrpc-response.util.ts b/packages/twenty-server/src/engine/api/mcp/utils/wrap-jsonrpc-response.util.tsindex 78a44a06410..4eaea1f97f9 100644--- a/packages/twenty-server/src/engine/api/mcp/utils/wrap-jsonrpc-response.util.ts+++ b/packages/twenty-server/src/engine/api/mcp/utils/wrap-jsonrpc-response.util.ts@@ -1,28 +1,12 @@-import { MCP_SERVER_METADATA } from 'src/engine/api/mcp/constants/mcp.const';-export const wrapJsonRpcResponse = (id: string | number,payload:| Record<'result', Record<string, unknown>>| Record<'error', Record<string, unknown>>,- omitMetadata = false,) => {- const body =- 'result' in payload- ? {- result: omitMetadata- ? payload.result- : { ...payload.result, ...MCP_SERVER_METADATA },- }- : {- error: omitMetadata- ? payload.error- : { ...payload.error, ...MCP_SERVER_METADATA },- };-return {id,jsonrpc: '2.0',- ...body,+ ...payload,};};diff --git a/packages/twenty-server/test/integration/ai/suites/mcp.controller.integration-spec.ts b/packages/twenty-server/test/integration/ai/suites/mcp.controller.integration-spec.tsindex e13692b7c2e..401ab608a90 100644--- a/packages/twenty-server/test/integration/ai/suites/mcp.controller.integration-spec.ts+++ b/packages/twenty-server/test/integration/ai/suites/mcp.controller.integration-spec.ts@@ -21,7 +21,7 @@ describe('MCP Controller (integration)', () => {it('should respond to ping with a JSON-RPC result envelope', async () => {await postMcp({ jsonrpc: '2.0', method: 'ping', id: '1' })- .expect(201)+ .expect(200).expect((res) => {expect(res.body).toMatchObject({id: '1',@@ -32,18 +32,26 @@ describe('MCP Controller (integration)', () => {});});- it('should respond to initialize with server metadata and capabilities', async () => {+ it('should respond to initialize with spec-compliant InitializeResult', async () => {await postMcp({ jsonrpc: '2.0', method: 'initialize', id: 123 })- .expect(201)+ .expect(200).expect((res) => {expect(res.body.id).toBe(123);expect(res.body.jsonrpc).toBe('2.0');expect(res.body.result).toBeDefined();- // Should include capabilities and server metadata fields merged by wrapJsonRpcResponse+ expect(res.body.result.protocolVersion).toBe('2024-11-05');expect(res.body.result.capabilities).toBeDefined();- expect(Array.isArray(res.body.result.tools)).toBe(true);- expect(Array.isArray(res.body.result.resources)).toBe(true);- expect(Array.isArray(res.body.result.prompts)).toBe(true);+ expect(res.body.result.serverInfo).toBeDefined();+ expect(res.body.result.serverInfo.name).toBe('Twenty MCP Server');+ expect(typeof res.body.result.instructions).toBe('string');+ });+ });++ it('should return 202 with no body for notifications/initialized (no id)', async () => {+ await postMcp({ jsonrpc: '2.0', method: 'notifications/initialized' })+ .expect(202)+ .expect((res) => {+ expect(res.body).toEqual({});});});@@ -61,12 +69,11 @@ describe('MCP Controller (integration)', () => {jsonrpc: '2.0',method: 'tools/list',id: 'tools-list-1',- }).expect(201);+ }).expect(200);expect(res.body.id).toBe('tools-list-1');expect(res.body.jsonrpc).toBe('2.0');expect(res.body.result).toBeDefined();- expect(res.body.result.capabilities?.tools?.listChanged).toBe(false);expect(Array.isArray(res.body.result.tools)).toBe(true);// In a seeded workspace, there should be at least one toolexpect(res.body.result.tools.length).toBeGreaterThanOrEqual(0);@@ -80,18 +87,17 @@ describe('MCP Controller (integration)', () => {}});- it('should return empty result for tools/call without params', async () => {+ it('should return invalid params error for tools/call without params', async () => {const res = await postMcp({jsonrpc: '2.0',method: 'tools/call',id: 'tools-call-empty',- }).expect(201);+ }).expect(200);- expect(res.body).toMatchObject({- id: 'tools-call-empty',- jsonrpc: '2.0',- result: {},- });+ expect(res.body.id).toBe('tools-call-empty');+ expect(res.body.jsonrpc).toBe('2.0');+ expect(res.body.error).toBeDefined();+ expect(res.body.error.code).toBe(-32602);});it('should return error when calling a non-existent tool', async () => {@@ -100,13 +106,12 @@ describe('MCP Controller (integration)', () => {method: 'tools/call',id: 'tools-call-missing',params: { name: 'non_existent_tool', arguments: {} },- }).expect(201);+ }).expect(200);expect(res.body.id).toBe('tools-call-missing');expect(res.body.jsonrpc).toBe('2.0');expect(res.body.error).toBeDefined();- // From McpService error wrapper: code = HttpStatus.NOT_FOUND (404) and message containing tool name- expect(res.body.error.code).toBe(404);+ expect(res.body.error.code).toBe(-32602);expect(String(res.body.error.message)).toMatch(/non_existent_tool/);});@@ -115,7 +120,7 @@ describe('MCP Controller (integration)', () => {jsonrpc: '2.0',method: 'tools/list',id: 'tools-list-for-calls',- }).expect(201);+ }).expect(200);const tools: Array<{ name: string }> = list.body.result.tools || [];@@ -130,7 +135,7 @@ describe('MCP Controller (integration)', () => {method: 'tools/call',id,params: { name: tool.name, arguments: {} },- }).expect(201);+ }).expect(200);expect(res.body.jsonrpc).toBe('2.0');expect(res.body.id).toBe(id);@@ -142,27 +147,21 @@ describe('MCP Controller (integration)', () => {}});- it('should list prompts and resources as empty arrays with listChanged=false', async () => {+ it('should list prompts and resources as empty arrays', async () => {const prompts = await postMcp({jsonrpc: '2.0',method: 'prompts/list',id: 'prompts-1',- }).expect(201);+ }).expect(200);- expect(prompts.body.result.capabilities?.prompts?.listChanged).toBe(- false,- );expect(Array.isArray(prompts.body.result.prompts)).toBe(true);const resources = await postMcp({jsonrpc: '2.0',method: 'resources/list',id: 'resources-1',- }).expect(201);+ }).expect(200);- expect(resources.body.result.capabilities?.resources?.listChanged).toBe(- false,- );expect(Array.isArray(resources.body.result.resources)).toBe(true);});});