Servidor MCP de ServiceNow

Una implementación de servidor de Protocolo de finalización de modelo (MCP) para ServiceNow, que permite a Claude interactuar con instancias de ServiceNow.

Descripción general

Este proyecto implementa un servidor MCP que permite a Claude conectarse a instancias de ServiceNow, recuperar datos y realizar acciones a través de la API de ServiceNow. Actúa como puente entre Claude y ServiceNow, lo que permite una integración fluida.

Características

• Conéctese a instancias de ServiceNow utilizando varios métodos de autenticación (básico, OAuth, clave API)

• Consultar registros y tablas de ServiceNow

• Crear, actualizar y eliminar registros de ServiceNow

• Ejecutar scripts y flujos de trabajo de ServiceNow

• Acceder y consultar el catálogo de servicios de ServiceNow

• Analizar y optimizar el catálogo de servicios de ServiceNow

• Modo de depuración para la resolución de problemas

• Soporte para comunicación stdio y eventos enviados por el servidor (SSE)

Instalación

Prerrequisitos

• Python 3.11 o superior

• Una instancia de ServiceNow con credenciales de acceso adecuadas

Configuración

1. Clonar este repositorio:

   git clone https://github.com/yourusername/servicenow-mcp.git cd servicenow-mcp

2. Cree un entorno virtual e instale el paquete:

   python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install -e .

3. Cree un archivo .env con sus credenciales de 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

Uso

Modo estándar (stdio)

Para iniciar el servidor MCP:

O con variables de entorno:

Modo de eventos enviados por el servidor (SSE)

El servidor MCP de ServiceNow también puede ejecutarse como un servidor web utilizando eventos enviados por el servidor (SSE) para la comunicación, lo que permite opciones de integración más flexibles.

Iniciar el servidor SSE

Puede iniciar el servidor SSE utilizando la CLI proporcionada:

De forma predeterminada, el servidor escuchará en 0.0.0.0:8080 . Puedes personalizar el host y el puerto:

Conexión al servidor SSE

El servidor SSE expone dos puntos finales principales:

• /sse - El punto final de la conexión SSE

• /messages/ - El punto final para enviar mensajes al servidor

Ejemplo

Consulte el archivo examples/sse_server_example.py para obtener un ejemplo completo de cómo configurar y ejecutar el servidor SSE.

Embalaje de herramientas (opcional)

Para gestionar la cantidad de herramientas expuestas al modelo de lenguaje (especialmente en entornos con limitaciones), el servidor MCP de ServiceNow admite la carga de subconjuntos de herramientas denominados "paquetes". Esto se controla mediante la variable de entorno MCP_TOOL_PACKAGE .

Configuración

1. Variable de entorno: establezca la variable de entorno MCP_TOOL_PACKAGE con el nombre del paquete deseado.

   export MCP_TOOL_PACKAGE=catalog_builder

2. Definiciones de paquetes: Los paquetes disponibles y las herramientas que incluyen se definen en config/tool_packages.yaml . Puede personalizar este archivo para crear sus propios paquetes.

Comportamiento

• Si MCP_TOOL_PACKAGE se establece en un nombre de paquete válido definido en config/tool_packages.yaml , solo se cargarán las herramientas enumeradas en ese paquete.

• Si MCP_TOOL_PACKAGEno está configurado o está vacío, se carga de forma predeterminada el paquete full (que contiene todas las herramientas).

• Si MCP_TOOL_PACKAGE se establece en un nombre de paquete no válido, se carga el paquete none (no hay herramientas excepto list_tool_packages ) y se registra una advertencia.

• La configuración MCP_TOOL_PACKAGE=none no carga explícitamente ninguna herramienta (excepto list_tool_packages ).

Paquetes disponibles (predeterminado)

El config/tool_packages.yaml predeterminado incluye los siguientes paquetes basados en roles:

• service_desk : Herramientas para el manejo de incidentes y búsqueda básica de usuarios/conocimientos.

• catalog_builder : Herramientas para crear y administrar elementos del catálogo de servicios, categorías, variables y scripts relacionados (políticas de IU, criterios de usuario).

• change_coordinator : Herramientas para gestionar el ciclo de vida de las solicitudes de cambio, incluidas tareas y aprobaciones.

