ServiceNow MCP Server

Сервер MCP ServiceNow

Реализация сервера протокола завершения модели (MCP) для ServiceNow, позволяющая Клоду взаимодействовать с экземплярами ServiceNow.

Обзор

Этот проект реализует сервер MCP, который позволяет Claude подключаться к экземплярам ServiceNow, извлекать данные и выполнять действия через API ServiceNow. Он служит мостом между Claude и ServiceNow, обеспечивая бесшовную интеграцию.

Функции

• Подключайтесь к экземплярам ServiceNow, используя различные методы аутентификации (Basic, OAuth, API Key)
• Запрос записей и таблиц ServiceNow
• Создание, обновление и удаление записей ServiceNow
• Выполнение сценариев и рабочих процессов ServiceNow
• Доступ и запросы к каталогу услуг ServiceNow
• Анализ и оптимизация каталога услуг ServiceNow
• Режим отладки для устранения неполадок
• Поддержка связи как stdio, так и Server-Sent Events (SSE)

Установка

Предпосылки

• Python 3.11 или выше
• Экземпляр ServiceNow с соответствующими учетными данными для доступа

Настраивать

1. Клонируйте этот репозиторий:
   git clone https://github.com/yourusername/servicenow-mcp.git cd servicenow-mcp
2. Создайте виртуальную среду и установите пакет:
   python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install -e .
3. Создайте файл .env с вашими учетными данными ServiceNow:
   SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com SERVICENOW_USERNAME=your-username SERVICENOW_PASSWORD=your-password SERVICENOW_AUTH_TYPE=basic # or oauth, api_key

Использование

Стандартный (stdio) режим

Чтобы запустить сервер MCP:

Или с переменными окружения:

Режим событий, отправленных сервером (SSE)

Сервер ServiceNow MCP также может работать как веб-сервер, используя для связи Server-Sent Events (SSE), что обеспечивает более гибкие возможности интеграции.

Запуск сервера SSE

Вы можете запустить сервер SSE с помощью предоставленного CLI:

По умолчанию сервер будет прослушивать 0.0.0.0:8080 . Вы можете настроить хост и порт:

Подключение к серверу SSE

Сервер SSE предоставляет две основные конечные точки:

• /sse — конечная точка соединения SSE
• /messages/ - Конечная точка для отправки сообщений на сервер.

Пример

Полный пример настройки и запуска сервера SSE смотрите в файле examples/sse_server_example.py .

Упаковка инструментов (опционально)

Для управления количеством инструментов, доступных языковой модели (особенно в средах с ограничениями), сервер ServiceNow MCP поддерживает загрузку подмножеств инструментов, называемых «пакетами». Это контролируется с помощью переменной среды MCP_TOOL_PACKAGE .

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

1. Переменная среды: задайте для переменной среды MCP_TOOL_PACKAGE имя нужного пакета.
   export MCP_TOOL_PACKAGE=catalog_builder
2. Определения пакетов: Доступные пакеты и входящие в них инструменты определены в config/tool_packages.yaml . Вы можете настроить этот файл для создания собственных пакетов.

Поведение

• Если MCP_TOOL_PACKAGE задано допустимое имя пакета, определенное в config/tool_packages.yaml , будут загружены только инструменты, перечисленные в этом пакете.
• Если MCP_TOOL_PACKAGEне задан или пуст, по умолчанию загружается full пакет (содержащий все инструменты).
• Если MCP_TOOL_PACKAGE задано недопустимое имя пакета, загружается пакет none (никаких инструментов, кроме list_tool_packages ), и регистрируется предупреждение.
• Установка MCP_TOOL_PACKAGE=none явно не загружает никакие инструменты (кроме list_tool_packages ).

Доступные пакеты (по умолчанию)

По умолчанию config/tool_packages.yaml включает следующие пакеты на основе ролей:

