Microsoft Fabric Analytics

Um servidor de análise que fornece ferramentas para interagir com a plataforma de dados Microsoft Fabric.

Documentação

Microsoft Fabric Analytics MCP Server

Um servidor abrangente de Model Context Protocol (MCP) que fornece capacidades analíticas e ferramentas para interagir com a plataforma de dados Microsoft Fabric. Este servidor permite que assistentes de IA como Claude acessem, analisem e monitorem recursos do Microsoft Fabric de forma integrada por meio de protocolos MCP padronizados, trazendo o poder do Microsoft Fabric diretamente para suas conversas com IA.

📋 Sumário

🌟 Principais Recursos
🚀 Início Rápido
🛠️ Ferramentas e Capacidades
🧪 Desenvolvimento e Testes
💬 Exemplos de Consultas
🔐 Autenticação
🏗️ Arquitetura
⚙️ Configuração
🤝 Contribuição
🔒 Segurança "Cancele o aplicativo Spark problemático"
📞 Suporte

🌟 Principais Recursos

🏗️ Gerenciamento Completo de Workspaces - Crie, exclua e gerencie workspaces do Fabric com atribuição de capacidade
🔄 Operações CRUD Aprimoradas - Crie, leia, atualize e exclua todos os itens do Fabric (notebooks, lakehouses, datasets, relatórios)
📓 Gerenciamento Avançado de Notebooks - Crie, execute e gerencie notebooks do Fabric com 5 modelos predefinidos
⚡ Integração com API Livy - Gerenciamento completo de sessões Spark e jobs em lote com monitoramento em tempo real
📊 Monitoramento Abrangente do Spark - Monitoramento em tempo real em workspaces, itens e aplicativos
🤖 Suporte a Múltiplos Assistentes de IA - Funciona com Claude Desktop, GitHub Copilot e outras ferramentas de IA compatíveis com MCP
🔐 Autenticação Aprimorada com Azure CLI - Configuração zero com gerenciamento automático de tokens
️ Autenticação Empresarial - Múltiplos métodos de autenticação (Bearer, Service Principal, Device Code, Interativa, Azure CLI)
📈 Análises e Insights - Gere dashboards de monitoramento abrangentes com métricas em tempo real
🧪 Testes de Ponta a Ponta - Suíte de testes completa com criação real de workspaces e execução de jobs
🔄 Gerenciamento Avançado de Tokens - Validação automática de tokens, atualização e tratamento de expiração "Liste todas as capacidades do Fabric que posso usar" "Atribua o workspace 1234abcd-abcd-1234-abcd-123456789000 à capacidade f9998888-7777-6666-5555-444433332222" "Mostre todos os workspaces na capacidade f9998888-7777-6666-5555-444433332222" "Desatribua o workspace 1234abcd-abcd-1234-abcd-123456789000 de sua capacidade"

- **☸️ 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:**

"Crie um novo workspace chamado 'Analytics-Q1-2025' e atribua-o à nossa capacidade premium"


**📊 Multi-Workspace Analytics:**

"Liste todos os workspaces em nosso tenant e mostre suas atribuições de capacidade"


**🔒 Access Management:**

"Adicione o usuário john.doe@company.com como Admin ao workspace Analytics"


**🏗️ Environment Setup:**

"Crie um ambiente de desenvolvimento no workspace Analytics com bibliotecas Python e R"


**🔄 Git Integration:**

"Conecte o workspace Analytics ao nosso repositório GitHub para controle de versão"


### **🤖 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

🔀 Ferramentas de Migração do Synapse para o Fabric

🆕 Migração Automatizada de Cargas de Trabalho Spark

O servidor MCP agora inclui 4 ferramentas de migração especializadas que automatizam a migração de notebooks e pipelines Spark do Azure Synapse Analytics para o Microsoft Fabric:

🔍 Ferramentas de Descoberta de Migração

fabric_list_synapse_workspaces - Liste todos os workspaces do Synapse em sua assinatura do Azure
fabric_discover_synapse_workspace - Inventarie notebooks, pipelines, serviços vinculados e jobs Spark do Synapse

🔄 Ferramentas de Transformação e Migração

fabric_transform_notebooks - Transforme notebooks do Synapse para o formato do Fabric (mssparkutils → notebookutils)
fabric_migrate_synapse_to_fabric - Migração completa de ponta a ponta com descoberta, transformação e provisionamento

✨ Principais Recursos de Migração

Transformação Automática de Código - Converte código específico do Synapse para equivalentes do Fabric:
- mssparkutils → notebookutils
- Comandos mágicos do Synapse → Comandos mágicos do Fabric
- Reescrita de caminhos ABFSS para OneLake
- Limpeza de configuração do pool Spark
Descoberta Abrangente de Ativos - Inventaria todos os ativos migráveis:
- Notebooks Jupyter (formato ipynb)
- Pipelines e fluxos de trabalho de dados
- Serviços vinculados e conexões
- Definições de jobs Spark
Testes Seguros com Dry Run - Visualize todas as alterações antes de aplicar:
- Teste transformações sem provisionamento
- Valide o código transformado
- Revise relatórios de alterações
Automação de Ponta a Ponta - Pipeline de migração completo:
- Descoberta → Transformação → Provisionamento → Validação
- Criação automática de lakehouse
- Provisionamento de atalhos OneLake
- Relatórios abrangentes de migração

