🔌 Itential - MCP Server

🔌 Itential - MCP サーバー

LLM を Itential Platform に接続するための包括的なツールを提供する Model Context Protocol (MCP) サーバーです。AI アシスタントによるネットワーク自動化の管理、ワークフローのオーケストレーション、プラットフォームの健全性の監視、高度なネットワーク操作を可能にします。

🎯 対象ユーザー

プラットフォームエンジニア

AI を活用した自動化を通じて、インフラストラクチャの管理、システムの健全性の監視、デバイスの設定、ネットワーク操作のオーケストレーションを行います。

開発者

自動化ワークフローの構築、外部システムとの連携、アプリケーションライフサイクルの管理、プラットフォーム機能の拡張を行います。

📒 主な機能

コア機能

• 79 個の自動化ツール（デフォルトで 78 個が有効。実験的なツール 1 個はオプトイン）：ネットワーク自動化のあらゆるニーズに対応する、13 のタグカテゴリーにわたる包括的なツールキット
• 高度なツール選択：柔軟なタグ付けシステムを使用して、利用可能なツールをフィルタリングおよび制御
• 複数のトランスポート方式：stdio および HTTP（Streamable HTTP、推奨）トランスポートに対応し、オプションで TLS 暗号化を利用可能。レガシーの SSE トランスポートも利用できますが、非推奨です
• 動的なツール検出：コードを変更せずにツールを自動検出して登録
• 柔軟な認証：Itential Platform の基本認証、OAuth 2.0、JWT、ロールベースアクセスに対応
• 包括的な設定：CLI パラメーター、環境変数、または設定ファイルを使用
• ロールベースアクセス：プラットフォーム管理者、ネットワークエンジニア、開発者向けにカスタマイズされたツール設定

ネットワーク自動化とデバイス管理

• デバイス設定：設定の適用、デバイス設定のバックアップ、現在の設定の取得
• コマンド実行：ルール検証を行いながら、複数のデバイスで単一のコマンドまたはコマンドテンプレートを実行
• デバイスグループ：効率的な運用のために論理デバイスコレクションを作成および管理
• コンプライアンス管理：コンプライアンス計画の自動実行と詳細なレポート作成
• ゴールデン設定：バージョン管理を備えた階層型テンプレートベースの設定管理

ワークフローとオーケストレーション

• ワークフロー実行：API エンドポイント経由でワークフローを開始し、実行状況を監視
• ジョブ管理：包括的なステータス、メトリクス、タスク詳細を使ってワークフロージョブを追跡
• ワークフローの公開：ワークフローを外部から利用できる REST API エンドポイントに変換
• テンプレート管理：Jinja2 および TextFSM テンプレートを作成、更新、実行
• パフォーマンスメトリクス：ワークフロー最適化のためのジョブおよびタスク実行の詳細なメトリクス

プラットフォーム運用と監視

• 健全性監視：システムリソース、アプリケーション、アダプターを含むプラットフォームの健全性をリアルタイムで監視
• コンポーネントのライフサイクル：ステータスを監視しながら、アプリケーションとアダプターを起動、停止、再起動
• 統合管理：OpenAPI ベースの統合モデルを作成および管理
• ゲートウェイサービス：Gateway Manager を通じて外部サービス（Ansible、Python スクリプト、OpenTofu）を実行

ライフサイクルとリソース管理

• リソースモデル：ライフサイクルワークフローを備えた、JSON Schema ベースのリソース構造を定義します
• インスタンス管理：状態追跡機能を備えた、リソースインスタンスの完全な CRUD 操作を行います
• アクション実行：包括的な実行履歴とともに、ライフサイクルアクションを実行します
• データ検証：リソースデータとアクションパラメーターを、スキーマに基づいて検証します

🔍 要件

• Python 3.10 以降
• Itential Platform Instance へのアクセス
• 開発用 - uv と make

テスト済み Python バージョン

このプロジェクトは、以下の Python バージョンに対して自動的にテストされます：

• Python 3.10
• Python 3.11
• Python 3.12
• Python 3.13

🔧 インストール

itential-mcp アプリケーションは、PyPI を使用してインストールするか、ソースから直接実行できます。

PyPI からのインストール

PyPI からインストールするには、pip を使用します：

pip install itential-mcp

ローカル開発

リポジトリをローカル環境にクローンして、MCP サーバーを操作することもできます。このプロジェクトでは uv と make を使用するため、両方のツールをインストールし、環境内で使用できるようにする必要があります。

以下のコマンドで開始できます。

git clone https://github.com/itential/itential-mcp
cd itential-mcp
make build

開発時は、uv を使用してサーバーを直接実行できます：

# Run with stdio transport (default)
uv run itential-mcp run

# Run with HTTP transport (Streamable HTTP, recommended for web integration)
uv run itential-mcp run --transport http --host 0.0.0.0 --port 8000

# Run with specific configuration
uv run itential-mcp run --include-tags "health,configuration_manager" --exclude-tags "experimental"

コンテナーの使用

GitHub Container Registry からプル

最新リリースをプルして実行します：

# Pull the latest image
docker pull ghcr.io/itential/itential-mcp:latest

# Run with HTTP transport (Streamable HTTP, recommended)
docker run -p 8000:8000 \
  --env ITENTIAL_MCP_SERVER_TRANSPORT=http \
  --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
  --env ITENTIAL_MCP_SERVER_PORT=8000 \
  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
  --env ITENTIAL_MCP_PLATFORM_USER=your-username \
  --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \
  ghcr.io/itential/itential-mcp:latest

# Or with OAuth authentication
docker run -p 8000:8000 \
  --env ITENTIAL_MCP_SERVER_TRANSPORT=http \
  --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
  --env ITENTIAL_MCP_SERVER_PORT=8000 \
  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
  --env ITENTIAL_MCP_PLATFORM_CLIENT_ID=CLIENT_ID \
  --env ITENTIAL_MCP_PLATFORM_CLIENT_SECRET=CLIENT_SECRET \
  ghcr.io/itential/itential-mcp:latest

# Run with stdio transport (for MCP clients)
docker run -i \
  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
  --env ITENTIAL_MCP_PLATFORM_USER=your-username \
  --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \
  ghcr.io/itential/itential-mcp:latest

コンテナーイメージをローカルでビルド

ソースからビルドして実行します：

# Build the container image
make container

# Run the locally built container
docker run -p 8000:8000 \
  --env ITENTIAL_MCP_SERVER_TRANSPORT=http \
  --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
  --env ITENTIAL_MCP_SERVER_PORT=8000 \
  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
  --env ITENTIAL_MCP_PLATFORM_USER=your-username \
  --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \
  itential-mcp:devel

🚀 クイックスタート

1. サーバーをインストール

pip install itential-mcp

2. プラットフォーム接続を設定

Itential Platform の認証情報を設定します：

export ITENTIAL_MCP_PLATFORM_HOST="your-platform.example.com"
export ITENTIAL_MCP_PLATFORM_USER="your-username"
export ITENTIAL_MCP_PLATFORM_PASSWORD="your-password"

3. サーバーを起動

# Basic stdio transport (default)
itential-mcp run

# Or with HTTP transport (Streamable HTTP, recommended for web clients)
itential-mcp run --transport http --host 0.0.0.0 --port 8000

4. MCP クライアントを設定

統合ガイドに従って、Claude、Continue.dev、その他の MCP クライアントを接続します。

📝 基本的な使い方

デフォルト設定（stdio トランスポート）で MCP サーバーを起動します：

itential-mcp run

HTTP トランスポート（Streamable HTTP、ウェブ連携に推奨）で起動します：

itential-mcp run --transport http --host 0.0.0.0 --port 8000

SSE トランスポート（非推奨 - レガシーの HTTP+SSE。http を推奨）で起動します：

itential-mcp run --transport sse --host 0.0.0.0 --port 8000

一般的なオプション

グローバルオプションは、コマンド名の前後どちらにも指定できます。

オプション	説明	デフォルト
--config	設定ファイルへのパス	なし

例：

# Both of these work identically:
itential-mcp --config config.conf run
itential-mcp run --config config.conf

サーバーオプション

オプション	説明	デフォルト
--transport	トランスポートプロトコル（stdio、sse、http。sse は非推奨のため、http を推奨）	stdio
--host	リッスンするホストアドレス	127.0.0.1
--port	リッスンするポート	8000
--path	使用する HTTP パス	/mcp
--log-level	ログレベル（DEBUG、INFO、WARNING、ERROR、CRITICAL、NONE）	NONE
--include-tags	登録済みツールに含めるタグ	なし
--exclude-tags	登録済みツールから除外するタグ	experimental,beta

