# tab-ai-mcp

MCP-сервер для 1С:Предприятие — универсальный агент для взаимодействия с базой данных 1С через Claude и другие MCP-совместимые клиенты.

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

- **CRUD объектов 1С** — чтение, создание, изменение, удаление через стандартный OData REST API
- **Семантический поиск** — найти "молоко пастеризованное" без точного совпадения строк (через TAB AI)
- **Обогащение объектов** — возвращает максимально полный объект по стандарту EnterpriseData (XDTO)
- **Прогнозирование** — предсказание динамики продаж и других временных рядов
- **Проверка документов** — наличие подписи и печати на сканах

## Установка

```bash
# Способ 1: uvx (рекомендуется — не требует установки)
uvx tab-ai-mcp

# Способ 2: pip
pip install tab-ai-mcp
tab-ai-mcp
```

## Настройка Claude Desktop

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

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

```json
{
  "mcpServers": {
    "1c-tab-ai": {
      "command": "uvx",
      "args": ["tab-ai-mcp"],
      "env": {
        "ONEC_BASE_URL": "http://ваш-сервер/имя-базы",
        "ONEC_USERNAME": "ваш-логин",
        "ONEC_PASSWORD": "ваш-пароль",
        "TAB_AI_API_KEY": "a7f3b8c9d2e1f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
      }
    }
  }
}
```

Если используете `pip install`:
```json
{
  "mcpServers": {
    "1c-tab-ai": {
      "command": "tab-ai-mcp",
      "env": {
        "ONEC_BASE_URL": "http://ваш-сервер/имя-базы",
        "ONEC_USERNAME": "ваш-логин",
        "ONEC_PASSWORD": "ваш-пароль"
      }
    }
  }
}
```

## Переменные окружения

| Переменная | Описание | По умолчанию |
|---|---|---|
| `ONEC_BASE_URL` | URL базы 1С, например `http://server/myapp` | — (обязательно) |
| `ONEC_USERNAME` | Логин пользователя 1С | — |
| `ONEC_PASSWORD` | Пароль пользователя 1С | — |
| `TAB_AI_API_KEY` | Ключ TAB AI сервиса | встроенный ключ |
| `TAB_AI_BASE_URL` | URL TAB AI сервиса | Railway (облако) |

> **Требование к 1С:** Должен быть опубликован OData сервис.
> В конфигураторе: Администрирование → Публикация на веб-сервере → поставить галку "Публиковать стандартный интерфейс OData"

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

### Работа с объектами 1С

| Инструмент | Описание |
|---|---|
| `list_1c_types()` | Список всех типов объектов базы (каталоги, документы, регистры) |
| `query_1c(entity_type, filter, select, top, skip)` | OData запрос списка объектов с фильтрами |
| `get_1c_object(entity_type, ref_id)` | Получить объект по GUID с XDTO обогащением |
| `create_1c_object(entity_type, data)` | Создать новый объект |
| `update_1c_object(entity_type, ref_id, data)` | Обновить существующий объект |
| `delete_1c_object(entity_type, ref_id)` | Удалить объект |
| `get_xdto_schema(type_name)` | Схема полей типа по стандарту EnterpriseData |
| `list_xdto_covered_types()` | Какие типы поддерживают XDTO обогащение |

### Семантический поиск (TAB AI)

| Инструмент | Описание |
|---|---|
| `sync_1c_to_ai(entity_type, organization, object_type_label)` | Синхронизировать данные 1С → TAB AI кэш |
| `semantic_search_1c(organization, object_type_label, search_text)` | Поиск по смыслу |
| `semantic_search_multi_property(organization, object_type_label, search_properties)` | Поиск по нескольким свойствам |
| `set_ai_provider_token(provider, token)` | Настроить API ключ LLM провайдера |

### Аналитика и документы

| Инструмент | Описание |
|---|---|
| `forecast_1c_data(table_data, months_count)` | Прогноз временных рядов |
| `verify_document_signature(document_base64)` | Проверка подписи и печати на сканах |

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

### Пример 1: "Создай счёт на оплату на молоко"

Claude выполнит автоматически:
1. `sync_1c_to_ai("Catalog_Номенклатура", "org1", "Номенклатура")` — если ещё не синхронизировано
2. `semantic_search_1c("org1", "Номенклатура", "молоко")` → находит GUID товара
3. `get_xdto_schema("Document_СчетПокупателю")` → узнаёт обязательные поля
4. `create_1c_object("Document_СчетПокупателю", {...})` → создаёт документ

### Пример 2: "Покажи данные контрагента Ромашка"

```
query_1c("Catalog_Контрагенты", filter="contains(Наименование,'Ромашка')")
→ получаем Ref_Key
get_1c_object("Catalog_Контрагенты", ref_id)
→ полные данные контрагента со всеми полями EnterpriseData
```

### Пример 3: "Спрогнозируй продажи на 3 месяца"

```
forecast_1c_data(
  table_data=[{"Дата":"2024-01","Продажи":100}, ...],
  months_count=3
)
```

### OData фильтры — примеры

```
# Точное совпадение
"Наименование eq 'Молоко'"

# Поиск по вхождению
"contains(Наименование,'Мол')"

# По дате
"ДатаДокумента ge datetime'2024-01-01T00:00:00'"

# По GUID
"Контрагент_Key eq guid'12345678-1234-1234-1234-123456789012'"

# Комбинация
"ДатаДокумента ge datetime'2024-01-01T00:00:00' and contains(Комментарий,'срочно')"
```

## Как работает XDTO обогащение

При вызове `get_1c_object` сервер:
1. Получает объект из 1С через OData (только заполненные поля)
2. Находит соответствующий тип в схеме `EnterpriseData` (558 типов)
3. Добавляет все поля из стандарта с `null` для незаполненных
4. Возвращает объект с ключом `_xdto_schema` — полным описанием полей

Пример: OData вернул 5 полей для Номенклатуры → после обогащения объект содержит все 30+ стандартных полей, включая незаполненные.

## Требования к 1С

- 1С:Предприятие 8.3.18+
- Опубликованный OData сервис (standard.odata)
- Пользователь с правами на чтение/запись нужных объектов

### Публикация OData в 1С

1. Открыть Конфигуратор
2. Администрирование → Публикация на веб-сервере
3. В разделе "OData" поставить галку "Опубликовать стандартный интерфейс OData"
4. Выбрать нужные типы объектов или "Все"
5. Опубликовать

## Связь с ТАБ:Библиотека искусственного интеллекта

Данный MCP-сервер использует инфраструктуру TAB AI — облачного сервиса библиотеки [ТАБ:БИИ](https://tab-ai.ru). Семантический поиск реализован через тот же backend, что и функции `НайтиПоСмыслуОбъектСУказаннымиСвойствамиАсинх` и `СпрогнозируйДинамикуИзмененияДанных` в самой библиотеке.

## Лицензия

MIT
