tradeblocks-mcp 3.0.2 → 3.3.1

package/README.md

@@ -14,13 +14,7 @@ Model Context Protocol (MCP) server for options trading analysis. Works with Cla
 
 ## Installation
 
-### Option 1: MCPB Bundle (Claude Desktop - One Click)
-
-Download the latest `.mcpb` file from [Releases](https://github.com/tradeblocks-org/tradeblocks/releases) and double-click to install.
-
-The installer will prompt you to select your Trading Data Directory.
-
-### Option 2: npx (All Platforms)
+### Option 1: npx (All Platforms)
 
 Run directly without installation:
 
@@ -32,9 +26,9 @@ npx tradeblocks-mcp ~/Trading/backtests
 npx tradeblocks-mcp --http ~/Trading/backtests
 ```
 
-See [Configuration by Platform](#configuration-by-platform) below for platform-specific setup.
+For Claude Desktop, add the server to `claude_desktop_config.json` — see [Configuration by Platform](#configuration-by-platform) below for platform-specific setup.
 
-### Option 3: From Source
+### Option 2: From Source
 
 ```bash
 git clone https://github.com/tradeblocks-org/tradeblocks
@@ -58,11 +52,11 @@ For detailed usage examples, see [../../docs/usage.md](../../docs/usage.md).
 
 ### Claude Desktop
 
-| Platform | Config Location |
-|----------|-----------------|
-| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
-| Linux | `~/.config/Claude/claude_desktop_config.json` |
+| Platform | Config Location                                                   |
+| -------- | ----------------------------------------------------------------- |
+| macOS    | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows  | `%APPDATA%\Claude\claude_desktop_config.json`                     |
+| Linux    | `~/.config/Claude/claude_desktop_config.json`                     |
 
 ```json
 {
@@ -135,10 +129,10 @@ See [Web Platforms Guide](../../docs/web-platforms.md) for platform-specific set
 
 ## Transport Modes
 
-| Mode | Flag | Use Case | Platforms |
-|------|------|----------|-----------|
-| stdio | (default) | Local CLI tools | Claude Desktop, Claude Code, Codex CLI, Gemini CLI |
-| HTTP | `--http` | Web platforms, remote servers | ChatGPT, Google AI Studio, Julius AI |
+| Mode  | Flag      | Use Case                      | Platforms                                          |
+| ----- | --------- | ----------------------------- | -------------------------------------------------- |
+| stdio | (default) | Local CLI tools               | Claude Desktop, Claude Code, Codex CLI, Gemini CLI |
+| HTTP  | `--http`  | Web platforms, remote servers | ChatGPT, Google AI Studio, Julius AI               |
 
 ```bash
 # stdio mode (default)
@@ -154,21 +148,21 @@ tradeblocks-mcp --directory ./data --blocks-dir ~/backtests
 
 ### Options
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--http` | Start HTTP server instead of stdio | stdio |
-| `--port <n>` | HTTP server port | 3100 |
-| `--blocks-dir <path>` | Directory containing CSV block folders | same as data directory |
-| `--market-db <path>` | Path to market.duckdb | `<directory>/market.duckdb` |
-| `--no-auth` | Disable authentication (HTTP mode) | auth enabled |
+| Flag                  | Description                            | Default                     |
+| --------------------- | -------------------------------------- | --------------------------- |
+| `--http`              | Start HTTP server instead of stdio     | stdio                       |
+| `--port <n>`          | HTTP server port                       | 3100                        |
+| `--blocks-dir <path>` | Directory containing CSV block folders | same as data directory      |
+| `--market-db <path>`  | Path to market.duckdb                  | `<directory>/market.duckdb` |
+| `--no-auth`           | Disable authentication (HTTP mode)     | auth enabled                |
 
 ### Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `BLOCKS_DIRECTORY` | Default data directory if not specified as argument |
+| Variable                 | Description                                                    |
+| ------------------------ | -------------------------------------------------------------- |
+| `BLOCKS_DIRECTORY`       | Default data directory if not specified as argument            |
 | `TRADEBLOCKS_BLOCKS_DIR` | Directory for CSV block folders (overridden by `--blocks-dir`) |
-| `MARKET_DB_PATH` | Path to market.duckdb (overridden by `--market-db`) |
+| `MARKET_DB_PATH`         | Path to market.duckdb (overridden by `--market-db`)            |
 
 ### ThetaData MDDS Credentials
 
@@ -201,6 +195,7 @@ docker run -d -p 3100:3100 -v ./data:/data --env-file .env romeo345/tradeblocks-
 ```
 
 Or with docker compose, set the image in `docker-compose.yml`:
+
 ```yaml
 services:
   tradeblocks:
@@ -274,6 +269,7 @@ tradeblocks-mcp uninstall-skills
 ```
 
 Skills provide structured prompts for tasks like:
+
 - Strategy health checks
 - Walk-forward analysis interpretation
 - Portfolio addition recommendations
@@ -299,12 +295,14 @@ backtests/
 ### CSV Formats
 
 **tradelog.csv** - Trade records with these key columns:
+
 - Date Opened, Time Opened, Date Closed, Time Closed
 - P/L (gross profit/loss)
 - Strategy, Legs (or Symbol)
 - No. of Contracts, Premium (optional)
 
 **dailylog.csv** - Daily portfolio values:
+
 - Date
 - Net Liquidity (or Portfolio Value, Equity)
 - P/L, Drawdown % (optional)
@@ -314,68 +312,75 @@ backtests/
 ## Available Tools
 
 ### Core Tools
-| Tool | Description |
-|------|-------------|
-| `list_blocks` | List all available blocks with summary stats |
-| `get_block_info` | Detailed info for a specific block |
-| `get_statistics` | Performance metrics (Sharpe, Sortino, drawdown, etc.) |
-| `get_strategy_comparison` | Compare strategies within a block |
-| `compare_blocks` | Compare statistics across multiple blocks |
+
+| Tool                      | Description                                           |
+| ------------------------- | ----------------------------------------------------- |
+| `list_blocks`             | List all available blocks with summary stats          |
+| `get_block_info`          | Detailed info for a specific block                    |
+| `get_statistics`          | Performance metrics (Sharpe, Sortino, drawdown, etc.) |
+| `get_strategy_comparison` | Compare strategies within a block                     |
+| `compare_blocks`          | Compare statistics across multiple blocks             |
 
 ### Analysis Tools
-| Tool | Description |
-|------|-------------|
-| `run_walk_forward` | Walk-forward analysis with configurable windows |
-| `run_monte_carlo` | Monte Carlo simulation with worst-case scenarios |
+
+| Tool                     | Description                                              |
+| ------------------------ | -------------------------------------------------------- |
+| `run_walk_forward`       | Walk-forward analysis with configurable windows          |
+| `run_monte_carlo`        | Monte Carlo simulation with worst-case scenarios         |
 | `get_correlation_matrix` | Strategy correlation matrix (Kendall, Spearman, Pearson) |
-| `get_tail_risk` | Tail dependence and copula-based risk analysis |
-| `get_position_sizing` | Kelly criterion position sizing |
+| `get_tail_risk`          | Tail dependence and copula-based risk analysis           |
+| `get_position_sizing`    | Kelly criterion position sizing                          |
 
 ### Performance Tools
-| Tool | Description |
-|------|-------------|
-| `get_performance_charts` | 16 chart types (equity, drawdown, distribution) |
-| `get_period_returns` | Returns aggregated by time period |
-| `compare_backtest_to_actual` | Backtest vs live performance comparison |
+
+| Tool                         | Description                                     |
+| ---------------------------- | ----------------------------------------------- |
+| `get_performance_charts`     | 16 chart types (equity, drawdown, distribution) |
+| `get_period_returns`         | Returns aggregated by time period               |
+| `compare_backtest_to_actual` | Backtest vs live performance comparison         |
 
 ### SQL Tools
-| Tool | Description |
-|------|-------------|
-| `run_sql` | Execute SQL queries against trades and market data |
+
+| Tool                | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `run_sql`           | Execute SQL queries against trades and market data   |
 | `describe_database` | Schema discovery with table info and example queries |
 
 ### Market Data Tools
-| Tool | Description |
-|------|-------------|
-| `import_market_csv` | Import market data CSV with column mapping |
-| `import_from_database` | Import from external DuckDB databases |
-| `import_flat_file` | Import a local Parquet or CSV flat file for a ticker/timespan |
-| `fetch_bars` | Fetch daily or intraday OHLCV bars from configured provider |
-| `fetch_quotes` | Fetch option minute quotes from configured provider |
-| `fetch_chain` | Fetch option chain snapshot for an underlying on a given date |
-| `compute_vix_context` | Compute cross-ticker VIX regime fields for a date range |
-| `refresh_market_data` | Composite daily refresh: fetch bars, auto-fire VIX context, return coverage report |
-| `enrich_market_data` | Compute ~40 derived indicators from raw OHLCV |
-| `enrich_trades` | Enrich trades with market context (lookahead-free) |
-| `analyze_regime_performance` | Analyze P&L by market regime |
-| `suggest_filters` | Suggest trade filters based on market conditions |
-| `calculate_orb` | Opening range breakout analysis from intraday bars |
+
+| Tool                         | Description                                                                        |
+| ---------------------------- | ---------------------------------------------------------------------------------- |
+| `import_market_csv`          | Import market data CSV with column mapping                                         |
+| `import_from_database`       | Import from external DuckDB databases                                              |
+| `import_flat_file`           | Import a local Parquet or CSV flat file for a ticker/timespan                      |
+| `fetch_bars`                 | Fetch daily or intraday OHLCV bars from configured provider                        |
+| `fetch_quotes`               | Fetch option minute quotes from configured provider                                |
+| `fetch_chain`                | Fetch option chain snapshot for an underlying on a given date                      |
+| `compute_vix_context`        | Compute cross-ticker VIX regime fields for a date range                            |
+| `refresh_market_data`        | Composite daily refresh: fetch bars, auto-fire VIX context, return coverage report |
+| `enrich_market_data`         | Compute ~40 derived indicators from raw OHLCV                                      |
+| `enrich_trades`              | Enrich trades with market context (lookahead-free)                                 |
+| `analyze_regime_performance` | Analyze P&L by market regime                                                       |
+| `suggest_filters`            | Suggest trade filters based on market conditions                                   |
+| `calculate_orb`              | Opening range breakout analysis from intraday bars                                 |
 
 ### Strategy Profile Tools
-| Tool | Description |
-|------|-------------|
-| `profile_strategy` | Create or update a strategy profile with structured metadata |
-| `get_strategy_profile` | Retrieve a stored strategy profile |
-| `list_profiles` | List all strategy profiles (optionally filtered by block) |
-| `delete_profile` | Delete a strategy profile |
-| `analyze_structure_fit` | Analyze strategy performance by regime/condition dimensions |
-| `validate_entry_filters` | Test each entry filter's contribution to edge |
-| `portfolio_structure_map` | Regime x structure coverage matrix across strategies |
+
+| Tool                      | Description                                                  |
+| ------------------------- | ------------------------------------------------------------ |
+| `profile_strategy`        | Create or update a strategy profile with structured metadata |
+| `get_strategy_profile`    | Retrieve a stored strategy profile                           |
+| `list_profiles`           | List all strategy profiles (optionally filtered by block)    |
+| `delete_profile`          | Delete a strategy profile                                    |
+| `analyze_structure_fit`   | Analyze strategy performance by regime/condition dimensions  |
+| `validate_entry_filters`  | Test each entry filter's contribution to edge                |
+| `portfolio_structure_map` | Regime x structure coverage matrix across strategies         |
 
 ### Import Tools
-| Tool | Description |
-|------|-------------|
-| `import_csv` | Import a CSV file as a new block *(CLI only - not available in Claude Desktop)* |
+
+| Tool         | Description                                                                     |
+| ------------ | ------------------------------------------------------------------------------- |
+| `import_csv` | Import a CSV file as a new block _(CLI only - not available in Claude Desktop)_ |
 
 ## Development
 
@@ -388,9 +393,6 @@ npm run build
 
 # Run tests
 npm test
-
-# Pack MCPB bundle
-npm run mcpb:pack
 ```
 
 ## Market Data (Optional)
@@ -398,11 +400,13 @@ npm run mcpb:pack
 For market context (VIX regimes, intraday timing, gap analysis), import market data using MCP tools:
 
 **From a data provider (Massive.com default, or ThetaData):**
+
 1. **Fetch bars** via `fetch_bars { tickers, timespan, from, to }` — writes directly to Parquet
 2. **Fetch VIX context** via `fetch_bars` for VIX/VIX9D/VIX3M then `compute_vix_context`
 3. **Or use** `refresh_market_data` for a combined daily refresh in one call
 
 **From TradingView CSV exports:**
+
 1. **Export** from TradingView (any chart: SPX daily, VIX daily, SPX 5-min, etc.)
 2. **Import** via `import_market_csv` with a column mapping or `import_flat_file` for Parquet
 3. **Enrich** via `enrich_market_data` to compute ~40 derived indicators
@@ -410,6 +414,7 @@ For market context (VIX regimes, intraday timing, gap analysis), import market d
 No Pine Scripts needed — TradingView exports raw OHLCV natively.
 
 Market data lives in a separate `market.duckdb` (configurable via `MARKET_DB_PATH` or `--market-db`). Canonical v3.0 datasets:
+
 - `market.spot` — Raw per-minute OHLCV bars, ticker-first layout (keyed by `ticker, date, time`)
 - `market.spot_daily` — RTH-aggregated daily OHLCV view derived from `market.spot` (keyed by `ticker, date`)
 - `market.enriched` — Per-ticker computed enrichment indicators and calendar fields; OHLCV is NOT stored here (join `market.spot_daily` for OHLCV — keyed by `ticker, date`)

package/dist/{chunk-LDKTV7GW.js → chunk-27S67XW3.js}

@@ -254,12 +254,7 @@ async function getTradesByDateRange(blockId, startDate, endDate) {
   return withReadTransaction(STORES.TRADES, async (transaction) => {
     const store = transaction.objectStore(STORES.TRADES);
     const index = store.index("composite_block_date");
-    const range = IDBKeyRange.bound(
-      [blockId, startDate],
-      [blockId, endDate],
-      false,
-      false
-    );
+    const range = IDBKeyRange.bound([blockId, startDate], [blockId, endDate], false, false);
     const result = await promisifyRequest(index.getAll(range));
     return result;
   });
@@ -356,9 +351,7 @@ async function getTradeStatistics(blockId) {
   const dates = trades.map((trade) => new Date(trade.dateOpened));
   const start = new Date(Math.min(...dates.map((d) => d.getTime())));
   const end = new Date(Math.max(...dates.map((d) => d.getTime())));
-  const strategies = Array.from(
-    new Set(trades.map((trade) => trade.strategy))
-  ).sort();
+  const strategies = Array.from(new Set(trades.map((trade) => trade.strategy))).sort();
   return {
     totalTrades,
     totalPl,
@@ -517,11 +510,9 @@ async function initializeDatabase() {
           unique: false
         });
         tradesStore.createIndex("pl", "pl", { unique: false });
-        tradesStore.createIndex(
-          "composite_block_date",
-          ["blockId", "dateOpened"],
-          { unique: false }
-        );
+        tradesStore.createIndex("composite_block_date", ["blockId", "dateOpened"], {
+          unique: false
+        });
       }
       if (!db.objectStoreNames.contains(STORES.DAILY_LOGS)) {
         const dailyLogsStore = db.createObjectStore(STORES.DAILY_LOGS, {
@@ -533,11 +524,7 @@ async function initializeDatabase() {
         dailyLogsStore.createIndex(INDEXES.DAILY_LOGS_BY_DATE, "date", {
           unique: false
         });
-        dailyLogsStore.createIndex(
-          "composite_block_date",
-          ["blockId", "date"],
-          { unique: false }
-        );
+        dailyLogsStore.createIndex("composite_block_date", ["blockId", "date"], { unique: false });
       }
       if (!db.objectStoreNames.contains(STORES.REPORTING_LOGS)) {
         const reportingStore = db.createObjectStore(STORES.REPORTING_LOGS, {
@@ -546,26 +533,18 @@ async function initializeDatabase() {
         reportingStore.createIndex(INDEXES.REPORTING_LOGS_BY_BLOCK, "blockId", {
           unique: false
         });
-        reportingStore.createIndex(
-          INDEXES.REPORTING_LOGS_BY_STRATEGY,
-          "strategy",
-          { unique: false }
-        );
-        reportingStore.createIndex(
-          "composite_block_date",
-          ["blockId", "dateOpened"],
-          { unique: false }
-        );
+        reportingStore.createIndex(INDEXES.REPORTING_LOGS_BY_STRATEGY, "strategy", {
+          unique: false
+        });
+        reportingStore.createIndex("composite_block_date", ["blockId", "dateOpened"], {
+          unique: false
+        });
       }
       if (!db.objectStoreNames.contains(STORES.CALCULATIONS)) {
         const calculationsStore = db.createObjectStore(STORES.CALCULATIONS, {
           keyPath: "id"
         });
-        calculationsStore.createIndex(
-          INDEXES.CALCULATIONS_BY_BLOCK,
-          "blockId",
-          { unique: false }
-        );
+        calculationsStore.createIndex(INDEXES.CALCULATIONS_BY_BLOCK, "blockId", { unique: false });
         calculationsStore.createIndex("calculationType", "calculationType", {
           unique: false
         });
@@ -593,16 +572,12 @@ async function initializeDatabase() {
         const staticDatasetRowsStore = db.createObjectStore(STORES.STATIC_DATASET_ROWS, {
           autoIncrement: true
         });
-        staticDatasetRowsStore.createIndex(
-          INDEXES.STATIC_DATASET_ROWS_BY_DATASET,
-          "datasetId",
-          { unique: false }
-        );
-        staticDatasetRowsStore.createIndex(
-          INDEXES.STATIC_DATASET_ROWS_BY_TIMESTAMP,
-          "timestamp",
-          { unique: false }
-        );
+        staticDatasetRowsStore.createIndex(INDEXES.STATIC_DATASET_ROWS_BY_DATASET, "datasetId", {
+          unique: false
+        });
+        staticDatasetRowsStore.createIndex(INDEXES.STATIC_DATASET_ROWS_BY_TIMESTAMP, "timestamp", {
+          unique: false
+        });
         staticDatasetRowsStore.createIndex(
           "composite_dataset_timestamp",
           ["datasetId", "timestamp"],
@@ -669,12 +644,7 @@ async function getDailyLogsByDateRange(blockId, startDate, endDate) {
   return withReadTransaction(STORES.DAILY_LOGS, async (transaction) => {
     const store = transaction.objectStore(STORES.DAILY_LOGS);
     const index = store.index("composite_block_date");
-    const range = IDBKeyRange.bound(
-      [blockId, startDate],
-      [blockId, endDate],
-      false,
-      false
-    );
+    const range = IDBKeyRange.bound([blockId, startDate], [blockId, endDate], false, false);
     const result = await promisifyRequest(index.getAll(range));
     return result;
   });
@@ -750,7 +720,9 @@ async function getDailyLogStatistics(blockId) {
   const dates = entries.map((entry) => new Date(entry.date));
   const start = new Date(Math.min(...dates.map((d) => d.getTime())));
   const end = new Date(Math.max(...dates.map((d) => d.getTime())));
-  const sortedEntries = entries.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+  const sortedEntries = entries.sort(
+    (a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()
+  );
   const finalPortfolioValue = sortedEntries[0]?.netLiquidity || 0;
   const maxDrawdown = Math.min(...entries.map((entry) => entry.drawdownPct));
   const totalPl = entries.reduce((sum, entry) => sum + entry.dailyPl, 0);
@@ -864,4 +836,4 @@ export {
   getTradesPage,
   exportTradesToCSV
 };
-//# sourceMappingURL=chunk-LDKTV7GW.js.map
+//# sourceMappingURL=chunk-27S67XW3.js.map