• knowledge_author : Herramientas para crear y gestionar bases de conocimiento, categorías y artículos.

• platform_developer : Herramientas para scripts del lado del servidor (Script Includes), desarrollo de flujo de trabajo e implementación (Changesets).

• system_administrator : Herramientas para la gestión de usuarios/grupos y visualización de registros del sistema.

• full : incluye todas las herramientas disponibles (predeterminado).

• none : no incluye herramientas (excepto list_tool_packages ).

Herramienta de introspección

• list_tool_packages : Enumera todos los nombres de paquetes de herramientas disponibles definidos en la configuración y muestra el paquete cargado actualmente. Esta herramienta está disponible en todos los paquetes excepto none .

Herramientas disponibles

Nota: La disponibilidad de las siguientes herramientas depende del paquete de herramientas cargado (consulte la sección "Empaquetado de herramientas" más arriba). Por defecto (paquete full ), todas las herramientas están disponibles.

Herramientas de gestión de incidentes

1. create_incident - Crea un nuevo incidente en ServiceNow

2. update_incident - Actualizar un incidente existente en ServiceNow

3. add_comment - Agregar un comentario a un incidente en ServiceNow

4. resolve_incident - Resolver un incidente en ServiceNow

5. list_incidents - Lista de incidentes de ServiceNow

Herramientas del catálogo de servicios

1. list_catalog_items : lista de elementos del catálogo de servicios de ServiceNow

2. get_catalog_item : obtiene un elemento específico del catálogo de servicios de ServiceNow

3. list_catalog_categories : lista de categorías del catálogo de servicios de ServiceNow

4. create_catalog_category : crea una nueva categoría de catálogo de servicios en ServiceNow

5. update_catalog_category : actualiza una categoría del catálogo de servicios existente en ServiceNow

6. move_catalog_items - Mueve elementos del catálogo entre categorías en ServiceNow

7. create_catalog_item_variable - Crea una nueva variable (campo de formulario) para un artículo del catálogo

8. list_catalog_item_variables : enumera todas las variables de un artículo del catálogo

9. update_catalog_item_variable - Actualizar una variable existente para un artículo del catálogo

10. list_catalogs - Lista de catálogos de servicios de ServiceNow

Herramientas de optimización de catálogos

1. get_optimization_recommendations - Obtenga recomendaciones para optimizar el catálogo de servicios

2. update_catalog_item - Actualizar un elemento del catálogo de servicios

Herramientas de gestión del cambio

1. create_change_request - Crea una nueva solicitud de cambio en ServiceNow

2. update_change_request - Actualizar una solicitud de cambio existente

3. list_change_requests : lista de solicitudes de cambio con opciones de filtrado

4. get_change_request_details : obtener información detallada sobre una solicitud de cambio específica

5. add_change_task - Agregar una tarea a una solicitud de cambio

6. submit_change_for_approval - Enviar una solicitud de cambio para su aprobación

7. approved_change - Aprobar una solicitud de cambio

8. reject_change - Rechazar una solicitud de cambio

Herramientas de gestión del flujo de trabajo

1. list_workflows - Lista de flujos de trabajo de ServiceNow

2. get_workflow : obtener un flujo de trabajo específico de ServiceNow

3. create_workflow - Crea un nuevo flujo de trabajo en ServiceNow

4. update_workflow - Actualizar un flujo de trabajo existente en ServiceNow

5. delete_workflow - Eliminar un flujo de trabajo de ServiceNow

Herramientas de administración de inclusión de scripts

1. list_script_includes - Lista de scripts incluidos en ServiceNow

2. get_script_include - Obtener un script específico incluido desde ServiceNow

3. create_script_include - Crea un nuevo script incluido en ServiceNow

4. update_script_include - Actualizar un script existente incluido en ServiceNow

5. delete_script_include - Eliminar un script incluido de ServiceNow

Herramientas de gestión de conjuntos de cambios

1. list_changesets : lista de conjuntos de cambios de ServiceNow con opciones de filtrado

2. get_changeset_details : obtener información detallada sobre un conjunto de cambios específico

3. create_changeset - Crea un nuevo conjunto de cambios en ServiceNow

4. update_changeset - Actualizar un conjunto de cambios existente

5. commit_changeset - Confirmar un conjunto de cambios

6. publish_changeset - Publicar un conjunto de cambios

7. add_file_to_changeset - Agregar un archivo a un conjunto de cambios

Herramientas de gestión de bases de conocimientos

1. create_knowledge_base - Crea una nueva base de conocimiento en ServiceNow

2. list_knowledge_bases - Lista de bases de conocimiento con opciones de filtrado

3. create_category - Crea una nueva categoría en una base de conocimiento

4. create_article - Crea un nuevo artículo de conocimiento en ServiceNow

5. update_article - Actualizar un artículo de conocimiento existente en ServiceNow

6. publish_article - Publicar un artículo de conocimiento en ServiceNow

7. list_articles - Lista de artículos de conocimiento con opciones de filtrado

8. get_article - Obtener un artículo de conocimiento específico por ID

Herramientas de gestión de usuarios

1. create_user - Crea un nuevo usuario en ServiceNow

2. update_user - Actualizar un usuario existente en ServiceNow

3. get_user - Obtener un usuario específico por ID, nombre de usuario o correo electrónico

4. list_users - Lista de usuarios con opciones de filtrado

5. create_group - Crea un nuevo grupo en ServiceNow

6. update_group - Actualizar un grupo existente en ServiceNow

7. add_group_members - Agregar miembros a un grupo en ServiceNow

8. remove_group_members - Eliminar miembros de un grupo en ServiceNow

9. list_groups - Lista de grupos con opciones de filtrado

Herramientas de política de UI

1. create_ui_policy : crea una política de interfaz de usuario de ServiceNow, generalmente para un elemento del catálogo.

2. create_ui_policy_action : crea una acción asociada con una política de UI para controlar los estados de las variables (visibilidad, obligatoria, etc.).

Uso de la CLI de MCP

El servidor MCP de ServiceNow se puede instalar con la CLI de MCP, lo que proporciona una forma conveniente de registrar el servidor con Claude.

Este comando registrará el servidor MCP de ServiceNow con Claude y lo configurará para utilizar las variables de entorno del archivo .env.

Integración con Claude Desktop

Para configurar el servidor MCP de ServiceNow en Claude Desktop:

1. Edite el archivo de configuración de Claude Desktop en ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o la ruta adecuada para su sistema operativo:

2. Reinicie Claude Desktop para aplicar los cambios

Ejemplo de uso con Claude

A continuación se muestran algunos ejemplos de consultas en lenguaje natural que puede utilizar con Claude para interactuar con ServiceNow a través del servidor MCP:

Ejemplos de gestión de incidentes

• Crear un nuevo incidente por una interrupción de red en la región este.

• "Actualizar la prioridad del incidente INC0010001 a alta"

• "Añadir un comentario al incidente INC0010001 indicando que se está investigando el problema"

• "Resolver el incidente INC0010001 con una nota indicando que se reinició el servidor"

• "Enumere todos los incidentes de alta prioridad asignados al equipo de Red"

• "Enumere todos los incidentes P1 activos asignados al equipo de Red".

Ejemplos de catálogos de servicios

• "Muéstrame todos los artículos del catálogo de servicios"

• "Enumerar todas las categorías del catálogo de servicios"

• Obtener detalles sobre el artículo del catálogo de solicitud de portátil

• "Muéstrame todos los artículos del catálogo de la categoría Hardware"

• "Buscar 'software' en el catálogo de servicios"

• "Crear una nueva categoría llamada 'Servicios en la nube' en el catálogo de servicios"

• Actualizar la categoría 'Hardware' para renombrarla como 'Equipo de TI'.

• "Mover el elemento del catálogo 'Máquina Virtual' a la categoría 'Servicios en la Nube'"

• Cree una subcategoría llamada "Monitores" dentro de la categoría "Equipos de TI".

• Reorganizar nuestro catálogo moviendo todos los artículos de software a la categoría "Software".

• "Crear un campo de descripción para el artículo del catálogo de solicitud de portátil"

• "Añadir un campo desplegable para seleccionar modelos de portátiles al catálogo"

• "Enumerar todos los campos del formulario para el elemento del catálogo de solicitud de acceso VPN"

• "Hacer que el campo de departamento sea obligatorio en el formulario de solicitud de software"

• "Actualizar el texto de ayuda para el campo del centro de coste"

