{"id":50974860,"url":"https://github.com/duy0699cat/worldquant-brain-mcp","last_synced_at":"2026-06-19T06:33:01.849Z","repository":{"id":365145436,"uuid":"1270745839","full_name":"duy0699cat/worldquant-brain-mcp","owner":"duy0699cat","description":"Python MCP server for automating WorldQuant BRAIN alpha-research workflows: async API client, batch-simulation lab, and an AST-based expression parser with novelty detection. Independent/unofficial project.","archived":false,"fork":false,"pushed_at":"2026-06-16T03:20:50.000Z","size":109,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T05:13:39.623Z","etag":null,"topics":["async","fastapi","llm-agents","mcp","model-context-protocol","python","quantitative-finance","worldquant"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/duy0699cat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-16T02:33:01.000Z","updated_at":"2026-06-16T03:20:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/duy0699cat/worldquant-brain-mcp","commit_stats":null,"previous_names":["duy0699cat/worldquant-brain-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/duy0699cat/worldquant-brain-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duy0699cat%2Fworldquant-brain-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duy0699cat%2Fworldquant-brain-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duy0699cat%2Fworldquant-brain-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duy0699cat%2Fworldquant-brain-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duy0699cat","download_url":"https://codeload.github.com/duy0699cat/worldquant-brain-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duy0699cat%2Fworldquant-brain-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34520431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","fastapi","llm-agents","mcp","model-context-protocol","python","quantitative-finance","worldquant"],"created_at":"2026-06-19T06:33:00.957Z","updated_at":"2026-06-19T06:33:01.843Z","avatar_url":"https://github.com/duy0699cat.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WorldQuant MCP\n\nA Python [MCP](https://modelcontextprotocol.io) server for automating WorldQuant BRAIN\nalpha-research workflows, plus a local reference pipeline that converts documentation\ninto LLM-friendly artifacts. Built as a personal research-engineering project.\n\n\u003e **Note:** This is an independent, unofficial project and is not affiliated with or\n\u003e endorsed by WorldQuant. WorldQuant's platform documentation is **not** included in this\n\u003e repository — you supply your own PDF (see *Reference ingestion*). Use of the BRAIN API is\n\u003e subject to WorldQuant's own terms.\n\n## Status\n\nInitial working scaffold in place.\n\nCurrent capabilities:\n\n- Load credentials from `.env` or `WQ_BRAIN_*` environment variables.\n- Convert scanned or text-based PDFs into markdown and chunked JSON.\n- Authenticate against `api.worldquantbrain.com`.\n- Search local operator/reference material.\n- Fetch platform operators, account details, and data fields.\n- Turn text hypotheses into field proxies and expression templates.\n- Ingest external research links or notes into mechanism summaries.\n- Mutate seed expressions into nearby variants.\n- Submit simulations and poll simulation progress.\n- Simulate batches of expressions and rank the results.\n- Fetch alpha details and submission status.\n- Validate whether an alpha is ready to submit and summarize blockers.\n- Compare candidate expressions against recent alphas and logged experiments.\n- Persist local experiment memory for future agents.\n- Submit alphas behind an explicit confirmation flag.\n\n## Reference ingestion\n\nThe first implemented component is the PDF ingestion pipeline.\n\n```powershell\n.venv/Scripts/python.exe -m pip install -e .\nwq-ingest-reference --input wq-ops.pdf\n```\n\nGenerated artifacts (produced locally, git-ignored — not committed):\n\n- `src/worldquant_mcp/reference/data/wq-ops.md`\n- `src/worldquant_mcp/reference/data/wq-ops.chunks.json`\n\nIf the PDF has no text layer, the ingester falls back to OCR using in-process\nPython libraries so it still works on a clean Windows machine.\n\n## Running the MCP server\n\nInstall the package in editable mode:\n\n```powershell\n.venv/Scripts/python.exe -m pip install -e .\n```\n\nDo not start the stdio MCP server manually if you want to use it from VS Code. VS Code should launch it for you from `mcp.json`.\n\nAdd this to your user-level `mcp.json` or workspace `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"worldquant-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \".venv/Scripts/worldquant-mcp.exe\",\n      \"env\": {\n        \"WQ_BRAIN_EMAIL\": \"\u003cyour-email\u003e\",\n        \"WQ_BRAIN_PASSWORD\": \"\u003cyour-password\u003e\"\n      }\n    }\n  }\n}\n```\n\nAfter saving `mcp.json`, use the VS Code MCP server management UI to reload or start the server. Once it shows as running, the tools from this server become available to Copilot agents.\n\nIf you want to run the server yourself for debugging only, use one of these commands:\n\n```powershell\n.venv/Scripts/worldquant-mcp.exe\n```\n\nOr run it via Python:\n\n```powershell\n.venv/Scripts/python.exe -m worldquant_mcp\n```\n\n## Timeout behavior\n\n- Polling tools now default to bounded waits instead of open-ended multi-minute blocking.\n- `wait_simulation`, `batch_simulate`, and `parallel_mechanism_search` default to `180` seconds.\n- Override with `timeout_seconds` when you intentionally want a longer or shorter wait.\n- Set `WQ_BRAIN_MAX_POLL_SECONDS` if you want to change the client-wide default used by direct code paths.\n- 429 handling is now more robust in the shared client: temporary rate limits are retried with bounded backoff, and `CONCURRENT_SIMULATION_LIMIT_EXCEEDED` backs off more aggressively before failing.\n- Tune `WQ_BRAIN_RATE_LIMIT_MAX_RETRIES` and `WQ_BRAIN_RATE_LIMIT_MAX_WAIT_SECONDS` if you want stricter or looser retry behavior.\n\n## Example session\n\nOnce the server is running, an MCP-aware agent calls the tools directly. Illustrative output\nbelow (metric values are synthetic and field/alpha names are placeholders — no real platform\ndata is shown):\n\n```text\n\u003e healthcheck\n{ \"status\": \"ok\", \"authenticated\": true }\n\n\u003e get_platform_operators\n[ \"rank\", \"zscore\", \"ts_delta\", \"ts_backfill\", \"ts_decay_linear\", \"group_zscore\", ... ]\n\n\u003e create_simulation  expression=\"rank(\u003cyour_signal\u003e)\"  settings=USA/TOP3000/delay=1\n{ \"status\": \"COMPLETE\", \"alpha_id\": \"\u003cid\u003e\",\n  \"is\": { \"sharpe\": 1.21, \"fitness\": 0.74, \"returns\": 0.052, \"turnover\": 0.11 } }\n\n\u003e validate_alpha_submission_by_id  alpha_id=\"\u003cid\u003e\"\n{ \"ready\": false, \"blocking\": [\"LOW_FITNESS\"], \"pending\": [\"SELF_CORRELATION\"] }\n```\n\nThe operator names above are part of BRAIN's public expression language; the pipeline never\nhard-codes proprietary data fields or alpha identifiers.\n\n## Implemented tools\n\n- `healthcheck`\n- `get_account`\n- `get_platform_operators`\n- `search_local_reference`\n- `get_reference_operators`\n- `get_data_fields`\n- `get_recent_alphas`\n- `get_alpha`\n- `get_alpha_submission`\n- `create_simulation`\n- `batch_simulate`\n- `summarize_alpha_batch_by_id`\n- `mutate_alpha_expression`\n- `map_research_hypothesis`\n- `ingest_research_material`\n- `get_simulation`\n- `wait_simulation`\n- `analyze_alpha_novelty`\n- `log_alpha_experiment`\n- `list_alpha_experiments`\n- `validate_alpha_submission_by_id`\n- `submit_alpha_by_id`\n\n## Research Notes\n\n- `docs/mcp-roadmap.md` tracks pragmatic MCP upgrades for alpha research.\n- `docs/quant-journey.md` is a running experiment log for future agents.\n- `src/worldquant_mcp/data/experiment_memory.json` stores the same experiments in machine-readable form.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduy0699cat%2Fworldquant-brain-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduy0699cat%2Fworldquant-brain-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduy0699cat%2Fworldquant-brain-mcp/lists"}