happy-technologies-llc/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 SN-Docs-* 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 version supported by the MCP server
• 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

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