tradeblocks-mcp 0.4.0 → 0.4.2

package/README.md

@@ -216,7 +216,7 @@ backtests/
 ### Core Tools
 | Tool | Description |
 |------|-------------|
-| `list_backtests` | List all available blocks with summary stats |
+| `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 |

package/agent-skills/tradeblocks-health-check/SKILL.md

@@ -19,7 +19,7 @@ Surface key performance metrics and stress test results to help understand a str
 List available blocks and help the user choose what to analyze.
 
 ```
-Use list_backtests to show available options.
+Use list_blocks to show available options.
 ```
 
 Ask clarifying questions:

package/agent-skills/tradeblocks-optimize/SKILL.md

@@ -39,7 +39,7 @@ Ask what the user wants to explore:
 
 Ask: "What aspect of your strategy would you like to explore?"
 
-Use `list_backtests` to identify the target block.
+Use `list_blocks` to identify the target block.
 
 ### Step 2: Explore Available Fields
 

package/agent-skills/tradeblocks-portfolio/SKILL.md

@@ -29,7 +29,7 @@ Ask:
 - "Which strategies would you like to analyze together?"
 - "What aspect of portfolio composition interests you?"
 
-Use `list_backtests` to show available blocks.
+Use `list_blocks` to show available blocks.
 
 ### Step 2: Correlation Analysis
 

package/agent-skills/tradeblocks-risk/SKILL.md

@@ -27,7 +27,7 @@ Risk analysis serves different purposes. Ask what the user wants to understand:
 
 Ask: "What aspect of risk would you like to explore?"
 
-Then use `list_backtests` to identify the target block.
+Then use `list_blocks` to identify the target block.
 
 ### Step 2: Run Appropriate Analysis
 

package/agent-skills/tradeblocks-wfa/SKILL.md

@@ -33,7 +33,7 @@ If OOS performance is close to IS performance, the parameters may be capturing r
 
 ### Step 1: Select Strategy
 
-Use `list_backtests` to show available blocks.
+Use `list_blocks` to show available blocks.
 
 Ask:
 - "Which backtest contains the strategy you want to analyze?"

package/manifest.json

@@ -31,7 +31,7 @@
   },
   "tools": [
     {
-      "name": "list_backtests",
+      "name": "list_blocks",
       "description": "List all available trading backtests/blocks in the configured directory"
     },
     {
@@ -91,7 +91,7 @@
     {
       "name": "getting_started",
       "description": "How to set up and use TradeBlocks for trading analysis",
-      "text": "# Getting Started with TradeBlocks\n\n## Setup\nYour trading data should be in your configured Trading Data Directory. Each strategy/backtest is a **block** - a folder containing:\n- `tradelog.csv` (required): Your trade records with columns like Date Opened, Date Closed, P/L, etc.\n- `dailylog.csv` (optional): Daily portfolio values for more accurate drawdown calculations\n\n## Adding New Backtests\nTo add a new backtest for analysis:\n1. Create a new folder in your Trading Data Directory (e.g., `my-strategy-2024`)\n2. Export your trade log CSV from Option Omega (or other backtesting platform)\n3. Save it as `tradelog.csv` in the new folder\n4. The block will appear when you run `list_backtests`\n\n**Folder structure example:**\n```\nTrading Data Directory/\n  my-strategy-2024/\n    tradelog.csv\n    dailylog.csv (optional)\n  another-strategy/\n    tradelog.csv\n```\n\n## Quick Start\n1. **List your blocks**: Use `list_backtests` to see available strategies\n2. **Get statistics**: Use `get_statistics` with a block ID to see performance metrics\n3. **Run analysis**: Use `run_walk_forward` or `run_monte_carlo` for deeper analysis"
+      "text": "# Getting Started with TradeBlocks\n\n## Setup\nYour trading data should be in your configured Trading Data Directory. Each strategy/backtest is a **block** - a folder containing:\n- `tradelog.csv` (required): Your trade records with columns like Date Opened, Date Closed, P/L, etc.\n- `dailylog.csv` (optional): Daily portfolio values for more accurate drawdown calculations\n\n## Adding New Backtests\nTo add a new backtest for analysis:\n1. Create a new folder in your Trading Data Directory (e.g., `my-strategy-2024`)\n2. Export your trade log CSV from Option Omega (or other backtesting platform)\n3. Save it as `tradelog.csv` in the new folder\n4. The block will appear when you run `list_blocks`\n\n**Folder structure example:**\n```\nTrading Data Directory/\n  my-strategy-2024/\n    tradelog.csv\n    dailylog.csv (optional)\n  another-strategy/\n    tradelog.csv\n```\n\n## Quick Start\n1. **List your blocks**: Use `list_blocks` to see available strategies\n2. **Get statistics**: Use `get_statistics` with a block ID to see performance metrics\n3. **Run analysis**: Use `run_walk_forward` or `run_monte_carlo` for deeper analysis"
     },
     {
       "name": "analyze_strategy",
@@ -104,7 +104,7 @@
     {
       "name": "optionomega_guide",
       "description": "Guide for setting up Option Omega backtests that export clean data for TradeBlocks",
-      "text": "# Option Omega Backtest Setup for TradeBlocks\n\n## Supported Assets\nSPY, SPX (afternoon expirations only), QQQ, IWM, AAPL, TSLA\n- Historical data from January 1, 2013 through previous trading day\n- Data updates overnight (3-5am ET), available before market open\n\n## Strategy Configuration\n\n### Strike Selection Methods\n- **Delta**: Select strikes by delta value (default)\n- **Percentage OTM**: Target specific out-of-the-money distances\n- **Fixed Premium**: Choose strikes nearest a specified price\n- **Strike Offset**: Position relative to parent legs (for linked legs)\n\n### Option Legs\n- Up to 8 legs per backtest\n- Linked legs for dependent strike selections\n- Round strikes to nearest multiples for liquidity\n\n## Entry Configuration\n\n### Timing\n- Entry window: 9:32am - 3:59pm ET (1-minute intervals)\n- Frequency: Daily, Weekly (specific days), Monthly (specific dates), or Specific Dates\n\n### Entry Filters (Optional)\n- VIX levels (min/max), VIX movement\n- Technical indicators: RSI (14-day), SMA, EMA\n- Opening Range Breakout (ORB)\n- Gap conditions, intraday movement\n- SqueezeMetrics: DIX, GEX, GXV\n\n## Exit Conditions\n\n### Profit/Loss Targets\n- Percentage-based\n- Fixed dollar amount\n- Closing order price\n\n### Stop Loss Options\n- Fixed stop loss\n- Trailing stop (recalculated or fixed)\n- 0-DTE intra-minute stops (SPX/SPY only)\n- Per-leg stop loss\n\n### Time-Based Exits\n- By DTE remaining\n- Days in trade\n- Minutes in trade\n\n### Other Exits\n- Technical indicator triggers\n- Delta-based (position or leg level)\n- Short tested / underlying movement\n\n## Risk Controls (The Punisher)\n- Commission/fee modeling (per contract)\n- Slippage adjustments (entry, exit, stop loss)\n- Bid-ask spread filter (default: 10,000 bps max)\n- Consecutive hits requirement (2 intervals at target/stop)\n- Min/max entry premium filters\n- Blackout days\n- Re-entry delays after exits\n\n## Data Quality Notes\n- Uses mid-price from OPRA bid/ask data\n- 1-minute resolution (open price for signals)\n- RTH only (9:30-4:00 market time)\n- SPX uses standard EOD contracts only (no AM expirations)\n- Calendar days for DTE calculations\n- March 2020 / Spring 2025 show unusual volatility\n\n## Exporting for TradeBlocks\n\n1. Run your backtest in Option Omega\n2. Go to Results -> Trade Log\n3. Click Export/Download CSV\n4. Create a new folder in your Trading Data Directory (e.g., `my-strategy-2024`)\n5. Save the CSV as `tradelog.csv` in that folder\n6. Run `list_backtests` to see your new block\n\nTradeBlocks expects these columns (Option Omega exports them automatically):\n- Date Opened, Time Opened\n- Date Closed, Time Closed\n- P/L, Strategy, Legs\n- No. of Contracts, Premium\n- Opening/Closing Prices\n- Reason For Close\n\n**Note**: The visual context from Option Omega's trade log (replay, charts) is lost in CSV export. TradeBlocks provides its own analysis tools to compensate."
+      "text": "# Option Omega Backtest Setup for TradeBlocks\n\n## Supported Assets\nSPY, SPX (afternoon expirations only), QQQ, IWM, AAPL, TSLA\n- Historical data from January 1, 2013 through previous trading day\n- Data updates overnight (3-5am ET), available before market open\n\n## Strategy Configuration\n\n### Strike Selection Methods\n- **Delta**: Select strikes by delta value (default)\n- **Percentage OTM**: Target specific out-of-the-money distances\n- **Fixed Premium**: Choose strikes nearest a specified price\n- **Strike Offset**: Position relative to parent legs (for linked legs)\n\n### Option Legs\n- Up to 8 legs per backtest\n- Linked legs for dependent strike selections\n- Round strikes to nearest multiples for liquidity\n\n## Entry Configuration\n\n### Timing\n- Entry window: 9:32am - 3:59pm ET (1-minute intervals)\n- Frequency: Daily, Weekly (specific days), Monthly (specific dates), or Specific Dates\n\n### Entry Filters (Optional)\n- VIX levels (min/max), VIX movement\n- Technical indicators: RSI (14-day), SMA, EMA\n- Opening Range Breakout (ORB)\n- Gap conditions, intraday movement\n- SqueezeMetrics: DIX, GEX, GXV\n\n## Exit Conditions\n\n### Profit/Loss Targets\n- Percentage-based\n- Fixed dollar amount\n- Closing order price\n\n### Stop Loss Options\n- Fixed stop loss\n- Trailing stop (recalculated or fixed)\n- 0-DTE intra-minute stops (SPX/SPY only)\n- Per-leg stop loss\n\n### Time-Based Exits\n- By DTE remaining\n- Days in trade\n- Minutes in trade\n\n### Other Exits\n- Technical indicator triggers\n- Delta-based (position or leg level)\n- Short tested / underlying movement\n\n## Risk Controls (The Punisher)\n- Commission/fee modeling (per contract)\n- Slippage adjustments (entry, exit, stop loss)\n- Bid-ask spread filter (default: 10,000 bps max)\n- Consecutive hits requirement (2 intervals at target/stop)\n- Min/max entry premium filters\n- Blackout days\n- Re-entry delays after exits\n\n## Data Quality Notes\n- Uses mid-price from OPRA bid/ask data\n- 1-minute resolution (open price for signals)\n- RTH only (9:30-4:00 market time)\n- SPX uses standard EOD contracts only (no AM expirations)\n- Calendar days for DTE calculations\n- March 2020 / Spring 2025 show unusual volatility\n\n## Exporting for TradeBlocks\n\n1. Run your backtest in Option Omega\n2. Go to Results -> Trade Log\n3. Click Export/Download CSV\n4. Create a new folder in your Trading Data Directory (e.g., `my-strategy-2024`)\n5. Save the CSV as `tradelog.csv` in that folder\n6. Run `list_blocks` to see your new block\n\nTradeBlocks expects these columns (Option Omega exports them automatically):\n- Date Opened, Time Opened\n- Date Closed, Time Closed\n- P/L, Strategy, Legs\n- No. of Contracts, Premium\n- Opening/Closing Prices\n- Reason For Close\n\n**Note**: The visual context from Option Omega's trade log (replay, charts) is lost in CSV export. TradeBlocks provides its own analysis tools to compensate."
     }
   ],
   "keywords": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tradeblocks-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "MCP server for options trade analysis - works with Claude Desktop/Cowork",
   "author": "David Romeo <davidmromeo@gmail.com>",
   "type": "module",

package/server/http-server.js

@@ -1,27 +1,68 @@
 import { createServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
-async function startHttpServer(server, options) {
+import express from "express";
+async function startHttpServer(serverFactory, options) {
   const { port, host = "0.0.0.0" } = options;
-  const app = createMcpExpressApp({ host });
-  const transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: void 0
-    // Stateless mode
+  const app = express();
+  app.use(express.json());
+  app.get("/", (_req, res) => {
+    res.status(200).json({
+      name: "tradeblocks-mcp",
+      status: "ok",
+      mcp_endpoint: "/mcp"
+    });
+  });
+  app.post("/", handleMcpRequest(serverFactory));
+  app.post("/mcp", handleMcpRequest(serverFactory));
+  app.get("/mcp", (_req, res) => {
+    res.status(405).json({
+      jsonrpc: "2.0",
+      error: { code: -32601, message: "Method not allowed. Use POST for MCP requests." },
+      id: null
+    });
   });
-  app.all("/mcp", async (req, res) => {
-    await transport.handleRequest(req, res);
+  app.delete("/mcp", (_req, res) => {
+    res.status(202).send();
   });
-  await server.connect(transport);
   const httpServer = createServer(app);
   return new Promise((resolve, reject) => {
     httpServer.on("error", reject);
     httpServer.listen(port, host, () => {
       console.error(`TradeBlocks MCP HTTP server listening on http://${host}:${port}/mcp`);
+      console.error(`Health check available at http://${host}:${port}/`);
       console.error(`For web platforms, expose via: ngrok http ${port}`);
       resolve(httpServer);
     });
   });
 }
+function handleMcpRequest(serverFactory) {
+  return async (req, res) => {
+    try {
+      const server = serverFactory();
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: void 0
+        // Stateless mode - no session tracking
+      });
+      res.on("close", () => {
+        transport.close().catch(() => {
+        });
+        server.close().catch(() => {
+        });
+      });
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      console.error("MCP request error:", error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal server error" },
+          id: null
+        });
+      }
+    }
+  };
+}
 export {
   startHttpServer
 };

package/server/index.js

@@ -43321,9 +43321,9 @@ function calculatePeakExposure(trades, initialCapital) {
 function registerBlockTools(server, baseDir) {
   const calculator = new PortfolioStatsCalculator();
   server.registerTool(
-    "list_backtests",
+    "list_blocks",
     {
-      description: "List all available backtest blocks with summary stats (trade count, date range, P&L)",
+      description: "START HERE: List all available portfolio blocks. Returns blockId values needed for all other tools (get_statistics, get_block_info, get_performance_charts, etc.). Each block contains trade history and optional daily logs.",
       inputSchema: external_exports.object({
         sortBy: external_exports.enum(["name", "tradeCount", "netPl", "dateRange"]).default("name").describe("Sort results by field (default: name)"),
         sortOrder: external_exports.enum(["asc", "desc"]).default("asc").describe("Sort direction (default: asc)"),
@@ -43412,9 +43412,9 @@ function registerBlockTools(server, baseDir) {
   server.registerTool(
     "get_block_info",
     {
-      description: "Get detailed info for a specific block (trade count, date range, strategies, daily log status)",
+      description: "Get detailed metadata for a block including available strategies, date range, and daily log status. Use blockId from list_blocks.",
       inputSchema: external_exports.object({
-        blockId: external_exports.string().describe("Block folder name")
+        blockId: external_exports.string().describe("Block ID from list_blocks (e.g., 'main-port')")
       })
     },
     async ({ blockId }) => {
@@ -43458,9 +43458,9 @@ function registerBlockTools(server, baseDir) {
   server.registerTool(
     "get_statistics",
     {
-      description: "Get full portfolio statistics with optional strategy, ticker, and date filters",
+      description: "Get comprehensive portfolio statistics: win rate, Sharpe ratio, max drawdown, P&L metrics, and more. Use blockId from list_blocks. Optionally filter by strategy, ticker, or date range.",
       inputSchema: external_exports.object({
-        blockId: external_exports.string().describe("Block folder name"),
+        blockId: external_exports.string().describe("Block ID from list_blocks (e.g., 'main-port')"),
         strategy: external_exports.string().optional().describe("Filter by strategy name (case-insensitive)"),
         tickerFilter: external_exports.string().optional().describe("Filter trades by underlying ticker symbol (e.g., 'SPY', 'AAPL')"),
         startDate: external_exports.string().optional().describe("Start date filter (YYYY-MM-DD)"),
@@ -43674,9 +43674,9 @@ function registerBlockTools(server, baseDir) {
   server.registerTool(
     "compare_blocks",
     {
-      description: "Compare statistics across multiple blocks (max 5)",
+      description: "Compare performance statistics across multiple portfolios side-by-side. Use blockIds from list_blocks.",
       inputSchema: external_exports.object({
-        blockIds: external_exports.array(external_exports.string()).min(1).max(5).describe("Array of block folder names to compare (max 5)"),
+        blockIds: external_exports.array(external_exports.string()).min(1).max(5).describe("Array of block IDs from list_blocks (max 5)"),
         metrics: external_exports.array(
           external_exports.enum([
             "totalTrades",
@@ -45503,7 +45503,14 @@ function registerAnalysisTools(server, baseDir) {
         maxTailDependenceThreshold: external_exports.number().min(0).max(1).default(0.5).describe("Maximum allowed tail dependence between any strategy pair (default: 0.5). Only used if enableTailRiskConstraint is true."),
         tailThreshold: external_exports.number().min(0.01).max(0.5).default(0.1).describe("Percentile threshold for tail definition (default: 0.1 = worst 10%). Only used if enableTailRiskConstraint is true."),
         diversificationNormalization: external_exports.enum(["raw", "margin", "notional"]).default("raw").describe("How to normalize returns for diversification calculations (default: raw)."),
-        diversificationDateBasis: external_exports.enum(["opened", "closed"]).default("opened").describe("Which trade date to use for diversification calculations (default: opened).")
+        diversificationDateBasis: external_exports.enum(["opened", "closed"]).default("opened").describe("Which trade date to use for diversification calculations (default: opened)."),
+        // Parameter ranges for position sizing sweeps
+        parameterRanges: external_exports.record(
+          external_exports.string(),
+          external_exports.tuple([external_exports.number(), external_exports.number(), external_exports.number()])
+        ).optional().describe(
+          `Parameter ranges for optimization sweep. Format: {paramName: [min, max, step]}. POSITION SIZING: 'kellyMultiplier' scales P&L by multiplier (e.g., {"kellyMultiplier": [0.25, 1.0, 0.25]} tests quarter/half/3-quarter/full Kelly); 'fixedFractionPct' scales relative to 2% baseline (e.g., [1, 4, 1] tests 1-4%); 'fixedContracts' scales relative to avg contracts (e.g., [1, 5, 1] tests 1-5 contracts). RISK CONSTRAINTS (reject combinations exceeding threshold): 'maxDrawdownPct' max drawdown % (e.g., [15, 25, 5] allows 15-25%); 'maxDailyLossPct' max single-day loss %; 'consecutiveLossLimit' max consecutive losing trades. STRATEGY WEIGHTS: 'strategy:StrategyName' weight multiplier per strategy (e.g., {"strategy:IronCondor": [0, 1, 0.5], "strategy:Straddle": [0, 1, 0.5]} tests include/exclude combinations). Multiple parameters create a grid search across all combinations.`
+        )
       })
     },
     async ({
@@ -45532,7 +45539,8 @@ function registerAnalysisTools(server, baseDir) {
       maxTailDependenceThreshold,
       tailThreshold,
       diversificationNormalization,
-      diversificationDateBasis
+      diversificationDateBasis,
+      parameterRanges
     }) => {
       try {
         const block = await loadBlock(baseDir, blockId);
@@ -45622,7 +45630,7 @@ function registerAnalysisTools(server, baseDir) {
             outOfSampleDays,
             stepSizeDays,
             optimizationTarget,
-            parameterRanges: {},
+            parameterRanges: parameterRanges ?? {},
             minInSampleTrades,
             minOutOfSampleTrades,
             normalizeTo1Lot,
@@ -45653,7 +45661,8 @@ function registerAnalysisTools(server, baseDir) {
             oosWindowCount,
             minInSampleTrades,
             minOutOfSampleTrades,
-            normalizeTo1Lot
+            normalizeTo1Lot,
+            parameterRanges: parameterRanges ?? null
           },
           performanceFloor: hasPerformanceFloor ? {
             minSharpeRatio: minSharpeRatio ?? null,
@@ -46982,9 +46991,9 @@ function registerPerformanceTools(server, baseDir) {
   server.registerTool(
     "get_performance_charts",
     {
-      description: "Get data for performance visualizations. Returns multiple chart datasets for equity analysis, return distributions, rolling metrics, and trade patterns.",
+      description: "Get chart data for performance visualizations: equity curves, drawdowns, return distributions, rolling metrics, and trade patterns. Use blockId from list_blocks.",
       inputSchema: external_exports.object({
-        blockId: external_exports.string().describe("Block folder name"),
+        blockId: external_exports.string().describe("Block ID from list_blocks (e.g., 'main-port')"),
         strategy: external_exports.string().optional().describe("Filter by strategy name (case-insensitive)"),
         charts: external_exports.array(
           external_exports.enum([
@@ -48872,7 +48881,7 @@ SPY, SPX (afternoon expirations only), QQQ, IWM, AAPL, TSLA
 3. Click Export/Download CSV
 4. Create a new folder in your Trading Data Directory (e.g., \`my-strategy-2024\`)
 5. Save the CSV as \`tradelog.csv\` in that folder
-6. Run \`list_backtests\` to see your new block
+6. Run \`list_blocks\` to see your new block
 
 TradeBlocks expects these columns (Option Omega exports them automatically):
 - Date Opened, Time Opened
@@ -49073,7 +49082,7 @@ async function handleDirectCall(args) {
     console.log(JSON.stringify({
       availableTools: tools,
       usage: "tradeblocks-mcp --call <tool-name> '<json-args>'",
-      example: "TRADEBLOCKS_DATA_DIR=~/backtests tradeblocks-mcp --call list_backtests '{}'"
+      example: "TRADEBLOCKS_DATA_DIR=~/backtests tradeblocks-mcp --call list_blocks '{}'"
     }, null, 2));
     process.exit(0);
   }
@@ -49181,7 +49190,7 @@ Skill Command Options:
   --force            Reinstall even if skills exist (install only)
 
 Direct Tool Invocation:
-  TRADEBLOCKS_DATA_DIR=~/backtests tradeblocks-mcp --call list_backtests '{}'
+  TRADEBLOCKS_DATA_DIR=~/backtests tradeblocks-mcp --call list_blocks '{}'
 
 Examples:
   tradeblocks-mcp ~/backtests
@@ -49334,20 +49343,24 @@ async function main() {
     console.error(`Error: Directory does not exist: ${resolvedDir}`);
     process.exit(1);
   }
-  const server = new McpServer(
-    { name: "tradeblocks-mcp", version: "0.4.0" },
-    { capabilities: { tools: {}, resources: {} } }
-  );
-  registerBlockTools(server, resolvedDir);
-  registerAnalysisTools(server, resolvedDir);
-  registerPerformanceTools(server, resolvedDir);
-  registerReportTools(server, resolvedDir);
-  registerImportTools(server, resolvedDir);
-  registerResources(server);
+  const createServer = () => {
+    const server = new McpServer(
+      { name: "tradeblocks-mcp", version: "0.4.1" },
+      { capabilities: { tools: {}, resources: {} } }
+    );
+    registerBlockTools(server, resolvedDir);
+    registerAnalysisTools(server, resolvedDir);
+    registerPerformanceTools(server, resolvedDir);
+    registerReportTools(server, resolvedDir);
+    registerImportTools(server, resolvedDir);
+    registerResources(server);
+    return server;
+  };
   if (http) {
     const { startHttpServer } = await import("./http-server.js");
-    await startHttpServer(server, { port });
+    await startHttpServer(createServer, { port });
   } else {
+    const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`TradeBlocks MCP ready (stdio). Watching: ${resolvedDir}`);