Tradeblocks

TradeBlocks

Options trading analytics platform with a web dashboard and AI-powered analysis via MCP (Model Context Protocol).

Web App | npm | Docker Hub | Buy Me a Coffee

Repository Structure

tradeblocks/
├── app/                      # Next.js web application
├── components/               # React components (shadcn/ui + Plotly charts)
├── tests/                    # Jest test suites
├── docs/                     # Documentation
│   └── development.md        # Architecture and local dev guide
└── packages/
    ├── lib/                  # Core business logic (@tradeblocks/lib)
    └── mcp-server/           # MCP server (npm: tradeblocks-mcp)

Quick Start

Development Setup

git clone https://github.com/tradeblocks-org/tradeblocks.git
cd tradeblocks
npm install
npm run dev              # Web dashboard at http://localhost:3000

MCP Server

# Run directly with npx
npx tradeblocks-mcp ~/Trading/backtests

# Or from source
npm run build -w packages/mcp-server
node packages/mcp-server/server/cli.js ~/Trading/backtests

Testing

npm test                 # All tests
npm test -- path/to/file.test.ts    # Single file
npm run test:coverage    # Coverage report

Documentation

Data Format

Both the web dashboard and MCP server accept CSV exports from platforms like Option Omega. Each block contains:

• tradelog.csv (required) - Trade history with P/L, dates, strategy name
• dailylog.csv (optional) - Daily portfolio values for enhanced drawdown calculations
• reportinglog.csv (optional) - Actual/reported trades for backtest vs live comparison

Files are auto-detected by column headers, not filenames. See Usage Guide for format details.

Option Omega

TradeBlocks never calls Option Omega. Install both MCP servers, TradeBlocks and OO's, in the same AI client:

• Capture (Claude Code only). The optional tradeblocks-skills plugin's /tradeblocks:oo-capture saves OO's responses for a saved backtest, saved portfolio or run to disk, verifies the trades against OO's own count and net profit, and imports the trade log into one block with OO's marked daily curve. A run whose OO headline reports no date range is imported with its trades only, and the capture says so. It needs TradeBlocks running locally over stdio; it is not supported with the Docker image or HTTP mode.
• CSV fallback (every client and mode). Export the trade log, and optionally the daily log, from OO and import both with one import_csv call using dailyLogPath. For Docker/HTTP, put the CSVs inside the server's mounted data directory.
• Prompts. bring-in-oo-backtest, is-this-optimum-real, stress-oo-portfolio, live-vs-oo and allocate-oo-portfolio guide the OO workflows. See the MCP server README.

Capture is verified against OO's staging MCP server. See the 4.0.0 release notes.

User daily datasets

Since 4.1.0, the MCP server imports your own numeric or categorical CSV series with import_daily_dataset, lists them with list_daily_datasets, removes them with delete_daily_dataset, and discovers built-in and dataset fields with list_analysis_fields. Use <dataset>.<column> fields in profile filters, predictive reports, regime analysis and threshold sweeps. User datasets are stored separately from market data and need no provider key.

Both MCP imports and new web Static Datasets declare when each column was known: date-only close values become available the next calendar day at 00:00 ET; date-only open values require a known-by time; timestamped values are as-of. Existing web datasets retain their values with a legacy-same-day warning until timing is declared. See the dataset tools reference and 4.1.0 release notes, including changes to existing analysis results.

4.3 adds covered/uncovered dataset baselines, missed-XNYS-session age diagnostics and an optional maxMissedSessions limit. suggest_filters now defaults to P&L improvement (objective: "totalPl"), not win-rate gain. See the 4.3.0 behavior changes before comparing suggestions with earlier reports.

Predictive field ranking also supports opt-in Spearman and Kendall correlation via find_predictive_fields.method; omitted methods retain Pearson and its response shape. filter_curve adds opt-in multi-field comparison, P&L/win-rate objectives, per-year stability, and seeded whole-month block permutation with full-sweep selection adjustment and Holm p-values. Existing single-field calls remain unchanged. See the tool contract and limits. Day-level filter analysis (unit: "day", 4.5.0) aggregates multi-entry days before scoring and permutation, refuses within-day varying fields by name, and admits large requests before expensive field resolution. Day mode also supports risk objectives sharpe, mar, and maxDrawdown on the covered daily P&L curve, with explicit definitions and named unit/capital refusals. Optional groupBy adds chosen-threshold regime breakdowns, numeric bins or categorical groups, explicit uncovered rows, and day-constancy refusals. See the 4.5.0 release notes for field-scoped resolution, reported large-block timings, risk conventions and the categorical-field behavior change.

Features Overview

Web Dashboard

• Performance dashboards with equity curves, drawdowns, monthly returns
• Risk tooling: Monte Carlo simulator, position sizing, correlation analysis
• Block-based organization for multiple strategies
• Client-side storage (IndexedDB) - data stays on your machine

MCP Server

• Tools for statistics, simulations, walk-forward analysis, and SQL queries
• SQL analytics layer (run_sql + describe_database) for flexible data exploration
• Massive.com API integration for automated market data import
• Market data import and enrichment (import_market_csv + enrich_market_data)
• User Static Dataset import (import_daily_dataset) with shared CSV parsing and causal per-column timing; discover fields with list_analysis_fields.
• Trade replay with MFE/MAE analysis using historical option minute bars
• Lookahead-free trade enrichment with market context (VIX regimes, intraday timing)
• Works with Claude Desktop, Claude Code, Codex CLI, Gemini CLI, ChatGPT, Google AI Studio
• Agent skills for guided strategy health checks and portfolio recommendations

Contributing

1. Create a feature branch
2. Update or add tests when behavior changes
3. Run npm run lint and npm test before opening a pull request

License

MIT