Dataverse MCP Server

Instructions

Implementation Reference

• src/tools/optionset-tools.ts:45-89 (handler)

  The main handler function that executes the tool logic: validates input, builds the OptionSetMetadata payload using the helper, calls the Dataverse API to create the global option set, and returns success/error response.

  async (params) => {
    try {
      if (!params.options || params.options.length === 0) {
        throw new Error("At least one option is required");
      }
  
      const optionSetDefinition = {
        "@odata.type": "Microsoft.Dynamics.CRM.OptionSetMetadata",
        Name: params.name,
        DisplayName: createLocalizedLabel(params.displayName),
        Description: params.description ? createLocalizedLabel(params.description) : undefined,
        OptionSetType: "Picklist", // Use string instead of numeric
        IsGlobal: params.isGlobal,
        IsCustomOptionSet: true,
        Options: params.options.map(option => ({
          Value: option.value,
          Label: createLocalizedLabel(option.label),
          Description: option.description ? createLocalizedLabel(option.description) : undefined,
          Color: option.color,
          IsManaged: false
        }))
      };
  
      const result = await client.postMetadata("GlobalOptionSetDefinitions", optionSetDefinition);
  
      return {
        content: [
          {
            type: "text",
            text: `Successfully created option set '${params.name}' with ${params.options.length} options.\n\nResponse: ${JSON.stringify(result, null, 2)}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error creating option set: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/optionset-tools.ts:32-43 (schema)

  Zod schema defining the input parameters for the tool: name, displayName, optional description and isGlobal, and array of options with value, label, etc.

  inputSchema: {
    name: z.string().describe("Name for the option set (e.g., 'new_priority')"),
    displayName: z.string().describe("Display name for the option set"),
    description: z.string().optional().describe("Description of the option set"),
    isGlobal: z.boolean().default(true).describe("Whether this is a global option set"),
    options: z.array(z.object({
      value: z.number().describe("Numeric value for the option"),
      label: z.string().describe("Display label for the option"),
      description: z.string().optional().describe("Description for the option"),
      color: z.string().optional().describe("Color for the option (hex format, e.g., '#FF0000')")
    })).describe("Array of options for the option set")
  }

• src/tools/optionset-tools.ts:26-91 (registration)

  The createOptionSetTool function which registers the 'create_dataverse_optionset' tool on the MCP server, providing title, description, input schema, and handler.

  export function createOptionSetTool(server: McpServer, client: DataverseClient) {
    server.registerTool(
      "create_dataverse_optionset",
      {
        title: "Create Dataverse Option Set",
        description: "Creates a new global option set (choice list) in Dataverse with predefined options. Use this to create reusable choice lists that can be used across multiple tables and columns. Option sets provide consistent data entry options and improve data quality.",
        inputSchema: {
          name: z.string().describe("Name for the option set (e.g., 'new_priority')"),
          displayName: z.string().describe("Display name for the option set"),
          description: z.string().optional().describe("Description of the option set"),
          isGlobal: z.boolean().default(true).describe("Whether this is a global option set"),
          options: z.array(z.object({
            value: z.number().describe("Numeric value for the option"),
            label: z.string().describe("Display label for the option"),
            description: z.string().optional().describe("Description for the option"),
            color: z.string().optional().describe("Color for the option (hex format, e.g., '#FF0000')")
          })).describe("Array of options for the option set")
        }
      },
      async (params) => {
        try {
          if (!params.options || params.options.length === 0) {
            throw new Error("At least one option is required");
          }
  
          const optionSetDefinition = {
            "@odata.type": "Microsoft.Dynamics.CRM.OptionSetMetadata",
            Name: params.name,
            DisplayName: createLocalizedLabel(params.displayName),
            Description: params.description ? createLocalizedLabel(params.description) : undefined,
            OptionSetType: "Picklist", // Use string instead of numeric
            IsGlobal: params.isGlobal,
            IsCustomOptionSet: true,
            Options: params.options.map(option => ({
              Value: option.value,
              Label: createLocalizedLabel(option.label),
              Description: option.description ? createLocalizedLabel(option.description) : undefined,
              Color: option.color,
              IsManaged: false
            }))
          };
  
          const result = await client.postMetadata("GlobalOptionSetDefinitions", optionSetDefinition);
  
          return {
            content: [
              {
                type: "text",
                text: `Successfully created option set '${params.name}' with ${params.options.length} options.\n\nResponse: ${JSON.stringify(result, null, 2)}`
              }
            ]
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `Error creating option set: ${error instanceof Error ? error.message : 'Unknown error'}`
              }
            ],
            isError: true
          };
        }
      }
    );
  }

• src/tools/optionset-tools.ts:7-24 (helper)

  Helper function to create standardized LocalizedLabel objects for option set metadata, used in DisplayName, Description, and Option Labels.

  function createLocalizedLabel(text: string, languageCode: number = 1033): LocalizedLabel {
    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"
      }
    };
  }

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

  Invocation of the registration function in the main server initialization file, passing the MCP server and Dataverse client instances.

  createOptionSetTool(server, dataverseClient);