ServiceNow Knowledge MCP

一个确定性的、只读的 FastMCP 集成，用于 ServiceNow Knowledge 检索。它不执行答案生成、摘要、语义重排序、向量搜索或文档解析。

架构

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

该客户端集中处理认证头、端点构建、字段选择、有界瞬时重试、超时/错误映射、JSON 规范化以及二进制附件限制。凭据、授权头、文章内容和附件正文不会被记录。

Related MCP server: ServiceNow MCP Server

工具映射

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 保留 ServiceNow 结果排序并返回精简候选结果。它不声称具有语义、向量、AI 或全文搜索行为。get_knowledge_article 返回选定的规范文章和有用的有效性元数据。get_knowledge_attachment 以 base64 形式返回有界二进制数据，因为结构化的 MCP 输出是 JSON 兼容的；调用方必须对其进行解码，且不执行任何解析或 OCR。

开发

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

默认网络传输是无状态的 Streamable HTTP，地址为 http://localhost:8080/mcp。对于本地生成的 MCP 客户端，设置 TRANSPORT=stdio。

容器构建：

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

配置

所有设置均显示在 .env.example 中。SERVICENOW_BASE_URL 在运行时为必填项。SERVICENOW_ACCESS_TOKEN 提供集成身份令牌。搜索和文章字段选择集中在 SERVICENOW_SEARCH_FIELDS 和 SERVICENOW_ARTICLE_FIELDS 中，以便在不修改客户端的情况下采用已验证的标准或自定义字段。

默认 API 路径和查询参数名称是实现假设，必须根据所选的 ServiceNow Knowledge Management API 版本进行核对。搜索可以通过配置的或按工具指定的 Knowledge Base 和语言值来限定范围。请求的结果数量限制、文章内容长度、附件字节数、超时和瞬时重试次数均设有上限。

授权边界

集成身份本身并不能证明最终用户的 Knowledge 权限已得到执行。认证器接受内部授权上下文，以便在无需重新设计客户端的情况下添加已确认的委派机制，但 MCP 工具目前不会发明或接受委派凭据。

开放的安全问题：当 MCP 使用集成身份调用 ServiceNow 时，Knowledge Base ACL、用户条件、角色、组成员身份和文章级限制是仅针对集成身份进行评估，还是可以传播并执行最终用户的授权上下文？

在适用的授权契约得到确认和测试之前，不得进行生产使用。

假设与开放问题

可追踪的 Epic、Stories、Tasks、假设和未解决的集成问题维护在 docs/implementation-plan.md 中。重要的未解决事项包括：

1. 支持 query 参数的是哪种搜索/索引/排序能力，它是否与 Knowledge UI 一致？

2. 哪些 Knowledge Base、语言和发布状态在范围内？

3. 当使用集成身份时，如何执行最终用户授权？

4. 哪个标准或自定义字段包含规范文章内容？

5. 哪些字段是受众、有效性、发布、引用和新鲜度所必需的？

6. 适用哪种认证机制、API 版本、速率限制和吞吐量？

7. 哪些非生产环境和具有代表性的检索质量测试夹具可用？