1c-buddy-mcp

Лёгкий standalone MCP-сервер для работы с 1C.ai из Codex и других MCP-клиентов. Запускается напрямую в Python через stdio: без Docker, веб-чата, OpenAI-совместимого шлюза и отдельного HTTP-сервера.

Проект основан на MCP/API-реализации ROCTUP/1c-buddy. Последний проверенный upstream commit: 7f2b0305cd80e3a9f2cebb2dc69603fd7c7ab054.

Инструменты

Инструмент	Назначение
ask_1c_ai	Общие вопросы по платформе 1С и практическим сценариям
explain_1c_syntax	Объяснение объекта, метода, типа или конструкции 1С
check_1c_code	Синтаксическая проверка или code review BSL-кода
modify_1c_code	Изменение BSL-кода по явному заданию
search_1c_documentation	Поиск по документации платформы 1С:Предприятие
search_its	Поиск по базе знаний ИТС
fetch_its	Получение документа или раздела ИТС по id
diff_1c_documentation_versions	Сравнение документации между версиями платформы

Требования

• Python 3.10 или новее;
• Git;
• действующий токен 1C.ai в переменной ONEC_AI_TOKEN;
• Codex или другой MCP-клиент с поддержкой stdio.

Установка в Windows PowerShell

git clone https://github.com/VVi3ard/1c-buddy-mcp.git "$HOME\.codex\mcp\1c-buddy-mcp"
Set-Location "$HOME\.codex\mcp\1c-buddy-mcp"
py -m venv .venv
& .\.venv\Scripts\python.exe -m pip install --upgrade pip
& .\.venv\Scripts\python.exe -m pip install .

Сохраните токен в пользовательском окружении и перезапустите Codex:

[Environment]::SetEnvironmentVariable("ONEC_AI_TOKEN", "ВАШ_ТОКЕН", "User")

Не добавляйте токен в Git, README или публичные конфигурации.

Установка в Linux/macOS

git clone https://github.com/VVi3ard/1c-buddy-mcp.git ~/.codex/mcp/1c-buddy-mcp
cd ~/.codex/mcp/1c-buddy-mcp
python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install .
export ONEC_AI_TOKEN='ВАШ_ТОКЕН'

Для постоянного хранения переменной используйте защищённое хранилище или конфигурацию оболочки с ограниченным доступом.

Подключение к Codex

Добавьте в C:\Users\<имя>\.codex\config.toml:

[mcp_servers.onec-ai-1c]
command = 'C:\Users\<имя>\.codex\mcp\1c-buddy-mcp\.venv\Scripts\python.exe'
args = ["-m", "onec_buddy_mcp"]
cwd = 'C:\Users\<имя>\.codex\mcp\1c-buddy-mcp'
startup_timeout_sec = 30

[mcp_servers.onec-ai-1c.env]
ONEC_AI_UI_LANGUAGE = "russian"
ONEC_AI_TIMEOUT = "30"
MCP_TOOL_CALL_MODE = "direct"

Токен намеренно отсутствует в TOML: процесс получает ONEC_AI_TOKEN из пользовательского окружения. После изменения конфигурации перезапустите Codex.

Для Linux/macOS укажите абсолютные пути к .venv/bin/python и каталогу репозитория.

Проверка

Установите зависимости разработки и запустите unit-тесты:

& .\.venv\Scripts\python.exe -m pip install -e ".[dev]"
& .\.venv\Scripts\python.exe -m pytest -m "not live" -q

Live-тест выполняется только по явному запросу и использует токен окружения:

$env:RUN_LIVE_TESTS = "1"
& .\.venv\Scripts\python.exe -m pytest -m live -q

После перезапуска Codex проверьте список MCP-инструментов и выполните, например:

• ask_1c_ai: «Что такое ТаблицаЗначений?»;
• check_1c_code: синтаксическая проверка короткой процедуры;
• search_1c_documentation: поиск HTTPСоединение для нужной версии.

Настройки

Переменная	Обязательная	Значение по умолчанию
ONEC_AI_TOKEN	да	—
ONEC_AI_BASE_URL	нет	https://code.1c.ai
ONEC_AI_TIMEOUT	нет	30
ONEC_AI_UI_LANGUAGE	нет	russian
ONEC_AI_PROGRAMMING_LANGUAGE	нет	пусто
DEFAULT_SSL_VERSION	нет	пусто
DEFAULT_1C_CONFIGURATION	нет	пусто
MCP_TOOL_INPUT_MIN_LENGTH	нет	4
MCP_TOOL_INPUT_MAX_LENGTH	нет	100000
MCP_TOOL_CALL_MODE	нет	direct
ONEC_AI_INCLUDE_LIMITATIONS	нет	true

direct вызывает специализированные upstream-инструменты для синтаксиса, документации и ИТС. standard формулирует обычный запрос к 1C.ai и полезен как режим совместимости при изменениях upstream.

Успешный ответ каждого инструмента содержит секции Ответ, Ограничения инструмента и Требуемая проверка. Ограничения формируются MCP-сервером, а не AI-моделью, и учитывают назначение конкретного инструмента. Чтобы вернуть ответы в исходном виде, задайте ONEC_AI_INCLUDE_LIMITATIONS=false.

Обновление из upstream

Проекты имеют разные структуры и не предназначены для полного git merge. Изменения 1C.ai API и MCP-инструментов переносятся контролируемо по инструкции docs/UPDATING_FROM_UPSTREAM.md.

Устранение проблем

• ONEC_AI_TOKEN missing: задайте пользовательскую переменную и полностью перезапустите Codex, чтобы новый процесс получил окружение.
• HTTP 401/403: токен отклонён 1C.ai или не передан процессу.
• HTTP 422: upstream изменил payload; сравните актуальные модули 1c-buddy по руководству обновления.
• Сервер не появляется в Codex: проверьте абсолютные command, cwd, наличие .venv и запустите python -m onec_buddy_mcp вручную. В рабочем stdio-режиме процесс ожидает MCP-ввод и ничего не печатает в stdout.
• Поиск ИТС не возвращает данные: доступ зависит от возможностей аккаунта и текущих upstream-инструментов 1C.ai.

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

• токен хранится как SecretStr и не включается в repr настроек;
• ошибки MCP не возвращают заголовок Authorization;
• логи пишутся в stderr, stdout зарезервирован для MCP;
• .env, виртуальные окружения и тестовые артефакты исключены из Git.

Лицензия и авторство

Проект распространяется по GNU AGPL v3. Реализация API-взаимодействия, схемы инструментов и часть prompt-логики производны от ROCTUP/1c-buddy, также распространяемого по GNU AGPL v3. Новый проект не является официальным продуктом фирмы «1С».