mcp-conf-mcp-server: Instructions file for Claude Code

CLAUDE.md

このファイルは、このリポジトリでコードを扱う際にClaude Code（claude.ai/code）にガイダンスを提供します。

開発コマンド

環境セットアップ

# 仮想環境を作成
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 開発モードでインストール
pip install -e ".[dev]"

テスト実行

# すべてのテストを実行
pytest

# 詳細な出力でテストを実行
pytest -v

# 特定のテストファイルを実行
pytest tests/test_server.py
pytest tests/test_edge_cases.py

# 特定のテストを実行
pytest tests/test_server.py::test_list_servers

# カバレッジ付きでテスト実行
pytest --cov=src --cov-report=html

コード品質チェック

# コードフォーマット
ruff format .

# リント
ruff check .
ruff check . --fix  # 自動修正可能な問題を修正

# 型チェック
mypy src --strict

サーバー実行

# MCPサーバーを起動
mcp-conf-mcp-server

# カスタム設定ファイルパスを指定して起動
MCP_CONFIG_PATH=/path/to/custom/mcp.json mcp-conf-mcp-server

# Windows環境変数での起動
MCP_CONFIG_PATH=%APPDATA%\Claude\claude_desktop_config.json mcp-conf-mcp-server

アーキテクチャ概要

このプロジェクトは、AWS Q DeveloperとClaude DesktopのMCP設定ファイルを管理するMCPサーバーです。

コアアーキテクチャ

設定ファイル (JSON) ← → MCPサーバー (FastMCP) ← → クライアント (AWS Q/Claude Desktop)
     ↓                        ↓
  バックアップ            ツール定義
                      (list/add/update/remove)

重要な設計判断

1. パス展開の多重サポート:

   • os.path.expanduser(): Unix形式のチルダ展開（~）
   • os.path.expandvars(): Windows環境変数展開（%APPDATA%等）
   • 両方を組み合わせることでクロスプラットフォーム対応

2. アトミックなファイル操作:

   # 一時ファイルに書き込んでから置き換え
   temp_path = CONFIG_PATH.with_suffix(".tmp")
   with open(temp_path, "w") as f:
       json.dump(config.model_dump(exclude_none=True), f, indent=2)
   temp_path.replace(CONFIG_PATH)
   

3. エラーハンドリング階層:

   • 設定ファイル不在 → 空の設定を返す（非破壊的）
   • JSONパースエラー → 空の設定を返す（既存設定を保護）
   • バックアップ失敗 → ログ記録して処理継続

ツールの相互作用

• add_server: 重複チェック → 失敗時はupdate_serverを推奨
• update_server: 環境変数のマージ/置換オプション
• remove_server: 削除前に自動バックアップ
• validate_config: 設定の構造的妥当性を検証

重要な実装詳細

環境変数の処理（server.py:27-36）

config_path_env = os.environ.get("MCP_CONFIG_PATH", str(DEFAULT_CONFIG_PATH))
CONFIG_PATH = Path(os.path.expandvars(os.path.expanduser(config_path_env)))