• "Muéstrame todos los catálogos de servicios del sistema"

• "Enumere todos los elementos del catálogo de hardware".

• "Encuentre el artículo del catálogo 'Solicitud de computadora portátil nueva'".

• "Muéstrame las variables para el elemento 'Solicitar nueva computadora portátil'".

• Cree una nueva variable llamada 'código_departamento' para el elemento del catálogo 'Configuración de nuevos empleados'. Conviértalo en un campo de cadena obligatorio.

Ejemplos de optimización de catálogos

• Analizar nuestro catálogo de servicios e identificar oportunidades de mejora.

• "Encuentre artículos del catálogo con descripciones deficientes que necesitan mejoras"

• Identificar los artículos del catálogo con poco uso que podríamos querer retirar.

• Encuentra artículos del catálogo con altas tasas de abandono.

• Optimizar nuestra categoría de hardware para mejorar la experiencia del usuario.

Ejemplos de gestión del cambio

• "Crear una solicitud de cambio para que el mantenimiento del servidor aplique parches de seguridad mañana por la noche"

• "Programar una actualización de la base de datos para el próximo martes de 2 a. m. a 4 a. m."

• "Añadir una tarea al cambio de mantenimiento del servidor para las comprobaciones previas a la implementación"

• "Enviar el cambio de mantenimiento del servidor para su aprobación"

• "Aprobar el cambio de actualización de la base de datos con el comentario: el plan de implementación parece completo"

• "Muéstrame todos los cambios de emergencia programados para esta semana"

• "Enumerar todos los cambios asignados al equipo de Red"

• "Cree una solicitud de cambio normal para actualizar el servidor de base de datos de producción".

• "Actualizar cambio CHG0012345, establecer el estado en 'Implementar'."

Ejemplos de gestión del flujo de trabajo

• "Muéstrame todos los flujos de trabajo activos en ServiceNow"

• Obtenga detalles sobre el flujo de trabajo de aprobación de incidentes.

• "Enumerar todas las versiones del flujo de trabajo de solicitud de cambio"

• "Muéstrame todas las actividades en el flujo de trabajo de solicitud del catálogo de servicios"

• Crear un nuevo flujo de trabajo para gestionar las solicitudes de licencias de software

• Actualizar la descripción del flujo de trabajo de escalamiento de incidentes.

• Activar el flujo de trabajo de incorporación de nuevos empleados

• "Desactivar el flujo de trabajo de restablecimiento de contraseña antigua"

• Agregar una actividad de aprobación al flujo de trabajo de solicitud de licencia de software

• Actualizar la actividad de notificación en el flujo de trabajo de escalamiento de incidentes.

• Eliminar la actividad innecesaria del flujo de trabajo de solicitud de cambio

• Reordenar las actividades en el flujo de trabajo de solicitud del catálogo de servicios

Ejemplos de gestión de conjuntos de cambios

• "Enumerar todos los conjuntos de cambios en ServiceNow"

• "Muéstrame todos los conjuntos de cambios creados por el desarrollador 'john.doe'"

• Obtener detalles sobre el conjunto de cambios 'sys_update_set_123'

• Crear un nuevo conjunto de cambios para la aplicación 'Portal de RR. HH.'

• "Actualizar la descripción del conjunto de cambios 'sys_update_set_123'"

• "Confirmar el conjunto de cambios 'sys_update_set_123' con el mensaje 'Problema de inicio de sesión solucionado'"

• "Publicar el conjunto de cambios 'sys_update_set_123' en producción"

• "Añadir un archivo al conjunto de cambios 'sys_update_set_123'"

• "Muéstrame todos los cambios en el conjunto de cambios 'sys_update_set_123'"

Ejemplos de bases de conocimientos

• "Crear una nueva base de conocimientos para el departamento de TI"

• "Enumerar todas las bases de conocimiento de la organización"

• Crear una categoría llamada "Solución de problemas de red" en la base de conocimientos de TI.

• "Escribe un artículo sobre la configuración de VPN en la categoría de Solución de problemas de red".

• Actualizar el artículo de configuración de VPN para incluir instrucciones para dispositivos móviles.

• Publicar el artículo de configuración de VPN para que sea visible para todos los usuarios.