🎯 Cenários de Migração

Migration Demo

📋 Explore Antes de Migrar:

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

🔄 Visualize Transformações:

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

🚀 Migração Completa:

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

📊 Guia Detalhado de Migração: Consulte MIGRATION.md para documentação abrangente de migração, incluindo:

Fluxos de trabalho passo a passo
Detalhes das regras de transformação
Melhores práticas e solução de problemas
Exemplos completos

🎯 Testes de Ponta a Ponta com Workspaces Reais

O servidor MCP agora inclui testes abrangentes de ponta a ponta que criam workspaces reais, atribuem-nos a capacidades e executam jobs reais para validar o fluxo de trabalho completo:

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

O que é testado:

✅ Criação de Workspace - Cria workspaces reais do Fabric
✅ Atribuição de Capacidade - Anexa workspaces à sua capacidade do Fabric
✅ Criação de Itens - Cria notebooks, lakehouses e outros itens
✅ Execução de Jobs - Executa jobs Spark reais e monitora a conclusão
✅ Limpeza de Recursos - Remove automaticamente todos os recursos de teste

🚀 Opções de Implantação

🤖 Integração com Claude Desktop

Recomendado para uso com Assistentes 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"
      }
    }
  }
}

💡 Obtenha o Bearer Token: Visite Power BI Embed Setup para gerar tokens

⚠️ Importante: Os tokens expiram após ~1 hora e precisam ser atualizados

🔧 Correção de Autenticação do Claude Desktop

Se você enfrentar timeouts de 60 segundos durante a inicialização, isso se deve a fluxos de autenticação interativos que bloqueiam o ambiente sandbox do Claude Desktop. Solução:

Use o Método Bearer Token (Recomendado):
- Defina FABRIC_AUTH_METHOD: "bearer_token" em sua configuração
- Forneça FABRIC_TOKEN com um bearer token válido
- Isso ignora completamente a autenticação interativa
Alternativa - Autenticação por Ferramenta:
- Forneça o token diretamente nas chamadas de ferramenta: bearerToken: "your_token_here"
- Ou use o modo de simulação: bearerToken: "simulation"
Solução de Problemas:
- O servidor agora tem proteção de timeout de 10 segundos para evitar travamentos
- Retorna ao modo de simulação se a autenticação falhar
- Mensagens de erro aprimoradas fornecem orientação clara

🎯 Correção Rápida: O servidor prioriza automaticamente a variável de ambiente FABRIC_TOKEN em vez de fluxos de autenticação interativos, prevenindo timeouts do Claude Desktop.

📱 Desenvolvimento 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

🐳 Implantação com 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 (Pré-visualização)

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

📚 Guias Detalhados:

🛠️ Ferramentas e Capacidades

🔍 Operações CRUD para Itens do Fabric

Ferramenta: list-fabric-items
Descrição: Liste itens em um workspace do Microsoft Fabric (Lakehouses, Notebooks, etc.)
Parâmetros:
- bearerToken: Bearer token do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- itemType: Filtrar por tipo de item (opcional)
Ferramenta: create-fabric-item
Descrição: Crie novos itens no workspace do Microsoft Fabric
Parâmetros:
- bearerToken: Bearer token do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- itemType: Tipo de item (Lakehouse, Notebook, Dataset, Relatório, Dashboard)
- displayName: Nome de exibição para o novo item
- description: Descrição opcional
Ferramenta: get-fabric-item
Descrição: Obtenha informações detalhadas sobre um item específico do Microsoft Fabric
Parâmetros:
- bearerToken: Bearer token do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- itemId: ID do item a ser recuperado
Ferramenta: update-fabric-item
Descrição: Atualize itens existentes no workspace do Microsoft Fabric
Parâmetros:
- bearerToken: Bearer token do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- itemId: ID do item a ser atualizado
- displayName: Novo nome de exibição (opcional)
- description: Nova descrição (opcional)
Ferramenta: delete-fabric-item
Descrição: Exclua itens do workspace do Microsoft Fabric
Parâmetros:
- bearerToken: Bearer token do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- itemId: ID do item a ser excluído

🔍 Consultar Dataset do Fabric (Aprimorado)

Ferramenta: query-fabric-dataset
Descrição: Execute consultas SQL ou KQL em datasets do Microsoft Fabric
Parâmetros:
- bearerToken: Bearer token do Microsoft Fabric (opcional - usa simulação se não fornecido)
- workspaceId: ID do workspace do Microsoft Fabric
- datasetName: Nome do dataset a ser consultado
- query: Consulta SQL ou KQL a ser executada

🚀 Executar Notebook do Fabric

Ferramenta: execute-fabric-notebook
Descrição: Execute um notebook no workspace do Microsoft Fabric
Parâmetros:
- bearerToken: Bearer token do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- notebookId: ID do notebook a ser executado
- parameters: Parâmetros opcionais a serem passados ao notebook

📊 Obter Métricas de Análise

Ferramenta: get-fabric-metrics
Descrição: Recupere métricas de desempenho e uso para itens do Microsoft Fabric
Parâmetros:
- workspaceId: ID do workspace do Microsoft Fabric
- itemId: ID do item (dataset, relatório, etc.)
- timeRange: Intervalo de tempo para métricas (1h, 24h, 7d, 30d)
- metrics: Lista de métricas a serem analisadas

🔧 Analisar Modelo de Dados

