Dataverse MCP Server

Instructions

Implementation Reference

• src/tools/optionset-tools.ts:326-373 (handler)

  The core handler logic that constructs an OData query for GlobalOptionSetDefinitions, retrieves option set metadata, transforms it into a user-friendly list with details like name, display name, description, status flags, and option count, then returns formatted text output or error.

  async (params) => {
    try {
      // Note: $filter is not supported on GlobalOptionSetDefinitions
      let queryParams: Record<string, any> = {
        $select: "Name,DisplayName,Description,IsCustomOptionSet,IsManaged,IsGlobal,OptionSetType"
      };
  
      // Add top parameter if specified
      if (params.top) {
        queryParams.$top = params.top;
      }
  
      const result = await client.getMetadata<ODataResponse<OptionSetMetadata>>(
        "GlobalOptionSetDefinitions",
        queryParams
      );
  
      const optionSetList = result.value.map(optionSet => ({
        name: optionSet.Name,
        displayName: optionSet.DisplayName?.UserLocalizedLabel?.Label || optionSet.Name,
        description: optionSet.Description?.UserLocalizedLabel?.Label || "",
        isCustom: optionSet.IsCustomOptionSet,
        isManaged: optionSet.IsManaged,
        isGlobal: optionSet.IsGlobal,
        optionSetType: optionSet.OptionSetType,
        optionCount: optionSet.Options?.length || 0
      }));
  
      return {
        content: [
          {
            type: "text",
            text: `Found ${optionSetList.length} option sets:\n\n${JSON.stringify(optionSetList, null, 2)}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error listing option sets: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/optionset-tools.ts:317-325 (schema)

  Tool schema definition including title, description, and Zod-validated input schema for optional parameters to filter and limit option set listing.

    title: "List Dataverse Option Sets",
    description: "Retrieves a list of option sets in the Dataverse environment with filtering options. Use this to discover available choice lists, find custom option sets, or get an overview of reusable options. Supports filtering by custom/system and managed/unmanaged status.",
    inputSchema: {
      customOnly: z.boolean().default(false).describe("Whether to list only custom option sets"),
      includeManaged: z.boolean().default(false).describe("Whether to include managed option sets"),
      top: z.number().optional().describe("Maximum number of option sets to return (default: 50)"),
      filter: z.string().optional().describe("OData filter expression")
    }
  },

• src/tools/optionset-tools.ts:313-375 (registration)

  The exported registration function that defines and registers the 'list_dataverse_optionsets' tool on the MCP server using the provided schema and handler.

  export function listOptionSetsTool(server: McpServer, client: DataverseClient) {
    server.registerTool(
      "list_dataverse_optionsets",
      {
        title: "List Dataverse Option Sets",
        description: "Retrieves a list of option sets in the Dataverse environment with filtering options. Use this to discover available choice lists, find custom option sets, or get an overview of reusable options. Supports filtering by custom/system and managed/unmanaged status.",
        inputSchema: {
          customOnly: z.boolean().default(false).describe("Whether to list only custom option sets"),
          includeManaged: z.boolean().default(false).describe("Whether to include managed option sets"),
          top: z.number().optional().describe("Maximum number of option sets to return (default: 50)"),
          filter: z.string().optional().describe("OData filter expression")
        }
      },
      async (params) => {
        try {
          // Note: $filter is not supported on GlobalOptionSetDefinitions
          let queryParams: Record<string, any> = {
            $select: "Name,DisplayName,Description,IsCustomOptionSet,IsManaged,IsGlobal,OptionSetType"
          };
  
          // Add top parameter if specified
          if (params.top) {
            queryParams.$top = params.top;
          }
  
          const result = await client.getMetadata<ODataResponse<OptionSetMetadata>>(
            "GlobalOptionSetDefinitions",
            queryParams
          );
  
          const optionSetList = result.value.map(optionSet => ({
            name: optionSet.Name,
            displayName: optionSet.DisplayName?.UserLocalizedLabel?.Label || optionSet.Name,
            description: optionSet.Description?.UserLocalizedLabel?.Label || "",
            isCustom: optionSet.IsCustomOptionSet,
            isManaged: optionSet.IsManaged,
            isGlobal: optionSet.IsGlobal,
            optionSetType: optionSet.OptionSetType,
            optionCount: optionSet.Options?.length || 0
          }));
  
          return {
            content: [
              {
                type: "text",
                text: `Found ${optionSetList.length} option sets:\n\n${JSON.stringify(optionSetList, null, 2)}`
              }
            ]
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `Error listing option sets: ${error instanceof Error ? error.message : 'Unknown error'}`
              }
            ],
            isError: true
          };
        }
      }
    );
  }

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

  Top-level invocation of the listOptionSetsTool registration function during server initialization, passing the MCP server and Dataverse client instances.

  listOptionSetsTool(server, dataverseClient);