ServiceNow Knowledge MCP

ServiceNow Knowledge取得のための、決定論的で読み取り専用のFastMCP統合です。回答生成、要約、セマンティック再ランキング、ベクトル検索、ドキュメント解析は一切行いません。

アーキテクチャ

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 は、構造化されたMCP出力がJSON互換であるため、上限付きのバイナリデータをbase64として返します。呼び出し側はこれをデコードする必要があり、解析や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

デフォルトのネットワークトランスポートは、http://localhost:8080/mcp でのステートレスなStreamable HTTPです。ローカルで起動する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 は統合IDトークンを提供します。検索および記事のフィールド選択は SERVICENOW_SEARCH_FIELDS と SERVICENOW_ARTICLE_FIELDS に一元化されており、検証済みの標準フィールドまたはカスタムフィールドをクライアントを変更せずに採用できます。

デフォルトのAPIパスとクエリパラメータ名は実装上の仮定であり、選択したServiceNow Knowledge Management APIバージョンに対して確認する必要があります。検索は、設定済みまたはツールごとのKnowledge Baseと言語の値でスコープを絞り込めます。要求される結果数上限、記事コンテンツの長さ、添付ファイルのバイト数、タイムアウト、一時的リトライには上限があります。

認可境界

統合ID自体は、エンドユーザーのKnowledge権限が適用されることを保証するものではありません。認証器は内部の認可コンテキストを受け入れるため、クライアントを再設計せずに確認済みの委任メカニズムを追加できますが、MCPツールは現在、委任された認証情報を生成したり受け入れたりしません。

未解決のセキュリティ上の質問: MCPが統合IDを使用してServiceNowを呼び出す場合、Knowledge BaseのACL、User Criteria、ロール、グループメンバーシップ、記事レベルの制限は統合IDに対してのみ評価されるのでしょうか、それともエンドユーザーの認可コンテキストを伝播して適用できるのでしょうか?

該当するエンタイトルメント契約が確認されテストされるまで、本番環境での使用を進めてはなりません。

前提条件と未解決の質問

追跡可能なEpic、Stories、Tasks、前提条件、未解決の統合に関する質問は docs/implementation-plan.md に管理されています。重要な未解決項目は次のとおりです:

1. query パラメータを支える検索/インデックス/ランキング機能は何か、またKnowledge UIと一致するか?

2. 対象範囲のKnowledge Base、言語、公開状態はどれか?

3. 統合IDを使用する場合、エンドユーザーの認可はどのように適用されるか?

4. 正規の記事コンテンツを含む標準またはカスタムフィールドはどれか?

5. 対象読者、有効性、公開、引用、鮮度に必要なフィールドはどれか?

6. 適用される認証メカニズム、APIバージョン、レート制限、スループットは何か?

7. 利用可能な非本番環境と代表的な取得品質のフィクスチャはどれか?