Ferramenta: analyze-fabric-model
Descrição: Analise um modelo de dados do Microsoft Fabric e obtenha recomendações de otimização
Parâmetros:
- workspaceId: ID do workspace do Microsoft Fabric
- itemId: ID do item a ser analisado

📋 Gerar Relatório de Análise

Ferramenta: generate-fabric-report
Descrição: Gere relatórios analíticos abrangentes para workspaces do Microsoft Fabric
Parâmetros:
- workspaceId: ID do workspace do Microsoft Fabric
- reportType: Tipo de relatório (desempenho, uso, saúde, resumo)

🚀 Integração com API Livy (Sessões e Jobs em Lote)

Gerenciamento de Sessões

Ferramenta: create-livy-session
Descrição: Crie uma nova sessão Livy para execução interativa de Spark/SQL
Parâmetros:
- bearerToken: Bearer token do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
- sessionConfig: Configuração opcional da sessão
Ferramenta: get-livy-session
Descrição: Obter detalhes de uma sessão Livy
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
- sessionId: ID da sessão Livy
Ferramenta: list-livy-sessions
Descrição: Listar todas as sessões Livy em um lakehouse
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
Ferramenta: delete-livy-session
Descrição: Excluir uma sessão Livy
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
- sessionId: ID da sessão Livy

Execução de Instruções

Ferramenta: execute-livy-statement
Descrição: Executar instruções SQL ou Spark em uma sessão Livy
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
- sessionId: ID da sessão Livy
- code: Código SQL ou Spark a ser executado
- kind: Tipo de instrução (sql, spark, etc.)
Ferramenta: get-livy-statement
Descrição: Obter status e resultados de uma instrução Livy
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
- sessionId: ID da sessão Livy
- statementId: ID da instrução

Gerenciamento de Trabalhos em Lote

Ferramenta: create-livy-batch
Descrição: Criar um novo trabalho em lote Livy para operações de longa duração
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
- batchConfig: Configuração do trabalho em lote
Ferramenta: get-livy-batch
Descrição: Obter detalhes de um trabalho em lote Livy
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
- batchId: ID do trabalho em lote
Ferramenta: list-livy-batches
Descrição: Listar todos os trabalhos em lote Livy em um lakehouse
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
Ferramenta: delete-livy-batch
Descrição: Excluir um trabalho em lote Livy
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse do Microsoft Fabric
- batchId: ID do trabalho em lote

📊 Monitoramento de Aplicações Spark

Monitoramento em Nível de Workspace

Ferramenta: get-workspace-spark-applications
Descrição: Obter todas as aplicações Spark em um workspace do Microsoft Fabric
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- continuationToken: Token opcional para paginação

Monitoramento Específico de Itens

Ferramenta: get-notebook-spark-applications
Descrição: Obter todas as aplicações Spark para um notebook específico
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- notebookId: ID do notebook
- continuationToken: Token opcional para paginação
Ferramenta: get-lakehouse-spark-applications
Descrição: Obter todas as aplicações Spark para um lakehouse específico
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- lakehouseId: ID do lakehouse
- continuationToken: Token opcional para paginação
Ferramenta: get-spark-job-definition-applications
Descrição: Obter todas as aplicações Spark para uma Definição de Trabalho Spark específica
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- sparkJobDefinitionId: ID da Definição de Trabalho Spark
- continuationToken: Token opcional para paginação

Gerenciamento de Aplicações

Ferramenta: get-spark-application-details
Descrição: Obter informações detalhadas sobre uma aplicação Spark específica
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- livyId: ID da sessão Livy
Ferramenta: cancel-spark-application
Descrição: Cancelar uma aplicação Spark em execução
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- livyId: ID da sessão Livy

Painel de Monitoramento

Ferramenta: get-spark-monitoring-dashboard
Descrição: Gerar um painel de monitoramento abrangente com análises
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric

📓 Gerenciamento de Notebooks

O servidor MCP fornece recursos abrangentes de gerenciamento de notebooks com modelos predefinidos e suporte a notebooks personalizados.

Criar Notebook a partir de Modelo

Ferramenta: create-fabric-notebook
Descrição: Criar novos notebooks do Fabric a partir de modelos predefinidos ou definições personalizadas
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- displayName: Nome de exibição para o novo notebook
- template: Tipo de modelo (blank, sales_analysis, nyc_taxi_analysis, data_exploration, machine_learning, custom)
- customNotebook: Definição personalizada do notebook (obrigatória se o modelo for 'custom')
- environmentId: ID de ambiente opcional para anexar
- lakehouseId: ID de lakehouse padrão opcional
- lakehouseName: Nome de lakehouse padrão opcional

Modelos Disponíveis:

blank: Notebook básico com configuração mínima
sales_analysis: Análise abrangente de dados de vendas com conjunto de dados de exemplo
nyc_taxi_analysis: Análise de dados de viagens de táxi em NYC com conjunto de dados de exemplo
data_exploration: Modelo estruturado de exploração de dados
machine_learning: Modelo completo de fluxo de trabalho de ML
custom: Use sua própria definição de notebook

Obter Definição do Notebook

Ferramenta: get-fabric-notebook-definition
Descrição: Recuperar a definição do notebook (células, metadados) de um notebook existente do Fabric
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- notebookId: ID do notebook a ser recuperado
- format: Formato de retorno (ipynb ou fabricGitSource)

