# 1C MCP Toolkit

**Система интеграции AI-агентов с базами данных 1С:Предприятие через MCP и REST API**

## 📋 Описание

1C MCP Toolkit — это решение для подключения AI-агентов (Kiro, Claude и др.) к базам данных 1С:Предприятие. Поддерживает два варианта работы: **встроенный сервер** (HTTP-сервер запускается прямо внутри обработки 1С, без Python) и **прокси** (Python-сервер с long polling).

**Ключевые преимущества:**
- ✅ Не требуется изменение конфигурации 1C
- ✅ Не нужна публикация 1C сервера
- ✅ Не использует COM-соединение
- ✅ Совместимость с 1С:Предприятие 8.2.13+ / 8.3.25
- ✅ **Встроенный сервер**: Python не нужен — HTTP-сервер запускается прямо в 1С
- ✅ Поддержка Docker (режим Прокси)

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

### Вариант 1: Встроенный сервер

HTTP-сервер запускается прямо внутри обработки 1С. Python не нужен.

```
┌─────────────────┐   MCP / REST API   ┌──────────────────┐
│    AI Агент     │ ◄───────────────►  │ 1С (.epf)        │
│  (Kiro, Claude) │   /mcp /api/*      │ Встр. HTTP-сервер│
└─────────────────┘                    └──────────────────┘
                                          │
                                          ▼
                                  ┌───────────────┐
                                  │ База данных 1С│
                                  └───────────────┘
```

### Вариант 2: Прокси-режим

```
┌─────────────────┐   MCP / REST API            ┌─────────────────┐
│    AI Агент     │ ◄─────────────────────────► │                 │
│  (Kiro, Claude) │         /mcp    /api/*      │   Python Proxy  │
└─────────────────┘                             │     Server      │
                                                │                 │
┌─────────────────┐     HTTP Long Polling       │   (FastAPI +    │
│  1С Обработка   │ ◄─────────────────────────► │    MCP SDK)     │
│  (внешняя .epf) │    /1c/poll, /1c/result     │                 │
└─────────────────┘                             └─────────────────┘
        │                                               │
        ▼                                               │
┌─────────────────┐                             ┌───────┴───────┐
│  База данных 1С │                             │    Docker     │
│ (8.2.13/8.3.25) │                             │   Container   │
└─────────────────┘                             └───────────────┘
```

## 🚀 Быстрый старт

### Вариант 0: Встроенный сервер (без Python, рекомендуется)

1. Откройте `build/MCP_Toolkit.epf` в 1С:Предприятие
2. В форме выберите режим **«Встроенный сервер»**
3. Нажмите «Запустить сервер»
4. Настройте AI-агент на `http://<ip-компьютера-1С>:6003/mcp`

> **macOS:** встроенный сервер работает и на macOS нативно (без Python). Нужно
> собрать нативные компоненты как universal (x86_64 + arm64) — см.
> [`native_components/BUILDING_MACOS.md`](native_components/BUILDING_MACOS.md).
> Сборку автоматизирует CI (`.github/workflows/build-macos.yml`), Mac для этого
> иметь не обязательно.

### Вариант 1: Docker Hub (режим Прокси)

Запуск прокси-сервера из готового образа на Docker Hub:

```bash
docker run -d -p 6003:6003 -e ALLOW_DANGEROUS_WITH_APPROVAL=true --restart unless-stopped --name 1c-mcp-toolkit-proxy roctup/1c-mcp-toolkit-proxy
```

### Вариант 2: Docker Compose

```bash
# Клонировать репозиторий
git clone <repository-url>
cd 1c-mcp-toolkit

# Запустить через Docker Compose
docker-compose up -d
```

### Вариант 3: Прямой запуск Python

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

# Установить зависимости
pip install -r requirements.txt

# Запустить сервер
python -m onec_mcp_toolkit_proxy
```

Сервер запустится по адресу `http://localhost:6003`

## 📦 Установка обработки 1C

1. Скачайте готовую обработку из папки build **[MCP_Toolkit.epf](./build/MCP_Toolkit.epf)**
2. Откройте обработку в 1C (Файл → Открыть)
3. В настройках обработки укажите:
   - URL прокси-сервера: `http://localhost:6003`
   - (опционально) ID канала для изоляции команд
4. Нажмите кнопку "Подключиться"

## ⚙️ Настройка AI-агента