• "Enumerar todos los artículos de la categoría Solución de problemas de red"

• "Muéstrame los detalles del artículo de configuración de VPN"

• Encuentre artículos de conocimiento que contengan "restablecimiento de contraseña" en la base de conocimientos de TI.

• Cree una subcategoría llamada "Redes inalámbricas" dentro de la categoría "Solución de problemas de red".

Ejemplos de gestión de usuarios

• Crear un nuevo usuario: Dra. Alice Radiology, en el departamento de Radiología.

• "Actualizar el registro de usuario de Bob para convertirlo en el administrador de Alice"

• Asignar el rol de ITIL a Bob para que pueda aprobar las solicitudes de cambio.

• "Enumerar todos los usuarios del departamento de Radiología"

• Crear un nuevo grupo llamado 'Ingeniería Biomédica' para la gestión de dispositivos médicos.

• "Agregar un usuario administrador al grupo de Ingeniería Biomédica como miembro"

• "Actualizar el grupo de Ingeniería Biomédica para cambiar de responsable"

• Eliminar un usuario del grupo de Ingeniería Biomédica

• "Buscar todos los usuarios activos en el sistema que tengan la palabra 'doctor' en su título"

• "Crear un usuario que actuará como aprobador del departamento de Radiología"

• "Enumerar todos los grupos de soporte de TI en el sistema"

Ejemplos de políticas de UI

• "Cree una política de IU para el elemento 'Solicitud de software' (sys_id: abc...) llamado 'Mostrar justificación' que se aplique cuando 'software_cost' sea mayor que 100".

• "Para la política de UI 'Mostrar justificación' (sys_id: def...), agregue una acción para hacer que la variable 'business_justification' sea visible y obligatoria".

• "Crea otra acción para la política 'Mostrar justificación' para ocultar la variable 'alternative_software'".

Scripts de ejemplo

El repositorio incluye scripts de ejemplo que demuestran cómo utilizar las herramientas:

• examples/catalog_optimization_example.py : Demuestra cómo analizar y mejorar el catálogo de servicios de ServiceNow

• examples/change_management_demo.py : Muestra cómo crear y administrar solicitudes de cambio en ServiceNow

Métodos de autenticación

Autenticación básica

Autenticación OAuth

Autenticación de clave API

Desarrollo

Documentación

Hay documentación adicional disponible en el directorio docs :

• Integración del catálogo : información detallada sobre la integración del catálogo de servicios

• Optimización del catálogo : plan detallado para las funciones de optimización del catálogo

• Gestión del cambio : información detallada sobre las herramientas de gestión del cambio

• Gestión del flujo de trabajo : información detallada sobre las herramientas de gestión del flujo de trabajo

• Gestión de conjuntos de cambios : información detallada sobre las herramientas de gestión de conjuntos de cambios

Solución de problemas

Errores comunes con las herramientas de gestión de cambios

1. Error:

   • Este error se produce cuando se pasa un objeto CreateChangeRequestParams en lugar de un diccionario a la función create_change_request .

   • Solución: asegúrese de que está pasando un diccionario con los parámetros, no un objeto de modelo Pydantic.

   • Nota: Las herramientas de gestión de cambios se han actualizado para gestionar este error automáticamente. Las funciones ahora intentarán desempaquetar los parámetros si están incorrectamente empaquetados o se pasan como un objeto de modelo de Pydantic.

2. Error:

   • Este error ocurre cuando no proporciona todos los parámetros necesarios para crear una solicitud de cambio.

   • Solución: Asegúrese de incluir todos los parámetros obligatorios. Para create_change_request , se requieren short_description y type .

3. Error:

   • Este error se produce cuando se proporciona un valor no válido para el parámetro type .

   • Solución: utilice uno de los valores válidos: “normal”, “estándar” o “emergencia”.

4. Error:

   • Este error ocurre cuando los parámetros se pasan en el orden incorrecto o cuando se utilizan objetos que no tienen los métodos requeridos.

   • Solución: Asegúrese de pasar los parámetros auth_manager y server_config en el orden correcto. Las funciones se han actualizado para gestionar el intercambio automático de parámetros.

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

1. Bifurcar el repositorio

2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )

3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

4. Empujar a la rama ( git push origin feature/amazing-feature )

5. Abrir una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.