tradeblocks-mcp 0.1.0

package/README.md

@@ -0,0 +1,246 @@
+# TradeBlocks MCP Server
+
+Model Context Protocol (MCP) server for options trading analysis. Provides programmatic access to backtest statistics, walk-forward analysis, Monte Carlo simulations, and risk metrics.
+
+## Features
+
+- **19 MCP tools** for comprehensive trading analysis
+- **Block-based data organization** - each folder is a trading strategy
+- **Automatic caching** - statistics cached in `.block.json` for fast access
+- **Flexible CSV detection** - auto-detects file types by column headers
+- **Cross-platform** - works with Claude, Codex CLI, Gemini CLI, and any MCP client
+
+## Installation
+
+### Option 1: MCPB Bundle (Claude Desktop - One Click)
+
+Download the latest `.mcpb` file from [GitHub Releases](https://github.com/davidromeo/tradeblocks/releases) and double-click to install.
+
+The installer will prompt you to select your Trading Data Directory.
+
+### Option 2: npx (Claude Desktop / Claude Code)
+
+Run directly without installation:
+
+```bash
+npx tradeblocks-mcp ~/Trading/backtests
+```
+
+For Claude Desktop, add to your config file:
+
+```json
+{
+  "mcpServers": {
+    "tradeblocks": {
+      "command": "npx",
+      "args": ["tradeblocks-mcp", "/path/to/your/backtests"]
+    }
+  }
+}
+```
+
+### Option 3: From Source
+
+```bash
+git clone https://github.com/davidromeo/tradeblocks
+cd tradeblocks
+npm install
+npm run build -w packages/mcp-server
+
+# Run the server
+node packages/mcp-server/server/index.js ~/Trading/backtests
+```
+
+## Quick Start
+
+1. **Set up your data** - Create folders for each strategy with CSV files
+2. **Connect Claude** - Install via MCPB or configure manually
+3. **Start analyzing** - Ask Claude to "list my backtests" or "run a health check on iron-condor"
+
+For detailed usage examples, see [docs/USAGE.md](docs/USAGE.md).
+
+## Configuration by Platform
+
+### 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` |
+
+```json
+{
+  "mcpServers": {
+    "tradeblocks": {
+      "command": "npx",
+      "args": ["tradeblocks-mcp", "/path/to/your/backtests"]
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+# Add the MCP server
+claude mcp add tradeblocks -- npx tradeblocks-mcp ~/Trading/backtests
+
+# Or with environment variable
+export BLOCKS_DIRECTORY=~/Trading/backtests
+claude mcp add tradeblocks -- npx tradeblocks-mcp
+```
+
+### OpenAI Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.tradeblocks]
+command = "npx"
+args = ["tradeblocks-mcp", "/path/to/your/backtests"]
+```
+
+Or add via command line:
+
+```bash
+codex mcp add tradeblocks -- npx tradeblocks-mcp ~/Trading/backtests
+```
+
+See [Codex MCP documentation](https://developers.openai.com/codex/mcp/) for more options.
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "tradeblocks": {
+      "command": "npx",
+      "args": ["tradeblocks-mcp", "/path/to/your/backtests"]
+    }
+  }
+}
+```
+
+See [Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/) for more options.
+
+## Agent Skills
+
+For guided conversational workflows, install the bundled agent skills:
+
+```bash
+# Install skills to Claude Code
+tradeblocks-mcp install-skills
+
+# Install to other platforms
+tradeblocks-mcp install-skills --platform codex
+tradeblocks-mcp install-skills --platform gemini
+
+# Check installation status
+tradeblocks-mcp check-skills
+
+# Remove skills
+tradeblocks-mcp uninstall-skills
+```
+
+Skills provide structured prompts for tasks like:
+- Strategy health checks
+- Walk-forward analysis interpretation
+- Portfolio addition recommendations
+- Correlation analysis
+
+See [Agent Skills README](../agent-skills/README.md) for details.
+
+## Block Directory Structure
+
+Each folder in your blocks directory represents a trading strategy:
+
+```
+backtests/
+  SPX-Iron-Condor/
+    tradelog.csv      # Required - trade history
+    dailylog.csv      # Optional - daily portfolio values
+    reportinglog.csv  # Optional - live/reported trades
+    .block.json       # Auto-generated - cached metadata
+  NDX-Put-Spread/
+    my-export.csv     # Works! Auto-detected by columns
+    ...
+```
+
+### 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)
+
+**Flexible Detection**: Files don't need standard names. The server detects CSV types by examining column headers (ISS-006).
+
+## Available Tools
+
+### Core Tools
+| Tool | Description |
+|------|-------------|
+| `list_backtests` | List all available blocks |
+| `get_statistics` | Performance metrics (Sharpe, Sortino, drawdown, etc.) |
+| `get_trades` | Raw trade data with optional filters |
+| `reprocess_block` | Re-parse CSVs and recalculate statistics |
+
+### Analysis Tools
+| Tool | Description |
+|------|-------------|
+| `run_walk_forward` | Walk-forward analysis with configurable windows |
+| `run_monte_carlo` | Monte Carlo simulation with worst-case scenarios |
+| `calculate_correlation` | Strategy correlation matrix (Kendall's tau) |
+| `get_tail_risk` | VaR, CVaR, and max drawdown analysis |
+| `calculate_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_vs_actual` | Backtest vs live performance comparison |
+
+### Report Builder Tools
+| Tool | Description |
+|------|-------------|
+| `list_available_fields` | List filterable trade fields |
+| `run_filtered_query` | Query trades with custom filters |
+| `get_field_statistics` | Statistics for a specific field |
+| `aggregate_by_field` | Group and aggregate by field values |
+
+### Import Tools
+| Tool | Description |
+|------|-------------|
+| `import_csv` | Import a CSV file as a new block *(CLI only - not available in Claude Desktop)* |
+
+## Development
+
+```bash
+# Watch mode
+npm run dev
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Pack MCPB bundle
+npm run mcpb:pack
+```
+
+## Related
+
+- [Usage Guide](docs/USAGE.md) - Detailed usage examples and workflows
+- [Agent Skills](../agent-skills/README.md) - Conversational workflows for guided analysis
+- [Main Application](../../README.md) - Web-based UI for TradeBlocks

package/agent-skills/INSTALL.md

@@ -0,0 +1,240 @@
+# TradeBlocks Skills Installation Guide
+
+This guide covers installation of TradeBlocks skills for all supported AI agent platforms.
+
+## Prerequisites
+
+Before installing skills, ensure you have:
+
+1. **Node.js 18+** installed
+2. **TradeBlocks MCP server** built and configured
+3. **At least one block directory** with trade data
+
+### Verify MCP Server
+
+```bash
+# Build the MCP server (if not already done)
+cd packages/mcp-server
+npm install
+npm run build
+
+# Set blocks directory environment variable
+export TRADEBLOCKS_BLOCKS_DIR=/path/to/your/blocks
+```
+
+## Claude Code Installation
+
+Claude Code supports skills in two locations:
+
+### Option A: Personal Installation (Recommended)
+
+Skills in `~/.claude/skills/` are available in all projects:
+
+```bash
+# Create skills directory if it doesn't exist
+mkdir -p ~/.claude/skills
+
+# Symlink all TradeBlocks skills
+ln -s /path/to/tradeblocks/packages/agent-skills/tradeblocks-* ~/.claude/skills/
+```
+
+Or use the installation script:
+
+```bash
+cd /path/to/tradeblocks/packages/agent-skills
+./install.sh claude
+```
+
+### Option B: Project Installation
+
+Skills in `.claude/skills/` (project root) are shared with your team via git:
+
+```bash
+# From your project root
+mkdir -p .claude/skills
+ln -s /path/to/tradeblocks/packages/agent-skills/tradeblocks-* .claude/skills/
+```
+
+### Verification
+
+Ask Claude: "What skills are available?"
+
+Or check directly:
+
+```bash
+ls -la ~/.claude/skills/
+```
+
+You should see symlinks for all 6 TradeBlocks skills.
+
+### Debug Mode
+
+If skills aren't loading, run Claude with debug output:
+
+```bash
+claude --debug
+```
+
+Look for skill loading messages in the output.
+
+## Codex CLI Installation
+
+Codex CLI uses a similar skills directory structure:
+
+```bash
+# Create skills directory
+mkdir -p ~/.codex/skills
+
+# Symlink all TradeBlocks skills
+ln -s /path/to/tradeblocks/packages/agent-skills/tradeblocks-* ~/.codex/skills/
+```
+
+Or use the installation script:
+
+```bash
+./install.sh codex
+```
+
+**Note:** Codex may use different syntax to invoke skills. Consult Codex documentation for the current activation method.
+
+## Gemini CLI Installation
+
+Gemini CLI follows the same pattern:
+
+```bash
+# Create skills directory
+mkdir -p ~/.gemini/skills
+
+# Symlink all TradeBlocks skills
+ln -s /path/to/tradeblocks/packages/agent-skills/tradeblocks-* ~/.gemini/skills/
+```
+
+Or use the installation script:
+
+```bash
+./install.sh gemini
+```
+
+**Note:** Gemini may use different syntax to invoke skills. Consult Gemini documentation for the current activation method.
+
+## All Platforms at Once
+
+To install to all platforms:
+
+```bash
+./install.sh all
+```
+
+## Troubleshooting
+
+### "Skill not found"
+
+1. Verify the skill directory exists:
+   ```bash
+   ls ~/.claude/skills/tradeblocks-health-check/SKILL.md
+   ```
+
+2. Check that SKILL.md has valid YAML frontmatter (must start on line 1):
+   ```yaml
+   ---
+   name: tradeblocks-health-check
+   description: ...
+   ---
+   ```
+
+3. Ensure no tabs in YAML (use spaces only)
+
+### "Tool not found" during skill execution
+
+The skill invokes MCP tools but the server isn't available:
+
+1. Verify MCP server is built:
+   ```bash
+   ls packages/mcp-server/dist/index.js
+   ```
+
+2. Check MCP server configuration in your agent settings
+
+3. Verify `TRADEBLOCKS_BLOCKS_DIR` is set correctly
+
+### YAML Parsing Errors
+
+- Frontmatter must start on line 1 (no blank lines before `---`)
+- Use spaces, not tabs
+- Ensure closing `---` is present
+
+### Symlink Issues (macOS/Linux)
+
+If symlinks aren't working:
+
+```bash
+# Remove existing broken symlink
+rm ~/.claude/skills/tradeblocks-health-check
+
+# Recreate with absolute path
+ln -s /absolute/path/to/tradeblocks/packages/agent-skills/tradeblocks-health-check ~/.claude/skills/
+```
+
+### Windows Installation
+
+Windows doesn't support Unix symlinks. Use the PowerShell install script instead:
+
+```powershell
+cd C:\path\to\tradeblocks\packages\agent-skills
+.\install.ps1 claude
+```
+
+Or copy manually:
+
+```powershell
+# Create skills directory
+mkdir $env:USERPROFILE\.claude\skills
+
+# Copy all TradeBlocks skills
+Copy-Item -Recurse C:\path\to\tradeblocks\packages\agent-skills\tradeblocks-* $env:USERPROFILE\.claude\skills\
+```
+
+**Note:** When updating skills on Windows, re-run `.\install.ps1 claude` (unlike macOS/Linux where symlinks auto-update).
+
+### Permission Denied
+
+Ensure the install script is executable:
+
+```bash
+chmod +x install.sh
+```
+
+## Updating Skills
+
+### If Using Symlinks (Recommended)
+
+Simply pull the latest code:
+
+```bash
+cd /path/to/tradeblocks
+git pull
+```
+
+Skills update automatically since symlinks point to the source.
+
+### If You Copied Files
+
+Re-copy after updates:
+
+```bash
+# Remove old skills
+rm -rf ~/.claude/skills/tradeblocks-*
+
+# Re-copy
+cp -r /path/to/tradeblocks/packages/agent-skills/tradeblocks-* ~/.claude/skills/
+```
+
+## Uninstalling
+
+Remove the symlinks:
+
+```bash
+rm ~/.claude/skills/tradeblocks-*
+rm ~/.codex/skills/tradeblocks-*
+rm ~/.gemini/skills/tradeblocks-*
+```

package/agent-skills/README.md

@@ -0,0 +1,115 @@
+# TradeBlocks Agent Skills
+
+Conversational workflows for options trading analysis. These skills guide AI agents through structured analysis processes using the TradeBlocks MCP server.
+
+**Compatible with:** Claude Code, Codex CLI, Gemini CLI
+
+## What Are Skills?
+
+Skills are markdown files that teach AI agents how to perform specific tasks. They:
+
+- Guide conversation through structured analytical workflows
+- Ask clarifying questions to understand context
+- Use MCP tools to gather data and run analyses
+- Present results with educational context
+
+Skills do not execute code directly - they require the TradeBlocks MCP server for actual data access and calculations.
+
+## Available Skills
+
+| Skill | Purpose | Key MCP Tools Used |
+|-------|---------|-------------------|
+| `tradeblocks-health-check` | Strategy health evaluation - metrics, stress tests, risk indicators | `get_statistics`, `run_monte_carlo`, `get_tail_risk` |
+| `tradeblocks-wfa` | Walk-forward analysis - test parameter robustness on unseen data | `run_walk_forward` |
+| `tradeblocks-risk` | Risk assessment and position sizing | `calculate_position_sizing`, `get_tail_risk` |
+| `tradeblocks-compare` | Performance comparison - backtest vs actual, strategy correlations | `compare_backtest_vs_actual`, `calculate_correlation` |
+| `tradeblocks-portfolio` | Portfolio addition decisions - should I add this strategy? | `calculate_correlation`, `get_statistics` |
+| `tradeblocks-optimize` | Parameter optimization with overfitting awareness | `list_available_fields`, `aggregate_by_field` |
+
+## Prerequisites
+
+Before using these skills, you need:
+
+1. **TradeBlocks MCP server** configured and accessible
+2. **At least one block directory** containing your trade data (tradelog.csv required)
+3. **An AI agent** that supports skills (Claude Code, Codex CLI, or Gemini CLI)
+
+See [MCP Server Setup](../mcp-server/README.md) for server configuration.
+
+## Quick Start (Claude Code)
+
+```bash
+# Personal installation (available in all projects)
+ln -s /path/to/tradeblocks/packages/agent-skills/tradeblocks-* ~/.claude/skills/
+
+# Or project installation (shared via git)
+ln -s /path/to/tradeblocks/packages/agent-skills/tradeblocks-* .claude/skills/
+```
+
+Then invoke a skill by name:
+
+```
+/tradeblocks-health-check
+```
+
+## Usage Pattern
+
+Skills are conversational - they ask clarifying questions before diving into analysis:
+
+1. **Step 1**: Skill verifies MCP server connection
+2. **Step 2**: User selects what to analyze (block, strategy, etc.)
+3. **Step 3**: Skill gathers data and runs appropriate analyses
+4. **Step 4**: Results presented with educational context
+5. **Step 5**: Related skills suggested for further exploration
+
+Example conversation:
+```
+User: /tradeblocks-health-check
+
+Agent: Let me check which backtests are available...
+       [lists available blocks]
+       Which backtest would you like to analyze?
+
+User: SPX-Iron-Condor
+
+Agent: [runs get_statistics, run_monte_carlo, get_tail_risk]
+       Here's the health check for SPX-Iron-Condor:
+       ...
+```
+
+## Installation Script
+
+For convenience, use the installation script:
+
+```bash
+cd packages/agent-skills
+./install.sh claude    # Install to Claude Code
+./install.sh codex     # Install to Codex CLI
+./install.sh gemini    # Install to Gemini CLI
+./install.sh all       # Install to all platforms
+```
+
+## See Also
+
+- [Detailed Installation Guide](INSTALL.md) - Instructions for all platforms
+- [MCP Server for Claude Desktop](../mcp-server/README.md) - Desktop Extension installation
+
+## Skill Development
+
+Each skill follows this structure:
+
+```
+tradeblocks-{name}/
+  SKILL.md           # Main skill definition (YAML frontmatter + markdown)
+  references/        # Supporting educational materials
+    {topic}.md
+```
+
+The `SKILL.md` file contains:
+- YAML frontmatter with `name` and `description`
+- Prerequisites section
+- Step-by-step process
+- Interpretation guidance
+- Related skills
+
+Reference files provide deeper educational content that agents can consult when users need more explanation.

package/agent-skills/index.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0.0",
+  "skills": [
+    "tradeblocks-health-check",
+    "tradeblocks-wfa",
+    "tradeblocks-risk",
+    "tradeblocks-compare",
+    "tradeblocks-portfolio",
+    "tradeblocks-optimize"
+  ],
+  "platforms": {
+    "claude": ".claude/skills",
+    "codex": ".codex/skills",
+    "gemini": ".gemini/skills"
+  }
+}

package/agent-skills/install.ps1

@@ -0,0 +1,77 @@
+# Install TradeBlocks skills for Claude Code, Codex CLI, or Gemini CLI (Windows)
+# Usage: .\install.ps1 <platform>
+# Platforms: claude, codex, gemini, all
+
+param(
+    [Parameter(Position=0)]
+    [ValidateSet("claude", "codex", "gemini", "all")]
+    [string]$Platform
+)
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$Skills = @(
+    "tradeblocks-health-check",
+    "tradeblocks-wfa",
+    "tradeblocks-risk",
+    "tradeblocks-compare",
+    "tradeblocks-portfolio",
+    "tradeblocks-optimize"
+)
+
+function Show-Usage {
+    Write-Host "Usage: .\install.ps1 <platform>"
+    Write-Host ""
+    Write-Host "Platforms:"
+    Write-Host "  claude    Install to ~\.claude\skills\"
+    Write-Host "  codex     Install to ~\.codex\skills\"
+    Write-Host "  gemini    Install to ~\.gemini\skills\"
+    Write-Host "  all       Install to all platforms"
+    Write-Host ""
+    Write-Host "Example:"
+    Write-Host "  .\install.ps1 claude"
+    exit 1
+}
+
+function Install-Skills {
+    param([string]$PlatformName)
+
+    $TargetDir = Join-Path $env:USERPROFILE ".$PlatformName\skills"
+
+    Write-Host "Installing skills to $TargetDir..."
+
+    if (-not (Test-Path $TargetDir)) {
+        New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
+    }
+
+    foreach ($Skill in $Skills) {
+        $Source = Join-Path $ScriptDir $Skill
+        $Target = Join-Path $TargetDir $Skill
+
+        if (Test-Path $Target) {
+            Write-Host "  Updating: $Skill"
+            Remove-Item -Recurse -Force $Target
+        } else {
+            Write-Host "  Installing: $Skill"
+        }
+
+        Copy-Item -Recurse $Source $Target
+    }
+
+    Write-Host ""
+    Write-Host "Done! Verify with: Get-ChildItem $TargetDir"
+}
+
+if (-not $Platform) {
+    Show-Usage
+}
+
+switch ($Platform) {
+    "all" {
+        Install-Skills "claude"
+        Install-Skills "codex"
+        Install-Skills "gemini"
+    }
+    default {
+        Install-Skills $Platform
+    }
+}