feat(ai): add mcp-metadata (#13150)

Co-authored-by: Félix Malfait <felix@twenty.com>
2025-07-16 21:32:32 +02:00
parent b25f50e288
commit 11abe5440b
50 changed files with 1288 additions and 230 deletions
@@ -0,0 +1,220 @@
+import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
+
+import { Request } from 'express';
+import { validationMetadatasToSchemas } from 'class-validator-jsonschema';
+import { JSONSchema7 } from 'json-schema';
+
+import { Workspace } from 'src/engine/core-modules/workspace/workspace.entity';
+import { wrapJsonRpcResponse } from 'src/engine/core-modules/ai/utils/wrap-jsonrpc-response.util';
+import { FeatureFlagKey } from 'src/engine/core-modules/feature-flag/enums/feature-flag-key.enum';
+import { FeatureFlagService } from 'src/engine/core-modules/feature-flag/services/feature-flag.service';
+import { CreateToolsService } from 'src/engine/api/mcp/services/tools/create.tools.service';
+import { UpdateToolsService } from 'src/engine/api/mcp/services/tools/update.tools.service';
+import { DeleteToolsService } from 'src/engine/api/mcp/services/tools/delete.tools.service';
+import { GetToolsService } from 'src/engine/api/mcp/services/tools/get.tools.service';
+import { MetricsService } from 'src/engine/core-modules/metrics/metrics.service';
+import { MetricsKeys } from 'src/engine/core-modules/metrics/types/metrics-keys.type';
+
+@Injectable()
+export class MCPMetadataService {
+  schemas: Record<string, JSONSchema7>;
+
+  constructor(
+    private readonly featureFlagService: FeatureFlagService,
+    private readonly createToolsService: CreateToolsService,
+    private readonly updateToolsService: UpdateToolsService,
+    private readonly deleteToolsService: DeleteToolsService,
+    private readonly getToolsService: GetToolsService,
+    private readonly metricsService: MetricsService,
+  ) {}
+
+  async onModuleInit() {
+    this.schemas = validationMetadatasToSchemas() as Record<
+      string,
+      JSONSchema7
+    >;
+  }
+
+  async checkAiEnabled(workspaceId: string): Promise<void> {
+    const isAiEnabled = await this.featureFlagService.isFeatureEnabled(
+      FeatureFlagKey.IS_AI_ENABLED,
+      workspaceId,
+    );
+
+    if (!isAiEnabled) {
+      throw new HttpException(
+        'AI feature is not enabled for this workspace',
+        HttpStatus.FORBIDDEN,
+      );
+    }
+  }
+
+  handleInitialize(requestId: string | number | null) {
+    return wrapJsonRpcResponse(requestId, {
+      result: {
+        capabilities: {
+          tools: { listChanged: false },
+          resources: { listChanged: false },
+          prompts: { listChanged: false },
+        },
+      },
+    });
+  }
+
+  get commonProperties() {
+    return {
+      fields: {
+        type: 'array',
+        items: {
+          type: 'string',
+          description:
+            'Names of field properties to include in the response for field entities. ',
+          examples: [
+            'type',
+            'name',
+            'label',
+            'description',
+            'icon',
+            'isCustom',
+            'isActive',
+            'isSystem',
+            'isNullable',
+            'createdAt',
+            'updatedAt',
+            'defaultValue',
+            'options',
+            'relation',
+          ],
+        },
+        description:
+          'List of field names to select in the query for field entity. Strongly recommended to limit token usage and reduce response size. Use this to include only the properties you need.',
+      },
+      objects: {
+        type: 'array',
+        items: {
+          type: 'string',
+          description:
+            'Object property names to include in the response for object entities.',
+          examples: [
+            'dataSourceId',
+            'nameSingular',
+            'namePlural',
+            'labelSingular',
+            'labelPlural',
+            'description',
+            'icon',
+            'isCustom',
+            'isActive',
+            'isSystem',
+            'createdAt',
+            'updatedAt',
+            'labelIdentifierFieldMetadataId',
+            'imageIdentifierFieldMetadataId',
+          ],
+        },
+        description:
+          'List of object properties to select in the query for object entities. Strongly recommended to limit token usage and reduce response size. Specify only the necessary properties to optimize your request.',
+      },
+    };
+  }
+
+  get tools() {
+    return [
+      ...this.createToolsService.tools,
+      ...this.updateToolsService.tools,
+      ...this.deleteToolsService.tools,
+      ...this.getToolsService.tools,
+    ];
+  }
+
+  async handleToolCall(
+    request: Request,
+  ): Promise<Parameters<typeof wrapJsonRpcResponse>[1]> {
+    const tool = this.tools.find(
+      ({ name }) => name === request.body.params.name,
+    );
+
+    if (tool) {
+      try {
+        const result = await tool.execute(request);
+
+        await this.metricsService.incrementCounter({
+          key: MetricsKeys.AIToolExecutionSucceeded,
+          attributes: {
+            tool: request.body.params.name,
+          },
+        });
+
+        return { result };
+      } catch (err) {
+        await this.metricsService.incrementCounter({
+          key: MetricsKeys.AIToolExecutionFailed,
+          attributes: {
+            tool: request.body.params.name,
+          },
+        });
+      }
+    }
+
+    return {
+      error: {
+        code: HttpStatus.NOT_FOUND,
+        message: `Tool ${request.body.params.name} not found`,
+      },
+    };
+  }
+
+  async listTools(request: Request) {
+    return wrapJsonRpcResponse(request.body.id, {
+      result: {
+        capabilities: {
+          tools: { listChanged: false },
+        },
+        commonProperties: this.commonProperties,
+        tools: Object.values(this.tools),
+      },
+    });
+  }
+
+  async handleMCPQuery(
+    request: Request,
+    {
+      workspace,
+    }: { workspace: Workspace; userWorkspaceId?: string; apiKey?: string },
+  ): Promise<Record<string, unknown>> {
+    try {
+      await this.checkAiEnabled(workspace.id);
+
+      if (request.body.method === 'initialize') {
+        return this.handleInitialize(request.body.id);
+      }
+
+      if (request.body.method === 'ping') {
+        return wrapJsonRpcResponse(
+          request.body.id,
+          {
+            result: {},
+          },
+          true,
+        );
+      }
+
+      if (request.body.method === 'tools/call' && request.body.params) {
+        return wrapJsonRpcResponse(
+          request.body.id,
+          await this.handleToolCall(request),
+        );
+      }
+
+      return this.listTools(request);
+    } catch (error) {
+      return wrapJsonRpcResponse(request.body.id, {
+        error: {
+          code: error.status || HttpStatus.INTERNAL_SERVER_ERROR,
+          message:
+            error.response?.messages?.join?.('\n') || 'Failed to execute tool',
+        },
+      });
+    }
+  }
+}
@@ -0,0 +1,58 @@
+import { Injectable } from '@nestjs/common';
+
+import { Request } from 'express';
+import pick from 'lodash.pick';
+
+import { MetadataQueryBuilderFactory } from 'src/engine/api/rest/metadata/query-builder/metadata-query-builder.factory';
+import { MCPMetadataToolsService } from 'src/engine/api/mcp/services/tools/mcp-metadata-tools.service';
+import { validationSchemaManager } from 'src/engine/api/mcp/utils/get-json-schema';
+import { ObjectName } from 'src/engine/api/rest/metadata/types/metadata-entity.type';
+
+@Injectable()
+export class CreateToolsService {
+  constructor(
+    private readonly metadataQueryBuilderFactory: MetadataQueryBuilderFactory,
+    private readonly mCPMetadataToolsService: MCPMetadataToolsService,
+  ) {}
+
+  get tools() {
+    return [
+      {
+        name: 'create-field-metadata',
+        description: 'Create a new field metadata',
+        inputSchema:
+          this.mCPMetadataToolsService.mergeSchemaWithCommonProperties(
+            validationSchemaManager.getSchemas().CreateFieldInput,
+          ),
+        execute: (request: Request) => this.execute(request, 'fields'),
+      },
+      {
+        name: 'create-object-metadata',
+        description: 'Create a new object metadata',
+        inputSchema:
+          this.mCPMetadataToolsService.mergeSchemaWithCommonProperties(
+            validationSchemaManager.getSchemas().CreateObjectInput,
+          ),
+        execute: (request: Request) => this.execute(request, 'objects'),
+      },
+    ];
+  }
+
+  async execute(request: Request, objectName: ObjectName) {
+    const requestContext = {
+      body: request.body.params.arguments,
+      baseUrl: this.mCPMetadataToolsService.generateBaseUrl(request),
+      path: `/rest/metadata/${objectName}`,
+      headers: request.headers,
+    };
+    const response = await this.mCPMetadataToolsService.send(
+      requestContext,
+      await this.metadataQueryBuilderFactory.create(
+        requestContext,
+        pick(request.body.params.arguments, ['fields', 'objects']),
+      ),
+    );
+
+    return response.data.data;
+  }
+}
@@ -0,0 +1,55 @@
+import { Injectable } from '@nestjs/common';
+
+import { Request } from 'express';
+
+import { MetadataQueryBuilderFactory } from 'src/engine/api/rest/metadata/query-builder/metadata-query-builder.factory';
+import { MCPMetadataToolsService } from 'src/engine/api/mcp/services/tools/mcp-metadata-tools.service';
+import { validationSchemaManager } from 'src/engine/api/mcp/utils/get-json-schema';
+import { ObjectName } from 'src/engine/api/rest/metadata/types/metadata-entity.type';
+
+@Injectable()
+export class DeleteToolsService {
+  constructor(
+    private readonly metadataQueryBuilderFactory: MetadataQueryBuilderFactory,
+    private readonly mCPMetadataToolsService: MCPMetadataToolsService,
+  ) {}
+
+  get tools() {
+    return [
+      {
+        name: 'delete-field-metadata',
+        description: 'Delete a field metadata',
+        inputSchema:
+          this.mCPMetadataToolsService.mergeSchemaWithCommonProperties(
+            validationSchemaManager.getSchemas().DeleteOneFieldInput,
+          ),
+        execute: (request: Request) => this.execute(request, 'fields'),
+      },
+      {
+        name: 'delete-object-metadata',
+        description: 'Delete an object metadata',
+        inputSchema:
+          this.mCPMetadataToolsService.mergeSchemaWithCommonProperties(
+            validationSchemaManager.getSchemas().DeleteOneObjectInput,
+          ),
+        execute: (request: Request) => this.execute(request, 'objects'),
+      },
+    ];
+  }
+
+  async execute(request: Request, objectName: ObjectName) {
+    const requestContext = {
+      body: request.body.params.arguments,
+      baseUrl: this.mCPMetadataToolsService.generateBaseUrl(request),
+      path: `/rest/metadata/${objectName}/${request.body.params.arguments.id}`,
+      headers: request.headers,
+    };
+
+    const response = await this.mCPMetadataToolsService.send(
+      requestContext,
+      await this.metadataQueryBuilderFactory.delete(requestContext),
+    );
+
+    return response.data.data;
+  }
+}
@@ -0,0 +1,95 @@
+import { Injectable } from '@nestjs/common';
+
+import { Request } from 'express';
+import pick from 'lodash.pick';
+
+import { MetadataQueryBuilderFactory } from 'src/engine/api/rest/metadata/query-builder/metadata-query-builder.factory';
+import { MCPMetadataToolsService } from 'src/engine/api/mcp/services/tools/mcp-metadata-tools.service';
+import { ObjectName } from 'src/engine/api/rest/metadata/types/metadata-entity.type';
+
+@Injectable()
+export class GetToolsService {
+  constructor(
+    private readonly metadataQueryBuilderFactory: MetadataQueryBuilderFactory,
+    private readonly mCPMetadataToolsService: MCPMetadataToolsService,
+  ) {}
+
+  get tools() {
+    const validationSchema =
+      this.mCPMetadataToolsService.mergeSchemaWithCommonProperties({
+        type: 'object',
+        properties: {
+          id: {
+            type: 'string',
+            format: 'uuid',
+            description: 'Unique identifier for the resource, in UUID format.',
+          },
+          limit: {
+            type: 'integer',
+            minimum: 0,
+            default: 100,
+            description:
+              'The maximum number of items to return in the response',
+          },
+          starting_after: {
+            type: 'string',
+            description:
+              'A cursor for paginating results. Provide the starting_after value returned by the previous request to fetch subsequent items.',
+          },
+          ending_before: {
+            type: 'string',
+            description:
+              'A cursor for paginating results. Provide the ending_before value returned by the previous request to fetch subsequent items.',
+          },
+        },
+        dependencies: {
+          starting_after: {
+            not: {
+              required: ['ending_before'],
+            },
+          },
+          ending_before: {
+            not: {
+              required: ['starting_after'],
+            },
+          },
+        },
+        additionalProperties: false,
+      });
+
+    return [
+      {
+        name: 'get-field-metadata',
+        description: 'Find fields metadata',
+        inputSchema: validationSchema,
+        execute: (request: Request) => this.execute(request, 'fields'),
+      },
+      {
+        name: 'get-object-metadata',
+        description: 'Find objects metadata',
+        inputSchema: validationSchema,
+        execute: (request: Request) => this.execute(request, 'objects'),
+      },
+    ];
+  }
+
+  async execute(request: Request, objectName: ObjectName) {
+    const requestContext = {
+      body: request.body.params.arguments,
+      baseUrl: this.mCPMetadataToolsService.generateBaseUrl(request),
+      path: `/rest/metadata/${objectName}${request.body.params.arguments.id ? `/${request.body.params.arguments.id}` : ''}`,
+      query: request.body.params.arguments,
+      headers: request.headers,
+    };
+
+    const response = await this.mCPMetadataToolsService.send(
+      requestContext,
+      await this.metadataQueryBuilderFactory.get(
+        requestContext,
+        pick(request.body.params.arguments, ['fields', 'objects']),
+      ),
+    );
+
+    return response.data.data;
+  }
+}
@@ -0,0 +1,51 @@
+import { Injectable } from '@nestjs/common';
+
+import { Request } from 'express';
+import { JSONSchema7 } from 'json-schema';
+
+import { RequestContext } from 'src/engine/api/rest/types/RequestContext';
+import {
+  RestApiService,
+  GraphqlApiType,
+} from 'src/engine/api/rest/rest-api.service';
+import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twenty-config.service';
+import { getServerUrl } from 'src/utils/get-server-url';
+import { Query } from 'src/engine/api/rest/core/types/query.type';
+
+@Injectable()
+export class MCPMetadataToolsService {
+  constructor(
+    protected readonly restApiService: RestApiService,
+    protected readonly twentyConfigService: TwentyConfigService,
+  ) {}
+
+  mergeSchemaWithCommonProperties(schema: JSONSchema7) {
+    return {
+      ...schema,
+      properties: {
+        ...schema.properties,
+        fields: {
+          $ref: '#/result/commonProperties/fields',
+        },
+        objects: {
+          $ref: '#/result/commonProperties/objects',
+        },
+      },
+    };
+  }
+
+  generateBaseUrl(request: Request) {
+    return getServerUrl(
+      this.twentyConfigService.get('SERVER_URL'),
+      `${request.protocol}://${request.get('host')}`,
+    );
+  }
+
+  async send(requestContext: RequestContext, data: Query) {
+    return await this.restApiService.call(
+      GraphqlApiType.METADATA,
+      requestContext,
+      data,
+    );
+  }
+}
@@ -0,0 +1,72 @@
+import { Injectable } from '@nestjs/common';
+
+import { Request } from 'express';
+import omit from 'lodash.omit';
+import pick from 'lodash.pick';
+
+import { MetadataQueryBuilderFactory } from 'src/engine/api/rest/metadata/query-builder/metadata-query-builder.factory';
+import { MCPMetadataToolsService } from 'src/engine/api/mcp/services/tools/mcp-metadata-tools.service';
+import { validationSchemaManager } from 'src/engine/api/mcp/utils/get-json-schema';
+import { ObjectName } from 'src/engine/api/rest/metadata/types/metadata-entity.type';
+
+@Injectable()
+export class UpdateToolsService {
+  constructor(
+    private readonly metadataQueryBuilderFactory: MetadataQueryBuilderFactory,
+    private readonly mCPMetadataToolsService: MCPMetadataToolsService,
+  ) {}
+
+  get tools() {
+    return [
+      {
+        name: 'update-field-metadata',
+        description: 'Update a field metadata',
+        inputSchema:
+          this.mCPMetadataToolsService.mergeSchemaWithCommonProperties({
+            ...validationSchemaManager.getSchemas().UpdateOneFieldMetadataInput,
+            properties: omit(
+              validationSchemaManager.getSchemas().FieldMetadataDTO.properties,
+              [
+                'id',
+                'type',
+                'createdAt',
+                'updatedAt',
+                'isCustom',
+                'standardOverrides',
+              ],
+            ),
+          }),
+        execute: (request: Request) => this.execute(request, 'fields'),
+      },
+      {
+        name: 'update-object-metadata',
+        description: 'Update an object metadata',
+        inputSchema:
+          this.mCPMetadataToolsService.mergeSchemaWithCommonProperties(
+            validationSchemaManager.getSchemas().UpdateOneObjectInput,
+          ),
+        execute: (request: Request) => this.execute(request, 'objects'),
+      },
+    ];
+  }
+
+  async execute(request: Request, objectName: ObjectName) {
+    const { id, ...body } = request.body.params.arguments;
+    const requestContext = {
+      body,
+      baseUrl: this.mCPMetadataToolsService.generateBaseUrl(request),
+      path: `/rest/metadata/${objectName}/${id}`,
+      headers: request.headers,
+    };
+
+    const response = await this.mCPMetadataToolsService.send(
+      requestContext,
+      await this.metadataQueryBuilderFactory.update(
+        requestContext,
+        pick(request.body.params.arguments, ['fields', 'objects']),
+      ),
+    );
+
+    return response.data.data;
+  }
+}