• service_desk : Инструменты для обработки инцидентов и базового поиска пользователей/знаний.
• catalog_builder : инструменты для создания и управления элементами каталога услуг, категориями, переменными и соответствующими сценариями (политики пользовательского интерфейса, критерии пользователя).
• change_coordinator : инструменты для управления жизненным циклом запроса на изменение, включая задачи и утверждения.
• knowledge_author : Инструменты для создания и управления базами знаний, категориями и статьями.
• platform_developer : Инструменты для написания скриптов на стороне сервера (включение скриптов), разработки и развертывания рабочих процессов (наборы изменений).
• system_administrator : Инструменты для управления пользователями/группами и просмотра системных журналов.
• full : включает все доступные инструменты (по умолчанию).
• none : не содержит инструментов (кроме list_tool_packages ).

Инструмент самоанализа

• list_tool_packages : Перечисляет все доступные имена пакетов инструментов, определенные в конфигурации, и показывает текущий загруженный пакет. Этот инструмент доступен во всех пакетах, кроме none .

Доступные инструменты

Примечание: Доступность следующих инструментов зависит от загруженного пакета инструментов (см. раздел Упаковка инструментов выше). По умолчанию ( full пакет) доступны все инструменты.

Инструменты управления инцидентами

1. create_incident — создать новый инцидент в ServiceNow
2. update_incident — обновить существующий инцидент в ServiceNow
3. add_comment — Добавить комментарий к инциденту в ServiceNow
4. resolve_incident — разрешение инцидента в ServiceNow
5. list_incidents — список инцидентов из ServiceNow

Инструменты каталога услуг

1. list_catalog_items — Список элементов каталога услуг от ServiceNow
2. get_catalog_item — Получить определенный элемент каталога услуг от ServiceNow
3. list_catalog_categories - Список категорий каталога услуг от ServiceNow
4. create_catalog_category — создание новой категории каталога услуг в ServiceNow
5. update_catalog_category — обновление существующей категории каталога услуг в ServiceNow
6. move_catalog_items — перемещение элементов каталога между категориями в ServiceNow
7. create_catalog_item_variable — Создать новую переменную (поле формы) для элемента каталога
8. list_catalog_item_variables — список всех переменных для элемента каталога
9. update_catalog_item_variable — обновить существующую переменную для элемента каталога
10. list_catalogs - Список каталогов услуг от ServiceNow

Инструменты оптимизации каталога

1. get_optimization_recommendations - Получить рекомендации по оптимизации каталога услуг
2. update_catalog_item — обновление элемента каталога услуг

Инструменты управления изменениями

1. create_change_request — создать новый запрос на изменение в ServiceNow
2. update_change_request — обновить существующий запрос на изменение
3. list_change_requests — список запросов на изменение с параметрами фильтрации
4. get_change_request_details — Получить подробную информацию о конкретном запросе на изменение
5. add_change_task — Добавить задачу в запрос на изменение
6. submit_change_for_approval — отправить запрос на изменение для одобрения
7. approved_change — Одобрить запрос на изменение
8. reject_change — Отклонить запрос на изменение

Инструменты управления рабочим процессом

1. list_workflows — список рабочих процессов от ServiceNow
2. get_workflow — получить определенный рабочий процесс из ServiceNow
3. create_workflow — создание нового рабочего процесса в ServiceNow
4. update_workflow — обновление существующего рабочего процесса в ServiceNow
5. delete_workflow — Удалить рабочий процесс из ServiceNow

Скрипт включает инструменты управления

1. list_script_includes — список включений скрипта из ServiceNow
2. get_script_include — получить определенный скрипт, включенный из ServiceNow
3. create_script_include — создание нового скрипта, включаемого в ServiceNow
4. update_script_include — обновление существующего включения скрипта в ServiceNow
5. delete_script_include — удаление включения скрипта из ServiceNow

Инструменты управления наборами изменений

1. list_changesets — список наборов изменений от ServiceNow с параметрами фильтрации
2. get_changeset_details — Получить подробную информацию о конкретном наборе изменений
3. create_changeset — создать новый набор изменений в ServiceNow
4. update_changeset — обновить существующий набор изменений
5. commit_changeset — зафиксировать набор изменений
6. publish_changeset — Опубликовать набор изменений
7. add_file_to_changeset — Добавить файл в набор изменений

