servicenow-docs-mcp

ServiceNowDocs MCP 搜索

概述

本技能介绍如何在 Happy Platform MCP 中，使用公开的 ServiceNow/ServiceNowDocs GitHub 仓库添加和维护 ServiceNow 文档搜索。

适用于用户要求：

• 在 Happy Platform MCP 中添加 ServiceNow 文档查找功能
• 同步、缓存或本地化 ServiceNowDocs 内容
• 通过 MCP 工具搜索 ServiceNow 文档
• 为 MCP 文档功能添加 SQLite FTS5、sqlite-vec、嵌入或向量搜索
• 排查五个文档工具的问题
• 为 ServiceNow 文档选择 QMD、GitHub 搜索、SQLite FTS 或向量索引

如需安装 MCP 服务本身，请使用 development/mcp-server-installation。如需了解 MCP 服务的常规设计，请使用 development/mcp-server。

前置条件

• Happy Platform MCP 源码检出
• Node.js >= 20
• 实时模式或同步时可访问网络 https://github.com/ServiceNow/ServiceNowDocs
• 仅在启用本地索引时才需要可选的 better-sqlite3 支持
• 仅在启用向量搜索时才需要可选的嵌入提供方

v5.1 仅文档引导模式

当不存在注册表/配置，也没有旧版环境凭据时，stdio 服务会自动回退到仅文档模式。可通过 HAPPY_MCP_DOCS_ONLY=true 强制启用此模式。v5.1 的 --docs-only 标志无法可靠地覆盖已存在的注册表，因此不得用于此工作流。

仅文档模式会提供 SN-Docs-Families、SN-Docs-Status、SN-Docs-Sync、 SN-Docs-Search 和 SN-Docs-Get，以及 SN-Register-Instance。 SN-Register-Instance 仅用于元数据，不接受密钥字段。成功注册后，正常的实时服务会重新加载注册表；若要使用实时 ServiceNow 工具，请先重启仅文档模式进程。

凭据引导存在 v5.1 顺序限制：注册时需要凭据引用，但本地凭据集命令要求实例名称已存在。对于 Basic、OAuth client_credentials 和 OAuth 密码注册，请使用本地交互式 happy-platform-mcp instance add。直接注册适用于公开的 authorization_code，或管理员已创建外部预置的确定性钥匙串引用的情况。切勿要求用户或 Agent 在工具调用中提供凭据材料。

操作步骤

第 1 步：默认使用实时 GitHub 查找

默认文档模式不应依赖本地存储、SQLite、嵌入或 QMD。Agent 应能使用 SN-Docs-Families 和 SN-Docs-Get 列出文档系列并直接从 GitHub 获取原始文档。

默认行为：

localIndexEnabled: false
enableVector: false
embeddingProvider: none

以下情况使用实时 GitHub 访问：

• 首次运行体验
• 通过 npx happy-platform-mcp 进行轻量级安装
• 没有持久化卷的 Docker 镜像
• 仅需精确检索文档的用户

第 2 步：将本地 SQLite FTS 设为可选功能

使用 SQLite FTS5 实现离线或更快的文本搜索，但绝不能将 SQLite 设为启动必需项。

实现规则：

• 将 better-sqlite3 等 SQLite 软件包放入可选依赖项。
• 从文档存储模块延迟加载 SQLite。
• 若 SQLite 不可用且未启用本地索引，启动仍必须成功。
• 若用户请求本地索引但 SQLite 不可用，文档工具必须返回清晰的设置说明。
• 将本地索引文件存储在可配置的缓存目录中，默认不要存放在代码仓库内。

推荐配置格式：

{
  "docs": {
    "localIndexEnabled": false,
    "cacheDir": "~/.happy-platform-mcp/docs/servicenow",
    "enableVector": false,
    "embeddingProvider": "none"
  }
}

推荐环境变量：

HAPPY_DOCS_ENABLE_LOCAL_INDEX=false
HAPPY_DOCS_CACHE_DIR=
HAPPY_DOCS_ENABLE_VECTOR=false
HAPPY_DOCS_EMBEDDING_PROVIDER=none

第 3 步：将向量搜索设为需提供方支持的功能

向量搜索适用于语义查找，但应设为可选功能，并且必须由提供方支持。