### Kiro IDE

Добавьте в файл `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "onec-mcp-toolkit-proxy": {
      "url": "http://localhost:6003/mcp",
      "transport": "http",
      "type": "streamable-http",
      "disabled": false,
      "autoApprove": ["execute_query", "get_metadata"]
    }
  }
}
```

### Claude Desktop

> **Важно:** `claude_desktop_config.json` поддерживает только stdio-серверы
> (поля `command`/`args`). Формат с `url`/`transport` (как в секции Kiro IDE выше)
> Claude Desktop **не понимает** — такая запись игнорируется. Для подключения к
> HTTP-серверу используйте один из вариантов ниже.

#### Вариант 1. Мост mcp-remote (требуется Node.js)

Откройте конфигурационный файл:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Добавьте конфигурацию:

```json
{
  "mcpServers": {
    "onec-mcp-toolkit-proxy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:6003/mcp",
        "--allow-http",
        "--transport", "http-only"
      ]
    }
  }
}
```

Перезапустите приложение.

> Используйте `127.0.0.1`, а не `localhost` — так надёжнее с точки зрения
> IPv4/IPv6-биндинга. Флаг `--allow-http` разрешает подключение по http без TLS.

#### Вариант 2. Custom Connector (без Node.js)

На платных планах HTTP-сервер можно добавить через UI:
**Settings → Connectors → Add custom connector**, указав URL `http://localhost:6003/mcp`.

### 🔐 Аутентификация по токену (встроенный сервер)

По умолчанию встроенный сервер не требует аутентификации. Чтобы её включить, задайте на форме в поле **«Токен доступа»** значение (или нажмите «Сгенерировать»), затем добавьте в конфигурацию клиента заголовок `Authorization: Bearer <token>`:

```json
{
  "mcpServers": {
    "onec-mcp-toolkit": {
      "url": "http://127.0.0.1:6003/mcp",
      "transport": "http",
      "headers": { "Authorization": "Bearer ВАШ_ТОКЕН" }
    }
  }
}
```