Atualizar Definição do Notebook

Ferramenta: update-fabric-notebook-definition
Descrição: Atualizar a definição do notebook (células, metadados) de um notebook existente do Fabric
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- notebookId: ID do notebook a ser atualizado
- notebookDefinition: Objeto de definição do notebook atualizado

Executar Notebook

Ferramenta: run-fabric-notebook
Descrição: Executar um notebook do Fabric sob demanda com parâmetros e configuração opcionais
Parâmetros:
- bearerToken: Token de portador do Microsoft Fabric
- workspaceId: ID do workspace do Microsoft Fabric
- notebookId: ID do notebook a ser executado
- parameters: Parâmetros opcionais do notebook (pares chave-valor com tipos)
- configuration: Configuração opcional de execução (ambiente, lakehouse, pools, etc.)

Recursos:

📓 Suporte a payload de notebook codificado em Base64
🔧 Gerenciamento abrangente de metadados
🌐 Integração com ambiente e lakehouse
🎛️ Execução parametrizada de notebooks
⚡ Suporte a configuração do Spark
🔤 Suporte a múltiplas linguagens de programação (Python, Scala, SQL, R)

🚀 Início Rápido

🎯 Métodos de Instalação

Escolha seu método de instalação preferido:

Opção 1: Pacote 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

Opção 2: Pacote 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

Opção 3: Script de Instalação Universal

Para configuração automatizada com configuração de ambiente:

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

Opção 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

📖 Consulte o Guia de Instalação Docker para opções detalhadas de implantação com Docker e Kubernetes.

Opção 5: A partir do Código-Fonte (Desenvolvimento)

# 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!

⚙️ Configuração

Configure suas variáveis de ambiente:

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

🔧 Configuração do Claude Desktop

Adicione à sua configuração do Claude Desktop:

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

Para Instalação via PyPI:

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

Para Instalação via NPM:

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

Para Instalação a partir do Código-Fonte:

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

🚀 Comece a Usar

Reinicie o Claude Desktop e tente estas consultas:

"Listar todos os workspaces aos quais tenho acesso"
"Encontrar workspace chamado 'Analytics'"
"Listar todos os itens no meu workspace do Fabric [seu-id-do-workspace]"
"Criar um novo lakehouse chamado 'Analytics Hub'"
"Mostrar todas as aplicações Spark em execução"
"Executar esta consulta SQL: SELECT * FROM my_table LIMIT 10"

🧪 Desenvolvimento e Testes

Executando o Servidor

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

Testando a Integração com a API Livy

Para testes abrangentes da funcionalidade Spark, instale as dependências Python:

pip install -r livy_requirements.txt

Scripts de Teste Disponíveis:

livy_api_test.ipynb - Notebook interativo para testes passo a passo
comprehensive_livy_test.py - Teste completo com tratamento de erros
spark_monitoring_test.py - Testes de monitoramento de aplicações Spark
mcp_spark_monitoring_demo.py - Demonstração de integração do servidor MCP

Integração com Claude Desktop

Adicione esta configuração ao seu arquivo de configuração do 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"]
    }
  }
}

🎉 Você está pronto! Reinicie o Claude Desktop e comece a fazer perguntas sobre seus dados do Microsoft Fabric!

Configuração de Testes da API Livy

Para testar a funcionalidade da API Livy, dependências Python adicionais são necessárias:

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

Scripts de Teste Disponíveis:

livy_api_test.ipynb - Notebook Jupyter interativo para testes passo a passo
comprehensive_livy_test.py - Teste completo com tratamento de erros
simple_livy_test.py - Teste simples seguindo padrões de exemplo
livy_batch_test.py - Recursos de teste de trabalhos em lote
spark_monitoring_test.py - Testes de monitoramento de aplicações Spark

Uso

Executando o Servidor

npm start

Modo de Desenvolvimento

npm run dev

Testando com Claude Desktop

Adicione a seguinte configuração ao seu arquivo de configuração do 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"]
    }
  }
}

💬 Exemplos de Consultas

Uma vez conectado ao Claude Desktop, você pode fazer perguntas em linguagem natural como:

Operações CRUD:

"Listar todos os Lakehouses no meu workspace"
"Criar um novo Notebook chamado 'Data Analysis'"
"Atualizar a descrição do meu lakehouse"
"Excluir o notebook de teste do meu workspace"

Gerenciamento de Notebooks:

"Criar um notebook de análise de vendas com dados de exemplo"
"Gerar um novo notebook de análise de táxis em NYC"
"Criar um modelo de notebook de machine learning"
"Obter a definição do meu notebook existente"
"Executar meu notebook com parâmetros específicos"
"Atualizar meu notebook com novas células"

Operações de Dados:

"Consultar o conjunto de dados de vendas para obter a receita total por região"
"Executar meu notebook de análise com a data de hoje"

Análises:

"Obter métricas de desempenho das últimas 24 horas"
"Analisar meu modelo de dados e fornecer recomendações de otimização"
"Gerar um relatório de uso para meu workspace"

Operações da API Livy:

"Criar uma sessão Livy para análise Spark interativa"
"Executar consulta SQL 'SELECT * FROM my_table LIMIT 10'"
"Executar código Spark para mostrar todas as tabelas"
"Monitorar o progresso do meu trabalho em lote"

Monitoramento de Aplicativos Spark:

"Mostre-me todos os aplicativos Spark no meu workspace"
"Qual é o status dos meus jobs Spark do notebook?"
"Gere um dashboard abrangente de monitoramento Spark"
"Mostre-me aplicativos reprovados recentes"
"Cancele o aplicativo Spark problemático"

Gerenciamento de Capacidade:

"Liste todas as capacidades Fabric que posso usar"
"Atribua o workspace 1234abcd-abcd-1234-abcd-123456789000 à capacidade f9998888-7777-6666-5555-444433332222"
"Mostre todos os workspaces na capacidade f9998888-7777-6666-5555-444433332222"
"Desatribua o workspace 1234abcd-abcd-1234-abcd-123456789000 de sua capacidade"

🧩 Ferramentas de Gerenciamento de Capacidade

Gerencie atribuições de capacidade do Microsoft Fabric diretamente do seu assistente de IA. Essas ferramentas permitem inspecionar capacidades disponíveis, anexar/desanexar workspaces e auditar o uso de capacidade.

Ferramentas Disponíveis

fabric_list_capacities – Enumere todas as capacidades que você pode acessar (ID, SKU, região, estado)
fabric_assign_workspace_to_capacity – Anexe um workspace a uma capacidade dedicada
fabric_unassign_workspace_from_capacity – Retorne um workspace à capacidade compartilhada
fabric_list_capacity_workspaces – Liste todos os workspaces atualmente hospedados em uma determinada capacidade

Notas

Se a autenticação falhar ou você estiver no modo de simulação, as respostas de capacidade serão simuladas.
Operações reais de capacidade exigem permissões de administrador apropriadas do Fabric / Power BI.
Você pode fornecer um token de portador por chamada (campo bearerToken) ou depender da autenticação global.

Referência Mínima de Parâmetros

Ferramenta	Parâmetros Obrigatórios	Opcional
fabric_list_capacities	(nenhum)	bearerToken
fabric_assign_workspace_to_capacity	capacityId, workspaceId	bearerToken
fabric_unassign_workspace_from_capacity	workspaceId	bearerToken
fabric_list_capacity_workspaces	capacityId	bearerToken

❗ Solução de Problemas

Erros de Análise JSON (ex.: `Unexpected token 'P'`)

Se o Claude Desktop ou outro cliente MCP relatar um erro como:

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

Este é EXATAMENTE o problema relatado na issue do GitHub onde o usuário viu erros "Unexpected token 'P', 'Please set'...".

Isso quase sempre significa que algo escreveu texto simples no STDOUT (que deve conter APENAS quadros JSON-RPC). Causas comuns:

Declarações de depuração console.log adicionadas no código do servidor
Uma dependência emitindo avisos para o STDOUT
Registro antecipado antes da inicialização do transporte

Correções Implementadas Neste Servidor

✅ Uma proteção de inicialização agora redireciona console.log / console.info para o STDERR automaticamente
✅ A saída de depuração foi consolidada atrás do sinalizador DEBUG_MCP_RUN=1
✅ Todas as mensagens de diagnóstico vão para o STDERR, mantendo o STDOUT limpo para o protocolo JSON-RPC

O Que Você Pode Fazer

Evite adicionar declarações console.log brutas—prefira console.error (vai para o STDERR)
Se você precisar permitir o registro de stdout temporariamente (NÃO recomendado), defina:
- ALLOW_UNSAFE_STDOUT=true
- Remova após a depuração
Regere o build (npm run build) após alterações para garantir que a saída compilada corresponda ao código-fonte

Ferramentas de Capacidade Não Aparecendo?

Se as ferramentas de capacidade não aparecerem quando o cliente listar as ferramentas:

Certifique-se de que você reconstruiu após puxar as alterações: npm run build
Confirme que você está iniciando o servidor a partir de build/index.js e não de um snapshot mais antigo
Verifique se nenhuma lista de permissões do lado do cliente MCP está filtrando nomes de ferramentas
Execute um teste rápido de enumeração: pergunte ao assistente "List all available tools"
Se ainda estiverem ausentes, exclua a pasta build/ e reconstrua para limpar artefatos obsoletos

Casos Extremos de Autenticação

A autenticação do Azure CLI pode falhar silenciosamente sem uma sessão az login ativa
Os tokens de portador expiram (~1 hora); atualize se as operações falharem repentinamente
Para testes locais: recorrer à simulação ainda permite que você prototipe fluxos de ferramentas

Obtendo Diagnósticos Detalhados

Defina o seguinte (enviado para o STDERR, seguro para enquadramento MCP):

DEBUG_MCP_RUN=1

Opcionalmente, adicione rastreamento de autenticação estruturado:

DEBUG_AUTH=1

Precisa de um novo tópico de solução de problemas? Abra uma issue ou PR para que outros se beneficiem da resolução.

🔐 Autenticação

Este servidor MCP suporta múltiplos métodos de autenticação alimentados pela Microsoft Authentication Library (MSAL):

🤖 Para Claude Desktop: Use Autenticação por Token de Portador (Método #1) para a melhor experiência e compatibilidade.

🔧 Correção do Claude Desktop: Atualizações recentes previnem timeouts de autenticação priorizando tokens de portador e adicionando proteção de timeout para fluxos de autenticação interativos.

🎫 1. Autenticação por Token de Portador (Recomendado para Claude Desktop)

Perfeito para assistentes de IA e uso interativo:

Para Claude Desktop:

Visite Power BI Embed Setup
Gere um token de portador para o seu workspace
Adicione ao seu claude_desktop_config.json
Sem problemas de timeout - ignora completamente a autenticação interativa

Para Testes:

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

🤖 2. Autenticação de Principal de Serviço (Recomendado para Produção)

Use credenciais de aplicativo do Azure AD:

Client ID (ID do Aplicativo)
Client Secret
Tenant ID (ID do Diretório)

Configuração de Variáveis de Ambiente:

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"

Configuração do 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. Autenticação por Código de Dispositivo

Entre com o navegador em outro dispositivo (ótimo para ambientes headless):

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

🌐 4. Autenticação Interativa

Autenticação automática baseada em navegador:

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

🔧 5. Autenticação do Azure CLI ⭐ (Recomendado para Desenvolvimento Local)

Use seu login existente do Azure CLI para testes locais sem interrupções:

export FABRIC_AUTH_METHOD="azure_cli"

Pré-requisitos:

Instale o Azure CLI: winget install Microsoft.AzureCLI (Windows) ou Download
Faça login no Azure: az login
Defina a assinatura ativa: az account set --subscription "your-subscription-name"

Benefícios:

✅ Configuração Zero - Usa seu login existente do Azure
✅ Configuração Instantânea - Sem registro de aplicativo ou client secrets necessários
✅ Suporte a Múltiplas Contas - Alterne contas do Azure facilmente
✅ Perfeito para Desenvolvimento - Experiência de teste local sem interrupções

Teste Rápido:

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

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

💡 Dica Profissional: A autenticação do Azure CLI é perfeita para desenvolvedores que desejam testar rapidamente o servidor MCP sem configuração complexa de aplicativo Azure AD. Basta az login e você está pronto!

🔧 Configuração Completa de Autenticação

📚 Guias Detalhados:

Authentication Setup Guide - Configuração completa do Azure AD
Claude Desktop Config Examples - Configurações prontas para uso

🔍 Teste de Autenticação

Verifique seu status de autenticação:

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

🔒 Melhores Práticas de Segurança

Nunca envie tokens de autenticação para o controle de versão
Use autenticação Service Principal para implantações de produção
O fluxo Device Code é perfeito para CI/CD e ambientes headless
A autenticação Interativa é ideal para desenvolvimento e testes
Todos os tokens são validados automaticamente e incluem verificação de expiração

Nota: O servidor MCP lida perfeitamente com a validação de tokens e fornece mensagens de erro claras para problemas de autenticação.

☸️ Implantação no Azure Kubernetes Service (AKS)

Implante o servidor MCP como um serviço escalável no Azure Kubernetes Service para uso empresarial em produção.

🚀 Implantação Rápida no AKS

Pré-requisitos

Azure CLI instalado e configurado
Docker instalado
kubectl instalado
Assinatura do Azure com permissões de AKS

1. Construir e Enviar Imagem Docker

# Build the Docker image
npm run docker:build

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

2. Implantar no AKS

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

3. Acessar o Servidor MCP

Uma vez implantado, seu servidor MCP estará disponível em:

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

🏗️ Visão Geral da Arquitetura

A implantação no AKS inclui:

Horizontal Pod Autoscaler (3-10 pods com base em CPU/memória)
Azure Load Balancer para alta disponibilidade
Terminação SSL/TLS com Azure Application Gateway
ConfigMaps para configuração de ambiente
Secrets para armazenamento seguro de credenciais
Health checks e sondas de prontidão
Limites de recursos e garantias de qualidade de serviço

📁 Arquivos de Implantação

Todos os manifestos Kubernetes estão localizados no diretório /k8s:

namespace.yaml - Namespace dedicado
deployment.yaml - Implantação do aplicativo com escalonamento
service.yaml - Serviço de balanceador de carga
ingress.yaml - Acesso externo e SSL
configmap.yaml - Gerenciamento de configuração
secret.yaml - Armazenamento seguro de credenciais
hpa.yaml - Horizontal Pod Autoscaler

🔧 Configuração

Configure a implantação definindo estas variáveis de ambiente:

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"

🔐 Segurança em Produção

A implantação no AKS inclui segurança de nível empresarial:

Execução de contêiner não-root
Sistema de arquivos raiz somente leitura
Gerenciamento de secrets via integração com Azure Key Vault
Políticas de rede para isolamento de tráfego
RBAC com permissões mínimas necessárias
Aplicação de padrões de segurança de pods

📊 Monitoramento e Escalonamento

Integração com Azure Monitor para logs e métricas
Application Insights para monitoramento de desempenho
Endpoint de métricas Prometheus para monitoramento personalizado
Auto-escalonamento com base em limites de CPU (70%) e memória (80%)
Health checks para reinicialização automática de pods

🔄 Integração CI/CD

Os scripts de implantação suportam:

Pipelines do Azure DevOps
Workflows do GitHub Actions
Testes automatizados antes da implantação
Implantações blue-green para zero tempo de inatividade
Capacidades de rollback para recuperação rápida

📚 Guia Detalhado: Consulte AKS_DEPLOYMENT.md para instruções completas de configuração.

🌐 Servidor Azure Model Context Protocol (Preview)

O Microsoft Azure agora oferece um serviço de preview para hospedar servidores MCP nativamente. Isso elimina a necessidade de gerenciamento de infraestrutura personalizada.

🚀 Implantação do Servidor MCP no Azure

Pré-requisitos

Assinatura do Azure com acesso ao preview do MCP
Azure CLI com extensões MCP

Implantar no Serviço MCP do 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 Autenticação

# 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"

Acessar Seu Servidor MCP

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

🔧 Recursos do Servidor MCP do Azure

Escalonamento automático com base no uso
Monitoramento e registro integrados
Segurança integrada com Azure AD
Gerenciamento de infraestrutura zero
CDN global para baixa latência
Certificados SSL/TLS automáticos

💰 Otimização de Custos

O Servidor MCP do Azure oferece:

Modelo de preço pay-per-request
Hibernação automática durante períodos ociosos
Compartilhamento de recursos entre vários clientes
Sem custos mínimos de infraestrutura

📚 Saiba Mais: Azure MCP Server Documentation

Nota: O Servidor MCP do Azure está atualmente em preview. Verifique Azure Preview Terms para disponibilidade e limitações do serviço.

🏗️ Arquitetura

Este servidor MCP é construído com:

TypeScript para desenvolvimento com segurança de tipos
MCP SDK para implementação do Model Context Protocol
Zod para validação de esquema e sanitização de entrada
Ambiente de execução Node.js

⚙️ Configuração

O servidor usa os seguintes arquivos de configuração:

tsconfig.json - Configuração do compilador TypeScript
package.json - Configuração do pacote Node.js
.vscode/mcp.json - Configuração do servidor MCP para VS Code

🔧 Desenvolvimento

Estrutura do Projeto

├── 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

Adicionando Novas Ferramentas

Para adicionar novas ferramentas ao servidor:

Defina o esquema de entrada usando Zod
Implemente a ferramenta usando server.tool()
Adicione tratamento de erros e validação
Atualize a documentação

Integração de API

Este servidor inclui:

✅ Pronto para Produção:

Integração completa com a API Microsoft Fabric Livy
Gerenciamento do ciclo de vida de sessões Spark
Execução de declarações com suporte a SQL e Spark
Gerenciamento de jobs em lote para operações de longa duração
Tratamento abrangente de erros e lógica de repetição
Polling em tempo real e recuperação de resultados 🧪 Recursos de Demonstração:
Operações CRUD (configuráveis para APIs reais)
Análises e métricas (framework extensível)
Análise de modelo de dados (implementação de modelo)

🧪 Testes

🚀 Testes de Ponta a Ponta

O servidor MCP inclui testes abrangentes de ponta a ponta que criam workspaces, itens e jobs reais para validar a funcionalidade completa usando autenticação da CLI do Azure.

Configuração Rápida para Testes 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

O que o Teste E2E Faz

O teste de ponta a ponta cria um fluxo de trabalho completo no seu locatário do Microsoft Fabric:

🔐 Valida a Autenticação da CLI do Azure - Usa sua sessão az login existente
🏗️ Cria um Workspace de Teste - Novo workspace com nomenclatura exclusiva
⚡ Anexa à Capacidade - Vincula o workspace à sua capacidade do Fabric (opcional)
📓 Cria Notebooks e Lakehouses - Itens de teste para validação
🏃 Executa Jobs Reais - Executa notebook com código Spark real
📊 Monitora a Execução - Rastreia o status e a conclusão do job
🧹 Limpa Recursos - Remove todos os recursos de teste criados

Configuração do Teste E2E

O script de configuração cria um arquivo de configuração .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

Recursos do Teste E2E

✅ Criação de Recursos Reais - Cria workspaces e itens reais do Fabric
✅ Integração com a CLI do Azure - Usa sua autenticação existente do Azure
✅ Atribuição de Capacidade - Testa a anexação de workspace à capacidade
✅ Execução de Jobs - Executa jobs Spark reais e monitora a conclusão
✅ Limpeza Automática - Remove todos os recursos de teste automaticamente
✅ Registro Abrangente - Registro detalhado de todas as operações
✅ Tratamento de Erros - Tratamento robusto de erros e recuperação

Pré-requisitos para Testes E2E

CLI do Azure instalada e conectada:
```
az login
```
Acesso ao Microsoft Fabric com permissões para:
- Criar workspaces
- Criar notebooks e lakehouses
- Executar jobs Spark
- (Opcional) Atribuir workspaces à capacidade
Capacidade do Fabric (opcional, mas recomendada):
- Defina FABRIC_CAPACITY_ID em .env.e2e para testes de capacidade
- Sem capacidade, o workspace usará a capacidade compartilhada

Executando Testes 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

Saída do Teste E2E

O teste fornece saída abrangente, incluindo:

🚀 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 Testes E2E

Cria Recursos Reais: O teste cria workspaces e itens reais no seu locatário do Fabric
Requer Permissões: Garanta que você tenha as permissões necessárias do Fabric
Usa Capacidade: Os jobs podem consumir unidades de capacidade se estiverem usando capacidade dedicada
Limpeza Automática: Todos os recursos são excluídos automaticamente após o teste
Depende da Rede: Requer conexão estável com a internet para chamadas de API

🧪 Testes Unitários e de Integração

Pré-requisitos

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

Scripts de Teste Disponíveis

livy_api_test.ipynb - Notebook interativo do Jupyter para testes passo a passo
comprehensive_livy_test.py - Teste completo com tratamento de erros
simple_livy_test.py - Teste simples seguindo padrões de exemplo
livy_batch_test.py - Recursos de teste de jobs em lote
spark_monitoring_test.py - Testes de monitoramento de aplicações Spark

Testes Rápidos

Testes Interativos:
```
jupyter notebook livy_api_test.ipynb
```

Testes por Linha de Comando:

python simple_livy_test.py
python spark_monitoring_test.py

Testes Abrangentes:

🤝 Contribuições

Aceitamos contribuições! Veja como começar:

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/amazing-feature)
Faça suas alterações e adicione testes, se aplicável
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Diretrizes de Desenvolvimento

