# PowerBI MCP Server

Полнофункциональный Model Context Protocol (MCP) сервер для интеграции с Microsoft Power BI через Azure AD API.

## 🎯 Возможности

### 📖 READ Operations (7 tools):
- **`get_workspaces`** - Получение списка всех доступных workspace
- **`get_datasets`** - Получение списка datasets (с возможностью фильтрации по workspace)
- **`get_reports`** - Получение списка отчетов (с возможностью фильтрации по workspace)
- **`get_dataset_tables`** - Получение структуры таблиц dataset
- **`query_dataset`** - Выполнение DAX запросов к dataset
- **`refresh_dataset`** - Запуск обновления dataset
- **`get_refresh_history`** - Получение истории обновлений dataset

### 🏗️ WORKSPACE Management (3 tools):
- **`create_workspace`** - Создание новых workspace
- **`delete_workspace`** - Удаление workspace
- **`add_workspace_user`** - Добавление пользователей с правами доступа

### 📊 DATASET Management (3 tools):
- **`create_dataset`** - Создание datasets с таблицами и схемой
- **`delete_dataset`** - Удаление datasets
- **`update_dataset`** - Обновление конфигурации datasets

### 🗃️ TABLE Management (3 tools):
- **`create_table`** - Создание таблиц в datasets
- **`delete_table`** - Удаление таблиц
- **`update_table`** - Модификация структуры таблиц

### 📋 COLUMN Management (3 tools):
- **`add_column`** - Добавление колонок с типами данных
- **`delete_column`** - Удаление колонок
- **`update_column`** - Изменение свойств колонок

### 🧮 MEASURE Management (3 tools):
- **`create_measure`** - Создание вычисляемых мер (DAX)
- **`delete_measure`** - Удаление мер
- **`update_measure`** - Обновление DAX выражений

### 📈 REPORT Management (3 tools):
- **`create_report`** - Создание новых отчетов
- **`delete_report`** - Удаление отчетов
- **`clone_report`** - Клонирование отчетов

### 📥 DATA Import (2 tools):
- **`add_table_rows`** - Добавление данных в таблицы
- **`clear_table_rows`** - Очистка данных таблиц

### 🌐 GATEWAY Management (2 tools):
- **`get_gateways`** - Получение списка gateway
- **`get_gateway_datasources`** - Получение источников данных gateway

### **ИТОГО: 28 полнофункциональных MCP tools для полного управления PowerBI!**

### Поддерживаемые функции:
- ✅ **Полное управление PowerBI**: от создания workspace до добавления визуализаций
- ✅ **Аутентификация через Azure AD** (Service Principal)
- ✅ **Автоматическое обновление токенов**
- ✅ **Comprehensive error handling** и логирование
- ✅ **CRUD операции** для всех основных сущностей
- ✅ **DAX query execution** и вычисляемые меры
- ✅ **Импорт данных** и управление таблицами
- ✅ **Gateway integration** для внешних источников данных
- ✅ **Workspace и permissions management**

## 📋 Требования

- Node.js 18+ 
- TypeScript
- Зарегистрированное приложение в Azure AD
- Permissions для Power BI API

## 🚀 Установка

### 1. Клонирование и установка зависимостей

```bash
git clone <repository-url>
cd powerbi_mcp_server
npm install
```

### 2. Настройка Azure AD Application

1. Перейдите в Azure Portal → App registrations
2. Создайте новое приложение или используйте существующее
3. В разделе "API permissions" добавьте:
   - **Power BI Service** permissions:
     - `Dataset.Read.All`
     - `Dataset.ReadWrite.All`
     - `Report.Read.All`
     - `Workspace.Read.All`
   - **Microsoft Graph** (optional):
     - `User.Read`

4. В разделе "Certificates & secrets" создайте новый client secret
5. Скопируйте Application (client) ID, Directory (tenant) ID, и client secret

### 3. Настройка переменных окружения

Скопируйте `.env.example` в `.env` и заполните:

```bash
cp .env.example .env
```

Отредактируйте `.env`:

```env
# Azure AD Configuration
AZURE_CLIENT_ID=your_application_client_id
AZURE_CLIENT_SECRET=your_client_secret
AZURE_TENANT_ID=your_tenant_id

# PowerBI API Configuration  
POWERBI_API_URL=https://api.powerbi.com/v1.0/myorg

# Logging
LOG_LEVEL=info
```

### 4. Сборка проекта

```bash
npm run build
```

## 🎮 Использование

### Запуск сервера

```bash
npm start
# или для development:
npm run dev
```

### Интеграция с Claude Desktop

Добавьте в файл конфигурации Claude Desktop:

```json
{
  "mcpServers": {
    "powerbi": {
      "command": "node",
      "args": ["/path/to/powerbi_mcp_server/build/index.js"],
      "env": {
        "AZURE_CLIENT_ID": "your_client_id",
        "AZURE_CLIENT_SECRET": "your_client_secret", 
        "AZURE_TENANT_ID": "your_tenant_id"
      }
    }
  }
}
```

### Использование в MCP-совместимых клиентах

После подключения доступны следующие tools:

#### Получение workspaces
```
get_workspaces()
```

#### Получение datasets
```
get_datasets(workspace_id?: string)
```

#### Выполнение DAX запроса
```
query_dataset(
  dataset_id: "your-dataset-id",
  dax_query: "EVALUATE VALUES('Table'[Column])",
  workspace_id?: "workspace-id"
)
```

#### Создание нового dataset с таблицей
```
create_dataset(
  name: "Sales Dataset",
  tables: [{
    name: "Sales",
    columns: [
      { name: "Date", dataType: "Datetime" },
      { name: "Amount", dataType: "Double" },
      { name: "Product", dataType: "String" }
    ],
    measures: [{
      name: "Total Sales",
      expression: "SUM(Sales[Amount])",
      formatString: "Currency"
    }]
  }],
  workspace_id?: "workspace-id"
)
```

#### Добавление данных в таблицу
```
add_table_rows(
  dataset_id: "dataset-id",
  table_name: "Sales",
  rows: [
    ["2024-01-01", 1000, "Product A"],
    ["2024-01-02", 1500, "Product B"]
  ],
  workspace_id?: "workspace-id"
)
```

## 📊 Примеры использования

### Пример 1: Получение всех workspace

```typescript
// Tool call: get_workspaces
// Response:
{
  "success": true,
  "data": [
    {
      "id": "workspace-guid",
      "name": "My Workspace", 
      "isReadOnly": false,
      "isOnDedicatedCapacity": true
    }
  ],
  "count": 1
}
```

### Пример 2: DAX запрос

```typescript
// Tool call: query_dataset
{
  "dataset_id": "dataset-guid",
  "dax_query": "EVALUATE TOPN(10, 'Sales', 'Sales'[Amount], DESC)",
  "workspace_id": "workspace-guid"
}

// Response:
{
  "success": true,
  "data": {
    "tables": [
      {
        "rows": [
          ["Product A", 1000],
          ["Product B", 800]
        ]
      }
    ]
  }
}
```

## 🔧 Разработка

### Структура проекта

```
src/
├── auth.ts          # Azure AD authentication
├── powerbi-client.ts # PowerBI REST API client  
├── server.ts        # MCP server implementation
├── types.ts         # TypeScript interfaces
├── logger.ts        # Logging configuration
└── index.ts         # Entry point
```

### Команды разработки

```bash
npm run build    # Сборка TypeScript
npm run dev      # Development режим
npm start        # Production запуск
```

## 🛡️ Безопасность

- ✅ Secure token storage и автоматическое обновление
- ✅ Никогда не логируются credentials или токены
- ✅ Валидация всех входящих параметров
- ✅ HTTPS для всех API вызовов
- ✅ Error handling для всех сценариев

## 📝 Логирование

Сервер использует Winston для логирования. Уровень логирования настраивается через переменную `LOG_LEVEL`:

- `error` - только ошибки
- `warn` - предупреждения и ошибки  
- `info` - информационные сообщения (по умолчанию)
- `debug` - подробная отладочная информация

## ❗ Troubleshooting

### Проблема: "Authentication failed"
**Решение:** Проверьте правильность Azure AD credentials и permissions

### Проблема: "Dataset not found" 
**Решение:** Убедитесь что service principal имеет доступ к workspace/dataset

### Проблема: "DAX query failed"
**Решение:** Проверьте синтаксис DAX запроса и права доступа к dataset

### Проблема: "MCP connection failed"
**Решение:** Проверьте что сервер правильно запущен и доступен через stdio

## 📖 Дополнительные ресурсы

- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [Power BI REST API Documentation](https://docs.microsoft.com/en-us/rest/api/power-bi/)
- [Azure AD Authentication Guide](https://docs.microsoft.com/en-us/azure/active-directory/develop/)
- [DAX Reference](https://docs.microsoft.com/en-us/dax/)

## 📄 Лицензия

ISC License

## 🤝 Вклад в проект

Приветствуются pull requests и issue reports. Перед внесением изменений:

1. Убедитесь что все тесты проходят
2. Следуйте code style проекта
3. Обновите документацию при необходимости

---

*Создано для Model Context Protocol ecosystem* 🚀