Для Claude Desktop через `mcp-remote` — аргумент `--header "Authorization: Bearer ВАШ_ТОКЕН"`. Пустой токен = аутентификация выключена. Подробнее (границы безопасности, ротация, legacy SSE) — в [README_FULL.md](README_FULL.md#аутентификация-по-токену-bearer).

## 🛠️ Доступные MCP-инструменты

| Инструмент | Описание |
|-----------|----------|
| **execute_query** | Выполнение запросов на языке запросов 1C |
| **execute_code** | Выполнение произвольного кода 1C |
| **get_metadata** | Получение информации о структуре метаданных базы |
| **get_event_log** | Получение записей из журнала регистрации |
| **get_object_by_link** | Получение объекта по навигационной ссылке |
| **get_link_of_object** | Генерация навигационной ссылки на объект |
| **find_references_to_object** | Поиск всех ссылок на объект |
| **get_access_rights** | Получение прав доступа к объектам метаданных |
| **get_bsl_syntax_help** | Справочник по встроенному языку BSL: поиск функций, методов, типов и языковых конструкций |
| **get_screenshot** | Снимок активного окна 1С и возврат в виде base64 PNG (только Windows) |
| **submit_for_deanonymization** | Отправка финального ответа для деанонимизации (только при включённой анонимизации) |
| **restart_1c_session** | Перезапуск текущей сессии 1С (требуется после обновления конфигурации; новая сессия стартует автоматически) |
| **close_1c_session** | Закрытие текущей сессии 1С с возвратом команды запуска новой (для операций, требующих эксклюзивного доступа к базе) |

## 🌐 REST API (альтернатива MCP)

Для AI-агентов, не поддерживающих протокол MCP, или при предпочтении стандартных HTTP-запросов, прокси предоставляет REST API с той же функциональностью.

**Базовый URL:** `http://localhost:6003/api/`

### Доступные эндпоинты

| Эндпоинт | Метод | Описание |
|----------|-------|----------|
| `/api/execute_query` | POST | Выполнение запросов 1C |
| `/api/execute_code` | POST | Выполнение кода 1C |
| `/api/get_metadata` | GET/POST | Получение метаданных |
| `/api/get_event_log` | POST | Журнал регистрации |
| `/api/get_object_by_link` | POST | Получить объект по ссылке |
| `/api/get_link_of_object` | POST | Генерация ссылки на объект |
| `/api/find_references_to_object` | POST | Поиск ссылок на объект |
| `/api/get_access_rights` | POST | Получение прав доступа |
| `/api/get_bsl_syntax_help` | POST | Справочник по языку BSL |
| `/api/submit_for_deanonymization` | POST | Отправить текст для деанонимизации (только при включённой анонимизации) |
| `/api/restart_1c_session` | POST | Перезапустить сессию 1С |
| `/api/close_1c_session` | POST | Закрыть сессию и получить команду запуска новой |

### Формат ответов

Большинство ответов следуют единой структуре:

**Успех:** `{"success": true, "data": <результат>}`
**Ошибка:** `{"success": false, "error": "Описание ошибки"}`

**Исключение:** `submit_for_deanonymization` возвращает `{"received": true}` при успехе (без поля `data`).

Подробные примеры использования REST API доступны в полной документации.

## 🕵️ Анонимизация данных

Инструмент поддерживает автоматическую анонимизацию персональных и конфиденциальных данных. Реальные значения заменяются стабильными токенами (`[ORG-00001]`, `[PER-00001]`, `[INN-00001]` и т.д.). Агент может передавать токены обратно в запросы — сервер автоматически восстанавливает реальные значения.

**Режим «Встроенный сервер»:**
- Настройка через форму обработки 1С: дерево полей метаданных, словарь из справочников 1С, регулярные выражения

**Режим «Прокси»:**
- Управляется переменными окружения (`ANONYMIZATION_ENABLED=true`)
- Дополнительно: SpaCy NER, изоляция токенов по каналам, умная анонимизация псевдонимов колонок

Подробная документация: **[ANONYMIZATION.md](./ANONYMIZATION.md)**

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

- Опасные операции блокируются настраиваемым черным списком
- Используйте `ALLOW_DANGEROUS_WITH_APPROVAL=true` для режима подтверждения
- Рекомендуется настроить `autoApprove` только для безопасных инструментов

## 📝 Изоляция каналов

При подключении нескольких клиентов 1C к одному прокси-серверу можно изолировать потоки команд с помощью ID каналов.

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

```json
{
  "mcpServers": {
    "onec-dev": {
      "url": "http://localhost:6003/mcp?channel=dev-environment",
      "transport": "http",
      "type": "streamable-http"
    },
    "onec-prod": {
      "url": "http://localhost:6003/mcp?channel=prod-environment",
      "transport": "http",
      "type": "streamable-http"
    }
  }
}
```

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

Все REST-эндпоинты поддерживают изоляцию каналов через параметр запроса `?channel=<id>`:

```bash
# Канал для разработки
curl -X POST "http://localhost:6003/api/execute_query?channel=dev-environment" \
  -H "Content-Type: application/json" \
  -d '{"query": "ВЫБРАТЬ 1"}'

# Канал для продакшена
curl -X POST "http://localhost:6003/api/execute_query?channel=prod-environment" \
  -H "Content-Type: application/json" \
  -d '{"query": "ВЫБРАТЬ 1"}'
```

**Важно:** Укажите тот же ID канала в настройках обработки 1C для соответствующего окружения.

## 🎓 Skills для AI-агентов

При использовании **REST API** рекомендуется использовать готовые skills, которые содержат детальные инструкции по работе с 1C MCP Toolkit.

### Доступные skills

📁 **Папка:** `skills/`

| Skill | Описание | Рекомендуется для |
|-------|----------|-------------------|
| **calling-1c-rest-api-via-curl** | Полное руководство по использованию REST API через curl: все эндпоинты, форматы запросов/ответов, примеры workflow, обработка ошибок | REST API клиенты, автоматизация, скрипты |
| **composing-1c-queries** | Правила составления корректных запросов на языке запросов 1C: синтаксис, оптимизация, виртуальные таблицы, временные таблицы, JOIN'ы | Работа с данными 1C через execute_query |

### Как использовать

Skills содержат подробные инструкции и reference-документацию для AI-агентов. Каждый skill включает:
- Описание возможностей
- Примеры использования
- Лучшие практики
- Типичные паттерны работы

Для AI-агентов, использующих REST API, skill `calling-1c-rest-api-via-curl` является основным руководством и содержит все необходимые детали для эффективной работы с API.

## 📚 Документация

Подробная документация доступна в **[README_FULL](./README_FULL.md)**