1C AI MCP - MCP-сервер для 1С:Напарник

MCP-сервер (Model Context Protocol) для интеграции IDE с API 1С:Напарник. Построен на FastMCP (Python), упакован в Docker. Работает с Cursor, Claude Code и любыми MCP-совместимыми клиентами.

12 инструментов: анализ кода (проверка, ревью, рефакторинг) и поиск в документации (ИТС, платформа, конфигурации).

Основан на идее comol/1c-code-checker с исправлениями API-формата (ошибки 422), заимствованными из SteelMorgan/spring-mcp-1c-copilot.

Предварительные требования

• Docker (или Docker Desktop)

• Токен 1С:Напарник - получить на code.1c.ai (требуется подписка ИТС)

Related MCP server: 1C_MCP_SERVER_OWN

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

Вариант A: Готовый образ из Docker Hub (рекомендуется)

docker run -d --name 1c-ai-mcp -p 8007:8007 \
  -e ONEC_AI_TOKEN="ваш-токен" \
  desko77/1c-ai-mcp:latest

Или через Docker Compose - создайте файл docker-compose.yml:

services:
  1c-ai-mcp:
    image: desko77/1c-ai-mcp:latest
    container_name: 1c-ai-mcp
    ports:
      - "8007:8007"
    environment:
      ONEC_AI_TOKEN: "${ONEC_AI_TOKEN}"
    restart: always

# Создать .env с токеном (не попадает в git)
echo 'ONEC_AI_TOKEN=ваш-токен' > .env

# Запустить
docker compose up -d

Вариант B: Сборка из исходников

git clone https://github.com/Desko77/1c-ai-mcp.git
cd 1c-ai-mcp

# Создать .env с токеном
echo 'ONEC_AI_TOKEN=ваш-токен' > .env

# Собрать и запустить
docker compose up -d --build

Проверка работоспособности

# Должен вернуть HTTP 200
curl http://localhost:8007/mcp

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

Cursor

Добавьте в ~/.cursor/mcp.json:

{
  "mcpServers": {
    "1c-naparnik": {
      "url": "http://localhost:8007/mcp"
    }
  }
}

Claude Code

Добавьте в ~/.claude/settings.json:

{
  "mcpServers": {
    "1c-naparnik": {
      "url": "http://localhost:8007/mcp"
    }
  }
}

Другие MCP-клиенты

Endpoint: http://localhost:8007/mcp Транспорт: Streamable HTTP (по умолчанию) или SSE (USESSE=true).

Инструменты

Анализ кода

check_1c_code

Проверка кода 1С: синтаксис, логика, производительность. В direct mode синтаксис проверяется через upstream syntax-checker.

ask_1c_ai

Произвольный вопрос к 1С:Напарник. Сохраняет контекст диалога между вызовами.

review_1c_code

Code review: стиль, стандарты ИТС, именование, структура, читаемость. Не проверяет синтаксис.

rewrite_1c_code

ИИ предлагает свою улучшенную версию кода с объяснением изменений.

modify_1c_code

Модификация кода по явной инструкции. Если код не указан - генерирует новый.

explain_1c_syntax

Объяснение конкретного элемента синтаксиса 1С.

Документация и справка

its_help

Поиск по базе знаний ИТС (стандарты, методики, статьи). Возвращает ID документов для fetch_its.

fetch_its

Чтение документа ИТС по идентификатору. Используется после its_help.

search_1c_documentation

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

onec_help

Поиск в документации платформы (последняя версия). Как search_1c_documentation, но без указания версии.

diff_1c_documentation_versions

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

config_help

Поиск документации по прикладным конфигурациям (ERP, Бухгалтерия, ЗУП, УТ и др.).

Конфигурация

Все параметры передаются через переменные окружения.

* Обязателен ONEC_AI_TOKEN или ONEC_AI_TOKEN_FILE.

Docker Secrets

Для production-окружений токен можно передать через файл:

services:
  1c-ai-mcp:
    image: desko77/1c-ai-mcp:latest
    environment:
      ONEC_AI_TOKEN_FILE: /run/secrets/onec_token
    secrets:
      - onec_token

secrets:
  onec_token:
    file: ./onec_token.txt

Direct Mode

При MCP_TOOL_CALL_MODE=direct документационные инструменты и check_1c_code (syntax) вызывают upstream-инструменты 1С:Напарник напрямую по имени, вместо текстовых промптов. Это дает более точные результаты.

Upstream-инструменты:

• mcp__knowledge-hub__Search_ITS - для its_help

• mcp__knowledge-hub__Fetch_ITS - для fetch_its

• mcp__knowledge-hub__Search_Documentation - для search_1c_documentation, onec_help

• mcp__knowledge-hub__Diff_Documentation_Versions - для diff_1c_documentation_versions

• mcp__syntax-checker__validate - для check_1c_code (syntax)

При сбое direct-вызова автоматический fallback на промпт-режим. По умолчанию standard для обратной совместимости.

Архитектура

MCP-клиент (Cursor / Claude Code)
  -> FastMCP HTTP endpoint (:8007/mcp)
    -> mcp_server.py (обработчики инструментов)
      -> OneCApiClient (HTTP-клиент)
        -> code.1c.ai API (SSE-стриминг)
          -> парсинг ответа -> возврат клиенту

Два режима работы

• Standard mode (по умолчанию): инструменты формируют текстовые промпты и отправляют в API. Документационные инструменты используют tool chain - модель сама решает какой серверный инструмент вызвать.

• Direct mode (MCP_TOOL_CALL_MODE=direct): инструменты явно запрашивают конкретный upstream-инструмент по имени, матчат ответ и подтверждают вызов. При сбое - автоматический fallback на standard mode.

SSE-парсер

Поддерживает три формата ответа API:

Дополнительно:

• Автоматическое удаление <thinking>/<think> блоков из ответов

• Unicode-нормализация и очистка управляющих символов

• Fallback при получении tool_calls - повтор запроса с skill_name="raw"

• Обрезка входных данных по ONEC_AI_INPUT_MAX_LENGTH

Разработка

Локальный запуск без Docker

pip install -r requirements.txt
export ONEC_AI_TOKEN="ваш-токен"
python main.py

Структура проекта

main.py                       # Точка входа
src/
  mcp_server.py                # MCP-инструменты (@mcp.tool)
  onec_api_client.py           # HTTP-клиент к API 1С:Напарник
Dockerfile                     # Dockerfile
docker-compose.yml             # Compose для сборки из исходников
tests/                         # Тестовые скрипты
.github/workflows/
  docker-publish.yml           # CI: сборка и публикация в Docker Hub

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

• comol/1c-code-checker - оригинальная идея (репозиторий закрыт)

• SteelMorgan/spring-mcp-1c-copilot - правильные алгоритмы API

• FastMCP - фреймворк MCP-серверов

Лицензия

MIT - см. LICENSE