feat(mcp-server): add create tool

alban bertolini · claude · alban bertolini · commit 1cc4c5b76e74 · 2025-12-23T17:17:30.000+01:00
Add a new MCP tool to create records in a collection: - Accepts collectionName and attributes object - Handles LLM sending attributes as JSON string - Activity logging with 'create' action - Returns the created record 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts
@@ -20,6 +20,7 @@ import * as http from 'http';
 
 import ForestOAuthProvider from './forest-oauth-provider';
 import { isMcpRoute } from './mcp-paths';
+import declareCreateTool from './tools/create';
 import declareDescribeCollectionTool from './tools/describe-collection';
 import declareListTool from './tools/list';
 import declareListRelatedTool from './tools/list-related';
@@ -51,6 +52,7 @@ const defaultLogger: Logger = (level, message) => {
 const SAFE_ARGUMENTS_FOR_LOGGING: Record<string, string[]> = {
   list: ['collectionName'],
   listRelated: ['collectionName', 'relationName', 'parentRecordId'],
+  create: ['collectionName'],
   describeCollection: ['collectionName'],
 };
 
@@ -131,6 +133,7 @@ export default class ForestMCPServer {
     );
     declareListTool(this.mcpServer, this.forestServerUrl, this.logger, collectionNames);
     declareListRelatedTool(this.mcpServer, this.forestServerUrl, this.logger, collectionNames);
+    declareCreateTool(this.mcpServer, this.forestServerUrl, this.logger, collectionNames);
   }
 
   private ensureSecretsAreSet(): { envSecret: string; authSecret: string } {
diff --git a/packages/mcp-server/src/tools/create.ts b/packages/mcp-server/src/tools/create.ts
@@ -0,0 +1,73 @@
+import type { Logger } from '../server';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import { z } from 'zod';
+
+import createActivityLog from '../utils/activity-logs-creator.js';
+import buildClient from '../utils/agent-caller.js';
+import parseAgentError from '../utils/error-parser.js';
+import registerToolWithLogging from '../utils/tool-with-logging.js';
+
+// Preprocess to handle LLM sending attributes as JSON string instead of object
+const attributesWithPreprocess = z.preprocess(val => {
+  if (typeof val !== 'string') return val;
+
+  try {
+    return JSON.parse(val);
+  } catch {
+    return val;
+  }
+}, z.record(z.string(), z.unknown()));
+
+interface CreateArgument {
+  collectionName: string;
+  attributes: Record<string, unknown>;
+}
+
+function createArgumentShape(collectionNames: string[]) {
+  return {
+    collectionName:
+      collectionNames.length > 0 ? z.enum(collectionNames as [string, ...string[]]) : z.string(),
+    attributes: attributesWithPreprocess.describe(
+      'The attributes of the record to create. Must be an object with field names as keys.',
+    ),
+  };
+}
+
+export default function declareCreateTool(
+  mcpServer: McpServer,
+  forestServerUrl: string,
+  logger: Logger,
+  collectionNames: string[] = [],
+): void {
+  const argumentShape = createArgumentShape(collectionNames);
+
+  registerToolWithLogging(
+    mcpServer,
+    'create',
+    {
+      title: 'Create a record',
+      description: 'Create a new record in the specified collection.',
+      inputSchema: argumentShape,
+    },
+    async (options: CreateArgument, extra) => {
+      const { rpcClient } = await buildClient(extra);
+
+      await createActivityLog(forestServerUrl, extra, 'create', {
+        collectionName: options.collectionName,
+      });
+
+      try {
+        const record = await rpcClient
+          .collection(options.collectionName)
+          .create(options.attributes);
+
+        return { content: [{ type: 'text', text: JSON.stringify({ record }) }] };
+      } catch (error) {
+        const errorDetail = parseAgentError(error);
+        throw errorDetail ? new Error(errorDetail) : error;
+      }
+    },
+    logger,
+  );
+}
diff --git a/packages/mcp-server/test/tools/create.test.ts b/packages/mcp-server/test/tools/create.test.ts
@@ -0,0 +1,264 @@
+import type { Logger } from '../../src/server';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol';
+import type { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types';
+
+import declareCreateTool from '../../src/tools/create';
+import createActivityLog from '../../src/utils/activity-logs-creator';
+import buildClient from '../../src/utils/agent-caller';
+
+jest.mock('../../src/utils/agent-caller');
+jest.mock('../../src/utils/activity-logs-creator');
+
+const mockLogger: Logger = jest.fn();
+
+const mockBuildClient = buildClient as jest.MockedFunction<typeof buildClient>;
+const mockCreateActivityLog = createActivityLog as jest.MockedFunction<typeof createActivityLog>;
+
+describe('declareCreateTool', () => {
+  let mcpServer: McpServer;
+  let registeredToolHandler: (options: unknown, extra: unknown) => Promise<unknown>;
+  let registeredToolConfig: { title: string; description: string; inputSchema: unknown };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    mcpServer = {
+      registerTool: jest.fn((name, config, handler) => {
+        registeredToolConfig = config;
+        registeredToolHandler = handler;
+      }),
+    } as unknown as McpServer;
+
+    mockCreateActivityLog.mockResolvedValue(undefined);
+  });
+
+  describe('tool registration', () => {
+    it('should register a tool named "create"', () => {
+      declareCreateTool(mcpServer, 'https://api.forestadmin.com', mockLogger);
+
+      expect(mcpServer.registerTool).toHaveBeenCalledWith(
+        'create',
+        expect.any(Object),
+        expect.any(Function),
+      );
+    });
+
+    it('should register tool with correct title and description', () => {
+      declareCreateTool(mcpServer, 'https://api.forestadmin.com', mockLogger);
+
+      expect(registeredToolConfig.title).toBe('Create a record');
+      expect(registeredToolConfig.description).toBe(
+        'Create a new record in the specified collection.',
+      );
+    });
+
+    it('should define correct input schema', () => {
+      declareCreateTool(mcpServer, 'https://api.forestadmin.com', mockLogger);
+
+      expect(registeredToolConfig.inputSchema).toHaveProperty('collectionName');
+      expect(registeredToolConfig.inputSchema).toHaveProperty('attributes');
+    });
+
+    it('should use string type for collectionName when no collection names provided', () => {
+      declareCreateTool(mcpServer, 'https://api.forestadmin.com', mockLogger);
+
+      const schema = registeredToolConfig.inputSchema as Record<
+        string,
+        { options?: string[]; parse: (value: unknown) => unknown }
+      >;
+      expect(schema.collectionName.options).toBeUndefined();
+      expect(() => schema.collectionName.parse('any-collection')).not.toThrow();
+    });
+
+    it('should use enum type for collectionName when collection names provided', () => {
+      declareCreateTool(mcpServer, 'https://api.forestadmin.com', mockLogger, [
+        'users',
+        'products',
+      ]);
+
+      const schema = registeredToolConfig.inputSchema as Record<
+        string,
+        { options: string[]; parse: (value: unknown) => unknown }
+      >;
+      expect(schema.collectionName.options).toEqual(['users', 'products']);
+      expect(() => schema.collectionName.parse('users')).not.toThrow();
+      expect(() => schema.collectionName.parse('invalid-collection')).toThrow();
+    });
+  });
+
+  describe('tool execution', () => {
+    const mockExtra = {
+      authInfo: {
+        token: 'test-token',
+        extra: {
+          forestServerToken: 'forest-token',
+          renderingId: '123',
+        },
+      },
+    } as unknown as RequestHandlerExtra<ServerRequest, ServerNotification>;
+
+    beforeEach(() => {
+      declareCreateTool(mcpServer, 'https://api.forestadmin.com', mockLogger);
+    });
+
+    it('should call buildClient with the extra parameter', async () => {
+      const mockCreate = jest.fn().mockResolvedValue({ id: 1, name: 'New Record' });
+      const mockCollection = jest.fn().mockReturnValue({ create: mockCreate });
+      mockBuildClient.mockReturnValue({
+        rpcClient: { collection: mockCollection },
+        authData: { userId: 1, renderingId: '123', environmentId: 1, projectId: 1 },
+      } as unknown as ReturnType<typeof buildClient>);
+
+      await registeredToolHandler(
+        { collectionName: 'users', attributes: { name: 'John' } },
+        mockExtra,
+      );
+
+      expect(mockBuildClient).toHaveBeenCalledWith(mockExtra);
+    });
+
+    it('should call rpcClient.collection with the collection name', async () => {
+      const mockCreate = jest.fn().mockResolvedValue({ id: 1, name: 'New Record' });
+      const mockCollection = jest.fn().mockReturnValue({ create: mockCreate });
+      mockBuildClient.mockReturnValue({
+        rpcClient: { collection: mockCollection },
+        authData: { userId: 1, renderingId: '123', environmentId: 1, projectId: 1 },
+      } as unknown as ReturnType<typeof buildClient>);
+
+      await registeredToolHandler(
+        { collectionName: 'products', attributes: { name: 'Product' } },
+        mockExtra,
+      );
+
+      expect(mockCollection).toHaveBeenCalledWith('products');
+    });
+
+    it('should call create with the attributes', async () => {
+      const mockCreate = jest
+        .fn()
+        .mockResolvedValue({ id: 1, name: 'John', email: 'john@test.com' });
+      const mockCollection = jest.fn().mockReturnValue({ create: mockCreate });
+      mockBuildClient.mockReturnValue({
+        rpcClient: { collection: mockCollection },
+        authData: { userId: 1, renderingId: '123', environmentId: 1, projectId: 1 },
+      } as unknown as ReturnType<typeof buildClient>);
+
+      const attributes = { name: 'John', email: 'john@test.com' };
+      await registeredToolHandler({ collectionName: 'users', attributes }, mockExtra);
+
+      expect(mockCreate).toHaveBeenCalledWith(attributes);
+    });
+
+    it('should return the created record as JSON text content', async () => {
+      const createdRecord = { id: 1, name: 'John', email: 'john@test.com' };
+      const mockCreate = jest.fn().mockResolvedValue(createdRecord);
+      const mockCollection = jest.fn().mockReturnValue({ create: mockCreate });
+      mockBuildClient.mockReturnValue({
+        rpcClient: { collection: mockCollection },
+        authData: { userId: 1, renderingId: '123', environmentId: 1, projectId: 1 },
+      } as unknown as ReturnType<typeof buildClient>);
+
+      const result = await registeredToolHandler(
+        { collectionName: 'users', attributes: { name: 'John', email: 'john@test.com' } },
+        mockExtra,
+      );
+
+      expect(result).toEqual({
+        content: [{ type: 'text', text: JSON.stringify({ record: createdRecord }) }],
+      });
+    });
+
+    describe('activity logging', () => {
+      beforeEach(() => {
+        const mockCreate = jest.fn().mockResolvedValue({ id: 1 });
+        const mockCollection = jest.fn().mockReturnValue({ create: mockCreate });
+        mockBuildClient.mockReturnValue({
+          rpcClient: { collection: mockCollection },
+          authData: { userId: 1, renderingId: '123', environmentId: 1, projectId: 1 },
+        } as unknown as ReturnType<typeof buildClient>);
+      });
+
+      it('should create activity log with "create" action type', async () => {
+        await registeredToolHandler(
+          { collectionName: 'users', attributes: { name: 'John' } },
+          mockExtra,
+        );
+
+        expect(mockCreateActivityLog).toHaveBeenCalledWith(
+          'https://api.forestadmin.com',
+          mockExtra,
+          'create',
+          { collectionName: 'users' },
+        );
+      });
+    });
+
+    describe('attributes parsing', () => {
+      it('should parse attributes sent as JSON string (LLM workaround)', () => {
+        const attributes = { name: 'John', age: 30 };
+        const attributesAsString = JSON.stringify(attributes);
+
+        const inputSchema = registeredToolConfig.inputSchema as Record<
+          string,
+          { parse: (value: unknown) => unknown }
+        >;
+        const parsedAttributes = inputSchema.attributes.parse(attributesAsString);
+
+        expect(parsedAttributes).toEqual(attributes);
+      });
+
+      it('should handle attributes as object when not sent as string', async () => {
+        const mockCreate = jest.fn().mockResolvedValue({ id: 1 });
+        const mockCollection = jest.fn().mockReturnValue({ create: mockCreate });
+        mockBuildClient.mockReturnValue({
+          rpcClient: { collection: mockCollection },
+          authData: { userId: 1, renderingId: '123', environmentId: 1, projectId: 1 },
+        } as unknown as ReturnType<typeof buildClient>);
+
+        const attributes = { name: 'John', age: 30 };
+        await registeredToolHandler({ collectionName: 'users', attributes }, mockExtra);
+
+        expect(mockCreate).toHaveBeenCalledWith(attributes);
+      });
+    });
+
+    describe('error handling', () => {
+      it('should parse error with nested error.text structure in message', async () => {
+        const errorPayload = {
+          error: {
+            status: 400,
+            text: JSON.stringify({
+              errors: [{ name: 'ValidationError', detail: 'Name is required' }],
+            }),
+          },
+        };
+        const agentError = new Error(JSON.stringify(errorPayload));
+        const mockCreate = jest.fn().mockRejectedValue(agentError);
+        const mockCollection = jest.fn().mockReturnValue({ create: mockCreate });
+        mockBuildClient.mockReturnValue({
+          rpcClient: { collection: mockCollection },
+          authData: { userId: 1, renderingId: '123', environmentId: 1, projectId: 1 },
+        } as unknown as ReturnType<typeof buildClient>);
+
+        await expect(
+          registeredToolHandler({ collectionName: 'users', attributes: {} }, mockExtra),
+        ).rejects.toThrow('Name is required');
+      });
+
+      it('should rethrow original error when no parsable error found', async () => {
+        const agentError = { unknownProperty: 'some value' };
+        const mockCreate = jest.fn().mockRejectedValue(agentError);
+        const mockCollection = jest.fn().mockReturnValue({ create: mockCreate });
+        mockBuildClient.mockReturnValue({
+          rpcClient: { collection: mockCollection },
+          authData: { userId: 1, renderingId: '123', environmentId: 1, projectId: 1 },
+        } as unknown as ReturnType<typeof buildClient>);
+
+        await expect(
+          registeredToolHandler({ collectionName: 'users', attributes: {} }, mockExtra),
+        ).rejects.toEqual(agentError);
+      });
+    });
+  });
+});
