MCP Simpleone

SimpleOne MCP Server

MCP-сервер для интеграции с SimpleOne (ESM) через REST API. Позволяет ИИ-агентам выполнять CRUD-операции в ESM-системе.

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

Установка

npm install

Настройка

1. Скопируйте .env.example в .env:

cp .env.example .env

1. Заполните конфигурацию:

SIMPLEONE_URL=https://your-instance.simpleone.ru
SIMPLEONE_API_KEY=your-api-key-here

Или используйте Basic Auth:

SIMPLEONE_URL=https://your-instance.simpleone.ru
SIMPLEONE_BASIC_USER=your-username
SIMPLEONE_BASIC_PASSWORD=your-password

Запуск

Разработка (stdio - для MCP-клиентов)

npm run dev

Разработка (HTTP/SSE - для отладки)

npm run dev:http    # SSE на порту 3000
npm run dev:sse     # то же самое

Продакшн

npm run build
npm start           # stdio режим
npm run start:http  # SSE режим на порту 3000

Сетевой доступ (SSE)

Для отладки и тестирования доступен HTTP/SSE транспорт:

Endpoints:

• GET /sse — SSE подключение
• POST /message?sessionId=xxx — отправка сообщений
• GET /health — проверка здоровья
• GET /info — информация о сервере и инструментах

Порт: 3000 (по умолчанию) или через MCP_PORT в .env

Пример:

# Запуск в режиме SSE
npm run dev:http

# Проверка
curl http://localhost:3000/health
curl http://localhost:3000/info

Инструменты

Параметры API

table_read

table_create

table_update

Примеры использования

Чтение данных (без подтверждения)

Базовый запрос:

Вызови table_read с tableName="itsm_incident"

С фильтрами и параметрами:

Вызови table_read с tableName="itsm_incident", query="active=1^priority=1", limit=10, fields="number,description,state"

Результат: Список активных инцидентов с высоким приоритетом (макс. 10 записей).

С отображаемыми значениями:

Вызови table_read с tableName="task", id="177431367402911371", display_value="true"

Результат: Задача с отображаемыми значениями полей (например, имя пользователя вместо ID).

С пагинацией и no_count:

Вызови table_read с tableName="itsm_incident", query="active=1", limit=50, page=2, no_count=true

Результат: Вторая страница по 50 записей без подсчёта общего количества (оптимизация).

С dot-walking (связанные поля):

Вызови table_read с tableName="task", query="assigned_user.department=IT", fields="number,assigned_user.name,assigned_user.email"

Результат: Задачи с полями из связанной таблицы пользователя.

Создание записи (с подтверждением)

Базовый запрос:

Вызови table_create с tableName="task", data={"subject": "Задача"}

С параметрами:

Вызови table_create с tableName="task", data={"subject": "Задача"}, fields="number,subject,sys_id"

Результат: Запрос подтверждения → после OK → задача создана с указанными полями в ответе.

Обновление записи (с подтверждением)

Базовый запрос:

Вызови table_update с tableName="task", id="177431367402911371", data={"subject": "Новая тема"}

С параметрами:

Вызови table_update с tableName="task", id="177431367402911371", data={"state": "2"}, display_value="true", fields="number,state"

Результат: Запрос подтверждения → после OK → запись обновлена.

Удаление записи (с подтверждением)

Вызови table_delete с tableName="task", id="177431367402911371"

Результат: Запрос подтверждения → после OK → запись удалена.

Тестирование

Дата: 2026-03-25

Dot-walking: Поддерживается в query и fields (например: assigned_user.department=IT)

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

# Health check
curl http://localhost:3000/health

# Info (список инструментов)
curl http://localhost:3000/info

# SSE подключение (для отладки)
curl -N http://localhost:3000/sse

Примеры использования

Создать инцидент

User: Создай инцидент с темой "Тестовая проблема"
Agent: [запросит подтверждение]
User: OK
Agent: INC001 создан

