ServiceNow Knowledge MCP

Una integración FastMCP determinista y de solo lectura para la recuperación de Knowledge de ServiceNow. No realiza generación de respuestas, resúmenes, reranking semántico, búsqueda vectorial ni análisis de documentos.

Arquitectura

AI platform / MCP client
        ↓
FastMCP server
        ↓
KnowledgeService
        ↓
ServiceNowKnowledgeClient
        ↓
ServiceNow Knowledge Management REST API

El cliente centraliza los encabezados de autenticación, la construcción de endpoints, la selección de campos, los reintentos transitorios acotados, el mapeo de tiempos de espera y errores, la normalización JSON y los límites de adjuntos binarios. Las credenciales, los encabezados de autorización, el contenido de los artículos y los cuerpos de los adjuntos no se registran en los logs.

Related MCP server: ServiceNow MCP Server

Mapeo de herramientas

search_knowledge
    → GET /knowledge/articles

get_knowledge_article
    → GET /knowledge/articles/{id}

get_knowledge_attachment
    → GET /knowledge/articles/{article_sys_id}/attachments/{attachment_sys_id}

search_knowledge conserva el orden de resultados de ServiceNow y devuelve candidatos compactos. No declara comportamiento semántico, vectorial, de IA ni de texto completo. get_knowledge_article devuelve el artículo canónico seleccionado y metadatos de validez útiles. get_knowledge_attachment devuelve datos binarios acotados como base64 porque la salida estructurada de MCP es compatible con JSON; los llamadores deben decodificarlos, y no se realiza ningún análisis ni OCR.

Desarrollo

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
pytest
ruff format --check src tests
ruff check src tests
mypy src
servicenow-knowledge-mcp

El transporte de red predeterminado es Streamable HTTP sin estado en http://localhost:8080/mcp. Establece TRANSPORT=stdio para un cliente MCP generado localmente.

Compilación del contenedor:

docker build -t servicenow-knowledge-mcp .
docker run --env-file .env -p 8080:8080 servicenow-knowledge-mcp

Configuración

Todos los ajustes se muestran en .env.example. SERVICENOW_BASE_URL es obligatorio en tiempo de ejecución. SERVICENOW_ACCESS_TOKEN proporciona el token de identidad de la integración. Las selecciones de campos de búsqueda y de artículos están centralizadas en SERVICENOW_SEARCH_FIELDS y SERVICENOW_ARTICLE_FIELDS para que se puedan adoptar campos estándar o personalizados verificados sin modificar el cliente.

La ruta de API predeterminada y los nombres de los parámetros de consulta son suposiciones de implementación que deben verificarse contra la versión seleccionada de la API de ServiceNow Knowledge Management. La búsqueda se puede acotar con valores de Knowledge Base e idioma configurados o por herramienta. El límite de resultados solicitado, la longitud del contenido del artículo, los bytes de los adjuntos, el tiempo de espera y los reintentos transitorios están acotados.

Límite de autorización

Una identidad de integración no demuestra por sí misma que se apliquen los permisos de Knowledge del usuario final. El autenticador acepta un contexto de autorización interno para que se pueda añadir un mecanismo delegado confirmado sin rediseñar el cliente, pero las herramientas MCP no inventan ni aceptan una credencial delegada hoy en día.

Pregunta de seguridad abierta: cuando el MCP llama a ServiceNow usando una identidad de integración, ¿se evalúan las ACL de Knowledge Base, los User Criteria, los roles, la pertenencia a grupos y las restricciones a nivel de artículo solo contra la identidad de integración, o se puede propagar y aplicar el contexto de autorización del usuario final?

El uso en producción no debe continuar hasta que se confirme y pruebe el contrato de derechos aplicable.

Suposiciones y preguntas abiertas

La Epic trazable, las Stories, las Tasks, las suposiciones y las preguntas de integración sin resolver se mantienen en docs/implementation-plan.md. Los elementos importantes sin resolver incluyen:

1. ¿Qué capacidad de búsqueda/indexación/clasificación respalda el parámetro query, y coincide con la interfaz de Knowledge?

2. ¿Qué Knowledge Bases, idiomas y estados de publicación están dentro del alcance?

3. ¿Cómo se aplicará la autorización del usuario final cuando se use una identidad de integración?

4. ¿Qué campo estándar o personalizado contiene el contenido canónico del artículo?

5. ¿Qué campos se requieren para audiencia, validez, publicación, citación y actualidad?

6. ¿Qué mecanismo de autenticación, versión de API, límites de velocidad y rendimiento se aplican?

7. ¿Qué entorno que no sea de producción y qué fixtures representativos de calidad de recuperación están disponibles?