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（FastMCP）、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           # FastMCP サーバー定義、24ツール実装
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 する例外。
• 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 を保持したまま実行する（設計どおり — 同一ホストの呼び出しのみをブロックし他ホストは妨げない）