# ZhenQuant MCP Integration Guide

> Status: transitional public download protocol guide.
>
> Canonical current-entry docs:
> - [/www/wwwroot/www.zhenquant.hk/docs/README.md](/www/wwwroot/www.zhenquant.hk/docs/README.md)
> - [/www/wwwroot/www.zhenquant.hk/docs/architecture/API_CONTRACT_BASELINE.md](/www/wwwroot/www.zhenquant.hk/docs/architecture/API_CONTRACT_BASELINE.md)
> - [/www/wwwroot/www.zhenquant.hk/docs/commercial/COMMERCIAL_FLOW.md](/www/wwwroot/www.zhenquant.hk/docs/commercial/COMMERCIAL_FLOW.md)
> - [/www/wwwroot/default/swam_zhen_platform_unification_plan.md](/www/wwwroot/default/swam_zhen_platform_unification_plan.md)
>
> This downloadable guide describes one current or historical MCP-facing distribution surface. It is not the top-level source of truth for formal API ownership, unified API key entry, billing ownership, or control-plane boundaries. If it conflicts with the formal baseline, follow the formal baseline first.

## Overview

This guide defines the public integration contract for ZhenQuant website downloads, Skill packaging, API key usage, and AI-assisted execution.

## Public Download Endpoints

- Skill package: `/downloads/skills/quant-trader-1.0.0.tar.gz`
- Python SDK package: `/downloads/skills/zhenquant-python-sdk-v1.0.0.tar.gz`
- SDK README: `/downloads/skills/python-sdk/README.md`
- MCP protocol guide: `/downloads/protocols/MCP_INTEGRATION_GUIDE.md`
- MCP server config: `/downloads/mcp-servers/zhenquant-factors.json`
- Getting-started bundle: `/downloads/examples/getting-started-bundle.tar.gz`
- Example script: `/downloads/examples/getting-started.py`

If you download `getting-started.py` separately, place `zhenquant_sdk.py` in the same directory or use the bundle above.

## Authentication

### Web users

- Authentication mode: JWT bearer token
- Entry point: website login and registration
- Main usage: dashboard, billing, chat, app and API key management

### Service integrations

- Authentication mode: API key
- Header: `X-API-Key: zq_live_xxx`
- Scope examples:
  - `factors:read`
  - `factors:execute`
  - `usage:read`
  - `chat:create`

## Core Flow

1. Visit the public site and review product and documentation pages.
2. Download the required Skill, SDK, protocol, or examples from the website.
3. Register and complete onboarding.
4. Open quota or create a charge order.
5. Create an application and generate an API key.
6. Enter the AI chat page or call the factor APIs from local tooling.
7. Receive business results from the backend conversation or API response.

## Chat Contract

- Create conversation: `POST /v1/chat/conversations`
- Send message: `POST /v1/chat/conversations/{conversation_id}/messages`
- Load messages: `GET /v1/chat/conversations/{conversation_id}/messages`

Expected assistant response shape:

```json
{
  "id": "message-id",
  "role": "assistant",
  "content": "markdown business result",
  "created_at": "2026-04-08T00:00:00Z"
}
```

## API Key Lifecycle

1. Open `/dashboard/keys`
2. Create key with a selected scope template
3. Copy the key once and store it securely
4. Use masked values only in screenshots, logs, and automation artifacts
5. Revoke leaked or temporary verification keys immediately

## Security Rules

- Never store plaintext live keys in screenshots or JSON artifacts.
- Always mask secrets before persisting automation results.
- Keep strategy logic and broker credentials in local systems.
- Use public downloads only for distributable resources and examples.

## Business Result Expectations

The current environment supports a real backend round-trip:

- website chat entry
- backend conversation creation
- user message persistence
- assistant result persistence
- result rendering back to the frontend

If an external model key is unavailable, the backend returns a local fallback business response while preserving the real request path.