English | 日本語

開発ガイド¶

システムの責務¶

Octopus MCP Proxy は、管理画面・REST API・MCP エンドポイントを1つの Flask アプリファクトリから提供します。MCP リクエストはサービス定義、Capability、接続アカウント、権限設定を参照して中継され、接続ログと監査ログに記録されます。

パス	責務
`app/__init__.py`	アプリファクトリ、拡張機能初期化、Blueprint 登録、`/health`
`app/config/`	環境変数を含む設定クラス
`app/controllers/`	HTTP ルート、認証、API、MCP リクエストの入口
`app/models/`	SQLAlchemy モデルと DB 拡張
`app/services/`	MCP 中継、権限、ログ、テンプレート同期、変数展開
`app/views/templates/`	Jinja2 の HTML テンプレート
`app/assets/`	CSS、JavaScript、画像などの静的ファイル
`db/migrations/`	Alembic マイグレーション
`db/seeds/`	初期管理者・設定・組み込みテンプレートの投入
`data/builtin_templates/`	組み込み MCP テンプレートの YAML 定義
`tests/unit/`	機能単位のテスト
`tests/integration/`	複数コンポーネントをまたぐテスト
`tests/e2e/`	Playwright によるブラウザテスト
`scripts/`	開発補助スクリプト。スクリーンショット生成など

詳細なファイル一覧はディレクトリ構造を参照してください。

app/controllers/mcp_controller.py はプロトコル入口とルーティングに留める。
中継・Capability 解決・変数置換・権限判定は既存のサービス層を優先して変更する。
tools/list、tools/call、Prompt、Resource、stdio、Streamable HTTP、旧仕様クライアントの互換性を意識する。
エラー時の JSON-RPC エラー、HTTP ステータス、接続ログの内容を既存テストで確認する。

# 開発用 DB に対するマイグレーション生成例
flask db migrate -m "describe schema change"
flask db upgrade

生成されたマイグレーションを必ず読み、既存データへの影響、NULL/デフォルト値、ロールバック可能性を確認します。db/migrate.py と既存のマイグレーション運用も確認してください。

主な設定は app/config/config.py にあります。

Docker Compose では web がマイグレーションを実行し、mcp は MCP エンドポイントを提供します。Redis は複数レプリカ間の Streamable HTTP セッション共有に使用します。構成の詳細はスケーリング・コンテナ構成を参照してください。

./run_check.sh

このスクリプトは Ruff lint、Ruff format check、mypy を実行します。設定は pyproject.toml にあります。

pytest tests/unit/path/to/test_file.py -q
pytest tests/integration/ -q
pytest tests/e2e/ -v
./run_tests.sh

E2E テストやスクリーンショット生成には Playwright のブラウザが必要です。

./setup_playwright.sh
python -m playwright install chromium

画面変更後は次のコマンドでドキュメント用画像を更新します。

python scripts/capture_screenshots.py

出力先は docs/assets/screenshots/ です。画像の差分は意図した画面だけか確認してください。