Сервер MCP ServiceNow

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

Обзор

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

Related MCP server: Azure MCP Server

Функции

• Подключайтесь к экземплярам 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. Ошибка:

   • Эта ошибка возникает, когда вы передаете объект CreateChangeRequestParams вместо словаря в функцию create_change_request .

   • Решение: убедитесь, что вы передаете словарь с параметрами, а не объект модели Pydantic.

   • Примечание: Инструменты управления изменениями были обновлены для автоматической обработки этой ошибки. Функции теперь попытаются развернуть параметры, если они неправильно упакованы или переданы как объект модели Pydantic.

2. Ошибка:

   • Эта ошибка возникает, если вы не указали все необходимые параметры для создания запроса на изменение.

   • Решение: Убедитесь, что включены все требуемые параметры. Для create_change_request требуются как short_description , так и type .

3. Ошибка:

   • Эта ошибка возникает, если вы указываете недопустимое значение параметра type .

   • Решение: используйте одно из допустимых значений: «нормальный», «стандартный» или «аварийный».

4. Ошибка:

   • Эта ошибка возникает, когда параметры передаются в неправильном порядке или при использовании объектов, не имеющих требуемых методов.

   • Решение: Убедитесь, что вы передаете параметры 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.