Прочитать список

User: Покажи последние инциденты
Agent: [вызовет esm_read без ID]

Обновить статус

User: Обнови статус INC001 на "В работе"
Agent: [запросит подтверждение]
User: OK
Agent: Статус обновлён

Безопасность

• Все write-операции требуют подтверждения — создание, обновление, удаление
• Секреты только в .env — никогда не храните в коде
• Маскировка в логах — API-ключи и пароли не логируются

Тестирование

npm test              # Запуск всех тестов
npm run test:watch    # Режим наблюдения
npm run test:coverage # Покрытие кода

Линтер

npm run lint

Автономная версия

Для развёртывания MCP-сервера на других машинах без зависимостей от репозитория:

Сборка

npm run build:standalone

Что делает скрипт:

1. Собирает TypeScript (npm run build)
2. Копирует dist/ в standalone/mcp-simpleone/
3. Устанавливает production-зависимости (node_modules/)
4. Копирует .env.example, README.md, LICENSE

Время сборки: ~15 секунд

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

standalone/mcp-simpleone/
├── dist/              # Скомпилированный код
├── node_modules/      # Зависимости (production only)
├── package.json       # Минимальный package.json
├── .env.example       # Шаблон конфигурации
├── README.md          # Краткая инструкция
└── LICENSE            # Лицензия

Размер: ~2.5 MB (131 пакет)

Развёртывание

# 1. Скопируйте каталог в нужное место
cp -r standalone/mcp-simpleone /opt/apps/mcp-simpleone

# 2. Настройте
cd /opt/apps/mcp-simpleone
cp .env.example .env
# Отредактируйте .env (SIMPLEONE_URL, SIMPLEONE_BASIC_USER, SIMPLEONE_BASIC_PASSWORD)

# 3. Запустите
npm start           # stdio (для MCP-клиентов)
npm run start:sse   # SSE на порту 3000
npm run start:http  # HTTP на порту 3000

Проверка

# Health check
curl http://localhost:3000/health

# Информация о сервере
curl http://localhost:3000/info

Обновление автономной версии

# В исходном репозитории
npm run build:standalone

# Замените каталог на сервере
rm -rf /opt/apps/mcp-simpleone
cp -r standalone/mcp-simpleone /opt/apps/mcp-simpleone

# Сохраните .env (не перезаписывайте!)
# Запустите сервер
cd /opt/apps/mcp-simpleone
npm start

→ Подробнее: DEPLOYMENT.md

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

mcp-simpleone/
├── src/
│   ├── index.ts           # Точка входа
│   ├── config.ts          # Конфигурация и валидация
│   ├── api/
│   │   ├── client.ts      # HTTP клиент
│   │   ├── auth.ts        # Аутентификация
│   │   └── types.ts       # Типы ресурсов
│   ├── tools/
│   │   ├── index.ts       # Регистрация инструментов
│   │   ├── table-create.ts
│   │   ├── table-read.ts
│   │   ├── table-update.ts
│   │   └── table-delete.ts
│   ├── utils/
│   │   ├── confirm.ts     # Подтверждение операций
│   │   ├── errors.ts      # Классы ошибок
│   │   └── logger.ts      # Логирование
│   └── tests/
├── .rules/                # Правила для ИИ-агента
├── AGENTS.md              # Центральный адаптер
└── QWEN.md                # Адаптер для Qwen Code

Ссылки

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

• MCP_SETUP.md — подробная инструкция по подключению MCP-клиентов
• DEPLOYMENT.md — развёртывание и автономная установка
• LOGGING.md — настройка логирования
• QUERY_EXAMPLES.md — примеры query-параметров

Правила и адаптеры

• .rules/ — ядро правил для ИИ-агентов (Source of Truth)
• AGENTS.md — центральный адаптер
• QWEN.md — адаптер для Qwen Code

Лицензия

MIT — см. LICENSE файл.