Инструменты управления базой знаний

1. create_knowledge_base — создать новую базу знаний в ServiceNow
2. list_knowledge_bases — список баз знаний с параметрами фильтрации
3. create_category — Создать новую категорию в базе знаний
4. create_article - Создать новую статью знаний в ServiceNow
5. update_article — обновление существующей статьи знаний в ServiceNow
6. publish_article - Опубликовать статью знаний в ServiceNow
7. list_articles - Список статей знаний с возможностью фильтрации
8. get_article - Получить конкретную статью знаний по идентификатору

Инструменты управления пользователями

1. create_user — создать нового пользователя в ServiceNow
2. update_user — обновить существующего пользователя в ServiceNow
3. get_user — получить определенного пользователя по идентификатору, имени пользователя или адресу электронной почты
4. list_users — список пользователей с возможностью фильтрации
5. create_group — создать новую группу в ServiceNow
6. update_group — обновить существующую группу в ServiceNow
7. add_group_members — Добавить участников в группу в ServiceNow
8. remove_group_members — удаление участников из группы в ServiceNow
9. list_groups — список групп с параметрами фильтрации

Инструменты политики пользовательского интерфейса

1. create_ui_policy — создает политику пользовательского интерфейса ServiceNow, обычно для элемента каталога.
2. create_ui_policy_action — создает действие, связанное с политикой пользовательского интерфейса, для управления состояниями переменных (видимость, обязательность и т. д.).

Использование MCP CLI

Сервер ServiceNow MCP можно установить с помощью MCP CLI, который обеспечивает удобный способ регистрации сервера в Claude.

Эта команда зарегистрирует сервер ServiceNow MCP в Клоде и настроит его для использования переменных среды из файла .env.

Интеграция с Claude Desktop

Чтобы настроить сервер ServiceNow MCP в Claude Desktop:

1. Отредактируйте файл конфигурации Claude Desktop по адресу ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или по соответствующему пути для вашей ОС:

2. Перезапустите Claude Desktop, чтобы изменения вступили в силу.

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

Ниже приведены некоторые примеры запросов на естественном языке, которые вы можете использовать с Клодом для взаимодействия с ServiceNow через сервер MCP:

Примеры управления инцидентами

• «Создать новый инцидент для сбоя сети в восточном регионе»
• «Обновить приоритет инцидента INC0010001 до высокого»
• «Добавьте комментарий к инциденту INC0010001, в котором говорится, что проблема расследуется»
• «Устранить инцидент INC0010001, указав, что сервер был перезапущен»
• «Перечислите все инциденты с высоким приоритетом, назначенные сетевой команде»
• «Перечислите все активные инциденты P1, назначенные сетевой команде».

Примеры каталога услуг

• «Показать мне все позиции в каталоге услуг»
• «Список всех категорий каталога услуг»
• «Получить подробную информацию о товаре каталога «Запрос на ноутбук»»
• «Показать мне все элементы каталога в категории «Оборудование»»
• «Поиск «программного обеспечения» в каталоге услуг»
• «Создайте новую категорию под названием «Облачные сервисы» в каталоге сервисов»
• «Обновите категорию «Оборудование», переименовав ее в «ИТ-оборудование»»
• «Переместить элемент каталога «Виртуальная машина» в категорию «Облачные сервисы»»
• «Создайте подкатегорию «Мониторы» в категории «ИТ-оборудование»»
• «Реорганизуйте наш каталог, переместив все элементы программного обеспечения в категорию «Программное обеспечение»»
• «Создать поле описания для элемента каталога запроса ноутбука»
• «Добавить раскрывающееся поле для выбора моделей ноутбуков в элемент каталога»
• «Список всех полей формы для элемента каталога запроса на доступ к VPN»
• «Сделать поле «Отдел» обязательным в форме запроса программного обеспечения»
• «Обновить текст справки для поля центра затрат»
• «Покажите мне все каталоги услуг в системе»
• «Перечислите все элементы каталога оборудования».
• «Найдите позицию в каталоге по запросу «Новый ноутбук».
• «Покажите мне переменные для элемента «Запрос на новый ноутбук».
• «Создайте новую переменную с именем 'department_code' для элемента каталога 'New Hire Setup'. Сделайте ее обязательным строковым полем».

