servicenow-docs-mcp

ServiceNowDocs MCP Search

Overview

This skill covers adding and maintaining ServiceNow documentation search in Happy Platform MCP using the public ServiceNow/ServiceNowDocs GitHub repository.

Use it when a user asks to:

• Add ServiceNow documentation lookup to Happy Platform MCP
• Sync, cache, or localize ServiceNowDocs content
• Search ServiceNow docs from MCP tools
• Add SQLite FTS5, sqlite-vec, embeddings, or vector search to the MCP docs capability
• Troubleshoot the five documentation tools
• Decide between QMD, GitHub search, SQLite FTS, or vector indexing for ServiceNow docs

For installing the MCP server itself, use development/mcp-server-installation. For general MCP server design, use development/mcp-server.

Prerequisites

• Happy Platform MCP source checkout
• Node.js >= 20
• Network access to https://github.com/ServiceNow/ServiceNowDocs for live mode or sync
• Optional better-sqlite3 support only when local indexing is enabled
• Optional embedding provider only when vector search is enabled

v5.1 Docs-Only Bootstrap

When no registry/config and no legacy environment credentials are present, the stdio server automatically falls back to docs-only mode. Force this mode with HAPPY_MCP_DOCS_ONLY=true. The v5.1 --docs-only flag does not reliably override a registry that already exists and must not be used for this workflow.

Docs-only mode exposes SN-Docs-Families, SN-Docs-Status, SN-Docs-Sync, SN-Docs-Search, and SN-Docs-Get, plus SN-Register-Instance. SN-Register-Instance is metadata-only and rejects secret fields. A normal live server reloads the registry after a successful registration; restart a docs-only process before expecting live ServiceNow tools.

Credential-backed bootstrap has a v5.1 ordering constraint: registration expects a credential reference, but the local credential-set command expects the instance name to exist. Use local interactive happy-platform-mcp instance add for Basic, OAuth client_credentials, and OAuth password registrations. Direct registration is reliable for public authorization_code, or when an administrator has created externally preprovisioned deterministic keychain refs. Never ask a user or agent to put credential material in the tool call.

Procedure

Step 1: Keep Live GitHub Lookup as the Default

The default docs mode should not require local storage, SQLite, embeddings, or QMD. Agents should be able to list docs families and fetch raw docs directly from GitHub using SN-Docs-Families and SN-Docs-Get.

Default behavior:

localIndexEnabled: false
enableVector: false
embeddingProvider: none

Use live GitHub access for:

• First-run experience
• Lightweight installs through npx happy-platform-mcp
• Docker images without persistent volumes
• Users who only need exact document retrieval

Step 2: Make Local SQLite FTS Optional

Use SQLite FTS5 for offline or faster text search, but never make SQLite a startup requirement.

Implementation rules:

• Put SQLite packages such as better-sqlite3 in optional dependencies.
• Load SQLite lazily from the docs store module.
• If SQLite is unavailable and local indexing is disabled, startup must still succeed.
• If local indexing is requested and SQLite is unavailable, return a clear setup message from the docs tools.
• Store local index files in a configurable cache directory, not inside the repo by default.

Recommended config shape:

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

Recommended environment variables:

HAPPY_DOCS_ENABLE_LOCAL_INDEX=false
HAPPY_DOCS_CACHE_DIR=
HAPPY_DOCS_ENABLE_VECTOR=false
HAPPY_DOCS_EMBEDDING_PROVIDER=none

Step 3: Treat Vector Search as Provider-Gated

Vector search is useful for semantic lookup, but it should be opt-in and provider-gated.

Use this pattern:

• Keep enableVector false by default.
• Support a no-op vector adapter when no provider is configured.
• Require an explicit embedding provider and credentials before generating embeddings.
• Keep FTS search usable without embeddings.
• Avoid silently calling hosted embedding APIs from a default install.

Step 4: Avoid QMD in Product Runtime

QMD can be useful for personal experimentation or offline training workflows, but it should not be required by Happy Platform MCP.

Prefer:

• GitHub API or raw GitHub content for live reads
• SQLite FTS5 for optional local keyword search
• sqlite-vec or a compatible vector adapter for optional semantic search
• Simple chunking for markdown sections and headings

Do not add a mandatory QMD dependency to product startup, Docker images, or npm install.

Step 5: Expose MCP Tools with Graceful Degradation

Docs tools should report capability state instead of failing mysteriously.

Expected tool behavior:

Tool	Local Index Disabled	Local Index Enabled
SN-Docs-Families	List families from GitHub	List families from GitHub or cache
SN-Docs-Get	Fetch raw doc from GitHub	Fetch raw doc from GitHub or cache
SN-Docs-Search	Return setup hint	Search SQLite FTS index
SN-Docs-Sync	Return setup hint	Sync GitHub docs into SQLite
SN-Docs-Status	Report disabled index	Report DB, sync, and vector status

Step 6: Verify Optionality

Before shipping, verify both online and offline-adjacent paths:

npm test
docker build .

Also run a no-SQLite smoke check by temporarily removing or hiding better-sqlite3 from node_modules and confirming that:

• MCP server startup still succeeds
• SN-Docs-Families works
• SN-Docs-Get works
• SN-Docs-Status reports SQLite availability accurately
• SN-Docs-Search returns an enable-local-index hint instead of crashing

Tool Usage

Tool	Purpose	When to Use
SN-Docs-Families	List available ServiceNow docs families	Discovery and choosing a docs branch/family
SN-Docs-Get	Fetch a specific docs markdown file	Direct citation or inspection
SN-Docs-Search	Search local FTS docs chunks	Offline or faster text search
SN-Docs-Sync	Build or refresh the local docs index	User explicitly enables local docs
SN-Docs-Status	Inspect docs config and capability state	Troubleshooting setup

Best Practices

1. Keep the first-run MCP experience live and lightweight.
2. Make offline/local docs an explicit user choice.
3. Put MCP runtime properties in local env/config, not ServiceNow sys_properties.
4. Do not commit generated SQLite databases or synced docs caches.
5. Chunk markdown by headings so search results point agents toward useful sections.
6. Return source metadata such as family, path, heading, and GitHub URL with search results.
7. Keep vector search additive; FTS should remain the dependable baseline.
8. Include tests for disabled, missing-dependency, and enabled-index states.

Troubleshooting

Issue	Cause	Resolution
Docs tools crash on startup	SQLite loaded eagerly	Lazy-load SQLite only when local index is enabled
SN-Docs-Search returns setup hint	Local index is disabled	Enable HAPPY_DOCS_ENABLE_LOCAL_INDEX=true or use live SN-Docs-Get
Sync fails against GitHub	Rate limit or network issue	Add GitHub token support or retry later
Docker image grows unexpectedly	Synced docs or DB copied into image	Keep cache paths outside repo and add generated files to ignore rules
Embedding calls happen unexpectedly	Vector provider enabled by default	Default provider to none and require explicit opt-in

Related Skills

• development/mcp-server - General MCP server design
• development/mcp-server-installation - Happy Platform MCP installation
• genai/ai-search-rag - ServiceNow AI Search and RAG configuration
• development/debugging-techniques - Troubleshooting ServiceNow and integration issues