PA MCP Server

MCP-сервер, который предоставляет движок Portfolio Advisor (PA) в качестве инструмента для ИИ-агентов. Количественный движок включён в 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. Для веб-клиентов его нужно временно выставить через HTTPS либо развернуть на удалённом хосте. Локальный запуск HTTP не включает аутентификацию и не должен публиковаться напрямую в production.

Одобрения, рецензии и кэш становятся постоянными и разделяемыми (переживают перезапуск) при включении записываемого пути состояния:

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-сервер остаётся без аутентификации (подходит для разработки и тестирования). В production токены OAuth следует сохранять в общем хранилище и настраивать авторизацию для каждого тенанта.

Защита инфраструктуры (HTTP)

• PA_RATE_LIMIT_PER_MIN — token-bucket на 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/src движка PA. Ничего не пересчитывает: делегирует весь конвейер движку и сериализует JSON-отчёт, созданный export_report_json. Если интерфейс движка изменится, обновите pa_mcp/engine.py.

Исправление ошибки, применённое к движку (numpy 2.x)

pa/src/core/stress_test.py: weights.to_numpy(dtype=float) с numpy 2.x возвращает массив только для чтения, и target /= target.sum() завершалось ошибкой ValueError: output array is read-only. Исправлено с помощью np.array(weights.to_numpy(dtype=float)). В процессе передачи в upstream движка.

Дорожная карта

1. Профессиональная ревизия финансовых, налоговых аспектов, конфиденциальности и лицензий на данные.

2. Удалённое развёртывание с OAuth 2.1, изоляцией тенантов, квотами и наблюдаемостью.

3. Публикация в поддерживаемых реестрах после независимой проверки безопасности.

Блокирующий контрольный список находится в GO_LIVE_CHECKLIST.md.