Insforge MCP Server

Instructions

Implementation Reference

• src/shared/tools.ts:599-669 (registration)

  Registration of the 'bulk-upsert' MCP tool, including name, description, Zod input schema (apiKey, table, upsertKey from schema, filePath), and handler function wrapped with usage tracking.

  server.tool(
    'bulk-upsert',
    'Bulk insert or update data from CSV or JSON file. Supports upsert operations with a unique key.',
    {
      apiKey: z
        .string()
        .optional()
        .describe('API key for authentication (optional if provided via --api_key)'),
      ...bulkUpsertRequestSchema.shape,
      filePath: z.string().describe('Path to CSV or JSON file containing data to import'),
    },
    withUsageTracking('bulk-upsert', async ({ apiKey, table, filePath, upsertKey }) => {
      try {
        const actualApiKey = getApiKey(apiKey);
        
        // Read the file
        const fileBuffer = await fs.readFile(filePath);
        const fileName = filePath.split('/').pop() || 'data.csv';
        
        // Create form data for multipart upload
        const formData = new FormData();
        formData.append('file', fileBuffer, fileName);
        formData.append('table', table);
        if (upsertKey) {
          formData.append('upsertKey', upsertKey);
        }
        
        const response = await fetch(`${API_BASE_URL}/api/database/advance/bulk-upsert`, {
          method: 'POST',
          headers: {
            'x-api-key': actualApiKey,
            ...formData.getHeaders(),
          },
          body: formData,
        });
        
        const result = await handleApiResponse(response);
        
        // Format the result message
        const message = result.success
          ? `Successfully processed ${result.rowsAffected} of ${result.totalRecords} records into table "${result.table}"`
          : result.message || 'Bulk upsert operation completed';
  
        return await addBackgroundContext({
          content: [
            {
              type: 'text',
              text: formatSuccessMessage('Bulk upsert completed', {
                message,
                table: result.table,
                rowsAffected: result.rowsAffected,
                totalRecords: result.totalRecords,
                errors: result.errors,
              }),
            },
          ],
        });
      } catch (error) {
        const errMsg = error instanceof Error ? error.message : 'Unknown error occurred';
        return {
          content: [
            {
              type: 'text',
              text: `Error performing bulk upsert: ${errMsg}`,
            },
          ],
          isError: true,
        };
      }
    })
  );

• src/shared/tools.ts:610-668 (handler)

  The handler function for bulk-upsert tool. Reads the input file, creates multipart form data with file, table, and upsertKey, sends POST request to backend API endpoint for bulk upsert, handles response, and returns formatted success or error message.

  withUsageTracking('bulk-upsert', async ({ apiKey, table, filePath, upsertKey }) => {
    try {
      const actualApiKey = getApiKey(apiKey);
      
      // Read the file
      const fileBuffer = await fs.readFile(filePath);
      const fileName = filePath.split('/').pop() || 'data.csv';
      
      // Create form data for multipart upload
      const formData = new FormData();
      formData.append('file', fileBuffer, fileName);
      formData.append('table', table);
      if (upsertKey) {
        formData.append('upsertKey', upsertKey);
      }
      
      const response = await fetch(`${API_BASE_URL}/api/database/advance/bulk-upsert`, {
        method: 'POST',
        headers: {
          'x-api-key': actualApiKey,
          ...formData.getHeaders(),
        },
        body: formData,
      });
      
      const result = await handleApiResponse(response);
      
      // Format the result message
      const message = result.success
        ? `Successfully processed ${result.rowsAffected} of ${result.totalRecords} records into table "${result.table}"`
        : result.message || 'Bulk upsert operation completed';
  
      return await addBackgroundContext({
        content: [
          {
            type: 'text',
            text: formatSuccessMessage('Bulk upsert completed', {
              message,
              table: result.table,
              rowsAffected: result.rowsAffected,
              totalRecords: result.totalRecords,
              errors: result.errors,
            }),
          },
        ],
      });
    } catch (error) {
      const errMsg = error instanceof Error ? error.message : 'Unknown error occurred';
      return {
        content: [
          {
            type: 'text',
            text: `Error performing bulk upsert: ${errMsg}`,
          },
        ],
        isError: true,
      };
    }
  })

• src/shared/tools.ts:602-609 (schema)

  Input parameters schema using Zod: optional apiKey, fields from imported bulkUpsertRequestSchema (likely table and upsertKey), and required filePath pointing to CSV or JSON data file.

  {
    apiKey: z
      .string()
      .optional()
      .describe('API key for authentication (optional if provided via --api_key)'),
    ...bulkUpsertRequestSchema.shape,
    filePath: z.string().describe('Path to CSV or JSON file containing data to import'),
  },