PA MCP Server

MCP 服务器，将 Portfolio Advisor (PA) 引擎作为工具暴露给 AI 智能体。量化引擎包含在 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，其中包含优化、预期收益、Monte Carlo、压力测试和基准比较。批准在 2 小时后过期，并在完整报告成功完成时被消耗。

如果用户提供了工具列表，智能体会将其传递给 verifica_strumenti，并逐条解释每个拒绝原因。如果用户没有列表并请求建议，智能体会使用 proponi_strumenti，展示代码、名称、交易所、预估费用和说明，然后在验证和配置之前等待明确确认。不会自动进行任何替换。

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（scope 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 — 每个租户的每小时分析配额（0 = 无限制）；租户键通过 PA_TENANT（默认 anonymous）。

可观测性（HTTP）

• GET /health/live — 存活检查。

• GET /health/ready — 就绪检查（未就绪时返回 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。

应用于引擎的 Bug 修复（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。