1C Buddy - Чат, MCP сервер и OpenAI совместимый API шлюз для общения с 1С:Напарник

⚠️ Дисклеймер: используйте на свой страх и риск

Проект обращается к API сервиса 1С:Напарник (code.1c.ai) из стороннего клиента. По пользовательскому соглашению API предназначено для работы из 1С:EDT; вызов из внешних приложений соглашением не предусмотрен и трактуется сервисом как нарушение.

Сам 1С:Напарник начал детектировать и напоминать об этом: если запрос пришёл не из 1С:EDT, модель получает указание в мягкой форме сообщить пользователю, что API предназначено для 1С:EDT. Поэтому в ответах периодически может появляться соответствующая приписка.

Проект сделан в исследовательских целях. Ответственность за использование — целиком на вас, включая возможную блокировку токена или учётной записи. Автор не связан с фирмой «1С» и никаких гарантий не даёт.

Если вы разработчик и у вас есть идеи сотрудничества — фирма «1С» предлагает писать на ailab@1c.ru.

Возможности

💬 Веб-интерфейс чата

• Современный, адаптивный интерфейс чата
• Управление историей разговоров с изолированными контекстами (история хранится локально в браузере)
• Ответы в реальном времени с потоковой передачей
• Отдельное отображение tool call / tool result / follow-up блоков
• Пользовательские инструкции рабочего пространства
• Подключение внешних HTTP MCP серверов прямо из настроек чата
• Отображение reasoning-дельт в процессе генерации
• Подсветка синтаксиса для кода 1C (BSL) и XML с автоопределением
• Прикрепление файлов (.bsl, .xml, .txt)
• Просмотр содержимого прикрепленных файлов в браузере
• Поиск по содержимому прикрепленных файлов
• Визуализация mermaid диаграмм с возможностью сохранить в png
• Поиск по истории сообщений
• Экспорт истории разговоров в JSON
• Отображение статистики токенов (входящие/исходящие/всего)
• Копирование сообщений в буфер обмена
• Контекстное меню форматирования кода с горячими клавишами

🔧 MCP сервер

• Два транспорта поверх одного набора инструментов:
  • HTTP — POST /mcp внутри основного сервиса (нужен запущенный контейнер или 1c-buddy http)
  • stdio — 1c-buddy-mcp для Codex / IDE: не открывает порт, не поднимает чат, не требует FastAPI
• Доступные инструменты:
  • ask_1c_ai - общие вопросы по платформе 1С и практическим сценариям
  • explain_1c_syntax - объяснение конкретного объекта, метода или конструкции 1С
  • check_1c_code - синтаксическая проверка или code review фрагмента кода 1С
  • modify_1c_code - изменение кода 1С по явному заданию пользователя
  • search_1c_documentation - поиск по документации платформы 1С:Предприятие
  • search_its - поиск по базе знаний ИТС
  • fetch_its - получение содержимого конкретного документа или раздела ИТС по id
  • diff_1c_documentation_versions - сравнение документации платформы между двумя версиями

🚀 OpenAI-совместимый API

• OpenAI-совместимый формат для /v1/models и /v1/chat/completions
• Потоковые и непотоковые ответы с поддержкой Server-Sent Events (SSE)
• Стандартная аутентификация с Bearer токенами

Быстрый старт

1. Получите токен code.1c.ai с сайта code.1c.ai

2. Запустите с Docker:

   docker pull roctup/1c-buddy
   
   docker run -d --name 1c-buddy --restart unless-stopped -p 6002:6002 -e "ONEC_AI_TOKEN=<your_1c_ai_token>" roctup/1c-buddy 
   

   Если нужен также OpenAI API шлюз:

   docker pull roctup/1c-buddy
   
   docker run -d --name 1c-buddy --restart unless-stopped -p 6002:6002 -e "ONEC_AI_TOKEN=<your_1c_ai_token>" -e "OPENAI_COMPAT_API_KEY=<your_custom_api_key>" roctup/1c-buddy 
   

3. Начните общение:

   • Веб-интерфейс чата: http://localhost:6002/chat

   Дополнительные настройки чата скрыты по умолчанию. Чтобы включить пользовательские инструкции и внешние MCP серверы, запустите контейнер с флагами:

   docker run -d --name 1c-buddy --restart unless-stopped -p 6002:6002 \
     -e "ONEC_AI_TOKEN=<your_1c_ai_token>" \
     -e "CHAT_CUSTOM_INSTRUCTIONS_ENABLED=true" \
     -e "CHAT_CUSTOM_MCP_ENABLED=true" \
     roctup/1c-buddy
   

   После этого в чате появится кнопка настроек. В ней можно задать инструкции рабочего пространства и подключить внешние Streamable HTTP MCP серверы, например http://192.168.0.1:6003/mcp.

   Запуск за корпоративным прокси. Сертификат передаётся снаружи через volume, образ не меняется:

   docker run -d --name 1c-buddy --restart unless-stopped -p 6002:6002 \
     -v "$PWD/certs/company-ca-bundle.pem:/certs/company-ca-bundle.pem:ro" \
     -e "SSL_CERT_FILE=/certs/company-ca-bundle.pem" \
     -e "HTTPS_PROXY=http://proxy.company.local:3128" \
     -e "NO_PROXY=localhost,127.0.0.1" \
     -e "ONEC_AI_TOKEN=<your_1c_ai_token>" \
     roctup/1c-buddy
   

   SSL_CERT_FILE должен указывать на полный PEM-бандл: если он задан, публичные корневые сертификаты берутся только из него, поэтому в файле должны быть и публичные CA, и корпоративный. Подробности и аварийный режим SSL_VERIFY=false — в README_FULL.md.

