PA MCP Server

AIエージェント向けツールとして Portfolio Advisor (PA) エンジンを公開するMCPサーバー。 クォンツエンジンは pa_engine/src に含まれているため、このプロジェクトは 自己完結しており、配布物外のフォルダやデータに依存しません。

製品ドキュメントと制限事項: PRODUCT_OVERVIEW.md。 専門家によるレビューが必要なプライバシーテンプレート: PRIVACY_NOTICE_TEMPLATE.md。 リリース前監査の結果: AUDIT_REPORT.md。

提供内容

エージェントはまず schema_input_pa を呼び出し、データを収集して、設定を valida_input_pa に渡します。valid=true の場合、prepara_simulazione を 呼び出します。クライアントは入力済みパラメータのパネルを表示し、 シミュレーションは停止したままになります。ユーザーは値を変更でき、明示的に 確認する必要があります。ウィジェットは設定を固定し、内部の承認識別子を エージェントに送信します。エージェントはその後、直接 analisi_completa を 呼び出します。これには最適化、期待リターン、モンテカルロ、ストレステスト、 ベンチマーク比較が含まれます。承認は2時間で失効し、完全なレポートが正常に 完了すると消費されます。

ユーザーが銘柄リストを提供した場合、エージェントはそれを verifica_strumenti に渡し、各拒否理由を具体的に説明します。リストがなく 提案を求める場合は、エージェントは proponi_strumenti を使用し、ticker、 名称、取引所、推定コスト、コメントを提示した後、検証と設定の前に明示的な 確認を待ちます。自動での置換は一切行われません。

cost_annual_pct はパーセントポイントで表されます。0.50 は年率 0,50% を意味します。MCP Apps をサポートしないクライアントは、検証とドラフト表示は できますが、インタラクティブな承認フローを完了できません。

セットアップ

python3.13 -m venv .venv
./.venv/bin/python -m pip install .

ウィジェットを変更・再ビルドするには、Node.js 20+ と npm ci も必要です。

Portfolio Advisor エンジンはプロジェクト内の pa_engine/src に含まれている ため、サーバーは自己完結しています。開発時には別のエンジンを指定することも 可能です:

export PA_ENGINE_DIR="/percorso/del/motore"   # opzionale, solo sviluppo

起動

ローカル（stdio）:

./.venv/bin/python -m pa_mcp.server

Streamable HTTP（リモートコネクタおよび MCP Apps テスト用）:

PA_MCP_TRANSPORT=http PA_MCP_PORT=3000 \
  ./.venv/bin/python -m pa_mcp.server

MCP エンドポイント: http://127.0.0.1:3000/mcp。Web クライアントの場合は、 HTTPS 経由で一時的に公開するか、リモートホストにデプロイする必要があります。 ローカルでの HTTP 起動は認証を有効にせず、本番環境に直接公開してはいけません。

承認、レビュー、キャッシュは、書き込み可能な状態パスを有効にすることで 永続化・共有可能（再起動後も保持）になります:

PA_STATE_PATH=/var/lib/pa_mcp/state.db PA_MCP_TRANSPORT=http PA_MCP_PORT=3000 \
  ./.venv/bin/python -m pa_mcp.server

PA_STATE_PATH がない場合、状態はメモリ内に保持されます（ローカル開発や テストでの通常の動作）。

OAuth（HTTP、エンドポイント公開前）

OAuth 2.1（スコープ pa.read）は FastMCP OAuthProvider 経由で利用できます:

PA_OAUTH=1 PA_PUBLIC_BASE_URL=https://pa.example.com \
  PA_MCP_TRANSPORT=http PA_MCP_PORT=3000 ./.venv/bin/python -m pa_mcp.server

PA_OAUTH が設定されていない場合、HTTP サーバーは認証なしのままです（開発・ テストに適しています）。本番環境では、OAuth トークンを共有ストアに永続化し、 テナントごとの認可を設定する必要があります。

インフラストラクチャ保護（HTTP）

• PA_RATE_LIMIT_PER_MIN — IP ごとのトークンバケット（HTTP 429）。

• PA_MAX_BODY_BYTES — リクエストボディサイズ制限（HTTP 413）。

• PA_ANALYSIS_TIMEOUT_SECONDS — 分析のハードデッドライン（デフォルト60秒。 スロットと承認を解放します）。

• PA_ANALYSIS_QUOTA_PER_HOUR — テナントごとの1時間あたりの分析クォータ （0 = 無制限）。テナントキーは PA_TENANT 経由（デフォルト anonymous）。

可観測性（HTTP）

• GET /health/live — liveness。

• GET /health/ready — readiness（準備未完了なら503。ストアの状態）。

• GET /metrics — 運用カウンター（個人データなし）。

デプロイとドキュメント

コネクタを公開するには、安定したエンドポイント（トンネルではない）が 必要です。DEPLOY_GUIDE.md を参照してください（Dockerfile を含む）。 告知文と利用規約のドラフトは PRIVACY_NOTICE_DRAFT.md と TERMS_OF_USE_DRAFT.md にあります（要レビュー）。

クライアント向けの新しいモジュール pa_mcp/auth.py、pa_mcp/limits.py、 pa_mcp/state.py、pa_mcp/oauth_provider.py、pa_mcp/quotas.py は wheel に含まれています。

サーバーは stdio で通信します。任意の MCP クライアントが接続できます。 汎用クライアント向けの設定例:

{
  "mcpServers": {
    "pa-engine": {
      "command": "/percorso/pa-mcp-server/.venv/bin/python",
      "args": ["/percorso/pa-mcp-server/server_script.py"],
      "cwd": "/percorso/pa-mcp-server"
    }
  }
}

ツールのテスト

契約と承認フローのオフラインテスト:

./.venv/bin/python -m unittest discover -s tests -p 'test_*.py'
node scripts/test_config_widget_render.js
node scripts/test_widget_render.js

市場データによる完全な自己チェック:

./.venv/bin/python -m pa_mcp.selfcheck

実際のデータを含むテスト設定に対してすべてのツールを実行し（Yahoo Finance へのネットワークが必要）、各出力のキーを表示します。

エンジンに関する注記

ラッパーは PA エンジンの pa/src を再利用します。再計算は一切行わず、 完全なパイプラインをエンジンに委任し、export_report_json が生成する JSON レポートをシリアライズします。エンジンのインターフェースが変更された場合は、 pa_mcp/engine.py を更新してください。

エンジンに適用されたバグ修正（numpy 2.x）

pa/src/core/stress_test.py: numpy 2.x では weights.to_numpy(dtype=float) が読み取り専用の配列を返すため、target /= target.sum() が ValueError: output array is read-only で失敗していました。 np.array(weights.to_numpy(dtype=float)) により修正。エンジンへの アップストリーム予定です。

ロードマップ

1. 財務、税務、プライバシー、データライセンスに関する専門家レビュー。

2. OAuth 2.1、テナント分離、クォータ、可観測性を備えたリモートデプロイ。

3. 独立したセキュリティレビュー後のサポート対象レジストリへの公開。

ブロッキングチェックリストは GO_LIVE_CHECKLIST.md にあります。