Dataverse MCP Server

Instructions

Implementation Reference

• src/tools/autonumber-tools.ts:180-242 (handler)

  Core handler logic for the 'update_autonumber_format' tool. Retrieves existing AutoNumber attribute metadata, updates the AutoNumberFormat and optional properties (displayName, description, maxLength), then performs a PUT request to the Dataverse metadata endpoint with MSCRM.MergeLabels header to merge labels.

  async (params) => {
    try {
      // First, retrieve the current attribute definition
      const currentAttribute = await client.getMetadata(
        `EntityDefinitions(LogicalName='${params.entityLogicalName}')/Attributes(LogicalName='${params.columnLogicalName}')`
      );
  
      // Create the updated attribute definition
      const updatedAttribute: any = {
        ...currentAttribute,
        "@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",
        "AutoNumberFormat": params.autoNumberFormat
      };
  
      // Add optional fields if provided
      if (params.displayName) {
        updatedAttribute.DisplayName = createLocalizedLabel(params.displayName);
      }
  
      if (params.description) {
        updatedAttribute.Description = createLocalizedLabel(params.description);
      }
  
      if (params.maxLength) {
        updatedAttribute.MaxLength = params.maxLength;
      }
  
      // Use PUT method with MSCRM.MergeLabels header
      await client.putMetadata(
        `EntityDefinitions(LogicalName='${params.entityLogicalName}')/Attributes(LogicalName='${params.columnLogicalName}')`,
        updatedAttribute,
        {
          'MSCRM.MergeLabels': 'true'
        }
      );
  
      return {
        content: [
          {
            type: "text",
            text: `Successfully updated AutoNumber format for column '${params.columnLogicalName}' in table '${params.entityLogicalName}'.\n\nNew AutoNumber Format: ${params.autoNumberFormat}${params.displayName ? `\nNew Display Name: ${params.displayName}` : ''}${params.maxLength ? `\nNew Max Length: ${params.maxLength}` : ''}`
          }
        ]
      };
  
    } catch (error: any) {
      let errorMessage = `Error updating AutoNumber format: ${error instanceof Error ? error.message : 'Unknown error'}`;
      
      if (error.message?.includes('Invalid Argument')) {
        errorMessage += '\n\nTip: Check AutoNumber format syntax. Use {SEQNUM:length}, {RANDSTRING:1-6}, {DATETIMEUTC:format}';
      }
      
      return {
        content: [
          {
            type: "text",
            text: errorMessage
          }
        ],
        isError: true
      };
    }
  }

• src/tools/autonumber-tools.ts:26-56 (schema)

  Zod validation schema for AutoNumber format strings. Validates placeholders {SEQNUM:length}, {RANDSTRING:1-6}, {DATETIMEUTC:format} and provides detailed error messaging. Reused across multiple AutoNumber tools.

  const autoNumberFormatSchema = z.string().refine((format) => {
    // Validate AutoNumber format placeholders
    const validPlaceholders = /^[^{}]*(\{(SEQNUM|RANDSTRING|DATETIMEUTC):[0-9]+\}[^{}]*)*$/;
    const hasValidPlaceholders = validPlaceholders.test(format);
    
    // Check RANDSTRING length constraints (1-6)
    const randStringMatches = format.match(/\{RANDSTRING:(\d+)\}/g);
    if (randStringMatches) {
      for (const match of randStringMatches) {
        const length = parseInt(match.match(/\{RANDSTRING:(\d+)\}/)![1]);
        if (length < 1 || length > 6) {
          return false;
        }
      }
    }
    
    // Check SEQNUM length constraints (minimum 1)
    const seqNumMatches = format.match(/\{SEQNUM:(\d+)\}/g);
    if (seqNumMatches) {
      for (const match of seqNumMatches) {
        const length = parseInt(match.match(/\{SEQNUM:(\d+)\}/)![1]);
        if (length < 1) {
          return false;
        }
      }
    }
    
    return hasValidPlaceholders;
  }, {
    message: "Invalid AutoNumber format. Use placeholders like {SEQNUM:4}, {RANDSTRING:3} (1-6), {DATETIMEUTC:yyyyMMdd}"
  });

