Сервер ARIM MCP

MCP-сервер (stdio) для прямого запроса измеренных данных, статистики, калибровки и отчётов системы мониторинга Arim Air прямо из Claude.

Только для чтения. Функции, изменяющие состояние сервера (публикация отчётов, применение калибровки, команды устройствам, обратное заполнение, регистрация/удаление аварий), не включены.

Установка

Требуется Node.js 18 или новее.

macOS / Linux

cd /Users/amdmania/Project/arimair-mcp
npm install
npm run build
./setup-arim-mcp.sh     # Claude Code + Claude Desktop 자동 등록

Windows

Поместите репозиторий в нужное место (например, C:\Users\<пользователь>\arimair-mcp) и запустите из этой папки. Скрипт установки определяет пути относительно своего расположения, поэтому работает из любого места без изменений.

В PowerShell:

cd C:\Users\<사용자>\arimair-mcp
npm install
npm run build
powershell -ExecutionPolicy Bypass -File .\setup-arim-mcp.ps1

-ExecutionPolicy Bypass — это опция, разрешающая выполнение неподписанного скрипта только один раз. Она не меняет системную политику.

Что делает скрипт установки (общее)

Адрес сервера жёстко задан как рабочий сервер (https://monitor.arimair.com), поэтому он не запрашивается. Оба скрипта запрашивают только идентификатор, пароль и тип учётной записи, после чего регистрируют сервер в двух местах:

• Claude Code CLI (claude mcp add arim -s user) — пропускается, если команда claude отсутствует

• Файл конфигурации Claude Desktop — существующий файл сохраняется как .bak.<временная метка>, а уже зарегистрированные другие MCP-серверы сохраняются

После регистрации необходимо полностью закрыть и снова открыть Claude Desktop, чтобы инструменты появились.

Ручная регистрация

# macOS / Linux
claude mcp add arim -s user -t stdio \
  -e ARIM_API_BASE_URL=https://monitor.arimair.com \
  -e ARIM_MCP_USER=<아이디> \
  -e ARIM_MCP_PASS=<비밀번호> \
  -- node /Users/amdmania/Project/arimair-mcp/build/index.js

# Windows (PowerShell) — 경로는 실제 설치 위치로
claude mcp add arim -s user -t stdio `
  -e "ARIM_API_BASE_URL=https://monitor.arimair.com" `
  -e "ARIM_MCP_USER=<아이디>" `
  -e "ARIM_MCP_PASS=<비밀번호>" `
  -- node C:\Users\<사용자>\arimair-mcp\build\index.js

Если пароль не был зарегистрирован, после подключения можно войти с помощью инструмента arim_login.

Переменные окружения

Если учётные данные указаны в переменных окружения, при первом вызове инструмента выполняется автоматический вход, а при истечении сессии — один повторный вход и повторная попытка.

Способ аутентификации

Сервер ARIM не выдаёт JWT, а аутентифицирует через HttpSession + сессионный cookie (SESSION от Spring Session). MCP сохраняет cookie, полученный при вызове /account/login, и отправляет его с последующими запросами.

Ко всем запросам добавляется заголовок X-Mcp-Client: 1. Если этот заголовок присутствует, AuthorizeInterceptor сервера возвращает 401 JSON вместо перенаправления 302 на страницу входа, и MCP считает это истечением сессии и выполняет повторный вход.

Сайт

Запросы измерителей, измеренных данных, статистики и отчётов выполняются относительно текущего выбранного сайта. Внутри сервера это monitorId сессии (учётная запись администратора, являющегося объектом мониторинга), но в инструментах это обрабатывается как «сайт». Это то же самое, что комбинированный список выбора сайта в верхней части веб-экрана.

site_list                        → 선택 가능한 사이트와 현재 사이트
site_select { site: "울산 환경보건센터" }   → 사이트 변경

Для site_select достаточно указать часть названия сайта. Даже если порядок слов отличается от зарегистрированного имени (например, зарегистрированное имя — [환경보건센터] 울산 울산대), поиск найдёт сайт, если присутствуют все слова. Поиск выполняется по отображаемому имени (company), имени ответственного (name) и siteId.

• Если кандидатов несколько, они не выбираются произвольно — возвращается список кандидатов (например, «환경보건센터» → 9 мест)

• Точное имя имеет приоритет над частичным совпадением (например, «도로교통연구원» → arimsc_ex)

Учётная запись обычного пользователя видит только одобренных поставщиков, учётная запись администратора — весь список (те же правила, что и в веб-интерфейсе).

Список инструментов

Аутентификация

Сайт

Измерители

Измеренные данные

Статистика и погода

Калибровка

Отчёты

Аварии

Сводки мониторинга

Обработка больших ответов

Инструменты запроса временных рядов принимают maxRows (по умолчанию 500). На сервере нет ограничения на количество строк, поэтому даже запрос сырых данных за один день даёт более 1 400 строк; при превышении выполняется равномерная выборка и в ответе возвращаются totalRows / returnedRows / sampled. Последняя (самая новая) строка всегда сохраняется.

Зависимости на стороне сервера

Этот MCP предполагает следующие изменения на сервере.

Если /account/me и /setting/sensorlist отсутствуют, не работают только arim_whoami, sensor_list, alarm_config_list (при опущенном adminId), а остальные инструменты работают нормально. site_list тоже работает, но без /account/me невозможно запросить текущий сайт у сервера, поэтому в качестве текущего сайта отображается значение, выбранное через site_select в этой сессии.

Сама функциональность сайта использует только существующие API (/site/update/{id}, /admin/list, /datarequest/providerlist) без изменений на сервере.