Siga as melhores práticas de TypeScript
Adicione comentários JSDoc para novas funções
Atualize os testes para qualquer nova funcionalidade
Atualize a documentação conforme necessário
Consulte CONTRIBUTING.md para diretrizes detalhadas

🔒 Segurança

Nunca faça commit de tokens de autenticação no controle de versão
Use variáveis de ambiente para configurações sensíveis
Siga as melhores práticas de segurança do Microsoft Fabric
Reporte problemas de segurança em particular via avisos de segurança do GitHub
Consulte SECURITY.md para nossa política de segurança completa

📝 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Suporte

Para problemas e perguntas:

📖 Consulte a documentação do MCP
📚 Revise a documentação da API do Microsoft Fabric
🐛 Abra um problema neste repositório
💬 Participe das discussões da comunidade

Agradecimentos

Equipe do Microsoft Fabric Analytics pela plataforma de dados abrangente e recursos de análise
Equipes da Plataforma Microsoft Fabric pela plataforma de API robusta e infraestrutura
Bogdan Crivat e Chris Finlan pela conversa inspiradora de brainstorming que me deu a ideia de tornar este projeto de código aberto
Anthropic pela especificação do Model Context Protocol

Este projeto começou como meu projeto de hack de fim de semana explorando a integração de IA com o Microsoft Fabric. Durante uma conversa casual com Chris e Bogdan sobre tornar as ferramentas de IA mais acessíveis. O que começou como um experimento pessoal durante um fim de semana agora está disponível para todos construírem.

