MCP-прокси сервер для «Управление IT-отделом 8», редакция 4.0

Что это

Прокси-сервер между MCP-клиентами (Claude Desktop, Cursor) и 1С:Предприятие. Транслирует MCP-протокол в JSON-RPC вызовы к HTTP-сервису 1С.

Предназначен для конфигурации «Управление IT-отделом 8» — встроенный в неё MCP-сервис предоставляет AI-агентам инструменты для работы с задачами, проектами, базой знаний, файлами и лентой уведомлений.

Возможности:

Два транспорта: stdio (для нативных клиентов) и Streamable HTTP (для веб)
Проксирование всех MCP-примитивов: Tools, Resources, Prompts
Опциональная OAuth2 авторизация с per-user креденшилами

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

Пошаговые руководства для решения «Управление IT-отделом 8», редакция 4.0:

Развертывание MCP-сервера на виртуальной машине — установка прокси на отдельной ВМ с Docker.
Подключение AI-клиентов к MCP-серверу — настройка Claude Desktop, Cursor и Claude Code, в том числе с OAuth2-авторизацией.

Ниже — техническая справка по самому прокси.

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

Требования

Node.js 22.19+
1С:Предприятие 8.3.24+ с опубликованным HTTP-сервисом

Установка

# Установка зависимостей
npm install

# Сборка
npm run build

Выбор режима работы

📖 Пошаговая настройка клиентов (Claude Desktop, Cursor, Claude Code) с OAuth2-авторизацией — в статье Подключение AI-клиентов.

Stdio режим

Для локальных MCP-клиентов (Claude Desktop, Cursor).

Настройки указываются в конфигурации клиента через переменные окружения.

Минимальная конфигурация клиента:

{
  "mcpServers": {
    "uit": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/mcp",
      "env": {
        "MCP_ONEC_URL": "http://localhost/base",
        "MCP_ONEC_USERNAME": "admin",
        "MCP_ONEC_PASSWORD": "password"
      }
    }
  }
}

HTTP режим

Для веб-приложений и множественных клиентов.

Настройки указываются в файле .env в корне проекта или через переменные окружения:

# Скопируйте пример
cp .env.example .env

Минимальный .env:

MCP_ONEC_URL=http://localhost/base
MCP_ONEC_USERNAME=admin
MCP_ONEC_PASSWORD=password

Запуск:

node dist/index.js http --port 8000

Подключение клиентов с нативной поддержкой HTTP (Cursor, VS Code, Claude Code):

