<p align="center">
  <img src="img/SigmaPilot-light-mode.png" alt="SigmaPilot Logo" width="400">
</p>

# SigmaPilot MCP Server v2.3

A remote Model Context Protocol (MCP) server for real-time cryptocurrency and stock market analysis. Provides AI-powered market intelligence tools with 9 theory-based analysis engines, multi-chain DEX discovery, and enterprise features. Deployable to Railway with Auth0 authentication.

## Features

### Market Scanners (6 tools)
- **Top Gainers/Losers Scanner** - Find best and worst performing assets across exchanges
- **Bollinger Scanner** - Detect squeeze patterns for potential breakouts
- **Rating Scanner** - Filter assets by Bollinger Band position (-3 to +3 rating)
- **Volume Scanner** - Find high-volume breakouts with RSI filtering
- **Pivot Points Scanner** - Find assets near key pivot levels (Classic/Fibonacci/Camarilla)

### Technical Analysis (10 tools)
- **Basic TA Analyzer** - Comprehensive indicator snapshot (Bollinger Bands, Moving Averages, Oscillators, Ichimoku, Pivot Points, MACD, ADX, VWAP, and more)
- **Dow Theory Analyzer** - Primary trend identification via higher highs/lows analysis
- **Ichimoku Analyzer** - Cloud analysis, TK crosses, Chikou confirmation
- **VSA Analyzer** - Volume Spread Analysis for smart money signal detection
- **Chart Pattern Analyzer** - Classical patterns (Head & Shoulders, Double Top/Bottom, Triangles)
- **Wyckoff Analyzer** - Accumulation/Distribution phase detection with event identification
- **Elliott Wave Analyzer** - Wave pattern identification and counting with rule validation
- **Chan Theory Analyzer** - Chanlun fractal, stroke, and hub analysis (缠论)
- **Harmonic Analyzer** - Gartley, Bat, Butterfly, Crab pattern detection with PRZ levels
- **Market Profile Analyzer** - POC, Value Area (VAH/VAL), profile shape analysis

### DEX Discovery (1 tool)
- **Memecoin Discovery** - Find trending, new, or high-volume tokens across DEX networks via GeckoTerminal

### Standardized Output
All theory-based analyzers return structured JSON with:
- **Confidence scoring** (0-100) using a standardized formula
- **No Signal protocol** - Returns neutral when confidence is below threshold, preventing weak signals
- **Attribution** - Theory name, triggered rules, and invalidation levels
- **LLM-ready summaries** for natural language responses

### Supported Markets

| Market Type | Sources |
|-------------|---------|
| Crypto (CEX) | Binance, Bybit, Bitget, OKX, Coinbase, Gate.io, MEXC |
| Crypto (DEX) | Solana, BSC, Ethereum, Base, Polygon, Arbitrum, Avalanche, Optimism, Tron, and more |
| US Stocks | NASDAQ, NYSE |
| UK Stocks | LSE (London Stock Exchange) |
| Hong Kong Stocks | HKEX, HSI |

**Data Sources:**
- **TradingView** - CEX crypto, stocks, and indices
- **GeckoTerminal** - Multi-chain DEX data (200+ networks)

### Timeframes
`5m` `15m` `1h` `4h` `1D` `1W` `1M`

> Note: DEX data via GeckoTerminal supports up to `1W`. Monthly (`1M`) is CEX-only.

## Quick Start

### Option 1: Remote Deployment (Recommended)