プラットフォーム設定

オプション	説明	デフォルト
--platform-host	Itential Platform のホスト名	localhost
--platform-port	Platform のポート（0 = 自動検出）	0
--platform-disable-tls	Platform 接続の TLS を無効にします	false
--platform-disable-verify	証明書の検証を無効にします	false
--platform-timeout	接続タイムアウト	30
--platform-user	認証用のユーザー名	admin
--platform-password	認証用のパスワード	admin
--platform-client-id	OAuth クライアント ID	none
--platform-client-secret	OAuth クライアントシークレット	none

環境変数

すべてのコマンドラインオプションは、ITENTIAL_MCP_SERVER_ をプレフィックスとする環境変数でも設定できます。例：

export ITENTIAL_MCP_SERVER_TRANSPORT=http
export ITENTIAL_MCP_PLATFORM_HOST=platform.example.com
itential-mcp run  # Will use the environment variables

セキュリティに関する考慮事項

⚠️ 重要なセキュリティに関する注意：

MCP サーバーは環境変数から設定を読み取るため、信頼できる環境で実行する必要があります。共有環境またはマルチテナント環境では、以下を確認してください。

1. 環境の分離：ユーザーが任意の環境変数を設定できない、分離されたコンテナまたは専用環境でサーバーを実行します
2. アクセス制御：承認された管理者のみが ITENTIAL_MCP_* 環境変数を設定できるようにします
3. 動的なツール設定：ITENTIAL_MCP_TOOL_* というパターンの環境変数を使って、カスタムツールのバインディングを定義できます。これは強力な機能ですが、信頼境界の設定が必要です
4. 認証情報の管理：共有環境で認証情報を公開しないでください。シークレット管理システム（Kubernetes Secrets、HashiCorp Vault など）を使用してください

推奨されるデプロイ方法：

• コンテナ化（Docker、Kubernetes）を使用して環境変数を分離します
• 最小権限のアクセス制御を実装します
• 認証情報を定期的にローテーションします
• 本番環境では TLS と証明書検証を有効にします
• HTTP/SSE トランスポートでは認証（JWT、OAuth）を使用します

本番環境へのデプロイについては、セキュリティのベストプラクティスガイドを参照してください。

設定ファイル

サーバー設定は、設定ファイルを使って指定することもできます。設定ファイルを使用すると、すべての設定パラメーターを渡すことができます。設定ファイルを使用するには、--config <path> コマンドライン引数を渡します。<path> は読み込む設定ファイルを指定します。

設定ファイルの形式と値については、こちらに記載されています。

設定オプションを複数の場所で指定した場合、使用する値は次の優先順位（高い順）に従って決定されます。

1. 環境変数
2. コマンドラインオプション
3. 設定ファイル
4. デフォルト値

🎛️ ツールの選択とタグ付け

Itential MCP サーバーは、包括的なタグ付けシステムを通じて強力なツールのフィルタリング機能を提供します。これにより、特定のニーズやセキュリティ要件に応じて、利用可能なツールをカスタマイズできます。

タグベースのフィルタリング

包含タグと除外タグを使って、利用可能なツールを制御します。

# Include only health and device management tools  
itential-mcp run --include-tags "health,configuration_manager"

# Exclude experimental and beta tools (default behavior)
itential-mcp run --exclude-tags "experimental,beta,lifecycle_manager"

利用可能なタググループ

タググループ	ツール数	説明	ユースケース
health	1	プラットフォームのヘルス状態と監視	プラットフォーム管理者
configuration_manager	16	デバイス、コンプライアンス、設定の管理	ネットワークエンジニア
operations_manager	9	自動化、ワークフロー、ジョブの管理	自動化開発者
automation_studio	12	コマンドテンプレート、プロジェクト、テンプレート	ネットワークオペレーター
lifecycle_manager	7	リソースのライフサイクルとインスタンスの管理	プロダクトマネージャー
work_center	2（うち1つは実験的）	手動タスク（作業項目）の確認と実験的な完了	自動化オペレーター
workflow_engine	6	ワークフロー実行のメトリクス	パフォーマンスアナリスト
adapters	4	アダプターのライフサイクル管理	インテグレーションスペシャリスト
applications	4	アプリケーションのライフサイクル管理	アプリケーション所有者
gateway_manager	5	外部サービスの管理	システムインテグレーター
integrations	3	外部システムとのインテグレーション	API 開発者
agent_session_manager	5	エージェントセッションとトークンの使用状況	AI／エージェントオペレーター
inventory_manager	5	インベントリ管理	ネットワークエンジニア

