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

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

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

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

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

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

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

# Создать виртуальное окружение
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
2. Откройте обработку в 1C (Файл → Открыть)
3. В настройках обработки укажите:
   • URL прокси-сервера: http://localhost:6003
   • (опционально) ID канала для изоляции команд
4. Нажмите кнопку "Подключиться"

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

Kiro IDE

Добавьте в файл .kiro/settings/mcp.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

Откройте конфигурационный файл:

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

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

{
  "mcpServers": {
    "onec-mcp-toolkit-proxy": {
      "url": "http://localhost:6003/mcp",
      "transport": "http"
    }
  }
}

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

🛠️ Доступные 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

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

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

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

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

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

{
  "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>:

# Канал для разработки
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