Microsoft Fabric Analytics

Documentação

Microsoft Fabric Analytics MCP Server

📋 Sumário

🌟 Principais Recursos

🔀 Ferramentas de Migração do Synapse para o Fabric

🆕 Migração Automatizada de Cargas de Trabalho Spark

🔍 Ferramentas de Descoberta de Migração

🔄 Ferramentas de Transformação e Migração

✨ Principais Recursos de Migração

🎯 Cenários de Migração

🎯 Testes de Ponta a Ponta com Workspaces Reais

🚀 Opções de Implantação

🤖 Integração com Claude Desktop

🔧 Correção de Autenticação do Claude Desktop

📱 Desenvolvimento Local

🐳 Implantação com Docker

☸️ Azure Kubernetes Service (AKS)

🌐 Azure MCP Server (Pré-visualização)

🛠️ Ferramentas e Capacidades

🔍 Operações CRUD para Itens do Fabric

🔍 Consultar Dataset do Fabric (Aprimorado)

🚀 Executar Notebook do Fabric

📊 Obter Métricas de Análise

🔧 Analisar Modelo de Dados

📋 Gerar Relatório de Análise

🚀 Integração com API Livy (Sessões e Jobs em Lote)

Gerenciamento de Sessões

Execução de Instruções

Gerenciamento de Trabalhos em Lote

📊 Monitoramento de Aplicações Spark

Monitoramento em Nível de Workspace

Monitoramento Específico de Itens

Gerenciamento de Aplicações

Painel de Monitoramento

📓 Gerenciamento de Notebooks

Criar Notebook a partir de Modelo

Obter Definição do Notebook

Atualizar Definição do Notebook

Executar Notebook

🚀 Início Rápido

🎯 Métodos de Instalação

Opção 1: Pacote Python (PyPI) ⭐ Recomendado

Opção 2: Pacote NPM

Opção 3: Script de Instalação Universal

Opção 4: Docker

Opção 5: A partir do Código-Fonte (Desenvolvimento)

⚙️ Configuração

🔧 Configuração do Claude Desktop

Para Instalação via PyPI:

Para Instalação via NPM:

Para Instalação a partir do Código-Fonte:

🚀 Comece a Usar

🧪 Desenvolvimento e Testes

Executando o Servidor

Testando a Integração com a API Livy

Integração com Claude Desktop

Configuração de Testes da API Livy

Scripts de Teste Disponíveis:

Uso

Executando o Servidor

Modo de Desenvolvimento

Testando com Claude Desktop

💬 Exemplos de Consultas

Operações CRUD:

Gerenciamento de Notebooks:

Operações de Dados:

Análises:

Operações da API Livy:

Monitoramento de Aplicativos Spark:

Gerenciamento de Capacidade:

🧩 Ferramentas de Gerenciamento de Capacidade

Ferramentas Disponíveis

Notas

Referência Mínima de Parâmetros

❗ Solução de Problemas

Erros de Análise JSON (ex.: Unexpected token 'P')

Correções Implementadas Neste Servidor

O Que Você Pode Fazer

Ferramentas de Capacidade Não Aparecendo?

Erros de Análise JSON (ex.: `Unexpected token 'P'`)