servicenow-docs-mcp

ServiceNowDocs MCP 検索

概要

このスキルでは、公開されている ServiceNow/ServiceNowDocs GitHub リポジトリを使用して、Happy Platform MCP における ServiceNow ドキュメント検索の追加と保守について説明します。

以下をユーザーから依頼された場合に使用してください。

• Happy Platform MCP に ServiceNow ドキュメントの検索機能を追加する
• ServiceNowDocs のコンテンツを同期、キャッシュ、またはローカライズする
• MCP ツールから ServiceNow のドキュメントを検索する
• MCP のドキュメント機能に SQLite FTS5、sqlite-vec、エンベディング、またはベクトル検索を追加する
• 5 つのドキュメントツールのトラブルシューティングを行う
• 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 password の登録には、ローカルで対話形式の happy-platform-mcp instance add を使用してください。直接登録が確実に機能するのは、公開 authorization_code の場合、または管理者が外部で事前にプロビジョニングされた決定的なキーチェーン参照を作成している場合です。認証情報をツール呼び出しに含めるよう、ユーザーやエージェントに決して求めないでください。

手順

ステップ 1：ライブ GitHub 検索をデフォルトにする

デフォルトのドキュメントモードでは、ローカルストレージ、SQLite、エンベディング、QMD は不要にしてください。エージェントは 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	無効なインデックスを報告	DB、同期、ベクトルの状態を報告

ステップ 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 を見出しごとにチャンク分割します。
6. 検索結果には、ファミリー、パス、見出し、GitHub URL などのソースメタデータを含めます。
7. ベクトル検索は追加機能として扱い、FTS を信頼できる基本機能として維持します。
8. 無効、依存関係の欠落、インデックス有効の各状態をテストに含めます。

トラブルシューティング

問題	原因	解決策
ドキュメントツールの起動時にクラッシュする	SQLite が先行して読み込まれている	ローカルインデックスが有効な場合にのみ SQLite を遅延読み込みする
SN-Docs-Search がセットアップ方法を返す	ローカルインデックスが無効	HAPPY_DOCS_ENABLE_LOCAL_INDEX=true を有効にするか、ライブの SN-Docs-Get を使用する
GitHub との同期に失敗する	レート制限またはネットワークの問題	GitHub トークンへの対応を追加するか、後で再試行する
Docker イメージが予想外に大きくなる	同期済みドキュメントまたは DB がイメージにコピーされている	キャッシュのパスをリポジトリの外に保ち、生成ファイルを ignore ルールに追加する
埋め込みの呼び出しが予期せず発生する	ベクトルプロバイダーがデフォルトで有効になっている	プロバイダーのデフォルトを none にし、明示的なオプトインを必須にする

関連するスキル

• development/mcp-server - MCP サーバーの一般的な設計
• development/mcp-server-installation - Happy Platform MCP のインストール
• genai/ai-search-rag - ServiceNow AI Search と RAG の設定
• development/debugging-techniques - ServiceNow と統合に関する問題のトラブルシューティング