Dataverse MCP Server

Un servidor Model Context Protocol (MCP) para Microsoft Dataverse.

Este servidor proporciona herramientas para explorar definiciones de tablas (metadatos), columnas (campos), relaciones, claves y OptionSets (columnas de elección) de Dataverse, además de crear entidades y gestionar campos mediante lenguaje natural usando un cliente MCP (como Claude Desktop u otros agentes de IA).

Características

• Actualizar metadatos: Descarga la definición completa de $metadata y StringMaps (OptionSets locales) de tu entorno de Dataverse.
• Listar tablas: Busca tablas por patrón de nombre.
• Obtener detalles de tabla: Obtiene información detallada del esquema para tablas específicas, incluyendo Campos, Relaciones y Claves.
• Obtener OptionSets globales: Recupera detalles para opciones globales (Global OptionSets).
• Obtener OptionSets locales: Recupera valores para opciones locales (StringMaps) específicas de una entidad y atributo.
• Crear entidad: Crea nuevas entidades en una solución específica de Dataverse.
• Gestionar campos: Crea o elimina campos (atributos) de forma masiva en una entidad.
• Listar vistas y formularios: Lista vistas del sistema (sin vistas personales) y formularios para una entidad.
• Obtener definición de vista: Recupera la definición completa de una vista por id.
• Obtener definición de formulario: Recupera la definición completa de un formulario por id.
• Inspeccionar solución: Lista componentes de la solución indicada al iniciar el servidor (id, tipo y nombre).
• Obtener webresource: Recupera un webresource por id con metadatos. El contenido textual se devuelve como texto y el binario como [Binary].

Nota importante: Las herramientas de manipulación de datos (create_entity y manage_fields) requieren que se inicie el servidor con el parámetro --solution indicando el nombre único de la solución donde se realizarán los cambios.

Instalación

npm install -g dataverse-mcp

Uso

Prerrequisitos

• Un entorno de Microsoft Dataverse.
• Una cuenta de usuario con permisos para leer metadatos y personalizar el sistema (si se usan herramientas de creación).
• Un cliente MCP.

Ejecución del servidor

Puedes ejecutar el servidor directamente usando npx o instalándolo globalmente.

Usando npx:

npx dataverse-mcp --url "https://your-org.crm.dynamics.com" --solution "NombreSolucion" --savetoken

El parámetro --solution es opcional para lectura, pero obligatorio para crear entidades o campos.

Parámetros de inicio

• --url (requerido): URL del entorno Dataverse.
• --solution (opcional): Nombre único de la solución. Requerido para create_entity, manage_fields e inspect_solution.
• --savetoken (opcional): Persiste el token en disco y lo reutiliza hasta su expiración.

Configuración en VsCode:

Agrega lo siguiente a tu mcp.json en la carpeta .vscode:

{
  "servers": {
    "dataverse": {
      "command": "npx",
      "args": [
        "-y",
        "arbentia-dataverse-mcp",
        "--url",
        "https://your-org.crm.dynamics.com",
        "--solution",
        "NombreSolucion" 
      ]
    }
  }
}

Configuración en Claude Desktop:

Agrega lo siguiente a tu claude_desktop_config.json:

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": [
        "-y",
        "arbentia-dataverse-mcp",
        "--url",
        "https://your-org.crm.dynamics.com",
        "--solution",
        "NombreSolucion"
      ]
    }
  }
}

Autenticación

Esta herramienta utiliza InteractiveBrowserCredential de @azure/identity. Cuando uses por primera vez una herramienta que requiera acceso, se abrirá una ventana del navegador pidiéndote que inicies sesión en tu cuenta de Microsoft.

El token se cachea en memoria por entorno. Si se inicia el servidor con --savetoken, también se guarda en disco (en .dataversemetadata/<entorno>/token.json) y se reutiliza hasta su expiración. Úsalo solo en equipos de confianza.

Herramientas

• refresh_metadata: Vuelve a descargar la caché de metadatos.
• list_tables_by_name: Lista tablas que coinciden con un patrón regex.
• get_tables_details: Esquema detallado para tablas dadas. Soporta filtrado por Fields (Campos), Relationships (Relaciones) o Keys (Claves).
• get_global_optionset_details: Detalles para OptionSets globales.
• get_local_optionset_details: Detalles para OptionSets locales (StringMaps) para entidades específicas.
• create_entity: Crea una nueva entidad en la solución especificada. Requiere el parámetro solution al inicio.
• manage_fields: Creación o eliminación por lotes de campos en una entidad. Requiere el parámetro solution al inicio.
• list_entity_views_and_forms: Lista vistas del sistema (solo savedqueries, sin userquery) y todos los formularios para una entidad. Admite include_views y include_forms (por defecto true). Se consulta bajo demanda y no forma parte del filtro All de get_tables_details.
• get_view_definition: Recupera la definición completa de una vista de sistema por id.
• get_form_definition: Recupera la definición completa de un formulario por id (incluye XML/JSON).
• inspect_solution: Devuelve componentes de la solución configurada al iniciar el servidor (id, tipo y nombre).
• get_webresource_by_id: Recupera un webresource por id con metadatos. El contenido textual se devuelve como texto y el binario como [Binary].

Aviso sobre Operaciones de Escritura (DDL)

Las herramientas que modifican la estructura de la base de datos (create_entity y manage_fields) incluyen medidas de seguridad adicionales:

1. Confirmación Visual: Antes de aplicar cualquier cambio, el servidor abrirá automáticamente una página en tu navegador predeterminado mostrando el detalle de la operación (tablas a crear, campos a añadir/borrar). Deberás aprobar la operación en esa página para que continúe.
2. Re-autenticación: Para prevenir cambios accidentales o no supervisados, es posible que el sistema solicite autenticación interactiva (abrir ventana de login) para cada operación de escritura.

Licencia

MIT