使用以下模式：

• 默认将 enableVector 设为 false。
• 未配置提供方时，支持无操作向量适配器。
• 生成嵌入前，必须明确配置嵌入提供方和凭据。
• 不使用嵌入时，FTS 搜索仍须可用。
• 避免在默认安装中静默调用托管嵌入 API。

第 4 步：避免在产品运行时使用 QMD

QMD 可用于个人试验或离线训练工作流，但不应成为 Happy Platform MCP 的必需组件。

建议使用：

• GitHub API 或 GitHub 原始内容进行实时读取
• SQLite FTS5 进行可选的本地关键词搜索
• sqlite-vec 或兼容的向量适配器进行可选的语义搜索
• 按 Markdown 章节和标题进行简单分块

不要在产品启动、Docker 镜像或 npm install 中添加必需的 QMD 依赖。

第 5 步：以优雅降级的方式公开 MCP 工具

文档工具应报告能力状态，而不是莫名其妙地失败。

预期的工具行为：

工具	本地索引已禁用	本地索引已启用
SN-Docs-Families	从 GitHub 列出文档系列	从 GitHub 或缓存列出文档系列
SN-Docs-Get	从 GitHub 获取原始文档	从 GitHub 或缓存获取原始文档
SN-Docs-Search	返回设置提示	搜索 SQLite FTS 索引
SN-Docs-Sync	返回设置提示	将 GitHub 文档同步到 SQLite
SN-Docs-Status	报告索引已禁用	报告数据库、同步和向量状态

第 6 步：验证可选性

发布前，请验证在线和近似离线路径：

npm test
docker build .

还要通过临时从 node_modules 中移除或隐藏 better-sqlite3，执行无 SQLite 冒烟测试，并确认：

• MCP 服务仍可成功启动
• SN-Docs-Families 可正常工作
• SN-Docs-Get 可正常工作
• SN-Docs-Status 能准确报告 SQLite 的可用性
• SN-Docs-Search 会返回启用本地索引的提示，而不是崩溃

工具用法

工具	用途	使用时机
SN-Docs-Families	列出可用的 ServiceNow 文档系列	发现并选择文档分支或系列
SN-Docs-Get	获取指定的文档 Markdown 文件	直接引用或检查
SN-Docs-Search	搜索本地 FTS 文档分块	离线搜索或更快的文本搜索
SN-Docs-Sync	构建或刷新本地文档索引	用户明确启用本地文档时
SN-Docs-Status	检查文档配置和能力状态	排查设置问题

最佳实践

1. 首次运行时，让 MCP 体验保持实时且轻量。
2. 将离线/本地文档作为明确的用户选项。
3. 将 MCP 运行时属性放在本地环境变量/配置中，而不是 ServiceNow sys_properties 中。
4. 不要提交生成的 SQLite 数据库或同步的文档缓存。
5. 按标题对 Markdown 分块，让搜索结果将 Agent 引导至有用的章节。
6. 在搜索结果中返回来源元数据，例如系列、路径、标题和 GitHub URL。
7. 将向量搜索作为增补功能；FTS 应继续作为可靠的基础方案。
8. 为索引禁用、缺少依赖和索引启用等状态添加测试。

故障排查

问题	原因	解决方法
文档工具在启动时崩溃	提前加载了 SQLite	仅在启用本地索引时延迟加载 SQLite
SN-Docs-Search 返回设置提示	本地索引已禁用	启用 HAPPY_DOCS_ENABLE_LOCAL_INDEX=true，或使用实时 SN-Docs-Get
与 GitHub 同步失败	触发速率限制或网络问题	添加 GitHub 令牌支持，或稍后重试
Docker 镜像意外变大	将同步的文档或数据库复制到了镜像中	将缓存路径放在仓库外，并将生成文件添加到忽略规则中
意外发起嵌入调用	默认启用了向量提供方	将提供方默认设为 none，并要求明确选择启用

相关技能

• development/mcp-server - MCP 服务的通用设计
• development/mcp-server-installation - Happy Platform MCP 安装
• genai/ai-search-rag - ServiceNow AI Search 和 RAG 配置
• development/debugging-techniques - 排查 ServiceNow 和集成问题