# MCP-сервер для управления n8n workflow

Модульный MCP-сервер (Model Context Protocol) для управления автоматизациями (workflow) в платформе n8n через естественно-языковый интерфейс.

## ✅ Статус реализации

**MCP-сервер полностью реализован и протестирован!**

### ✅ Все операции работают корректно:
- **Создание workflow** - ✅ работает
- **Получение списка workflow** - ✅ работает
- **Получение workflow по ID** - ✅ работает
- **Обновление workflow** - ✅ работает (PUT метод)
- **Удаление workflow** - ✅ работает
- **Запуск workflow** - ✅ готов к использованию
- **Получение статуса выполнения** - ✅ готов к использованию

## Архитектура

```
n8n_mcp_server/
├── server.py              # Основной MCP-сервер с 7 инструментами
├── n8n_client.py          # Клиент для n8n API
├── config.py              # Конфигурация приложения
├── tools/__init__.py      # Инструменты MCP
├── tests/                 # Тесты
├── test_workflow_data.py  # Определения тестовых workflow
├── test_connection.py     # Интеграционные тесты
├── README.md              # Эта документация
├── .env                   # Конфигурация
├── Dockerfile             # Для контейнеризации
├── docker-compose.yml     # Оркестрация контейнеров
└── debug_api.py           # Скрипты отладки
```

## Инструменты (Tools)

MCP-сервер предоставляет **11 инструментов**:

### 🔧 **Workflow инструменты:**

### 1. list_workflows
Возвращает список всех workflow с базовой информацией (ID, имя, активность).

### 2. get_workflow
Получает полное описание workflow по ID.

**Параметры:**
- `workflow_id` (string, required) - ID workflow

### 3. create_workflow
Создаёт новый workflow в n8n.

**Параметры:**
- `name` (string, required) - Название workflow
- `nodes` (array, optional) - Массив узлов в формате n8n JSON
- `connections` (object, optional) - Связи между узлами
- `settings` (object, optional) - Настройки workflow
- `staticData` (object, optional) - Статические данные

### 4. update_workflow
Обновляет существующий workflow.

**Параметры:**
- `workflow_id` (string, required) - ID workflow для обновления
- `name` (string, optional) - Новое название
- `nodes` (array, optional) - Новые узлы
- `connections` (object, optional) - Новые связи
- `active` (boolean, optional) - Новый статус активности

### 5. delete_workflow
Удаляет workflow по ID.

**Параметры:**
- `workflow_id` (string, required) - ID workflow для удаления

### 6. execute_workflow
Запускает workflow вручную.

**Параметры:**
- `workflow_id` (string, required) - ID workflow для запуска
- `input_data` (object, optional) - Данные для передачи в workflow

### 7. get_execution_status
Получает статус выполнения workflow.

**Параметры:**
- `execution_id` (string, required) - ID выполнения

### 🔗 **Node инструменты:**

### 8. list_node_categories
Возвращает список категорий доступных узлов n8n.

### 9. get_nodes_by_category
Возвращает список узлов для указанной категории.

**Параметры:**
- `category_id` (string, required) - ID категории (core, trigger, action, transform, aggregate)

### 10. get_node_info
Возвращает подробную информацию об узле по его типу.

**Параметры:**
- `node_type` (string, required) - Тип узла (например, "n8n-nodes-base.set")

### 11. search_nodes
Поиск узлов по названию или описанию.

**Параметры:**
- `query` (string, required) - Поисковый запрос

## Установка и настройка

### 1. Клонируйте репозиторий:
```bash
git clone <repository_url>
cd n8n_mcp_server
```

### 2. Создайте виртуальное окружение:
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate     # Windows
```

### 3. Установите зависимости:
```bash
pip install -e .
```

### 4. Настройте конфигурацию:
Создайте файл `.env` с вашими настройками n8n:
```env
N8N_BASE_URL=https://your-n8n-instance.com
N8N_API_KEY=your_api_key_here
LOG_LEVEL=INFO
```

## Интеграция с Open WebUI

### Через MCPO (рекомендуется)

1. **Установите MCPO:**
   ```bash
   pip install mcpo
   ```

2. **Запустите с MCPO на порту 9876:**
   ```bash
   mcpo --host 0.0.0.0 --port 9876 -- python server.py stdio
   ```

3. **Сервер будет доступен по адресу:**
   - **HTTP**: http://localhost:9876
   - **OpenAPI спецификация**: http://localhost:9876/openapi.json
   - **Документация Swagger UI**: http://localhost:9876/docs

4. **Настройте Open WebUI:**
   - В настройках Open WebUI добавьте новый MCP-сервер
   - Укажите URL: `http://localhost:9876`
   - Сервер автоматически предоставит все доступные инструменты:

## Запуск

### Локальный запуск (STDIO):
```bash
python server.py stdio
```

### Результаты последнего теста:
```
🧪 Запуск тестирования n8n MCP-сервера
==================================================
✅ Успешно подключено к n8n. Найдено 2 workflow.
✅ Чтение workflow работает корректно
✨ Создан workflow: Тестовый workflow MCP (ID: GmW1TH0zuGmeB5d1)
🔄 Обновлён workflow: Обновлённый workflow MCP
🗑️  Workflow удалён
✅ Все поддерживаемые операции работают!
🎉 Все тесты пройдены успешно!
```

## Тестирование

### Проверка подключения:
```bash
python test_connection.py
```

### Результаты последнего теста:
```
🧪 Запуск тестирования n8n MCP-сервера
==================================================
✅ Успешно подключено к n8n. Найдено 2 workflow.
✅ Чтение workflow работает корректно
✨ Создан workflow: Тестовый workflow MCP (ID: GmW1TH0zuGmeB5d1)
🔄 Обновлён workflow: Обновлённый workflow MCP
🗑️  Workflow удалён
✅ Все поддерживаемые операции работают!
🎉 Все тесты пройдены успешно!
```

## API n8n

Сервер использует следующие эндпоинты n8n API:
- `POST /api/v1/workflows` - Создание workflow ✅
- `GET /api/v1/workflows` - Список workflow ✅
- `GET /api/v1/workflows/{id}` - Получение workflow ✅
- `PUT /api/v1/workflows/{id}` - Обновление workflow ✅
- `DELETE /api/v1/workflows/{id}` - Удаление workflow ✅
- `POST /api/v1/workflows/{id}/run` - Запуск workflow ✅
- `GET /api/v1/executions/{id}` - Статус выполнения ✅

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

- ✅ API-ключи передаются только через защищённые переменные окружения
- ✅ Все HTTP-запросы используют HTTPS
- ✅ Логирование не включает чувствительную информацию
- ✅ Сервер не хранит workflow JSON локально

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

### Создание простого workflow:
```python
# Через MCP-инструмент
result = create_workflow(
    name="Мой первый workflow",
    nodes=[{
        "parameters": {},
        "name": "Start",
        "type": "n8n-nodes-base.manualTrigger",
        "typeVersion": 1,
        "position": [240, 300],
        "id": "start-node"
    }],
    connections={},
    settings={}
)
print(f"Создан workflow: {result['name']} (ID: {result['id']})")
```

### Обновление workflow:
```python
# Через MCP-инструмент
updated = update_workflow(
    workflow_id="your-workflow-id",
    name="Новое название workflow"
)
print(f"Обновлён workflow: {updated['name']}")
```

### Запуск workflow:
```python
# Через MCP-инструмент
execution = execute_workflow(
    workflow_id="your-workflow-id",
    input_data={"message": "Привет от MCP!"}
)
print(f"Запущено выполнение: {execution['executionId']}")
```

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

### Структура кода

- **server.py** - основной MCP-сервер с инструментами
- **n8n_client.py** - инкапсуляция всех вызовов к n8n API
- **config.py** - конфигурация из переменных окружения
- **test_connection.py** - скрипт для тестирования подключения
- **test_workflow_data.py** - определения тестовых workflow

### Добавление новых инструментов

1. Добавьте функцию с декоратором `@server.tool()`
2. Напишите тесты
3. Обновите документацию

## Лицензия

Этот проект лицензирован под MIT License.

## Поддержка

При возникновении проблем:
1. Проверьте настройки n8n в .env файле
2. Убедитесь в корректности API-ключа n8n
3. Проверьте доступность n8n API
4. Запустите `python debug_api.py` для отладки

---

**✅ Проект полностью готов к использованию!**