4. Настройте MCP для IDE (HTTP-транспорт, нужен запущенный сервис):

   {
     "mcpServers": {   
       "onec-buddy-mcp": {
         "url": "http://localhost:6002/mcp",
         "connection_id": "1c_buddy_service_001",
         "alwaysAllow": [],
         "type": "streamable-http",
         "timeout": 300,
         "disabled": false
      }
    }
   }
   

5. Отправляйте запросы по OpenAI API:

   Используйте любой OpenAI SDK или клиентскую библиотеку:

   from openai import OpenAI
   
   client = OpenAI(
   	base_url="http://localhost:6002/v1",
   	api_key="your_custom_api_key"
   )
   
   # Непотоковый режим
   response = client.chat.completions.create(
   	model="1c-buddy",
   	messages=[{"role": "user", "content": "Как создать HTTPСоединение в 1С?"}]
   )
   print(response.choices[0].message.content)
   
   # Потоковый режим
   for chunk in client.chat.completions.stream(
   	model="1c-buddy",
   	messages=[{"role": "user", "content": "Объясни объект Запрос"}]
   ):
   	print(chunk.choices[0].delta.content, end="")
   

Запуск без Docker

Проект устанавливается как обычный Python-пакет (требуется Python 3.10+). Зависимости разделены: HTTP-сервису не нужен MCP SDK, а stdio-режиму не нужен FastAPI.

Нативный HTTP-сервис (чат + HTTP MCP + опциональный OpenAI API)

Windows:

py -m venv .venv
& .\.venv\Scripts\python.exe -m pip install ".[http]"
& .\.venv\Scripts\1c-buddy.exe --env-file .env http

Linux / macOS:

python3 -m venv .venv
./.venv/bin/python -m pip install ".[http]"
./.venv/bin/1c-buddy --env-file .env http

Опции: --host (по умолчанию 0.0.0.0), --port (6002), --log-level, --reload.

⚠️ По умолчанию сервис слушает 0.0.0.0, а чат и /mcp не имеют встроенной аутентификации. Не выставляйте порт в недоверенную сеть; для локальной работы используйте --host 127.0.0.1. Маршруты /v1/* монтируются только при заданном OPENAI_COMPAT_API_KEY.

MCP через stdio для Codex / IDE

Этот режим даёт только MCP-инструменты через stdin/stdout: порт не открывается, чат и OpenAI API не поднимаются.

Windows:

py -m venv .venv
& .\.venv\Scripts\python.exe -m pip install ".[stdio]"
[Environment]::SetEnvironmentVariable("ONEC_AI_TOKEN", "<your_1c_ai_token>", "User")

Linux / macOS:

python3 -m venv .venv
./.venv/bin/python -m pip install ".[stdio]"
export ONEC_AI_TOKEN=<your_1c_ai_token>   # лучше прописать в ~/.profile

Есть и минимальный вариант. Отдельный дистрибутив 1c-buddy-mcp содержит только MCP — без чата, OpenAI API, статики и tiktoken:

& .\.venv\Scripts\python.exe -m pip install .\mcp-package          # stdio
& .\.venv\Scripts\python.exe -m pip install ".\mcp-package[http]"  # + HTTP MCP

Оба дистрибутива ставят console script с именем 1c-buddy-mcp, поэтому конфиг Codex ниже подходит и полному пакету, и минимальному. Но ставить их рядом, в один venv, нельзя: они делят модули app/ и саму команду. Подробности и порядок восстановления — в README_FULL.md.

Конфигурация Codex (~/.codex/config.toml) — Windows:

[mcp_servers.onec-buddy]
command = 'C:\Users\<user>\.codex\mcp\1c-buddy\.venv\Scripts\1c-buddy-mcp.exe'
startup_timeout_sec = 30

[mcp_servers.onec-buddy.env]
ONEC_AI_UI_LANGUAGE = "russian"
ONEC_AI_TIMEOUT = "30"
MCP_TOOL_CALL_MODE = "direct"

Linux / macOS:

[mcp_servers.onec-buddy]
command = "/home/<user>/.codex/mcp/1c-buddy/.venv/bin/1c-buddy-mcp"
startup_timeout_sec = 30

[mcp_servers.onec-buddy.env]
ONEC_AI_UI_LANGUAGE = "russian"
ONEC_AI_TIMEOUT = "30"
MCP_TOOL_CALL_MODE = "direct"

Токен лучше держать в пользовательском окружении, а не в конфиге. Явная альтернатива — передать файл: 1c-buddy-mcp --env-file C:\path\to\.env. После изменения пользовательского окружения Codex нужно перезапустить.

.env никогда не подхватывается автоматически из текущего каталога — только через --env-file. Значения уже существующего окружения имеют приоритет над значениями из файла.

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

Подробная документация доступна в README_FULL.md.

Благодарности

Огромное спасибо автору оригинального проекта MCP сервера для 1С:Напарник: artesk/1copilot_MCP