Skip to main content
Glama

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

Сравнение документации между версиями платформы

Related MCP server: 1C Buddy

Требования

  • 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С».

Available Tools

8 tools
ask_1c_aiD

Общие вопросы по платформе 1С и практическим сценариям.

Inputs: question (required), programming_language, ssl_version, configuration. Returns: result

check_1c_codeC

Синтаксическая проверка или code review фрагмента BSL-кода.

Inputs: code (required), check_type, extended. Returns: result

diff_1c_documentation_versionsC

Сравнение документации платформы между двумя версиями.

Inputs: version_a (required), version_b (required), query. Returns: result

explain_1c_syntaxC

Объяснение объекта, метода, типа или конструкции платформы 1С.

Inputs: syntax_element (required), context, ssl_version, configuration. Returns: result

fetch_itsA

Получение содержимого документа или раздела ИТС по идентификатору.

Inputs: id. Returns: result

modify_1c_codeC

Изменение BSL-кода по явному заданию пользователя.

Inputs: instruction (required), code. Returns: result

search_1c_documentationC

Поиск по документации платформы 1С:Предприятие указанной версии.

Inputs: query (required), version. Returns: result

search_itsC

Поиск материалов в базе знаний ИТС с идентификаторами источников.

Inputs: query (required), ssl_version, configuration. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 8 tools

    Disambiguation5/5

    Каждый инструмент нацелен на отдельное действие: общие вопросы (ask_1c_ai), проверка кода (check_1c_code), объяснение синтаксиса (explain_1c_syntax), изменение кода (modify_1c_code), поиск документации (search_1c_documentation), получение материалов ИТС (fetch_its) и т.д. Описания чётко разделяют сферы ответственности, исключая путаницу.

    Naming Consistency5/5

    Все имена следуют единому шаблону verb_noun в snake_case (ask_1c_ai, check_1c_code, diff_1c_documentation_versions, explain_1c_syntax, fetch_its, modify_1c_code, search_1c_documentation, search_its). Отклонений нет, стиль однороден.

    Tool Count5/5

    8 инструментов оптимально покрывают основные потребности в работе с платформой 1С: вопросы, разбор кода, документация, ИТС. Количество не избыточно и не недостаточно для заявленной цели.

    Completeness4/5

    Охвачены ключевые операции: поиск и получение документации, анализ и модификация кода, сравнение версий, общие вопросы. Отсутствует, например, запуск кода или создание с нуля, но это может быть вне области применения. В целом покрытие достаточное.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server for 1C:Enterprise that provides AI assistants with access to configuration data via vector search, structural indexing, and call graphs. It enables semantic code queries and rapid metadata object lookups without requiring the direct reading of raw files.
      79
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server providing tools for interacting with 1С:Напарник AI, including asking questions, syntax explanation, code review, and documentation search. Also serves as a web chat interface and OpenAI-compatible API gateway.
      110
      AGPL 3.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Acts as a bridge between AI agents (Claude, Cursor) and 1C:Enterprise databases, enabling metadata retrieval, configuration analysis, and code generation through natural language using the MCP protocol.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Integrates AI agents with 1C:Enterprise databases via MCP and REST API, supporting a built-in HTTP server (no Python required) or a Python proxy mode.
      363
      GPL 3.0