{
  "mcpServers": {
    "uit": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Подключение Claude Desktop к HTTP-серверу

claude_desktop_config.json не поддерживает поле "url" ("type": "http") — только stdio-запуск через "command". Поэтому Claude Desktop подключается к HTTP-серверу через локальный мост mcp-remote: он стартует по stdio и проксирует запросы на HTTP-endpoint. Нужен установленный Node.js (см. Требования) — его вызывает npx.

{
  "mcpServers": {
    "uit": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://192.168.88.124:8000/mcp", "--allow-http"]
    }
  }
}

Замените http://192.168.88.124:8000/mcp на адрес вашего HTTP-сервера (для локального запуска — http://localhost:8000/mcp). Флаг --allow-http обязателен, если endpoint работает по обычному HTTP, а не HTTPS.

Docker

Запуск в контейнере для изоляции и упрощения развертывания.

📖 Полное пошаговое руководство по развёртыванию на отдельной ВМ — Развертывание MCP-сервера.

Первичная установка

# 1. Клонируем репозиторий
git clone https://github.com/Diversus23/itmcp.git

# 2. Переходим в папку, где находится клонированный itmcp
cd itmcp

# 3. Скопировать конфигурацию
cp .env.docker.example .env

# 4. Отредактировать .env (обязательно: MCP_ONEC_URL, MCP_ONEC_USERNAME, MCP_ONEC_PASSWORD)

# 5. Запустить через docker compose
docker compose build --no-cache
docker compose up -d

# 6. Проверка, что все работает
curl http://localhost:8000/health

Или напрямую через Docker:

# Сборка образа
docker build -t 1c-mcp-proxy .

# Запуск с переменными окружения
docker run -d \
  -p 8000:8000 \
  -e MCP_ONEC_URL=http://host.docker.internal/base \
  -e MCP_ONEC_USERNAME=admin \
  -e MCP_ONEC_PASSWORD=password \
  --name mcp-proxy \
  1c-mcp-proxy

Важно про сеть:

Если 1С на том же хосте: используйте host.docker.internal (Mac/Windows) или IP хоста 172.17.0.1 (Linux) вместо localhost
Если 1С на другом сервере: указывайте его реальный адрес как обычно

Логи:

docker compose logs -f

Остановка:

docker compose down

Обновление в docker

Когда выходит новая версия необходимо пересобрать образ MCP в docker. Необходимо перейти в папку, куда клонировали репозиторий itmcp.

# 1. Получаем изменения новой версии
git pull

# 2. Останавливаем контейер
docker compose down

# 3. Пересобираем образ
docker compose build --no-cache

# 4. Запускаем новый образ (обновленный)
docker compose up -d

Режимы работы

Stdio режим

Общение через stdin/stdout
Используется локальными MCP-клиентами
Логи идут в stderr
OAuth2 не поддерживается (при MCP_AUTH_MODE=oauth2 запуск завершится ошибкой)

HTTP режим

Endpoints:

/mcp - Streamable HTTP транспорт
/health - проверка состояния
/info - информация о сервере
/ - список endpoints

Проверка работы:

curl http://localhost:8000/health

Режимы авторизации

Без OAuth2 (по умолчанию)

MCP_AUTH_MODE=none  # по умолчанию

Поведение:

Все обращения к 1С выполняются от одного пользователя
Креденшилы задаются в конфигурации: MCP_ONEC_USERNAME и MCP_ONEC_PASSWORD
Используется Basic Auth для всех запросов к 1С

С OAuth2

MCP_AUTH_MODE=oauth2
MCP_PUBLIC_URL=http://your-server:8000

Поведение:

OAuth2 доступен только в HTTP режиме (в stdio запуск завершится ошибкой)
Каждый клиент авторизуется своими креденшилами 1С
Креденшилы передаются через OAuth2 flow
MCP_ONEC_USERNAME и MCP_ONEC_PASSWORD не используются (если заданы, будут проигнорированы)

Поддерживаемые OAuth2 flows:

Password Grant - передача username/password напрямую
Authorization Code + PKCE - авторизация через HTML-форму
Dynamic Client Registration - автоматическая регистрация клиентов

Дополнительные endpoints (для OAuth2):

/.well-known/oauth-protected-resource - Protected Resource Metadata
/.well-known/oauth-authorization-server - Authorization Server Metadata
/register - регистрация клиентов
/authorize - HTML форма авторизации
/token - получение/обновление токенов

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

Все настройки задаются через переменные окружения с префиксом MCP_ или через CLI аргументы.

Подключение к 1С

Переменная	Описание	По умолчанию	Обязательная
`MCP_ONEC_URL`	URL базы 1С	-	Всегда
`MCP_ONEC_USERNAME`	Имя пользователя	-	При `AUTH_MODE=none`
`MCP_ONEC_PASSWORD`	Пароль	-	При `AUTH_MODE=none`
`MCP_ONEC_SERVICE_ROOT`	Корень HTTP-сервиса	`mcp`	Нет

HTTP-сервер

Переменная	Описание	По умолчанию	Обязательная
`MCP_HOST`	Хост для прослушивания	`127.0.0.1`	Нет
`MCP_PORT`	Порт	`8000`	Нет
`MCP_CORS_ORIGINS`	CORS origins (JSON array)	`["*"]`	Нет

MCP

Переменная	Описание	По умолчанию	Обязательная
`MCP_SERVER_NAME`	Имя сервера	`Управление IT-отделом 8 MCP`	Нет
`MCP_SERVER_VERSION`	Версия	`1.0.0`	Нет
`MCP_LOG_LEVEL`	Уровень логирования	`INFO`	Нет

Допустимые уровни: DEBUG, INFO, WARNING, ERROR

OAuth2

Переменная	Описание	По умолчанию	Обязательная
`MCP_AUTH_MODE`	Режим: `none` или `oauth2`	`none`	Нет
`MCP_PUBLIC_URL`	Публичный URL прокси	(определяется из запроса)	При `AUTH_MODE=oauth2`
`MCP_OAUTH2_CODE_TTL`	TTL authorization code (сек)	`120`	Нет
`MCP_OAUTH2_ACCESS_TTL`	TTL access token (сек)	`3600`	Нет
`MCP_OAUTH2_REFRESH_TTL`	TTL refresh token (сек)	`1209600`	Нет
`MCP_OAUTH2_STORE_PATH`	Путь к JSON-снапшоту токенов	(только в памяти)	Нет
`MCP_OAUTH2_REFRESH_GRACE_MS`	Окно идемпотентности refresh-rotation (мс)	`60000`	Нет

Персистентность токенов. При указанном MCP_OAUTH2_STORE_PATH access- и refresh-токены сериализуются в JSON-файл (атомарная запись через временный файл) каждые 30 секунд и при graceful shutdown. После рестарта прокси загружает снапшот, отбрасывая истекшие записи. Это устраняет повторные логины пользователей при перезапуске контейнера / краше процесса.

⚠️ Безопасность снапшота. Файл содержит логины и пароли пользователей 1С в открытом виде (Basic Auth требуется для каждого запроса к 1С). Файл создаётся с правами 0o600 (только владелец) на POSIX-системах; на Windows mode игнорируется — обеспечьте ограниченные NTFS ACL на каталог. Не храните снапшот в общем томе, не коммитьте в репозиторий (./data уже игнорируется через .gitignore).

Grace-window для refresh-rotation. При повторном использовании одного и того же refresh_token в течение MCP_OAUTH2_REFRESH_GRACE_MS сервер возвращает ранее выпущенную пару токенов (идемпотентно) — защита от race condition при параллельных refresh-запросах клиента. По истечении окна повторное использование считается атакой и приводит к отзыву всей цепочки токенов этой сессии (RFC 6819 §5.2.2.3).

CLI аргументы

Переопределяют переменные окружения:

node dist/index.js http \
  --onec-url http://server/base \
  --onec-username admin \
  --onec-password secret \
  --auth-mode oauth2 \
  --public-url http://proxy:8000 \
  --port 8000 \
  --log-level DEBUG

Полный список аргументов:

node dist/index.js --help

Архитектура

Общая схема

+------------------+
|   MCP Client     |  (Claude Desktop, Cursor)
|  (stdio/HTTP)    |
+--------+---------+
         | MCP Protocol
         v
+--------------------+
|  Node.js Proxy     |
|  - mcp-proxy       |  Проксирование MCP -> JSON-RPC
|  - http-server     |  Express + Streamable HTTP + OAuth2
|  - stdio-server    |  Stdio транспорт
|  - onec-client     |  HTTP-клиент для 1С
+--------+-----------+
         | JSON-RPC over HTTP
         | Basic Auth (username:password)
         v
+--------------------+
|  1C HTTP Service   |  /hs/mcp/rpc
|  МСP-подсистема    |  39 tools, resources, prompts
+--------------------+

Модули

index.ts - точка входа
main.ts - CLI парсинг и запуск
config.ts - конфигурация через Zod
mcp-proxy.ts - ядро MCP-сервера (проксирование)
onec-client.ts - HTTP-клиент для 1С
http-server.ts - Express + Streamable HTTP + OAuth2
stdio-server.ts - stdio транспорт
auth/oauth2.ts - OAuth2 авторизация (Store + Service)
logger.ts - логирование в stderr

Проксирование MCP-примитивов

Все MCP-запросы транслируются в JSON-RPC к 1С:

Tools (инструменты):

tools/list -> список доступных инструментов
tools/call -> вызов инструмента с аргументами

Resources (ресурсы):

resources/list -> список доступных ресурсов
resources/read -> чтение содержимого ресурса

Prompts (промпты):

prompts/list -> список доступных промптов
prompts/get -> получение промпта с параметрами

Интеграция с 1С

Прокси ожидает HTTP-сервис в 1С по адресу:

{MCP_ONEC_URL}/hs/{MCP_ONEC_SERVICE_ROOT}/

Например: http://localhost/base/hs/mcp/

Endpoints 1С

GET /health
- Проверка доступности сервиса
- Ответ: {"status": "ok"}
- Используется для валидации креденшилов в OAuth2
POST /rpc
- JSON-RPC endpoint для всех MCP-операций
- Content-Type: application/json
- Basic Auth: username:password

Формат JSON-RPC запроса

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Формат JSON-RPC ответа

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_metadata",
        "description": "Получить метаданные объекта",
        "inputSchema": {}
      }
    ]
  }
}

