ServiceNow Knowledge MCP

Eine deterministische, schreibgeschützte FastMCP-Integration für den Abruf von ServiceNow Knowledge. Sie führt keine Antwortgenerierung, Zusammenfassung, semantisches Reranking, Vektorsuche oder Dokumentenanalyse durch.

Architektur

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

Der Client zentralisiert Authentifizierungs-Header, Endpunktkonstruktion, Feldauswahl, begrenzte transiente Wiederholungsversuche, Timeout-/Fehlerzuordnung, JSON-Normalisierung und Grenzwerte für binäre Anhänge. Anmeldeinformationen, Autorisierungs-Header, Artikelinhalte und Anhangsinhalte werden nicht protokolliert.

Related MCP server: ServiceNow MCP Server

Tool-Zuordnung

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 bewahrt die ServiceNow-Ergebnisreihenfolge und gibt kompakte Kandidaten zurück. Es beansprucht kein semantisches, Vektor-, KI- oder Volltextverhalten. get_knowledge_article gibt den ausgewählten kanonischen Artikel und nützliche Gültigkeitsmetadaten zurück. get_knowledge_attachment gibt begrenzte Binärdaten als base64 zurück, da die strukturierte MCP-Ausgabe JSON-kompatibel ist; Aufrufer müssen sie dekodieren, und es wird keine Analyse oder OCR durchgeführt.

Entwicklung

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

Der Standard-Netzwerktransport ist zustandsloses Streamable HTTP unter http://localhost:8080/mcp. Setzen Sie TRANSPORT=stdio für einen lokal gestarteten MCP-Client.

Container-Build:

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

Konfiguration

Alle Einstellungen sind in .env.example aufgeführt. SERVICENOW_BASE_URL ist zur Laufzeit erforderlich. SERVICENOW_ACCESS_TOKEN liefert das Integrationsidentitätstoken. Such- und Artikelfeldauswahlen sind in SERVICENOW_SEARCH_FIELDS und SERVICENOW_ARTICLE_FIELDS zentralisiert, sodass verifizierte Standard- oder benutzerdefinierte Felder übernommen werden können, ohne den Client zu ändern.

Der Standard-API-Pfad und die Namen der Abfrageparameter sind Implementierungsannahmen, die gegen die ausgewählte ServiceNow Knowledge Management-API-Version geprüft werden müssen. Die Suche kann mit konfigurierten oder pro-Tool-Werten für Wissensdatenbank und Sprache eingegrenzt werden. Das angeforderte Ergebnislimit, die Artikelinhaltslänge, die Anhangsbytes, das Timeout und die transienten Wiederholungsversuche sind begrenzt.

Autorisierungsgrenze

Eine Integrationsidentität beweist für sich genommen nicht, dass die Knowledge-Berechtigungen eines Endbenutzers durchgesetzt werden. Der Authentifikator akzeptiert einen internen Autorisierungskontext, sodass ein bestätigter delegierter Mechanismus hinzugefügt werden kann, ohne den Client neu zu entwerfen, aber die MCP-Tools erfinden oder akzeptieren heute keine delegierte Anmeldeinformation.

Offene Sicherheitsfrage: Wenn der MCP ServiceNow mit einer Integrationsidentität aufruft, werden dann Knowledge Base-ACLs, User Criteria, Rollen, Gruppenmitgliedschaften und artikelbezogene Einschränkungen nur gegen die Integrationsidentität ausgewertet, oder kann der Autorisierungskontext des Endbenutzers propagiert und durchgesetzt werden?

Die Produktionsnutzung darf erst fortgesetzt werden, nachdem der geltende Berechtigungsvertrag bestätigt und getestet wurde.

Annahmen und offene Fragen

Die nachvollziehbaren Epics, Stories, Tasks, Annahmen und ungelösten Integrationsfragen werden in docs/implementation-plan.md gepflegt. Wichtige ungelöste Punkte sind:

1. Welche Such-/Indexierungs-/Ranking-Fähigkeit unterstützt den Parameter query, und entspricht sie der Knowledge-Benutzeroberfläche?

2. Welche Knowledge Bases, Sprachen und Veröffentlichungsstatus sind im Umfang enthalten?

3. Wie wird die Endbenutzer-Autorisierung durchgesetzt, wenn eine Integrationsidentität verwendet wird?

4. Welches Standard- oder benutzerdefinierte Feld enthält den kanonischen Artikelinhalt?

5. Welche Felder sind für Zielgruppe, Gültigkeit, Veröffentlichung, Zitierung und Aktualität erforderlich?

6. Welcher Authentifizierungsmechanismus, welche API-Version, Rate Limits und Durchsatz gelten?

7. Welche Nicht-Produktionsumgebung und repräsentative Testdaten für die Abrufqualität sind verfügbar?