Dataverse MCP Server

Instructions

Implementation Reference

• src/tools/role-tools.ts:102-143 (handler)

  The main handler function for the 'get_dataverse_role' tool. It queries the Dataverse API for the specified role ID, extracts relevant properties, formats them into a JSON object, and returns the information as text content. Handles errors by returning an error message.

  async (params) => {
    try {
      const role = await client.get(`roles(${params.roleId})?$select=roleid,name,description,appliesto,isautoassigned,isinherited,summaryofcoretablepermissions,businessunitid,createdon,modifiedon,createdby,modifiedby,ismanaged,iscustomizable,canbedeleted`);
  
      const roleInfo = {
        roleId: role.roleid,
        name: role.name,
        description: role.description,
        appliesTo: role.appliesto,
        isAutoAssigned: role.isautoassigned === 1,
        isInherited: role.isinherited,
        summaryOfCoreTablePermissions: role.summaryofcoretablepermissions,
        businessUnitId: role.businessunitid,
        createdOn: role.createdon,
        modifiedOn: role.modifiedon,
        createdBy: role.createdby,
        modifiedBy: role.modifiedby,
        isManaged: role.ismanaged,
        isCustomizable: role.iscustomizable,
        canBeDeleted: role.canbedeleted
      };
  
      return {
        content: [
          {
            type: "text",
            text: `Security role information:\n\n${JSON.stringify(roleInfo, null, 2)}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error retrieving security role: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/role-tools.ts:98-100 (schema)

  The input schema for the tool, defining a single required string parameter 'roleId' for the security role GUID.

  inputSchema: {
    roleId: z.string().describe("ID of the role to retrieve")
  }

• src/tools/role-tools.ts:92-145 (registration)

  The exported getRoleTool function that performs the server.registerTool call to register the 'get_dataverse_role' tool, including its metadata, schema, and inline handler.

  export function getRoleTool(server: McpServer, client: DataverseClient) {
    server.registerTool(
      "get_dataverse_role",
      {
        title: "Get Dataverse Security Role",
        description: "Retrieves detailed information about a specific security role including its properties, business unit association, and configuration settings. Use this to inspect role definitions and understand permission structures.",
        inputSchema: {
          roleId: z.string().describe("ID of the role to retrieve")
        }
      },
      async (params) => {
        try {
          const role = await client.get(`roles(${params.roleId})?$select=roleid,name,description,appliesto,isautoassigned,isinherited,summaryofcoretablepermissions,businessunitid,createdon,modifiedon,createdby,modifiedby,ismanaged,iscustomizable,canbedeleted`);
  
          const roleInfo = {
            roleId: role.roleid,
            name: role.name,
            description: role.description,
            appliesTo: role.appliesto,
            isAutoAssigned: role.isautoassigned === 1,
            isInherited: role.isinherited,
            summaryOfCoreTablePermissions: role.summaryofcoretablepermissions,
            businessUnitId: role.businessunitid,
            createdOn: role.createdon,
            modifiedOn: role.modifiedon,
            createdBy: role.createdby,
            modifiedBy: role.modifiedby,
            isManaged: role.ismanaged,
            isCustomizable: role.iscustomizable,
            canBeDeleted: role.canbedeleted
          };
  
          return {
            content: [
              {
                type: "text",
                text: `Security role information:\n\n${JSON.stringify(roleInfo, null, 2)}`
              }
            ]
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `Error retrieving security role: ${error instanceof Error ? error.message : 'Unknown error'}`
              }
            ],
            isError: true
          };
        }
      }
    );
  }

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

  Invocation of getRoleTool in the main server initialization to register all role-related tools on the MCP server.

  getRoleTool(server, dataverseClient);