OpenAlphaStack

<div align="center"> <h1>OpenAlphaStack</h1> <p><strong>An open-source Codex plugin stack for auditable A-share research, backtesting, and paper trading.</strong></p> [](https://github.com/44-99/OpenAlphaStack/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) [](.codex-plugin/plugin.json) [](.mcp.json) [](https://github.com/44-99/OpenAlphaStack/stargazers) [Quick start](#quick-start) · [Architecture](docs/architecture.md) · [Skills](docs/skills.md) · [Roadmap](docs/roadmap.md) </div> The plugin packages domain Skills and a local MCP server as one installable system. Codex Desktop may compose those Skills in scheduled tasks. The MCP server exposes typed market, risk, backtest, and paper-plan tools. Python validates plans and executes them mechanically; it never launches an Agent or invents a missing trading plan. > Paper trading only. OpenAlphaStack does not place real orders and does not promise investment returns.  ## Why OpenAlphaStack? - **One plugin, two extension layers** — package reusable domain Skills and a typed MCP server as one Codex-native system. - **Agent research, deterministic execution** — Codex analyzes and proposes; Python owns validation, T+1 rules, fees, state transitions and paper execution. - **Auditable by design** — explicit plans, version checks, idempotency keys, append-only ledgers and observable workflow events. - **Local-first and model-independent at the core** — market tools and execution state stay local instead of being hidden inside an Agent subprocess. - **Honest safety boundary** — all mutation tools are paper-only; there is no live-order MCP tool. ## Architecture ```text Codex task or scheduled prompt │ invokes ▼ Domain Skills ─────────► OpenAlphaStack MCP │ ┌────────────┼─────────────┐ ▼ ▼ ▼ Market data Plan + risk Backtests │ ▼ Deterministic paper engine │ plan / state / ledger │ ▼ Read-only Dashboard ``` The boundaries are intentional: - **Codex Desktop**: conversations, scheduled tasks, research, and operator review. - **Skills**: reusable market, screening, stock-analysis, and T0 domain capabilities. - **MCP**: typed access to live data and bounded paper-only actions. - **Python engine**: T+1 rules, fees, validation, state, audit, and mechanical execution. - **Dashboard**: K-line, plans, positions, ledger, workflow events, and diagnostics. ## Quick start Requirements: - Python 3.10+ - Node.js 20+ - Codex Desktop ```powershell git clone https://github.com/44-99/OpenAlphaStack.git cd OpenAlphaStack pip install -r requirements.txt pip install -e . npm install npm run dashboard:build openalphastack app start ``` Open `http://127.0.0.1:8800/dashboard`. Then open the repository in Codex Desktop and try: ```text Use $market-analyzer to assess today's A-share market, cite the MCP data used, and finish with risks and invalidation conditions. ``` The repository is also a Codex plugin: `.codex-plugin/plugin.json` discovers the Skills and `.mcp.json` registers the stdio server. After installing the Python package, install/open the plugin in Codex and verify the `open-alpha-stack` MCP tools are available. Start the MCP server manually for diagnostics: ```powershell openalphastack mcp serve ``` ## Codex Skills - `$market-analyzer`: market environment, sentiment, sectors, and leaders. - `$stock-screener`: deterministic screening and candidate verification. - `$stock-analyzer`: technical, fundamental, news, position, and risk analysis. - `$t0-intraday`: T0 feasibility, direction, sizing, and guardrails. Scheduled tasks compose these domain Skills; premarket and postclose are task prompts, not duplicate Skills. A local scheduled task requires the computer and Codex Desktop to remain running. ## MCP safety contract Read tools expose paper/backtest runs, market data, indicators, news, screens, risk calculations, and deterministic baseline backtests. The only plan mutations are: 1. `save_plan_draft` — writes a non-executable `plan.codex-draft.json`. 2. `publish_paper_plan` — validates, requires an idempotency key, checks the expected plan version, and atomically updates a paper run only. Live runs are hidden from MCP mutations. No shell, arbitrary file-write, or live-order tool is exposed. ## Engine commands ```powershell openalphastack engine start --mode paper -u default --daemon openalphastack engine list openalphastack engine status <run_id> openalphastack engine stop <run_id> openalphastack engine resume <run_id> --daemon openalphastack engine start --mode backtest \ --start 2024-01-01 --end 2024-06-30 -u default ``` The paper engine can stay running outside trading hours. It idles according to the trading calendar and remains observation-only until Codex publishes a valid plan for the current date. ## Verification ```powershell npm run dashboard:test npm run dashboard:build python -m pytest -q python -m compileall -q src\openalphastack ``` ## Documentation - [Architecture](docs/architecture.md) - [Roadmap](docs/roadmap.md) - [Skills](docs/skills.md) - [Feishu notifications](docs/feishu-bot-menu.md) ## Contributing Issues and focused pull requests are welcome. Before changing the repository, read [AGENT_GUIDE.md](AGENT_GUIDE.md), preserve the paper-only MCP boundary and add tests for behavior that affects validation, state, risk or idempotency. ## Security The Dashboard binds to localhost by default. Do not expose it directly to a LAN or the internet without adding authentication, TLS, CSRF protection, and an explicit network policy. ## License MIT © OpenAlphaStack