Примеры оптимизации каталога

• «Проанализируйте наш каталог услуг и определите возможности для улучшения»
• «Найдите элементы каталога с плохими описаниями, которые необходимо улучшить»
• «Определить редко используемые элементы каталога, которые, возможно, стоит изъять из обращения»
• «Найдите товары в каталоге с высоким уровнем отказов»
• «Оптимизируйте нашу категорию «Оборудование» для улучшения пользовательского опыта»

Примеры управления изменениями

• «Создайте запрос на изменение для обслуживания сервера, чтобы применить исправления безопасности завтра вечером»
• «Запланируйте обновление базы данных на следующий вторник с 2 до 4 утра»
• «Добавить задачу к изменению обслуживания сервера для проверок перед внедрением»
• «Отправить изменение обслуживания сервера на утверждение»
• «Одобрить изменение обновления базы данных с комментарием: план внедрения выглядит продуманным»
• «Покажите мне все экстренные изменения, запланированные на эту неделю»
• «Список всех изменений, назначенных сетевой команде»
• «Создайте обычный запрос на изменение для обновления сервера производственной базы данных».
• «Обновить изменение CHG0012345, установить состояние «Реализовать».

Примеры управления рабочим процессом

• «Покажите мне все активные рабочие процессы в ServiceNow»
• «Получите подробную информацию о рабочем процессе утверждения инцидента»
• «Перечислить все версии рабочего процесса запроса на изменение»
• «Показать мне все действия в рабочем процессе запроса каталога услуг»
• «Создать новый рабочий процесс для обработки запросов на лицензии на программное обеспечение»
• «Обновить описание рабочего процесса эскалации инцидента»
• «Активировать процесс адаптации нового сотрудника»
• «Деактивировать старый процесс сброса пароля»
• «Добавить действие по утверждению в рабочий процесс запроса лицензии на программное обеспечение»
• «Обновить активность уведомления в рабочем процессе эскалации инцидента»
• «Удалить ненужную активность из рабочего процесса запроса на изменение»
• «Изменение порядка действий в рабочем процессе запроса каталога услуг»

Примеры управления наборами изменений

• «Список всех наборов изменений в ServiceNow»
• «Показать мне все наборы изменений, созданные разработчиком 'john.doe'»
• "Получить сведения о наборе изменений 'sys_update_set_123'"
• «Создать новый набор изменений для приложения «HR Portal»»
• «Обновить описание набора изменений 'sys_update_set_123'»
• «Зафиксировать набор изменений sys_update_set_123 с сообщением «Исправлена проблема со входом»»
• «Опубликовать набор изменений sys_update_set_123 в рабочей среде»
• «Добавить файл в набор изменений 'sys_update_set_123'»
• «Показать мне все изменения в наборе изменений 'sys_update_set_123'»

Примеры базы знаний

• «Создать новую базу знаний для ИТ-отдела»
• «Перечислите все базы знаний в организации»
• «Создайте категорию под названием «Устранение неполадок сети» в базе знаний ИТ»
• «Напишите статью о настройке VPN в категории «Устранение неполадок в сети»
• «Обновите статью о настройке VPN, включив в нее инструкции для мобильных устройств»
• «Опубликуйте статью о настройке VPN, чтобы ее увидели все пользователи»
• «Список всех статей в категории «Устранение неполадок сети»»
• «Покажите мне подробности статьи о настройке VPN»
• «Найти статьи знаний, содержащие «сброс пароля», в базе знаний ИТ»
• «Создайте подкатегорию под названием «Беспроводные сети» в категории «Устранение неполадок сети»»

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

