Microsoft Fabric Analytics

Un servidor de análisis que proporciona herramientas para interactuar con la plataforma de datos Microsoft Fabric.

Documentación

Microsoft Fabric Analytics MCP Server

Un servidor integral de Model Context Protocol (MCP) que proporciona capacidades analíticas y herramientas para interactuar con la plataforma de datos de Microsoft Fabric. Este servidor permite que asistentes de IA como Claude accedan, analicen y monitoreen sin problemas los recursos de Microsoft Fabric a través de protocolos MCP estandarizados, llevando el poder de Microsoft Fabric directamente a tus conversaciones de IA.

📋 Tabla de Contenidos

🌟 Características Clave
🚀 Inicio Rápido
🛠️ Herramientas y Capacidades
🧪 Desarrollo y Pruebas
💬 Consultas de Ejemplo
🔐 Autenticación
🏗️ Arquitectura
⚙️ Configuración
🤝 Contribuciones
🔒 Seguridad "Cancelar la aplicación Spark problemática"
📞 Soporte

🌟 Características Clave

🏗️ Gestión Completa de Espacios de Trabajo - Crear, eliminar y gestionar espacios de trabajo de Fabric con asignación de capacidad
🔄 Operaciones CRUD Mejoradas - Crear, leer, actualizar y eliminar todos los elementos de Fabric (notebooks, lakehouses, conjuntos de datos, informes)
📓 Gestión Avanzada de Notebooks - Crear, ejecutar y gestionar notebooks de Fabric con 5 plantillas predefinidas
⚡ Integración con la API de Livy - Gestión completa de sesiones de Spark y trabajos por lotes con monitoreo en tiempo real
📊 Monitoreo Integral de Spark - Monitoreo en tiempo real en espacios de trabajo, elementos y aplicaciones
🤖 Soporte Multi-Asistente de IA - Funciona con Claude Desktop, GitHub Copilot y otras herramientas de IA compatibles con MCP
🔐 Autenticación Mejorada de Azure CLI - Configuración sin pasos adicionales con gestión automática de tokens
️ Autenticación Empresarial - Múltiples métodos de autenticación (Bearer, Service Principal, Device Code, Interactiva, Azure CLI)
📈 Análisis e Información - Generar paneles de monitoreo completos con métricas en tiempo real
🧪 Pruebas de Extremo a Extremo - Suite de pruebas completa con creación real de espacios de trabajo y ejecución de trabajos
🔄 Gestión Avanzada de Tokens - Validación, renovación y manejo de expiración automática de tokens "Listar todas las capacidades de Fabric que puedo usar" "Asignar el espacio de trabajo 1234abcd-abcd-1234-abcd-123456789000 a la capacidad f9998888-7777-6666-5555-444433332222" "Mostrar todos los espacios de trabajo en la capacidad f9998888-7777-6666-5555-444433332222" "Desasignar el espacio de trabajo 1234abcd-abcd-1234-abcd-123456789000 de su capacidad"

- **☸️ Enterprise Deployment** - Full Kubernetes and Azure deployment support with auto-scaling
- **🔄 Docker Support** - Containerized deployment with health checks and monitoring
- **📊 Monitoring & Observability** - Built-in Prometheus metrics and Grafana dashboards
- **🔀 Synapse to Fabric Migration** - Automated migration of Spark notebooks from Azure Synapse Analytics
- **🎯 52 Total Tools** - Comprehensive coverage of Fabric operations including migration (up from 48 tools)

## 🏗️ **New Workspace Management Features**

### **🆕 Latest Updates - Comprehensive Workspace Operations**

The MCP server now includes **21 new workspace management tools** that enable complete workspace lifecycle management:

### **🌟 Core Workspace Operations**
- **fabric_list_workspaces** - List all accessible workspaces with detailed metadata
- **fabric_create_workspace** - Create new workspaces with custom configuration
- **fabric_delete_workspace** - Delete workspaces with confirmation and cleanup
- **fabric_update_workspace** - Update workspace properties and settings
- **fabric_get_workspace** - Get detailed workspace information and status

### **⚡ Capacity & Resource Management**
- **fabric_list_capacities** - List all available Fabric capacities
- **fabric_assign_workspace_to_capacity** - Attach workspaces to dedicated capacity
- **fabric_unassign_workspace_from_capacity** - Move workspaces to shared capacity
- **fabric_list_capacity_workspaces** - List all workspaces in a capacity

### **👥 Access Control & Security**
- **fabric_get_workspace_role_assignments** - View workspace permissions
- **fabric_add_workspace_role_assignment** - Grant workspace access to users/groups
- **fabric_update_workspace_role_assignment** - Modify user permissions
- **fabric_remove_workspace_role_assignment** - Remove workspace access

### **🔄 Advanced Operations**
- **fabric_get_workspace_git_status** - Check Git integration status
- **fabric_connect_workspace_to_git** - Enable Git integration for workspace
- **fabric_disconnect_workspace_from_git** - Disable Git integration
- **fabric_update_workspace_git_connection** - Modify Git repository settings

### **🛠️ Environment & Pipeline Management**
- **fabric_list_workspace_environments** - List all environments in workspace
- **fabric_create_workspace_environment** - Create new environments
- **fabric_delete_workspace_environment** - Remove environments
- **fabric_list_workspace_data_pipelines** - List data integration pipelines
- **fabric_create_workspace_data_pipeline** - Create new data pipelines

### **🎯 Real-World Scenarios Enabled**

**🚀 Automated Workspace Provisioning:**

"Crear un nuevo espacio de trabajo llamado 'Analytics-Q1-2025' y asignarlo a nuestra capacidad premium"


**📊 Multi-Workspace Analytics:**

"Listar todos los espacios de trabajo en nuestro tenant y mostrar sus asignaciones de capacidad"


**🔒 Access Management:**

"Añadir al usuario john.doe@company.com como Administrador al espacio de trabajo Analytics"


**🏗️ Environment Setup:**

"Crear un entorno de desarrollo en el espacio de trabajo Analytics con bibliotecas de Python y R"


**🔄 Git Integration:**

"Conectar el espacio de trabajo Analytics a nuestro repositorio de GitHub para control de versiones"


### **🤖 GitHub Copilot Integration**

**Perfect for GitHub Copilot** - The enhanced workspace management works seamlessly with **GitHub Copilot's built-in terminal**, making it ideal for:

- **🔧 Azure CLI Authentication** - Uses your existing `az login` session
- **💻 Terminal-Based Operations** - Natural workflow within your coding environment  
- **⚡ Rapid Prototyping** - Quickly create test workspaces and environments
- **🏗️ Infrastructure as Code** - Manage Fabric resources alongside your codebase
- **🔄 CI/CD Integration** - Automate workspace provisioning in deployment pipelines

**GitHub Copilot Example Commands:**

```bash
# Using Azure CLI auth, create a new workspace for our ML project
# List all workspaces and their Git integration status
# Set up a complete analytics environment with lakehouse and notebooks

🔀 Herramientas de Migración de Synapse a Fabric

🆕 Migración Automatizada de Cargas de Trabajo de Spark

El servidor MCP ahora incluye 4 herramientas de migración especializadas que automatizan la migración de notebooks y pipelines de Spark desde Azure Synapse Analytics a Microsoft Fabric:

🔍 Herramientas de Descubrimiento de Migración

fabric_list_synapse_workspaces - Listar todos los espacios de trabajo de Synapse en tu suscripción de Azure
fabric_discover_synapse_workspace - Inventariar notebooks, pipelines, servicios vinculados y trabajos de Spark desde Synapse

🔄 Herramientas de Transformación y Migración

fabric_transform_notebooks - Transformar notebooks de Synapse al formato de Fabric (mssparkutils → notebookutils)
fabric_migrate_synapse_to_fabric - Migración completa de extremo a extremo con descubrimiento, transformación y aprovisionamiento

✨ Características Clave de Migración

Transformación Automática de Código - Convierte código específico de Synapse a equivalentes de Fabric:
- mssparkutils → notebookutils
- Comandos mágicos de Synapse → Comandos mágicos de Fabric
- Reescritura de rutas ABFSS a OneLake
- Limpieza de configuración de grupos de Spark
Descubrimiento Integral de Activos - Inventaria todos los activos migrables:
- Notebooks de Jupyter (formato ipynb)
- Pipelines y flujos de trabajo de datos
- Servicios vinculados y conexiones
- Definiciones de trabajos de Spark
Pruebas Seguras con Simulación - Previsualiza todos los cambios antes de aplicarlos:
- Probar transformaciones sin aprovisionar
- Validar el código transformado
- Revisar informes de cambios
Automatización de Extremo a Extremo - Pipeline de migración completo:
- Descubrimiento → Transformación → Aprovisionamiento → Validación
- Creación automática de lakehouse
- Aprovisionamiento de accesos directos de OneLake
- Informes de migración completos

🎯 Escenarios de Migración

Migration Demo

📋 Explorar Antes de Migrar:

"List all my Synapse workspaces and show me what notebooks are in workspace 'analytics-synapse'"

🔄 Previsualizar Transformaciones:

"Discover assets from my Synapse workspace 'analytics-synapse' and show me how the code would be transformed (dry run)"

🚀 Migración Completa:

"Migrate all notebooks from Synapse workspace 'analytics-synapse' to Fabric workspace 'abcd-1234' and create a lakehouse called 'MigratedData'"

📊 Guía Detallada de Migración: Consulta MIGRATION.md para documentación completa de migración que incluye:

Flujos de trabajo paso a paso
Detalles de reglas de transformación
Mejores prácticas y solución de problemas
Ejemplos completos

🎯 Pruebas de Extremo a Extremo con Espacios de Trabajo Reales

El servidor MCP ahora incluye pruebas integrales de extremo a extremo que crean espacios de trabajo reales, los asignan a capacidades y ejecutan trabajos reales para validar el flujo de trabajo completo:

# One-command end-to-end test
npm run test:e2e

Qué prueba:

✅ Creación de Espacios de Trabajo - Crea espacios de trabajo reales de Fabric
✅ Asignación de Capacidad - Adjunta espacios de trabajo a tu capacidad de Fabric
✅ Creación de Elementos - Crea notebooks, lakehouses y otros elementos
✅ Ejecución de Trabajos - Ejecuta trabajos reales de Spark y monitorea su finalización
✅ Limpieza de Recursos - Elimina automáticamente todos los recursos de prueba

🚀 Opciones de Despliegue

🤖 Integración con Claude Desktop

Recomendado para uso con Asistentes de IA:

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\build\\index.js"],
      "cwd": "C:\\path\\to\\your\\project",
      "env": {
        "FABRIC_AUTH_METHOD": "bearer_token",
        "FABRIC_TOKEN": "your_bearer_token_here",
        "FABRIC_WORKSPACE_ID": "your_workspace_id",
        "ENABLE_HEALTH_SERVER": "false"
      }
    }
  }
}

💡 Obtener Token Bearer: Visita Configuración de Power BI Embed para generar tokens

⚠️ Importante: Los tokens expiran después de ~1 hora y deben renovarse

🔧 Solución de Autenticación para Claude Desktop

Si experimentas tiempos de espera de 60 segundos durante el inicio, esto se debe a los flujos de autenticación interactiva que bloquean el entorno sandbox de Claude Desktop. Solución:

Usar el Método de Token Bearer (Recomendado):
- Establece FABRIC_AUTH_METHOD: "bearer_token" en tu configuración
- Proporciona FABRIC_TOKEN con un token bearer válido
- Esto evita por completo la autenticación interactiva
Alternativa - Autenticación por Herramienta:
- Proporciona el token directamente en las llamadas de herramienta: bearerToken: "your_token_here"
- O usa el modo de simulación: bearerToken: "simulation"
Solución de Problemas:
- El servidor ahora tiene protección de tiempo de espera de 10 segundos para evitar bloqueos
- Vuelve al modo de simulación si falla la autenticación
- Los mensajes de error mejorados proporcionan una guía clara

🎯 Solución Rápida: El servidor prioriza automáticamente la variable de entorno FABRIC_TOKEN sobre los flujos de autenticación interactiva, evitando tiempos de espera en Claude Desktop.

📱 Desarrollo Local

# Clone and run locally
git clone https://github.com/santhoshravindran7/Fabric-Analytics-MCP.git
cd Fabric-Analytics-MCP
npm install && npm run build && npm start

🐳 Despliegue con Docker

# Using Docker Compose
docker-compose up -d

# Or standalone Docker
docker build -t fabric-analytics-mcp .
docker run -p 3000:3000 -e FABRIC_CLIENT_ID=xxx fabric-analytics-mcp

☸️ Azure Kubernetes Service (AKS)

# One-command enterprise deployment
export ACR_NAME="your-registry" FABRIC_CLIENT_ID="xxx" FABRIC_CLIENT_SECRET="yyy" FABRIC_TENANT_ID="zzz"
./scripts/setup-azure-resources.sh && ./scripts/build-and-push.sh && ./scripts/deploy-to-aks.sh

🌐 Azure MCP Server (Vista Previa)

# Serverless deployment on Azure
az mcp server create --name "fabric-analytics-mcp" --repository "santhoshravindran7/Fabric-Analytics-MCP"

📚 Guías Detalladas:

🛠️ Herramientas y Capacidades

🔍 Operaciones CRUD para Elementos de Fabric

Herramienta: list-fabric-items
Descripción: Listar elementos en un espacio de trabajo de Microsoft Fabric (Lakehouses, Notebooks, etc.)
Parámetros:
- bearerToken: Token bearer de Microsoft Fabric
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- itemType: Filtrar por tipo de elemento (opcional)
Herramienta: create-fabric-item
Descripción: Crear nuevos elementos en el espacio de trabajo de Microsoft Fabric
Parámetros:
- bearerToken: Token bearer de Microsoft Fabric
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- itemType: Tipo de elemento (Lakehouse, Notebook, Dataset, Report, Dashboard)
- displayName: Nombre para mostrar del nuevo elemento
- description: Descripción opcional
Herramienta: get-fabric-item
Descripción: Obtener información detallada sobre un elemento específico de Microsoft Fabric
Parámetros:
- bearerToken: Token bearer de Microsoft Fabric
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- itemId: ID del elemento a recuperar
Herramienta: update-fabric-item
Descripción: Actualizar elementos existentes en el espacio de trabajo de Microsoft Fabric
Parámetros:
- bearerToken: Token bearer de Microsoft Fabric
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- itemId: ID del elemento a actualizar
- displayName: Nuevo nombre para mostrar (opcional)
- description: Nueva descripción (opcional)
Herramienta: delete-fabric-item
Descripción: Eliminar elementos del espacio de trabajo de Microsoft Fabric
Parámetros:
- bearerToken: Token bearer de Microsoft Fabric
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- itemId: ID del elemento a eliminar

🔍 Consultar Conjunto de Datos de Fabric (Mejorado)

Herramienta: query-fabric-dataset
Descripción: Ejecutar consultas SQL o KQL contra conjuntos de datos de Microsoft Fabric
Parámetros:
- bearerToken: Token bearer de Microsoft Fabric (opcional - usa simulación si no se proporciona)
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- datasetName: Nombre del conjunto de datos a consultar
- query: Consulta SQL o KQL a ejecutar

🚀 Ejecutar Notebook de Fabric

Herramienta: execute-fabric-notebook
Descripción: Ejecutar un notebook en el espacio de trabajo de Microsoft Fabric
Parámetros:
- bearerToken: Token bearer de Microsoft Fabric
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- notebookId: ID del notebook a ejecutar
- parameters: Parámetros opcionales para pasar al notebook

📊 Obtener Métricas de Análisis

Herramienta: get-fabric-metrics
Descripción: Recuperar métricas de rendimiento y uso para elementos de Microsoft Fabric
Parámetros:
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- itemId: ID del elemento (conjunto de datos, informe, etc.)
- timeRange: Rango de tiempo para métricas (1h, 24h, 7d, 30d)
- metrics: Lista de métricas a analizar

🔧 Analizar Modelo de Datos

Herramienta: analyze-fabric-model
Descripción: Analizar un modelo de datos de Microsoft Fabric y obtener recomendaciones de optimización
Parámetros:
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- itemId: ID del elemento a analizar

📋 Generar Informe de Análisis

Herramienta: generate-fabric-report
Descripción: Generar informes de análisis completos para espacios de trabajo de Microsoft Fabric
Parámetros:
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- reportType: Tipo de informe (rendimiento, uso, salud, resumen)

🚀 Integración con la API de Livy (Sesiones y Trabajos por Lotes)

Gestión de Sesiones

Herramienta: create-livy-session
Descripción: Crear una nueva sesión de Livy para ejecución interactiva de Spark/SQL
Parámetros:
- bearerToken: Token bearer de Microsoft Fabric
- workspaceId: ID del espacio de trabajo de Microsoft Fabric
- lakehouseId: ID del lakehouse de Microsoft Fabric
- sessionConfig: Configuración de sesión opcional
Herramienta: get-livy-session
Descripción: Obtener detalles de una sesión de Livy
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID de lakehouse de Microsoft Fabric
- sessionId: ID de sesión de Livy
Herramienta: list-livy-sessions
Descripción: Listar todas las sesiones de Livy en un lakehouse
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID de lakehouse de Microsoft Fabric
Herramienta: delete-livy-session
Descripción: Eliminar una sesión de Livy
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID de lakehouse de Microsoft Fabric
- sessionId: ID de sesión de Livy

Ejecución de Sentencias

Herramienta: execute-livy-statement
Descripción: Ejecutar sentencias SQL o Spark en una sesión de Livy
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID de lakehouse de Microsoft Fabric
- sessionId: ID de sesión de Livy
- code: Código SQL o Spark a ejecutar
- kind: Tipo de sentencia (sql, spark, etc.)
Herramienta: get-livy-statement
Descripción: Obtener estado y resultados de una sentencia de Livy
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID de lakehouse de Microsoft Fabric
- sessionId: ID de sesión de Livy
- statementId: ID de sentencia

Gestión de Trabajos por Lotes

Herramienta: create-livy-batch
Descripción: Crear un nuevo trabajo por lotes de Livy para operaciones de larga duración
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID de lakehouse de Microsoft Fabric
- batchConfig: Configuración del trabajo por lotes
Herramienta: get-livy-batch
Descripción: Obtener detalles de un trabajo por lotes de Livy
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID de lakehouse de Microsoft Fabric
- batchId: ID del trabajo por lotes
Herramienta: list-livy-batches
Descripción: Listar todos los trabajos por lotes de Livy en un lakehouse
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID de lakehouse de Microsoft Fabric
Herramienta: delete-livy-batch
Descripción: Eliminar un trabajo por lotes de Livy
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID de lakehouse de Microsoft Fabric
- batchId: ID del trabajo por lotes

📊 Monitoreo de Aplicaciones Spark

Monitoreo a Nivel de Área de Trabajo

Herramienta: get-workspace-spark-applications
Descripción: Obtener todas las aplicaciones Spark en un área de trabajo de Microsoft Fabric
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- continuationToken: Token opcional para paginación

Monitoreo Específico por Elemento

Herramienta: get-notebook-spark-applications
Descripción: Obtener todas las aplicaciones Spark para un notebook específico
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- notebookId: ID del notebook
- continuationToken: Token opcional para paginación
Herramienta: get-lakehouse-spark-applications
Descripción: Obtener todas las aplicaciones Spark para un lakehouse específico
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- lakehouseId: ID del lakehouse
- continuationToken: Token opcional para paginación
Herramienta: get-spark-job-definition-applications
Descripción: Obtener todas las aplicaciones Spark para una definición de trabajo Spark específica
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- sparkJobDefinitionId: ID de la definición de trabajo Spark
- continuationToken: Token opcional para paginación

Gestión de Aplicaciones

Herramienta: get-spark-application-details
Descripción: Obtener información detallada sobre una aplicación Spark específica
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- livyId: ID de sesión de Livy
Herramienta: cancel-spark-application
Descripción: Cancelar una aplicación Spark en ejecución
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- livyId: ID de sesión de Livy

Panel de Monitoreo

Herramienta: get-spark-monitoring-dashboard
Descripción: Generar un panel de monitoreo integral con análisis
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric

📓 Gestión de Notebooks

El servidor MCP proporciona capacidades integrales de gestión de notebooks con plantillas predefinidas y soporte para notebooks personalizados.

Crear Notebook desde Plantilla

Herramienta: create-fabric-notebook
Descripción: Crear nuevos notebooks de Fabric a partir de plantillas predefinidas o definiciones personalizadas
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- displayName: Nombre para mostrar del nuevo notebook
- template: Tipo de plantilla (blank, sales_analysis, nyc_taxi_analysis, data_exploration, machine_learning, custom)
- customNotebook: Definición de notebook personalizado (requerida si la plantilla es 'custom')
- environmentId: ID de entorno opcional para adjuntar
- lakehouseId: ID de lakehouse predeterminado opcional
- lakehouseName: Nombre de lakehouse predeterminado opcional

Plantillas Disponibles:

blank: Notebook básico con configuración mínima
sales_analysis: Análisis integral de datos de ventas con conjunto de datos de muestra
nyc_taxi_analysis: Análisis de datos de viajes en taxi de NYC con conjunto de datos de muestra
data_exploration: Plantilla estructurada de exploración de datos
machine_learning: Plantilla completa de flujo de trabajo de ML
custom: Usa tu propia definición de notebook

Obtener Definición de Notebook

Herramienta: get-fabric-notebook-definition
Descripción: Recuperar la definición del notebook (celdas, metadatos) de un notebook de Fabric existente
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- notebookId: ID del notebook a recuperar
- format: Formato de retorno (ipynb o fabricGitSource)

Actualizar Definición de Notebook

Herramienta: update-fabric-notebook-definition
Descripción: Actualizar la definición del notebook (celdas, metadatos) de un notebook de Fabric existente
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- notebookId: ID del notebook a actualizar
- notebookDefinition: Objeto de definición de notebook actualizado

Ejecutar Notebook

Herramienta: run-fabric-notebook
Descripción: Ejecutar un notebook de Fabric bajo demanda con parámetros y configuración opcionales
Parámetros:
- bearerToken: Token de portador de Microsoft Fabric
- workspaceId: ID del área de trabajo de Microsoft Fabric
- notebookId: ID del notebook a ejecutar
- parameters: Parámetros opcionales del notebook (pares clave-valor con tipos)
- configuration: Configuración de ejecución opcional (entorno, lakehouse, pools, etc.)

Características:

📓 Soporte de carga útil de notebook codificada en Base64
🔧 Gestión integral de metadatos
🌐 Integración con entorno y lakehouse
🎛️ Ejecución de notebooks parametrizada
⚡ Soporte de configuración de Spark
🔤 Soporte para múltiples lenguajes de programación (Python, Scala, SQL, R)

🚀 Inicio Rápido

🎯 Métodos de Instalación

Elige tu método de instalación preferido:

Opción 1: Paquete de Python (PyPI) ⭐ Recomendado

# Install via pip (easiest method)
pip install fabric-analytics-mcp

# Verify installation
fabric-analytics --version

# Start the server
fabric-analytics-mcp start

Opción 2: Paquete NPM

# Install globally via npm
npm install -g mcp-for-microsoft-fabric-analytics

# Verify installation
fabric-analytics --version

# Start the server
fabric-analytics

# Or using npx (no installation required)
npx mcp-for-microsoft-fabric-analytics

Opción 3: Script de Instalación Universal

Para configuración automatizada con configuración de entorno:

Unix/Linux/macOS:

# Download and run universal installer
curl -fsSL https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-universal.sh | bash

# Or with options for full setup
curl -fsSL https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-universal.sh | bash -s -- --method pip --config --env --test

Windows (PowerShell):

# Download and run Windows installer
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-windows.ps1'))

# Or with options for full setup
& ([scriptblock]::Create((iwr https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-windows.ps1).Content)) -Method pip -Config -Environment -Test

Opción 4: Docker

# Clone repository
git clone https://github.com/santhoshravindran7/Fabric-Analytics-MCP.git
cd Fabric-Analytics-MCP

# Build and run with Docker
docker build -t fabric-analytics-mcp .
docker run -d --name fabric-mcp -p 3000:3000 --env-file .env fabric-analytics-mcp

📖 Consulta la Guía de Instalación de Docker para opciones detalladas de implementación con Docker y Kubernetes.

Opción 5: Desde el Código Fuente (Desarrollo)

# Clone and build from source
git clone https://github.com/santhoshravindran7/Fabric-Analytics-MCP.git
cd Fabric-Analytics-MCP
npm install
npm run build    # ✅ All configuration files included!

⚙️ Configuración

Configura tus variables de entorno:

export FABRIC_AUTH_METHOD=bearer_token  # or service_principal, interactive
export FABRIC_CLIENT_ID=your-client-id
export FABRIC_CLIENT_SECRET=your-client-secret
export FABRIC_TENANT_ID=your-tenant-id
export FABRIC_DEFAULT_WORKSPACE_ID=your-workspace-id

🔧 Configuración de Claude Desktop

Agrega a tu configuración de Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Para Instalación desde PyPI:

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "fabric-analytics-mcp",
      "args": ["start"],
      "env": {
        "FABRIC_AUTH_METHOD": "bearer_token"
      }
    }
  }
}

Para Instalación desde NPM:

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "fabric-analytics",
      "env": {
        "FABRIC_AUTH_METHOD": "bearer_token"
      }
    }
  }
}

Para Instalación desde el Código Fuente:

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/PROJECT/build/index.js"]
    }
  }
}

🚀 Comenzar a Usar

Reinicia Claude Desktop y prueba estas consultas:

"Listar todos los áreas de trabajo a las que tengo acceso"
"Buscar el área de trabajo llamado 'Analytics'"
"Listar todos los elementos en mi área de trabajo de Fabric [tu-id-de-area-de-trabajo]"
"Crear un nuevo lakehouse llamado 'Analytics Hub'"
"Mostrarme todas las aplicaciones Spark en ejecución"
"Ejecutar esta consulta SQL: SELECT * FROM my_table LIMIT 10"

🧪 Desarrollo y Pruebas

Ejecutar el Servidor

npm start        # Production mode
npm run dev      # Development mode with auto-reload

Probar la Integración de la API de Livy

Para pruebas integrales de la funcionalidad de Spark, instala las dependencias de Python:

pip install -r livy_requirements.txt

Scripts de Prueba Disponibles:

livy_api_test.ipynb - Notebook interactivo para pruebas paso a paso
comprehensive_livy_test.py - Prueba completa con manejo de errores
spark_monitoring_test.py - Pruebas de monitoreo de aplicaciones Spark
mcp_spark_monitoring_demo.py - Demostración de integración del servidor MCP

Integración con Claude Desktop

Agrega esta configuración a tu archivo de configuración de Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/PROJECT/build/index.js"]
    }
  }
}

🎉 ¡Estás listo! Reinicia Claude Desktop y comienza a hacer preguntas sobre tus datos de Microsoft Fabric.

Configuración de Pruebas de la API de Livy

Para probar la funcionalidad de la API de Livy, se requieren dependencias adicionales de Python:

# Install Python dependencies for Livy API testing
pip install -r livy_requirements.txt

Scripts de Prueba Disponibles:

livy_api_test.ipynb - Notebook interactivo de Jupyter para pruebas paso a paso
comprehensive_livy_test.py - Prueba completa con manejo de errores
simple_livy_test.py - Prueba simple siguiendo patrones de ejemplo
livy_batch_test.py - Capacidades de prueba de trabajos por lotes
spark_monitoring_test.py - Pruebas de monitoreo de aplicaciones Spark

Uso

Ejecutar el Servidor

npm start

Modo de Desarrollo

npm run dev

Pruebas con Claude Desktop

Agrega la siguiente configuración a tu archivo de configuración de Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/PROJECT/build/index.js"]
    }
  }
}

💬 Consultas de Ejemplo

Una vez conectado a Claude Desktop, puedes hacer preguntas en lenguaje natural como:

Operaciones CRUD:

"Listar todos los Lakehouses en mi área de trabajo"
"Crear un nuevo Notebook llamado 'Data Analysis'"
"Actualizar la descripción de mi lakehouse"
"Eliminar el notebook de prueba de mi área de trabajo"

Gestión de Notebooks:

"Crear un notebook de análisis de ventas con datos de muestra"
"Generar un nuevo notebook de análisis de taxis de NYC"
"Crear una plantilla de notebook de aprendizaje automático"
"Obtener la definición de mi notebook existente"
"Ejecutar mi notebook con parámetros específicos"
"Actualizar mi notebook con nuevas celdas"

Operaciones de Datos:

"Consultar el conjunto de datos de ventas para obtener ingresos totales por región"
"Ejecutar mi notebook de análisis con la fecha de hoy"

Analítica:

"Obtener métricas de rendimiento de las últimas 24 horas"
"Analizar mi modelo de datos y proporcionar recomendaciones de optimización"
"Generar un informe de uso para mi área de trabajo"

Operaciones de la API de Livy:

"Crear una sesión de Livy para análisis interactivo de Spark"
"Ejecutar la consulta SQL 'SELECT * FROM my_table LIMIT 10'"
"Ejecutar código Spark para mostrar todas las tablas"
"Monitorear el progreso de mi trabajo por lotes"

Supervisión de aplicaciones Spark:

"Muéstrame todas las aplicaciones Spark en mi espacio de trabajo"
"¿Cuál es el estado de mis trabajos Spark de notebook?"
"Genera un panel de supervisión completo de Spark"
"Muéstrame las aplicaciones fallidas recientes"
"Cancela la aplicación Spark problemática"

Gestión de capacidad:

"Enumera todas las capacidades de Fabric que puedo usar"
"Asigna el espacio de trabajo 1234abcd-abcd-1234-abcd-123456789000 a la capacidad f9998888-7777-6666-5555-444433332222"
"Muestra todos los espacios de trabajo en la capacidad f9998888-7777-6666-5555-444433332222"
"Desasigna el espacio de trabajo 1234abcd-abcd-1234-abcd-123456789000 de su capacidad"

🧩 Herramientas de gestión de capacidad

Gestiona las asignaciones de capacidad de Microsoft Fabric directamente desde tu asistente de IA. Estas herramientas te permiten inspeccionar las capacidades disponibles, conectar/desconectar espacios de trabajo y auditar el uso de capacidad.

Herramientas disponibles

fabric_list_capacities – Enumera todas las capacidades a las que puedes acceder (ID, SKU, región, estado)
fabric_assign_workspace_to_capacity – Adjunta un espacio de trabajo a una capacidad dedicada
fabric_unassign_workspace_from_capacity – Devuelve un espacio de trabajo a la capacidad compartida
fabric_list_capacity_workspaces – Lista todos los espacios de trabajo alojados actualmente en una capacidad determinada

Notas

Si la autenticación falla o estás en modo simulación, las respuestas de capacidad se simulan.
Las operaciones de capacidad reales requieren permisos de administrador adecuados de Fabric / Power BI.
Puedes proporcionar un token de portador por llamada (campo bearerToken) o confiar en la autenticación global.

Referencia mínima de parámetros

Herramienta	Parámetros requeridos	Opcionales
fabric_list_capacities	(ninguno)	bearerToken
fabric_assign_workspace_to_capacity	capacityId, workspaceId	bearerToken
fabric_unassign_workspace_from_capacity	workspaceId	bearerToken
fabric_list_capacity_workspaces	capacityId	bearerToken

❗ Solución de problemas

Errores de análisis JSON (p. ej., `Unexpected token 'P'`)

Si Claude Desktop u otro cliente MCP informa un error como:

Error: Unexpected token 'P', "Please set"... is not valid JSON
SyntaxError: Unexpected token 'P', "Please set"... is not valid JSON

Este es EXACTAMENTE el problema informado en el issue de GitHub donde el usuario vio el error "Unexpected token 'P', 'Please set'...".

Esto casi siempre significa que algo escribió texto plano en STDOUT (que debe contener SOLO tramas JSON-RPC). Causas comunes:

Se agregaron declaraciones de depuración console.log en el código del servidor
Una dependencia que emite advertencias a STDOUT
Registro temprano antes de la inicialización del transporte

Correcciones implementadas en este servidor

✅ Un protector de inicio ahora redirige console.log / console.info a STDERR automáticamente
✅ La salida de depuración se ha consolidado detrás de la marca DEBUG_MCP_RUN=1
✅ Todos los mensajes de diagnóstico van a STDERR, manteniendo STDOUT limpio para el protocolo JSON-RPC

Qué puedes hacer

Evita agregar declaraciones console.log sin procesar; prefiere console.error (va a STDERR)
Si debes permitir el registro en stdout temporalmente (NO recomendado), establece:
- ALLOW_UNSAFE_STDOUT=true
- Elimínalo después de depurar
Regenera la compilación (npm run build) después de los cambios para asegurar que la salida compilada coincida con el código fuente

¿Las herramientas de capacidad no aparecen?

Si las herramientas de capacidad no aparecen cuando el cliente lista las herramientas:

Asegúrate de haber recompilado después de obtener los cambios: npm run build
Confirma que estás iniciando el servidor desde build/index.js y no desde una instantánea más antigua
Verifica que no haya una lista blanca del lado del cliente MCP que filtre los nombres de las herramientas
Ejecuta una prueba rápida de enumeración: pide al asistente "Listar todas las herramientas disponibles"
Si aún faltan, elimina la carpeta build/ y recompila para limpiar los artefactos obsoletos

Casos límite de autenticación

La autenticación de Azure CLI puede fallar silenciosamente sin una sesión activa de az login
Los tokens de portador expiran (~1 hora); actualízalos si las operaciones fallan repentinamente
Para pruebas locales: recurrir a la simulación aún te permite crear prototipos de flujos de herramientas

Obtener diagnósticos detallados

Establece lo siguiente (se envía a STDERR, seguro para el marco MCP):

DEBUG_MCP_RUN=1

Opcionalmente, agrega rastreo estructurado de autenticación:

DEBUG_AUTH=1

¿Necesitas un nuevo tema de solución de problemas? Abre un issue o PR para que otros se beneficien de la resolución.

🔐 Autenticación

Este servidor MCP admite múltiples métodos de autenticación impulsados por la Biblioteca de autenticación de Microsoft (MSAL):

🤖 Para Claude Desktop: Usa la autenticación con token de portador (Método #1) para la mejor experiencia y compatibilidad.

🔧 Corrección para Claude Desktop: Las actualizaciones recientes evitan los tiempos de espera de autenticación al priorizar los tokens de portador y agregar protección de tiempo de espera para los flujos de autenticación interactivos.

🎫 1. Autenticación con token de portador (Recomendada para Claude Desktop)

Perfecta para asistentes de IA y uso interactivo:

Para Claude Desktop:

Visita Configuración de Power BI Embed
Genera un token de portador para tu espacio de trabajo
Agrégalo a tu claude_desktop_config.json
Sin problemas de tiempo de espera - Omite la autenticación interactiva por completo

Para pruebas:

# All test scripts will prompt for authentication method
python enhanced_auth_test.py

🤖 2. Autenticación de entidad de servicio (Recomendada para producción)

Usa las credenciales de la aplicación de Azure AD:

ID de cliente (ID de aplicación)
Secreto de cliente
ID de inquilino (ID de directorio)

Configuración de variables de entorno:

export FABRIC_AUTH_METHOD="service_principal"
export FABRIC_CLIENT_ID="your-app-client-id"
export FABRIC_CLIENT_SECRET="your-app-client-secret"
export FABRIC_TENANT_ID="your-tenant-id"
export FABRIC_DEFAULT_WORKSPACE_ID="your-workspace-id"

Configuración de Claude Desktop:

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "node",
      "args": ["/path/to/build/index.js"],
      "env": {
        "FABRIC_AUTH_METHOD": "service_principal",
        "FABRIC_CLIENT_ID": "your-client-id",
        "FABRIC_CLIENT_SECRET": "your-client-secret",
        "FABRIC_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

📱 3. Autenticación con código de dispositivo

Inicia sesión con el navegador en otro dispositivo (ideal para entornos sin interfaz gráfica):

export FABRIC_AUTH_METHOD="device_code"
export FABRIC_CLIENT_ID="your-client-id"
export FABRIC_TENANT_ID="your-tenant-id"

🌐 4. Autenticación interactiva

Autenticación automática basada en navegador:

export FABRIC_AUTH_METHOD="interactive"
export FABRIC_CLIENT_ID="your-client-id"
export FABRIC_TENANT_ID="your-tenant-id"

🔧 5. Autenticación con Azure CLI ⭐ (Recomendada para desarrollo local)

Usa tu inicio de sesión existente de Azure CLI para pruebas locales sin inconvenientes:

export FABRIC_AUTH_METHOD="azure_cli"

Requisitos previos:

Instala Azure CLI: winget install Microsoft.AzureCLI (Windows) o Descargar
Inicia sesión en Azure: az login
Establece la suscripción activa: az account set --subscription "your-subscription-name"

Beneficios:

✅ Cero configuración - Usa tu inicio de sesión existente de Azure
✅ Configuración instantánea - No se necesitan registros de aplicación ni secretos de cliente
✅ Soporte multi-cuenta - Cambia entre cuentas de Azure fácilmente
✅ Perfecto para desarrollo - Experiencia de pruebas locales sin interrupciones

Prueba rápida:

# Verify Azure CLI setup
npm run test:azure-cli

# Start MCP server with Azure CLI auth
$env:FABRIC_AUTH_METHOD="azure_cli"; npm start

💡 Consejo profesional: La autenticación con Azure CLI es perfecta para desarrolladores que quieren probar rápidamente el servidor MCP sin una configuración compleja de aplicaciones de Azure AD. Solo az login y ¡listo!

🔧 Configuración completa de autenticación

📚 Guías detalladas:

Guía de configuración de autenticación - Configuración completa de Azure AD
Ejemplos de configuración de Claude Desktop - Configuraciones listas para usar

🔍 Pruebas de autenticación

Verifica tu estado de autenticación:

"Check my Fabric authentication status"
"What authentication method am I using?"
"Test my Microsoft Fabric authentication setup"

🔒 Prácticas recomendadas de seguridad

Nunca confirmes tokens de autenticación en el control de versiones
Usa la autenticación de entidad de servicio para implementaciones de producción
El flujo de código de dispositivo es perfecto para CI/CD y entornos sin interfaz gráfica
La autenticación interactiva es ideal para desarrollo y pruebas
Todos los tokens se validan automáticamente e incluyen verificación de expiración

Nota: El servidor MCP maneja sin problemas la validación de tokens y proporciona mensajes de error claros para problemas de autenticación.

☸️ Implementación en Azure Kubernetes Service (AKS)

Implementa el servidor MCP como un servicio escalable en Azure Kubernetes Service para uso empresarial en producción.

🚀 Implementación rápida en AKS

Requisitos previos

Azure CLI instalado y configurado
Docker instalado
kubectl instalado
Suscripción de Azure con permisos de AKS

1. Compilar y enviar la imagen de Docker

# Build the Docker image
npm run docker:build

# Tag and push to Azure Container Registry
npm run docker:push

2. Implementar en AKS

# Create Azure resources and deploy
./scripts/deploy-to-aks.sh

3. Acceder al servidor MCP

Una vez implementado, tu servidor MCP estará disponible en:

https://your-aks-cluster.region.cloudapp.azure.com/mcp

🏗️ Descripción general de la arquitectura

La implementación en AKS incluye:

Autoscaler horizontal de pods (3-10 pods según CPU/memoria)
Azure Load Balancer para alta disponibilidad
Terminación SSL/TLS con Azure Application Gateway
ConfigMaps para la configuración del entorno
Secretos para el almacenamiento seguro de credenciales
Comprobaciones de estado y sondas de preparación
Límites de recursos y garantías de calidad de servicio

📁 Archivos de implementación

Todos los manifiestos de Kubernetes se encuentran en el directorio /k8s:

namespace.yaml - Espacio de nombres dedicado
deployment.yaml - Implementación de la aplicación con escalado
service.yaml - Servicio de balanceador de carga
ingress.yaml - Acceso externo y SSL
configmap.yaml - Gestión de configuración
secret.yaml - Almacenamiento seguro de credenciales
hpa.yaml - Autoscaler horizontal de pods

🔧 Configuración

Configura la implementación estableciendo estas variables de entorno:

export AZURE_SUBSCRIPTION_ID="your-subscription-id"
export AZURE_RESOURCE_GROUP="fabric-mcp-rg"
export AKS_CLUSTER_NAME="fabric-mcp-cluster"
export ACR_NAME="fabricmcpregistry"
export DOMAIN_NAME="your-domain.com"

🔐 Seguridad de producción

La implementación en AKS incluye seguridad de nivel empresarial:

Ejecución de contenedor sin root
Sistema de archivos raíz de solo lectura
Gestión de secretos mediante la integración con Azure Key Vault
Políticas de red para el aislamiento del tráfico
RBAC con los permisos mínimos requeridos
Cumplimiento de estándares de seguridad de pods

📊 Supervisión y escalado

Integración con Azure Monitor para registros y métricas
Application Insights para el monitoreo de rendimiento
Punto de conexión de métricas de Prometheus para monitoreo personalizado
Autoescalado basado en umbrales de CPU (70%) y memoria (80%)
Comprobaciones de estado para el reinicio automático de pods

🔄 Integración CI/CD

Los scripts de implementación admiten:

Canalizaciones de Azure DevOps
Flujos de trabajo de GitHub Actions
Pruebas automatizadas antes de la implementación
Implementaciones azul-verde para cero tiempo de inactividad
Capacidades de reversión para una recuperación rápida

📚 Guía detallada: Consulta AKS_DEPLOYMENT.md para obtener instrucciones completas de configuración.

🌐 Servidor de Protocolo de Contexto de Modelo de Azure (Vista previa)

Microsoft Azure ahora ofrece un servicio de vista previa para alojar servidores MCP de forma nativa. Esto elimina la necesidad de gestionar infraestructura personalizada.

🚀 Implementación del servidor MCP de Azure

Requisitos previos

Suscripción de Azure con acceso de vista previa a MCP
Azure CLI con extensiones de MCP

Implementar en el servicio MCP de Azure

# Login to Azure
az login

# Enable MCP preview features
az extension add --name mcp-preview

# Deploy the MCP server
az mcp server create \
  --name "fabric-analytics-mcp" \
  --resource-group "your-rg" \
  --source-type "github" \
  --repository "santhoshravindran7/Fabric-Analytics-MCP" \
  --branch "main" \
  --auth-method "service-principal"

Configurar la autenticación

# Set up service principal authentication
az mcp server config set \
  --name "fabric-analytics-mcp" \
  --setting "FABRIC_CLIENT_ID=your-client-id" \
  --setting "FABRIC_CLIENT_SECRET=your-secret" \
  --setting "FABRIC_TENANT_ID=your-tenant-id"

Acceder a tu servidor MCP

# Get the server endpoint
az mcp server show --name "fabric-analytics-mcp" --query "endpoint"

🔧 Características del servidor MCP de Azure

Escalado automático según el uso
Supervisión y registro integrados
Seguridad integrada con Azure AD
Gestión de infraestructura cero
CDN global para baja latencia
Certificados SSL/TLS automáticos

💰 Optimización de costos

El servidor MCP de Azure ofrece:

Modelo de precios de pago por solicitud
Hibernación automática durante períodos de inactividad
Compartición de recursos entre múltiples clientes
Sin costos mínimos de infraestructura

📚 Más información: Documentación del servidor MCP de Azure

Nota: El servidor MCP de Azure está actualmente en vista previa. Consulta los Términos de vista previa de Azure para conocer la disponibilidad del servicio y las limitaciones.

🏗️ Arquitectura

Este servidor MCP está construido con:

TypeScript para desarrollo con seguridad de tipos
SDK de MCP para la implementación del Protocolo de Contexto de Modelo
Zod para la validación de esquemas y saneamiento de entradas
Entorno de ejecución de Node.js

⚙️ Configuración

El servidor utiliza los siguientes archivos de configuración:

tsconfig.json - Configuración del compilador de TypeScript
package.json - Configuración del paquete de Node.js
.vscode/mcp.json - Configuración del servidor MCP para VS Code

🔧 Desarrollo

Estructura del proyecto

├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── fabric-client.ts      # Microsoft Fabric API client
├── build/                    # Compiled JavaScript output
├── tests/                    # Test scripts and notebooks
├── .vscode/                  # VS Code configuration
├── package.json
├── tsconfig.json
└── README.md

Agregar nuevas herramientas

Para agregar nuevas herramientas al servidor:

Define el esquema de entrada usando Zod
Implementa la herramienta usando server.tool()
Agrega manejo de errores y validación
Actualiza la documentación

Integración de API

Este servidor incluye:

✅ Listo para producción:

Integración completa con la API de Microsoft Fabric Livy
Gestión del ciclo de vida de sesiones de Spark
Ejecución de declaraciones con soporte de SQL y Spark
Gestión de trabajos por lotes para operaciones de larga duración
Manejo integral de errores y lógica de reintentos
Sondeo y recuperación de resultados en tiempo real 🧪 Características de demostración:
Operaciones CRUD (configurables para APIs reales)
Analítica y métricas (marco extensible)
Análisis de modelo de datos (implementación de plantilla)

🧪 Pruebas

🚀 Pruebas de extremo a extremo

El servidor MCP incluye pruebas integrales de extremo a extremo que crean espacios de trabajo, elementos y trabajos reales para validar la funcionalidad completa mediante la autenticación de Azure CLI.

Configuración rápida para pruebas E2E

# 1. Set up end-to-end testing environment
npm run setup:e2e

# 2. Run the comprehensive end-to-end test
npm run test:e2e

Qué hace la prueba E2E

La prueba de extremo a extremo crea un flujo de trabajo completo en su inquilino de Microsoft Fabric:

🔐 Valida la autenticación de Azure CLI - Utiliza su sesión existente de az login
🏗️ Crea un espacio de trabajo de prueba - Nuevo espacio de trabajo con nombre único
⚡ Se adjunta a la capacidad - Vincula el espacio de trabajo a su capacidad de Fabric (opcional)
📓 Crea cuadernos y lakehouses - Elementos de prueba para validación
🏃 Ejecuta trabajos reales - Ejecuta el cuaderno con código Spark real
📊 Supervisa la ejecución - Realiza un seguimiento del estado y la finalización del trabajo
🧹 Limpia recursos - Elimina todos los recursos de prueba creados

Configuración de la prueba E2E

El script de configuración crea un archivo de configuración .env.e2e:

# Example configuration
FABRIC_CAPACITY_ID=your-capacity-id-here    # Optional: for capacity testing
E2E_TEST_TIMEOUT=300000                      # 5 minutes per operation
E2E_CLEANUP_ON_FAILURE=true                 # Clean up on test failure
E2E_RETRY_COUNT=3                           # Retry failed operations

Características de la prueba E2E

✅ Creación de recursos reales - Crea espacios de trabajo y elementos reales de Fabric
✅ Integración con Azure CLI - Utiliza su autenticación de Azure existente
✅ Asignación de capacidad - Prueba la vinculación del espacio de trabajo a la capacidad
✅ Ejecución de trabajos - Ejecuta trabajos Spark reales y supervisa su finalización
✅ Limpieza automática - Elimina todos los recursos de prueba automáticamente
✅ Registro integral - Registro detallado de todas las operaciones
✅ Manejo de errores - Manejo de errores y recuperación robustos

Requisitos previos para las pruebas E2E

Azure CLI instalado e iniciado sesión:
```
az login
```
Acceso a Microsoft Fabric con permisos para:
- Crear espacios de trabajo
- Crear cuadernos y lakehouses
- Ejecutar trabajos Spark
- (Opcional) Asignar espacios de trabajo a la capacidad
Capacidad de Fabric (opcional pero recomendada):
- Establezca FABRIC_CAPACITY_ID en .env.e2e para las pruebas de capacidad
- Sin capacidad, el espacio de trabajo utilizará la capacidad compartida

Ejecución de pruebas E2E

# Complete setup and run
npm run setup:e2e && npm run test:e2e

# Or run individual steps
npm run setup:e2e          # Set up environment
npm run test:e2e           # Run end-to-end test

# Direct execution
node setup-e2e.cjs         # Setup script
node test-end-to-end.cjs   # Test script

Salida de la prueba E2E

La prueba proporciona una salida integral que incluye:

🚀 Starting End-to-End Test for Microsoft Fabric Analytics MCP Server
✅ MCP Server Startup (1234ms)
✅ Azure CLI Authentication
✅ Workspace Creation
✅ Capacity Attachment
✅ Notebook Creation
✅ Lakehouse Creation
✅ Item Validation
✅ Job Execution

📊 TEST SUMMARY
================
✅ MCP Server Startup (2341ms)
✅ Azure CLI Authentication
✅ Workspace Creation
✅ Capacity Attachment
✅ Notebook Creation
✅ Lakehouse Creation
✅ Item Validation  
✅ Job Execution

Total: 8 | Passed: 8 | Failed: 0

⚠️ Notas importantes para las pruebas E2E

Crea recursos reales: La prueba crea espacios de trabajo y elementos reales en su inquilino de Fabric
Requiere permisos: Asegúrese de tener los permisos necesarios de Fabric
Utiliza capacidad: Los trabajos pueden consumir unidades de capacidad si se utiliza capacidad dedicada
Limpieza automática: Todos los recursos se eliminan automáticamente después de las pruebas
Dependiente de la red: Requiere una conexión a Internet estable para las llamadas a la API

🧪 Pruebas unitarias y de integración

Requisitos previos

# Install Python dependencies for API testing
pip install -r livy_requirements.txt

Scripts de prueba disponibles

livy_api_test.ipynb - Cuaderno Jupyter interactivo para pruebas paso a paso
comprehensive_livy_test.py - Prueba completa con manejo de errores
simple_livy_test.py - Prueba simple siguiendo patrones de ejemplo
livy_batch_test.py - Capacidades de prueba de trabajos por lotes
spark_monitoring_test.py - Pruebas de monitoreo de aplicaciones Spark

Pruebas rápidas

Pruebas interactivas:
```
jupyter notebook livy_api_test.ipynb
```

Pruebas de línea de comandos:

python simple_livy_test.py
python spark_monitoring_test.py

Pruebas integrales:

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Así es como puede comenzar:

Haga un fork del repositorio
Cree una rama de características (git checkout -b feature/amazing-feature)
Realice sus cambios y agregue pruebas si corresponde
Confirme sus cambios (git commit -m 'Add amazing feature')
Empuje a la rama (git push origin feature/amazing-feature)
Abra una solicitud de extracción

Directrices de desarrollo

Siga las mejores prácticas de TypeScript
Agregue comentarios JSDoc para nuevas funciones
Actualice las pruebas para cualquier nueva funcionalidad
Actualice la documentación según sea necesario
Consulte CONTRIBUTING.md para obtener directrices detalladas

🔒 Seguridad

Nunca confirme tokens de autenticación en el control de versiones
Utilice variables de entorno para la configuración sensible
Siga las mejores prácticas de seguridad de Microsoft Fabric
Informe problemas de seguridad de forma privada a través de GitHub security advisories
Consulte SECURITY.md para nuestra política de seguridad completa

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para obtener más detalles.

Soporte

Para problemas y preguntas:

📖 Consulte la documentación de MCP
📚 Revise la documentación de la API de Microsoft Fabric
🐛 Abra un problema en este repositorio
💬 Únase a las discusiones de la comunidad

Agradecimientos

Equipo de Microsoft Fabric Analytics por la plataforma de datos integral y las capacidades de análisis
Equipos de la plataforma Microsoft Fabric por la plataforma API robusta y la infraestructura
Bogdan Crivat y Chris Finlan por la inspiradora conversación de lluvia de ideas que me dio la idea de abrir este proyecto como código abierto
Anthropic por la especificación del Model Context Protocol

Este proyecto comenzó como mi proyecto de hack de fin de semana explorando la integración de IA con Microsoft Fabric. Durante una conversación casual con Chris y Bogdan sobre hacer que las herramientas de IA sean más accesibles. Lo que comenzó como un experimento personal durante un fin de semana ahora está disponible para que todos puedan construir sobre él.

Microsoft Fabric Analytics

Documentación

Microsoft Fabric Analytics MCP Server

📋 Tabla de Contenidos

🌟 Características Clave

🔀 Herramientas de Migración de Synapse a Fabric

🆕 Migración Automatizada de Cargas de Trabajo de Spark

🔍 Herramientas de Descubrimiento de Migración

🔄 Herramientas de Transformación y Migración

✨ Características Clave de Migración

🎯 Escenarios de Migración

🎯 Pruebas de Extremo a Extremo con Espacios de Trabajo Reales

🚀 Opciones de Despliegue

🤖 Integración con Claude Desktop

🔧 Solución de Autenticación para Claude Desktop

📱 Desarrollo Local

🐳 Despliegue con Docker

☸️ Azure Kubernetes Service (AKS)

🌐 Azure MCP Server (Vista Previa)

🛠️ Herramientas y Capacidades

🔍 Operaciones CRUD para Elementos de Fabric

🔍 Consultar Conjunto de Datos de Fabric (Mejorado)

🚀 Ejecutar Notebook de Fabric

📊 Obtener Métricas de Análisis

🔧 Analizar Modelo de Datos

📋 Generar Informe de Análisis

🚀 Integración con la API de Livy (Sesiones y Trabajos por Lotes)

Gestión de Sesiones

Ejecución de Sentencias

Gestión de Trabajos por Lotes

📊 Monitoreo de Aplicaciones Spark

Monitoreo a Nivel de Área de Trabajo

Monitoreo Específico por Elemento

Gestión de Aplicaciones

Panel de Monitoreo

📓 Gestión de Notebooks

Crear Notebook desde Plantilla

Obtener Definición de Notebook

Actualizar Definición de Notebook

Ejecutar Notebook

🚀 Inicio Rápido

🎯 Métodos de Instalación

Opción 1: Paquete de Python (PyPI) ⭐ Recomendado

Opción 2: Paquete NPM

Opción 3: Script de Instalación Universal

Opción 4: Docker

Opción 5: Desde el Código Fuente (Desarrollo)

⚙️ Configuración

🔧 Configuración de Claude Desktop

Para Instalación desde PyPI:

Para Instalación desde NPM:

Para Instalación desde el Código Fuente:

🚀 Comenzar a Usar

🧪 Desarrollo y Pruebas

Ejecutar el Servidor

Probar la Integración de la API de Livy

Integración con Claude Desktop

Configuración de Pruebas de la API de Livy

Scripts de Prueba Disponibles:

Uso

Ejecutar el Servidor

Modo de Desarrollo

Pruebas con Claude Desktop

💬 Consultas de Ejemplo

Operaciones CRUD:

Gestión de Notebooks:

Operaciones de Datos:

Analítica:

Operaciones de la API de Livy:

Supervisión de aplicaciones Spark:

Gestión de capacidad:

🧩 Herramientas de gestión de capacidad

Herramientas disponibles

Notas

Referencia mínima de parámetros

❗ Solución de problemas

Errores de análisis JSON (p. ej., Unexpected token 'P')

Correcciones implementadas en este servidor

Qué puedes hacer

¿Las herramientas de capacidad no aparecen?

Errores de análisis JSON (p. ej., `Unexpected token 'P'`)