junos-mcp: Instructions file for Claude Code

CLAUDE.md

このファイルはClaude Codeがリポジトリを理解するためのコンテキストを提供します。

プロジェクト概要

junos-mcpは、junos-ops の機能を MCP (Model Context Protocol) サーバーとして公開するパッケージです。Claude Desktop、Claude Code などの MCP 対応 AI アシスタントから Juniper Networks デバイスの操作が可能になります。

• junos-ops: CLI ツール + ライブラリ（人間が直接使う）
• junos-mcp: junos-ops を MCP サーバーとして公開（AI アシスタントが使う）

技術スタック

• 言語: Python 3（3.12以上）
• 主要ライブラリ: MCP Python SDK（MCPServer）、junos-ops（junos-eznc）
• トランスポート: STDIO（デフォルト）または Streamable HTTP（--transport で選択、JSON-RPC）
• パッケージ管理: pyproject.toml（pip installable）
• テスト: pytest + モック
• ライセンス: Apache License 2.0

ファイル構成

junos_mcp/
├── __init__.py         # パッケージ定義、__version__
├── __main__.py         # python -m junos_mcp 対応
├── pool.py             # per-host NETCONF 接続プール（ConnectionPool、get_pool）
└── server.py           # MCPServer サーバー定義、28ツール実装
tests/
├── __init__.py
├── test_pool.py                # 27 ユニットテスト（ConnectionPool）
├── test_server.py              # 128 ユニットテスト
└── test_version_consistency.py # 2 ユニットテスト（バージョン整合性）
pyproject.toml          # パッケージメタデータ、依存関係
LICENSE                 # Apache License 2.0
README.md               # 英語版
README.ja.md            # 日本語版

モジュール構成

pool.py — 接続プール

• ConnectionPool — per-host NETCONF 接続プール。acquire(hostname, config_path) context manager で checkout/checkin。per-host threading.Lock を操作全体で保持し PyEZ Device のスレッドセーフ問題を回避。アイドルタイムアウト超過・dev.connected==False で自動退場・再接続。
• PoolConnectionError — 接続失敗時に acquire() が raise する例外。
• PoolBusyError — acquire(timeout=...) で per-host lock が時間内に空かなかったときに raise する例外。_connect_and_run は push 以外の呼び出しで、JUNOS_DEADLINE の残りを timeout に渡し「host busy」を返す（push の確認と lock 取得の間に push が lock を取っても無期限に待たない）
• get_pool() — モジュールレベルシングルトンを lazy init して返す。JUNOS_MCP_POOL=0 で None を返す（プール無効）。
• 環境変数: JUNOS_MCP_POOL（無効化）・JUNOS_MCP_POOL_IDLE（アイドルタイムアウト秒、デフォルト 60）・JUNOS_MCP_POOL_CONNECT_ATTEMPTS（一過性接続失敗のリトライ回数、デフォルト 2＝1 回リトライ）・JUNOS_MCP_POOL_CONNECT_DELAY（リトライ間隔秒、デフォルト 1.0）
• 接続リトライの不変条件（PR #37）: リトライ対象は _RETRYABLE_CONNECT_ERRORS（ConnectError / ConnectTimeoutError のみ）に限定。ConnectAuthError（認証失敗）は意図的に除外 — 誤った資格情報でリトライするとアカウントロックの恐れがあるため即座に fail-fast する。リトライの sleep は per-host entry.lock を保持したまま実行する（設計どおり — 同一ホストの呼び出しのみをブロックし他ホストは妨げない）