Deploy as a secure remote MCP server with Auth0 authentication. Once deployed, connect from **any MCP-compatible AI platform**:
- **Claude.ai** - Via [Connectors](https://claude.ai/settings/connectors) ([documentation](https://support.claude.com/en/articles/11724452-using-the-connectors-directory-to-extend-claude-s-capabilities))
- **ChatGPT** - Via MCP plugin support
- **Other AI platforms** - Any service supporting MCP protocol

#### Prerequisites
- [Railway account](https://railway.app/) (free tier available)
- [Auth0 account](https://auth0.com/) (free tier available)
- GitHub account

#### Deploy Steps

1. **Fork/Clone this repository to GitHub**

2. **Set up Auth0**
   - Create account at [auth0.com](https://auth0.com)
   - Create API: Dashboard > Applications > APIs > Create API
   - Note your `Domain` and `API Identifier`

3. **Deploy to Railway**
   - Connect your GitHub repo to Railway
   - Add environment variables:
     ```
     AUTH0_DOMAIN=your-tenant.auth0.com
     AUTH0_AUDIENCE=https://your-api-identifier
     RESOURCE_SERVER_URL=https://your-app.up.railway.app/mcp
     ```
   - The included `Procfile` handles the `--auth` flag for production automatically.

   **Optional Configuration** (environment variables):
   ```
   # Database (enables user management, quotas, activity logging)
   DATABASE_URL=postgresql://user:pass@host:5432/dbname

   # Cache settings (timeframe-specific TTL is used by default)
   OHLCV_CACHE_TTL_SECONDS=60      # Default cache TTL in seconds
   OHLCV_CACHE_STANDARD_BARS=300   # Standard bar count to fetch
   OHLCV_CACHE_ENABLED=true        # Enable/disable caching

   # Analysis settings
   SIGMAPILOT_SIGNAL_THRESHOLD=50  # Minimum confidence for signal (default: 50)

   # Admin
   ADMIN_USER_IDS=uuid1,uuid2      # Auto-promote these user IDs to admin on login
   ```

   **Note:** Cache uses timeframe-specific TTL automatically:
   - 5m: 90s, 15m: 3min, 1h: 10min, 4h: 30min, 1D: 2hr, 1W: 12hr

4. **Connect to AI Platform**

   **Claude.ai (Web):**
   - Go to [claude.ai/settings/connectors](https://claude.ai/settings/connectors)
   - Add your MCP server URL: `https://your-app.up.railway.app/mcp`
   - Authenticate with Auth0 when prompted

   **Claude Desktop:**
   ```json
   {
     "mcpServers": {
       "sigmapilot": {
         "url": "https://your-app.up.railway.app/mcp",
         "transport": "streamable-http"
       }
     }
   }
   ```

See [Remote Deployment Guide](docs/REMOTE_DEPLOYMENT.md) for detailed instructions.

### Option 2: Local Installation

For local development or direct Claude Desktop connection (stdio mode).

1. **Install UV Package Manager:**
   ```bash
   # macOS
   brew install uv

   # Windows
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

   # Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

2. **Add to Claude Desktop config:**

   Config location:
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "sigmapilot-mcp": {
         "command": "uv",
         "args": [
           "tool", "run", "--from",
           "git+https://github.com/SigmaPilotAI/sigmapilot-mcp.git",
           "sigmapilot-mcp"
         ]
       }
     }
   }
   ```

3. **Restart Claude Desktop**

## Available Tools (17 Total)

### Market Scanners (6)

| Tool | Description |
|------|-------------|
| `top_gainers_scanner` | Top performing assets by exchange/timeframe |
| `top_losers_scanner` | Worst performing assets by exchange/timeframe |
| `bollinger_scanner` | Find assets with Bollinger Band squeeze (low BBW) |
| `rating_scanner` | Filter by Bollinger Band rating (-3 to +3) |
| `volume_scanner` | Volume breakout detection with optional RSI filtering |
| `pivot_points_scanner` | Find assets near pivot point levels (Classic/Fibonacci/Camarilla) |

### Analyzers (10)

| Tool | Description | DEX Support |
|------|-------------|-------------|
| `basic_ta_analyzer` | Versioned raw indicator snapshot (`basic_ta.v1`: BB, MA, RSI, MACD, Ichimoku, Pivots, Volume) | No (CEX only) |
| `dow_theory_analyzer` | Trend analysis via higher highs/higher lows patterns | Yes |
| `ichimoku_analyzer` | Ichimoku Kinko Hyo (cloud position, TK cross, Chikou span) | Yes |
| `vsa_analyzer` | Volume Spread Analysis - smart money signals | Yes |
| `chart_pattern_analyzer` | Classical patterns (H&S, triangles, double top/bottom) | Yes |
| `wyckoff_analyzer` | Wyckoff phases (accumulation, distribution, markup, markdown) | Yes |
| `elliott_wave_analyzer` | Elliott Wave impulse/corrective pattern analysis | Yes |
| `chan_theory_analyzer` | Chan Theory/Chanlun (fractals, strokes, segments, hubs) | Yes |
| `harmonic_analyzer` | Harmonic patterns (Gartley, Bat, Butterfly, Crab) with PRZ | Yes |
| `market_profile_analyzer` | Market Profile (POC, Value Area, profile shape) | Yes |

### DEX Discovery (1)

| Tool | Description |
|------|-------------|
| `memecoin_discovery` | Discover trending/new/high-volume tokens across DEX networks |

## Output & Validation Notes

- Theory-based analyzers return a standardized `AnalysisResult` with `status`, `confidence`, `attribution`, `llm_summary`, `invalidation`, `is_error`, and optional `timing` metadata for confirmed pivot/fractal methods.
- `basic_ta_analyzer` intentionally returns a raw TradingView indicator payload instead of `AnalysisResult`; success and error payloads now include `schema_version="basic_ta.v1"`, `tool`, `analysis_type`, and `is_error`.
- OHLCV bars are validated before analysis: non-finite values, negative prices, negative volume, and impossible high/low relationships are rejected.
- MCP enum inputs such as analyzer `mode`, volume scan filters, and pivot scan filters are validated before market data is fetched.

## Example Queries

```
"Show me top 10 crypto gainers on Binance in the last 15 minutes"
"Find coins with Bollinger Band squeeze on Binance"
"Analyze BTCUSDT with basic technical indicators"
"Show volume breakouts on Bybit with RSI oversold filter"
"Analyze ETHUSDT using Dow Theory on the daily timeframe"
"Check Ichimoku signals for BTCUSDT on 4h"
"Find Wyckoff accumulation patterns on SOLUSDT"
"Detect harmonic patterns on BTCUSDT 4h chart"
"Find trending memecoins on Solana"
"Discover new tokens on Base with at least $50k liquidity"
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     AI Platforms                             │
│  Claude.ai  │  ChatGPT  │  Claude Desktop  │  Other MCP    │
└──────┬──────┴─────┬─────┴───────┬──────────┴───────┬───────┘
       │ HTTPS+OAuth│             │ stdio            │
       ▼            ▼             ▼                  ▼
┌─────────────────────────────────────────────────────────────┐
│                    SigmaPilot MCP Server                     │
│  ┌───────────┐  ┌──────────────┐  ┌───────────────────────┐│
│  │ Scanners  │  │  Analyzers   │  │   DEX Discovery       ││
│  │ (6 tools) │  │  (10 tools)  │  │   (1 tool)            ││
│  └─────┬─────┘  └──────┬───────┘  └──────────┬────────────┘│
│        │               │                      │             │
│  ┌─────▼───────────────▼──────────────────────▼───────────┐│
│  │              Core Infrastructure                        ││
│  │  Confidence Scoring │ Caching │ Rate Limiting │ Schemas ││
│  └─────┬───────────────────────────────────────┬──────────┘│
│        │                                       │            │
│  ┌─────▼─────────────┐  ┌─────────────────────▼──────────┐│
│  │  Auth0 + Middleware│  │       PostgreSQL (optional)    ││
│  │  JWT Verification  │  │  Users │ Quotas │ Activity Log ││
│  └───────────────────┘  └────────────────────────────────┘│
└────────┬───────────────────────────────┬──────────────────┘
         │                               │
   ┌─────▼─────────────┐   ┌────────────▼────────────────┐
   │    TradingView     │   │       GeckoTerminal         │
   │  CEX + Stocks      │   │  DEX (Solana, BSC, ETH...) │
   └───────────────────┘   └─────────────────────────────┘
```

## Enterprise Features

When deployed with a PostgreSQL database (`DATABASE_URL`), the server provides:

### User Management & Admin Dashboard
- **Auto-Registration** - Users created automatically on first Auth0 login
- **Admin Dashboard** - Web UI at `/admin` for user management
- **Admin Auto-Setup** - Configure `ADMIN_USER_IDS` env var to auto-promote admins
- **User Revocation** - Revoke/restore user access with reason tracking and audit logging
- **Activity Logging** - Full audit trail of all tool calls with timing and error tracking

### Quota & Rate Limiting
- **Subscription Tiers** - Free/Pro/Enterprise with configurable limits
- **Usage Tracking** - Per-user request counting with per-tool breakdown
- **Rate Limiting** - Configurable requests per minute/hour limits
- **Graceful Degradation** - Continues serving if database is temporarily unavailable

### Risk Controls
- **IP/Email/User Blocking** - Block suspicious actors by multiple identifiers
- **Audit Events** - Comprehensive security event logging
- **User Status Management** - Active/Suspended/Revoked states

## Development

```bash
# Clone and install
git clone https://github.com/SigmaPilotAI/sigmapilot-mcp.git
cd sigmapilot-mcp
uv sync --dev

# Run tests
make test

# Run with coverage
make test-cov

# Lint and format
make lint
make format

# Typecheck uses local third-party stubs from typings/
uv run mypy src/

# Run locally (stdio mode for Claude Desktop)
uv run python src/sigmapilot_mcp/server.py

# Run as HTTP server (development mode, no auth)
uv run python src/sigmapilot_mcp/server.py streamable-http --port 8000

# Run as HTTP server with Auth0 authentication
AUTH0_DOMAIN=your-tenant.auth0.com AUTH0_AUDIENCE=https://your-api \
  uv run python src/sigmapilot_mcp/server.py streamable-http --auth
```

## Documentation

- [Architecture Overview](docs/architecture.md) - System design, data flow, key decisions
- [Remote Deployment Guide](docs/REMOTE_DEPLOYMENT.md) - Railway + Auth0 setup
- [Installation Guide](docs/INSTALLATION.md) - Local setup and configuration
- [Usage Examples](docs/EXAMPLES.md) - All 17 tools with sample inputs/outputs
- [Migration Guide](docs/MIGRATION.md) - Upgrading from v1.x to v2.x
- [Contributing](docs/CONTRIBUTING.md) - Development guidelines and standards
- [Development TODO](docs/TODO.md) - Roadmap and known limitations

Shared agent guidance can be committed under `.claude/agent.md`, `.claude/AGENT.md`, `.claude/agents.md`, `.claude/AGENTS.md`, and `.claude/skills/**`. Keep secrets and editor-local state out of those files.

## License

Proprietary - see [LICENSE](LICENSE)

## Support

- [GitHub Issues](https://github.com/SigmaPilotAI/sigmapilot-mcp/issues)