Разработка

# Установка зависимостей (заодно ставит git-хуки через husky)
npm install

# Сборка
npm run build

# Сборка в watch-режиме
npm run dev

# Запуск stdio
npm start

# Запуск HTTP
npm run start:http

Контроль качества

npm run typecheck      # проверка типов без сборки
npm run lint           # ESLint
npm run lint:fix       # ESLint с автоисправлением
npm run format         # Prettier: отформатировать
npm run format:check   # Prettier: только проверка
npm test               # запуск тестов (Vitest)
npm run test:watch     # тесты в watch-режиме
npm run test:coverage  # тесты с отчётом о покрытии
npm run check          # format:check + lint + typecheck + test (как в CI)

Перед каждым коммитом husky + lint-staged автоматически прогоняют ESLint и Prettier по изменённым файлам. CI (GitHub Actions) дополнительно проверяет сборку на Node 22 и 24, собирает Docker-образ и запускает CodeQL.

История изменений — в CHANGELOG.md.

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.github		.github
.husky		.husky
src		src
tests		tests
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.docker.example		.env.docker.example
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.eslint.json		tsconfig.eslint.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

MCP-прокси сервер для «Управление IT-отделом 8», редакция 4.0

Что это

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

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

Требования

Установка

Выбор режима работы

Stdio режим

HTTP режим

Docker

Первичная установка

Обновление в docker

Режимы работы

Stdio режим

HTTP режим

Режимы авторизации

Без OAuth2 (по умолчанию)

С OAuth2

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

Подключение к 1С

HTTP-сервер

MCP

OAuth2

CLI аргументы

Архитектура

Общая схема

Модули

Проксирование MCP-примитивов

Интеграция с 1С

Endpoints 1С

Формат JSON-RPC запроса

Формат JSON-RPC ответа

Разработка

Контроль качества

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages