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을 호출합니다. 클라이언트는 작성된 매개변수가 포함된 패널을 표시하며 시뮬레이션은 대기 상태로 유지됩니다. 사용자는 값을 수정할 수 있으며 명시적으로 확인해야 합니다. 위젯은 구성을 고정하고 에이전트에게 내부 승인 식별자를 보냅니다. 그러면 에이전트는 최적화, 기대 수익률, Monte Carlo, 스트레스 테스트 및 벤치마크 비교가 포함된 analisi_completa를 직접 호출합니다. 승인은 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

원격 커넥터 및 MCP Apps 테스트용 Streamable HTTP:

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 시작은 인증을 활성화하지 않으며 프로덕션에 직접 게시해서는 안 됩니다.

승인, 검토 및 캐시는 쓰기 가능한 상태 경로를 활성화하면 영구적이고 공유 가능해집니다(재시작 후에도 유지됩니다):

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별 token-bucket (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 — 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

실제 데이터가 포함된 테스트 config에 대해 모든 도구를 실행하고(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에 있습니다.