役割ベースの設定

以下の役割ベースの設定では、特定の職務と責任に応じて、利用できるツールを調整します。

プラットフォーム管理者： システムのヘルス状態の監視、コンポーネントの管理、プラットフォームの運用

itential-mcp run --include-tags "health,adapters,applications,integrations"

主なツール：プラットフォームのヘルス状態の監視、アダプター／アプリケーションのライフサイクル管理、インテグレーション管理

ネットワークエンジニア： デバイス管理、設定、コンプライアンス、ネットワーク自動化

itential-mcp run --include-tags "configuration_manager,automation_studio"

主なツール：デバイス設定、コンプライアンス計画、コマンドテンプレート、ゴールデン設定管理

自動化開発者： ワークフローの構築、パフォーマンス分析、プラットフォームの拡張

itential-mcp run --include-tags "operations_manager,workflow_engine,lifecycle_manager,gateway_manager"

主なツール：ワークフロー実行、パフォーマンスメトリクス、リソースのライフサイクル管理、外部サービスとのインテグレーション

プラットフォームオペレーター： 日常業務、ジョブの監視、レポートの生成

itential-mcp run --include-tags "operations_manager,configuration_manager"

主なツール：ワークフロー実行、ジョブの監視、デバイス操作、コンプライアンスレポート

📚 ドキュメントとインテグレーション

ツールの完全なリファレンス

利用可能なツールの全一覧と詳細なタグの関連付けは、ツールドキュメントを参照してください。

設定とセキュリティ

• MCP クライアントのインテグレーション - Claude、Continue.dev、その他の MCP クライアントを設定します
• TLS の設定 - 証明書を使用して安全な HTTPS 接続を有効にします
• JWT 認証 - JWT トークン認証を設定します
• OAuth 認証 - 複数のプロバイダーを使用する OAuth 2.0
• 設定例 - 設定ファイルの完全なリファレンス
• ステータスエンドポイント - 本番環境へのデプロイにおけるヘルス状態の監視

高度な機能

• タグ付けシステム - 高度なツールのフィルタリングと選択方法
• ワークフローの実行 - Itential ワークフローの実行と監視
• カスタムツールの開発 - カスタム MCP ツールの作成と統合

プロンプトの例

• Claude Desktop のプロンプト - Claude とのインテグレーションに最適化されたプロンプト
• GPT インテグレーションのプロンプト - GPT とのインテグレーションに最適化されたプロンプト

🛠️ 新しいツールの追加

新しいツールの追加は簡単です。

1. src/itential_mcp/tools/ ディレクトリに新しい Python ファイルを作成するか、既存のファイルに関数を追加します
2. Context パラメーターの型注釈を持つ非同期関数を定義します。

from fastmcp import Context

async def my_new_tool(ctx: Context) -> dict:
    """
    Description of what the tool does

    Args:
        ctx (Context): The FastMCP Context object

    Returns:
        dict: The response data

    Raises:
        None
    """
    # Get the platform client
    client = ctx.request_context.lifespan_context.get("client")

    # Make API requests
    res = await client.get("/your/api/path")

    # Return JSON-serializable results
    return res.json()

サーバーの起動時に、ツールは自動的に検出され、登録されます。

テストの実行

次のコマンドでテストスイートを実行します。

make test

テストカバレッジを確認するには、次を実行します。

make coverage

コントリビューション

コントリビューションを歓迎します！コントリビューションの前に、行動規範をお読みください。

1. リポジトリをフォークします
2. 機能ブランチを作成します：git checkout -b feature/my-feature
3. 変更をコミットします：git commit -am 'Add new feature'
4. ブランチにプッシュします：git push origin feature/my-feature
5. プルリクエストを送信します

送信する前に：

• make premergeを実行して、テストが合格し、コードスタイルが正しいことを確認します
• 新機能のドキュメントを追加します
• 新しい機能のテストを追加します

ライセンス

このプロジェクトはGNU General Public License v3.0の下でライセンスされています。詳細はLICENSEファイルをご覧ください。

Copyright (c) 2025 Itential, Inc