• «Создать нового пользователя Д-р Элис Радиология в отделении радиологии»
• «Обновить запись пользователя Боба, чтобы сделать его менеджером Алисы»
• «Назначьте Бобу роль ITIL, чтобы он мог утверждать запросы на изменение»
• «Список всех пользователей отделения радиологии»
• «Создать новую группу под названием «Биомедицинская инженерия» для управления медицинскими устройствами»
• «Добавить администратора в группу «Биомедицинская инженерия» в качестве участника»
• «Обновить группу биомедицинской инженерии, чтобы сменить ее руководителя»
• «Удалить пользователя из группы «Биомедицинская инженерия»»
• «Найти всех активных пользователей в системе, имеющих в названии слово «доктор»»
• «Создайте пользователя, который будет выступать в качестве утверждающего для отделения радиологии»
• «Перечислить все группы ИТ-поддержки в системе»

Примеры политики пользовательского интерфейса

• «Создайте политику пользовательского интерфейса для элемента «Запрос на программное обеспечение» (sys_id: abc...) с именем «Показать обоснование», которая применяется, когда «software_cost» больше 100».
• «Для политики пользовательского интерфейса «Показать обоснование» (sys_id: def...) добавьте действие, чтобы сделать переменную «business_justification» видимой и обязательной».
• «Создайте еще одно действие для политики «Показать обоснование», чтобы скрыть переменную «alternative_software».

Примеры скриптов

Репозиторий содержит примеры скриптов, демонстрирующие, как использовать инструменты:

• examples/catalog_optimization_example.py : Демонстрирует, как анализировать и улучшать каталог услуг ServiceNow
• examples/change_management_demo.py : показывает, как создавать и управлять запросами на изменение в ServiceNow

Методы аутентификации

Базовая аутентификация

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

Аутентификация API-ключа

Разработка

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

Дополнительная документация доступна в каталоге docs :

• Интеграция каталога - Подробная информация об интеграции каталога услуг
• Оптимизация каталога — подробный план функций оптимизации каталога
• Управление изменениями - Подробная информация об инструментах управления изменениями
• Управление рабочим процессом — подробная информация об инструментах управления рабочим процессом
• Управление наборами изменений — подробная информация об инструментах управления наборами изменений

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

Распространенные ошибки при использовании инструментов управления изменениями

1. Ошибка: argument after ** must be a mapping, not CreateChangeRequestParams
   • Эта ошибка возникает, когда вы передаете объект CreateChangeRequestParams вместо словаря в функцию create_change_request .
   • Решение: убедитесь, что вы передаете словарь с параметрами, а не объект модели Pydantic.
   • Примечание: Инструменты управления изменениями были обновлены для автоматической обработки этой ошибки. Функции теперь попытаются развернуть параметры, если они неправильно упакованы или переданы как объект модели Pydantic.
2. Ошибка: Missing required parameter 'type'
   • Эта ошибка возникает, если вы не указали все необходимые параметры для создания запроса на изменение.
   • Решение: Убедитесь, что включены все требуемые параметры. Для create_change_request требуются как short_description , так и type .
3. Ошибка: Invalid value for parameter 'type'
   • Эта ошибка возникает, если вы указываете недопустимое значение параметра type .
   • Решение: используйте одно из допустимых значений: «нормальный», «стандартный» или «аварийный».
4. Ошибка: Cannot find get_headers method in either auth_manager or server_config
   • Эта ошибка возникает, когда параметры передаются в неправильном порядке или при использовании объектов, не имеющих требуемых методов.
   • Решение: Убедитесь, что вы передаете параметры auth_manager и server_config в правильном порядке. Функции были обновлены для автоматической обработки замены параметров.

Внося вклад

Вклады приветствуются! Пожалуйста, не стесняйтесь отправлять запрос на включение.

1. Форк репозитория
2. Создайте ветку функций ( git checkout -b feature/amazing-feature )
3. Зафиксируйте свои изменения ( git commit -m 'Add some amazing feature' )
4. Отправить в ветку ( git push origin feature/amazing-feature )
5. Открыть запрос на извлечение

Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE.