# world-quant-brain-mcp

## Setup

1. Install dependencies:

```bash
python 配置前运行我_安装必要依赖包.py
```

2. Configure environment variables (recommended):

- Copy `.env.example` to `.env` and set your values. The server will automatically load these.
- Required:
	- `CREDENTIALS_EMAIL`, `CREDENTIALS_PASSWORD`
- Optional:
	- `API_SETTINGS_TIMEOUT` (seconds, default 30)
	- `FORUM_SETTINGS_BASE_URL` (default https://support.worldquantbrain.com)
	- `FORUM_SETTINGS_HEADLESS` (true/false, default true)
	- `FORUM_SETTINGS_TIMEOUT` (seconds, default 15)
	- `FORUM_MAX_CONCURRENCY` (default 1; serializes forum operations to reduce session contention)
	- `FORUM_RATE_LIMIT_SECONDS` (default 0; disables the extra MCP-side forum cooldown, set e.g. `10` if you want a soft gap between forum calls)
	- `MCP_HOST` (default 0.0.0.0 for remote HTTP)
	- `MCP_PORT` (default 8000)
	- `MCP_STREAMABLE_HTTP_PATH` (default /mcp)

The server still supports `user_config.json`, but `.env` values take precedence for overlapping keys.

3. Run the MCP server as described below.

## Run (Streamable HTTP)

From the project root with the virtual environment activated:

```bash
./.venv/bin/mcp run --transport streamable-http main.py:mcp
```

The Streamable HTTP endpoint will listen on `http://$MCP_HOST:$MCP_PORT$MCP_STREAMABLE_HTTP_PATH` (defaults: 0.0.0.0:8000/mcp). Use a reverse proxy with HTTPS for production.

## Detailed Install (recommended)

1. Create and activate a Python virtual environment (if you haven't):

```bash
python3 -m venv .venv
source .venv/bin/activate
```

2. Upgrade pip and install project dependencies using the provided installer script:

```bash
pip install -U pip
python 配置前运行我_安装必要依赖包.py
```

3. (Optional but required for forum/playwright tools) Install Playwright and browser engines:

```bash
pip install playwright
python -m playwright install chromium
```

System packages for Playwright (Linux)

If you plan to use the forum/playwright tools on a Linux host, Playwright's Chromium requires several OS libraries. On Ubuntu/Debian systems install the runtime dependencies before running `python -m playwright install chromium`:

```bash
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
	libnspr4 libnss3 libgbm1 libgtk-3-0 libx11-xcb1 libxss1 \
	libatk1.0-0 libatk-bridge2.0-0 libpango-1.0-0 libxrandr2 \
	libxcomposite1 libxdamage1 libxkbcommon0 libcups2 ca-certificates \
	fonts-liberation xz-utils unzip wget
# On some Ubuntu releases the ALSA package is provided under a different name
# (e.g. `libasound2t64`). If `libasound2` has no candidate, install the
# distribution-provided package that provides `libasound.so.2`.
sudo apt-get install -y libasound2 || sudo apt-get install -y libasound2t64 || true
```

After installing the OS packages, run the Playwright install and verify Chromium can launch:

```bash
pip install -U playwright
python -m playwright install chromium

# Quick verification (headless):
./.venv/bin/python - <<'PY'
from playwright.sync_api import sync_playwright
with sync_playwright() as pw:
		browser = pw.chromium.launch()
		page = browser.new_page()
		page.goto('https://example.com')
		print(page.title())
		browser.close()
PY
```

4. Start the Streamable HTTP MCP server:

```bash
./.venv/bin/mcp run --transport streamable-http main.py:mcp
```

Notes:
- If your environment restricts installing system packages, ask your admin to preinstall `python3-venv` and `python3-pip`.
- For production, place nginx/caddy (HTTPS) in front of the MCP Streamable HTTP endpoint and run the MCP process under `systemd` for reliability.

## Nginx reverse-proxy example

Place the example config at `/etc/nginx/sites-available/mcp_http` and symlink to `sites-enabled`.
Example file in this repo: `deploy/nginx/mcp_http.conf`.

Key points:
- Use `proxy_http_version 1.1` and `proxy_set_header Connection ""` to allow long-lived streaming connections.
- Disable buffering with `proxy_buffering off` so responses flow immediately.
- Put TLS (Let's Encrypt / certbot) in front of nginx or configure nginx with your certificates.

Reload nginx after enabling the site:

```bash
sudo ln -s /etc/nginx/sites-available/mcp_http /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

## systemd service example

A unit file is included at `deploy/systemd/mcp-sse.service` — copy it to `/etc/systemd/system/` and enable:

```bash
sudo cp deploy/systemd/mcp-sse.service /etc/systemd/system/mcp-http.service
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-http.service
sudo journalctl -u mcp-http -f
```

The unit uses `/opt/project/world-quant-brain-mcp/.env` as `EnvironmentFile` and runs the `mcp` CLI from the virtualenv. Adjust paths, `User`, and permissions to suit your environment.