Как установить и настроить MCP
Инструкция описывает установку MCP 3.3.7 с контрактом методов EPA_Projects 3.3.5. Перед началом проверьте версии, права и сетевые доступы. Установку MCP-сервера выполняют на машине, с которой доступны HTTP-публикации 1С или DCC.
.
1. Подготовьте информационную базу
Для прямого маршрута опубликуйте HTTP-сервис Экстрактора. Порядок для Windows и IIS приведён в разделе «Подготовка HTTP-публикации на IIS» ниже.
Для маршрута DCC настройте Экстрактор для обмена с DCC v2, зарегистрируйте коннектор и проверьте передачу метаданных. Входящая публикация 1С в этом маршруте не требуется.
В обоих случаях в базе должны быть установлены актуальные методы EPA_Projects. Установщик Python не обновляет Экстрактор, не создаёт публикацию и не регистрирует коннектор в DCC.
2. Получите MCP-сервер
Исходники доступны в репозитории MCP. Если каталог с сервером уже существует, используйте его после проверки версии и рабочих настроек. Для новой установки:
git clone https://github.com/Denvic-Tech/extractor-mcp-server.git cd extractor-mcp-server git switch main cd mcp
Все команды установки и запуска ниже выполняются из каталога mcp/ репозитория сервера. Это важно для чтения .env и относительных путей.
3. Выберите способ настройки
Можно использовать интерактивный установщик или подготовить файлы вручную. Установщик подходит для первоначальной настройки; ручной вариант удобен, если Python на хосте не нужен и сервер будет работать только в Docker.
Интерактивный установщик
Для Windows PowerShell:
py -3 --version py -3 scripts/install.py
Для Linux и macOS:
python3 --version python3 scripts/install.py
Нужен Python 3.11 или выше. Установщик использует стандартную библиотеку Python; заранее устанавливать PyYAML не требуется.
Ответьте на вопросы:
Использовать Docker или локальный Python. По умолчанию выбран локальный Python.
Подключаться через DCC v2 или напрямую к 1С. По умолчанию выбран прямой маршрут.
Для прямого маршрута укажите идентификатор, название, полный API URL и пользователя базы. Для DCC — адрес и пользователя DCC; список баз будет получен из Центра управления.
Для тестового HTTP подтвердите использование доверенной тестовой сети. Для эксплуатации используйте HTTPS.
Выберите установку зависимостей или сборку и запуск контейнера.
Пароль вводится скрыто. Установщик создаёт .env, bases.yaml и случайный токен MCP. Список баз может быть записан в JSON-нотации — это допустимый YAML.
Существующие .env и bases.yaml не заменяются без отдельного параметра. Для подготовки только настроек используйте --configure-only. Параметр --overwrite заменяет настройки с сохранением прежних файлов в .local-backups/installer-... в корне репозитория. Перед его использованием убедитесь, что выбрана нужная установка.
Пароли с переносами строк или ${...} установщик не записывает в .env; для них используйте окружение процесса или менеджер секретов. На Unix новые закрытые файлы получают права 600; на Windows ограничьте доступ NTFS владельцем и учётной записью службы.
Если установщик уже запустил сервер, переходите к подключению клиента. Если подготовлены только настройки, выполните нужный вариант запуска.
4. Настройка вручную
.env содержит параметры MCP, а bases.yaml — список прямых баз. Для DCC этот список не используется, но файл нужен универсальному Docker Compose. Сохраните рабочие файлы перед изменениями и ограничьте доступ к ним. Не добавляйте их в Git.
Прямой маршрут
Создайте .env в каталоге mcp/:
EXTRACTOR_PROJECTS_TRANSPORT=direct_http EXTRACTOR_PROJECTS_BASES_FILE=bases.yaml EXTRACTOR_PROJECTS_DEFAULT_BASE_ID=erp EXTRACTOR_PROJECTS_MCP_TOKENS=replace_with_a_random_secret EXTRACTOR_PROJECTS_TIMEOUT=60 EXTRACTOR_PROJECTS_OPERATION_DB=state/operations.sqlite3 EXTRACTOR_PROJECTS_PLAN_TTL_SECONDS=900
Создайте bases.yaml:
bases: - base_id: erp name: ERP url: https://1c.example.ru/erp/hs/extractor-projects/v1 user: mcp_service password: 'replace_with_1c_password' timeout: 60 allow_http_dev: false
Замените адрес, логин, пароль и токен своими значениями. base_id — идентификатор базы в MCP, а user — пользователь информационной базы. DEFAULT_BASE_ID, если он задан, должен соответствовать записи в YAML.
Для второй базы добавьте ещё одну запись в bases. Идентификаторы должны быть непустыми и уникальными. Единственный корневой ключ — bases; для прямого маршрута список непустой. Неизвестные поля отклоняются. Пустой пароль, если он используется в согласованной среде, записывается как '', а не YAML null.
Дополнительно база может задавать ca_bundle, а для mTLS — пару client_cert и client_key. В Docker эти файлы должны быть подключены в контейнер; в YAML указываются контейнерные пути.
Маршрут через DCC
Создайте .env:
EXTRACTOR_PROJECTS_TRANSPORT=dcc EXTRACTOR_PROJECTS_DCC_URL=https://dcc.example.ru/api EXTRACTOR_PROJECTS_DCC_USER=mcp EXTRACTOR_PROJECTS_DCC_PASSWORD='replace_with_dcc_password' # Общий срок ожидания результата операции, в секундах. EXTRACTOR_PROJECTS_DCC_WAIT_TIMEOUT=60 # Пауза между проверками результата, в секундах; не long polling. EXTRACTOR_PROJECTS_DCC_POLL_INTERVAL=1 EXTRACTOR_PROJECTS_MCP_TOKENS=replace_with_a_random_secret EXTRACTOR_PROJECTS_OPERATION_DB=state/operations.sqlite3
DCC_URL — корень API с префиксом /api или без него, как опубликован ваш DCC. Не добавляйте /v2, /docs или путь публикации 1С.
Для локального Python уберите EXTRACTOR_PROJECTS_BASES_FILE из .env. Для универсального Compose создайте bases.yaml:
bases: []
Compose монтирует файл и задаёт путь внутри контейнера, но маршрут DCC не читает из него список баз. UUID коннектора в .env не задаётся: базу выбирают через list_bases после подключения клиента.
Токен MCP и хранение настроек
Для HTTP-подключения замените replace_with_a_random_secret случайным секретом. При установленном Python токен можно получить в закрытом терминале:
python -c "import secrets; print(secrets.token_urlsafe(32))"
На Windows при необходимости используйте py -3, на Unix — python3. Передайте токен в настройки ИИ-клиента. При пустом MCP_TOKENS HTTP-доступ закрыт, кроме /health. Для stdio токен клиента не используется.
На Unix ограничьте права:
chmod 600 .env bases.yaml
На Windows задайте доступ к файлам владельцу и учётной записи службы. Переменные окружения процесса имеют приоритет над .env. Для службы используйте постоянный рабочий каталог или абсолютные пути. После изменения настроек перезапустите процесс, а в Docker пересоздайте контейнер через up -d.
5. Запустите сервер
Выберите один из вариантов. Перед запуском проверьте, что другой экземпляр MCP не занимает тот же порт.
Docker
На Linux нужны Engine и Compose v2. На Windows или macOS — Docker Desktop с Linux-контейнерами. В Windows проверьте доступ Docker Desktop к каталогу проекта, DNS и корпоративной сети.
docker version docker compose version docker compose -f docker-compose.install.yml config --quiet docker compose -f docker-compose.install.yml up -d --build docker compose -f docker-compose.install.yml ps
Проверка процесса в PowerShell:
Invoke-RestMethod -Uri http://127.0.0.1:8001/health
На Linux и macOS:
curl --fail http://127.0.0.1:8001/health
Адрес MCP для клиента на этой машине — http://127.0.0.1:8001/mcp. Внутри контейнера используется порт 8000. Универсальный Compose публикует порт только на 127.0.0.1 и сохраняет SQLite в томе extractor1c_state. Контейнерные пути — /var/lib/extractor1c/operations.sqlite3 для состояния и /run/extractor1c/bases.yaml для YAML.
Python на Windows
py -3 --version py -3 -m venv .venv .\.venv\Scripts\python.exe -m pip install -e . .\.venv\Scripts\python.exe -m extractor1c.mcp_server
Если .venv уже существует, используйте её после проверки назначения и зависимостей. Активация окружения и изменение ExecutionPolicy не требуются. Процесс остаётся работать в терминале. Проверку /health выполните из второго терминала.
Python на Linux и macOS
python3 --version python3 -m venv .venv .venv/bin/python -m pip install -e . .venv/bin/python -m extractor1c.mcp_server
На Linux для выбранной версии Python может понадобиться отдельный пакет venv. Сервер слушает 127.0.0.1:8001.
Если нужен другой порт, запускайте приложение через Uvicorn. Пример для Unix:
.venv/bin/python -m uvicorn extractor1c.mcp_server:app --host 127.0.0.1 --port 8002
У команды extractor1c-mcp нет собственных флагов --host и --port.
6. Подключите ИИ-клиент
ИИ-клиент должен поддерживать выбранный канал MCP. Названия полей интерфейса зависят от приложения; используйте следующие значения.
HTTP
/health проверяет процесс, а /mcp используется клиентом для работы с инструментами. Если клиент находится на другой машине, 127.0.0.1 указывает на машину клиента. Настройте перед MCP HTTPS reverse proxy с поддержкой streamable HTTP и передачей Authorization, затем используйте внешний адрес, например https://mcp.example.ru/mcp.
Локальный stdio
В этом режиме процесс MCP обычно запускает сам ИИ-клиент. Отдельная HTTP-служба не требуется.
Если клиент не позволяет задать рабочий каталог, передайте абсолютные пути EXTRACTOR_PROJECTS_BASES_FILE и EXTRACTOR_PROJECTS_OPERATION_DB через окружение процесса. Файл .env должен быть доступен установленной копии сервера. Выбор stdio относится к каналу ИИ-клиент → MCP и не переключает маршрут MCP → DCC / 1С.
7. Проверьте подключение
В ИИ-клиенте попросите помощника:
Проверь подключение к MCP Экстрактора. Прочитай доступные навыки, покажи список баз, для выбранной мной базы проверь readiness и прочитай метаданные. Проекты не создавай и выгрузку не запускай.
При первом подключении помощник вызывает list_skills и читает применимые документы через get_skill. Затем получает базы через list_bases, согласовывает нужную базу и передаёт её base_id в последующие вызовы.
В readiness проверьте:
mcpVersion— для описанной поставки3.3.7;expectedOneCMethodsVersion— ожидается3.3.5;oneCMethodsVersion— фактический контракт методов в базе;capabilities и готовность необходимых операций.
Установка завершена, если доступны нужная база, согласованные версии и чтение ожидаемых метаданных. Ответ /health сам по себе этого не подтверждает. Проверка приёмника и пробная выгрузка выполняются отдельно по поручению пользователя.
Если проверка не проходит, используйте таблицу проблем.
8. Автозапуск, обновление и резервные копии
Для локального HTTP-сервера настройте службу ОС или задание запуска с абсолютным путём к Python из .venv, аргументами -m extractor1c.mcp_server, рабочим каталогом mcp/, правами чтения настроек и записи каталога состояния. Начинайте с одного процесса. В stdio процессом управляет клиент.
Перед обновлением сохраните .env, bases.yaml, сертификаты и весь каталог состояния. Для Docker остановите приложение перед резервным копированием тома. После получения согласованного обновления исходников пересоберите образ с актуальной базой, затем пересоздайте контейнер:
docker compose -f docker-compose.install.yml build --pull docker compose -f docker-compose.install.yml up -d
После обновления проверьте /health, затем readiness.mcpVersion — ожидается 3.3.7.
Остановка:
docker compose -f docker-compose.install.yml down
Не используйте down -v: он удаляет том с планами и историей операций. Для локального Python остановите процесс, обновите исходники, повторите установку -m pip install -e . Python-интерпретатором из .venv и запустите сервер заново. После обновления повторите readiness.
Для вывода последних сообщений Docker:
docker compose -f docker-compose.install.yml logs --tail 100
Перед передачей диагностики удалите секреты. Не публикуйте рабочие .env, YAML с паролями, токены и заголовки авторизации.
Расширенные настройки
Все параметры ниже имеют префикс EXTRACTOR_PROJECTS_:
Переменные окружения процесса имеют приоритет над .env. При установке из исходников сервер читает mcp/.env; запускайте из mcp/, чтобы относительные пути и HTTP-аутентификация читались согласованно. В Compose .env передаётся через env_file. Для службы используйте абсолютные пути или фиксированный рабочий каталог. После изменения настроек перезапустите сервер; в Docker пересоздайте контейнер через up -d. При локальном использовании ALLOWED_HOSTS экспортируйте его в окружение до запуска: защита Host создаётся при импорте.
Подготовка HTTP-публикации на IIS
Для прямого HTTP-маршрута выполните веб-публикацию базы 1С. В отдельной инструкции описаны подготовка IIS, установка модулей веб-сервера 1С, публикация HTTP-сервиса и настройка доступа. Для маршрута через DCC входящая HTTP-публикация не требуется.
Дополнительные материалы
Далее: Как пользоваться MCP.