• src/tools/autonumber-tools.ts:165-244 (registration)

  Registration of the 'update_autonumber_format' MCP tool via server.registerTool(). Includes tool name, title, description, full inputSchema using autoNumberFormatSchema, and the handler function.

  export function updateAutoNumberFormatTool(server: McpServer, client: DataverseClient) {
    server.registerTool(
      'update_autonumber_format',
      {
        title: 'Update AutoNumber Format',
        description: 'Updates the AutoNumberFormat of an existing AutoNumber column. This changes how future values will be generated but does not affect existing records.',
        inputSchema: {
          entityLogicalName: z.string().describe('Logical name of the table containing the AutoNumber column'),
          columnLogicalName: z.string().describe('Logical name of the AutoNumber column to update'),
          autoNumberFormat: autoNumberFormatSchema.describe('New AutoNumber format using placeholders like "PREFIX-{SEQNUM:4}-{RANDSTRING:3}-{DATETIMEUTC:yyyyMMdd}"'),
          displayName: z.string().optional().describe('New display name for the column'),
          description: z.string().optional().describe('New description for the column'),
          maxLength: z.number().min(1).max(4000).optional().describe('New maximum length (ensure enough room for format expansion)')
        }
      },
      async (params) => {
        try {
          // First, retrieve the current attribute definition
          const currentAttribute = await client.getMetadata(
            `EntityDefinitions(LogicalName='${params.entityLogicalName}')/Attributes(LogicalName='${params.columnLogicalName}')`
          );
  
          // Create the updated attribute definition
          const updatedAttribute: any = {
            ...currentAttribute,
            "@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",
            "AutoNumberFormat": params.autoNumberFormat
          };
  
          // Add optional fields if provided
          if (params.displayName) {
            updatedAttribute.DisplayName = createLocalizedLabel(params.displayName);
          }
  
          if (params.description) {
            updatedAttribute.Description = createLocalizedLabel(params.description);
          }
  
          if (params.maxLength) {
            updatedAttribute.MaxLength = params.maxLength;
          }
  
          // Use PUT method with MSCRM.MergeLabels header
          await client.putMetadata(
            `EntityDefinitions(LogicalName='${params.entityLogicalName}')/Attributes(LogicalName='${params.columnLogicalName}')`,
            updatedAttribute,
            {
              'MSCRM.MergeLabels': 'true'
            }
          );
  
          return {
            content: [
              {
                type: "text",
                text: `Successfully updated AutoNumber format for column '${params.columnLogicalName}' in table '${params.entityLogicalName}'.\n\nNew AutoNumber Format: ${params.autoNumberFormat}${params.displayName ? `\nNew Display Name: ${params.displayName}` : ''}${params.maxLength ? `\nNew Max Length: ${params.maxLength}` : ''}`
              }
            ]
          };
  
        } catch (error: any) {
          let errorMessage = `Error updating AutoNumber format: ${error instanceof Error ? error.message : 'Unknown error'}`;
          
          if (error.message?.includes('Invalid Argument')) {
            errorMessage += '\n\nTip: Check AutoNumber format syntax. Use {SEQNUM:length}, {RANDSTRING:1-6}, {DATETIMEUTC:format}';
          }
          
          return {
            content: [
              {
                type: "text",
                text: errorMessage
              }
            ],
            isError: true
          };
        }
      }
    );
  }

• src/index.ts:241-241 (registration)

  Invocation of updateAutoNumberFormatTool to register the tool during MCP server initialization in main entry point.

  updateAutoNumberFormatTool(server, dataverseClient);

• src/tools/autonumber-tools.ts:6-22 (helper)

  Utility function to create standardized localized label objects for Dataverse metadata (used in displayName and description updates).

  function createLocalizedLabel(text: string, languageCode: number = 1033) {
    return {
      LocalizedLabels: [
        {
          Label: text,
          LanguageCode: languageCode,
          IsManaged: false,
          MetadataId: "00000000-0000-0000-0000-000000000000"
        }
      ],
      UserLocalizedLabel: {
        Label: text,
        LanguageCode: languageCode,
        IsManaged: false,
        MetadataId: "00000000-0000-0000-0000-000000000000"
      }
    };