{
  "markdown": "# Sentinel Execution MCP\n\n![CI](https://github.com/rohith1125/sentinel-execution-mcp/actions/workflows/ci.yml/badge.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n**A production-grade algorithmic trading control plane exposed as an MCP server — so Claude can manage watchlists, classify market regimes, validate risk, and submit paper orders through natural language.**\n\n---\n\n## What It Is\n\nSentinel is a two-package monorepo:\n\n| Package | Language | Role |\n|---|---|---|\n| `packages/engine` | Python 3.12 / FastAPI | All trading logic: risk checks, regime classification, order lifecycle, audit journal, strategy governance |\n| `packages/mcp` | TypeScript / Node 20 | Thin MCP server that routes 40+ tools to the engine via HTTP. Zero trading logic lives here. |\n\nClaude (or any MCP-compatible agent) talks to the MCP server. The MCP server talks to the engine. The engine owns the database and cache.\n\n---\n\n## Architecture\n\n```\n  Claude Desktop (or any MCP agent)\n           │\n           │  MCP protocol (stdio or SSE)\n           ▼\n  ┌─────────────────────────┐\n  │   MCP Server            │  TypeScript · Zod validation · tool routing\n  │   (packages/mcp)        │\n  └────────────┬────────────┘\n               │  HTTP REST (localhost:8100)\n               ▼\n  ┌─────────────────────────┐\n  │   Engine API            │  Python · FastAPI · all trading logic\n  │   (packages/engine)     │\n  └──────────┬──────────────┘\n             │\n     ┌───────┴────────┐\n     ▼                ▼\n PostgreSQL          Redis\n (orders,           (kill switch,\n  positions,         rate limits,\n  strategies,        cache)\n  audit log)\n```\n\nIf the engine is unavailable, every MCP tool call returns an error immediately. There is no fallback or partial execution.\n\n---\n\n## Quick Start (Docker — recommended)\n\nThe fastest way to get running. Requires [Docker](https://docs.docker.com/get-docker/) and [Node.js 20+](https://nodejs.org).\n\n```bash\n# 1. Clone and configure\ngit clone https://github.com/rohith1125/sentinel-execution-mcp.git\ncd sentinel-execution-mcp\ncp .env.example .env          # defaults work out of the box — no edits needed\n\n# 2. Start Postgres + Redis + engine (runs migrations automatically)\ndocker compose -f docker/docker-compose.yml up -d db redis engine\n\n# Wait ~10 seconds, then verify the engine is healthy:\ncurl http://localhost:8100/health\n# {\"status\": \"ok\", \"provider\": \"mock\", ...}\n\n# 3. Build the MCP server (one-time)\ncd packages/mcp\nnpm install\nnpm run build\n```\n\nThen add Sentinel to Claude Desktop (see [Connect Claude Desktop](#connect-claude-desktop) below) and restart Claude. That's it — all 40 tools are live.\n\n---\n\n## Manual Setup (no Docker)\n\nUse this if you have Postgres and Redis already running locally.\n\n**Prerequisites:**\n\n| Dependency | Minimum version | Notes |\n|---|---|---|\n| Python | 3.12 | Engine runtime — check with `python3 --version` |\n| Node.js | 20 | MCP server runtime |\n| PostgreSQL | 15+ | Primary data store |\n| Redis | 7+ | Kill switch and cache |\n\n### 1. Clone and configure\n\n```bash\ngit clone https://github.com/rohith1125/sentinel-execution-mcp.git\ncd sentinel-execution-mcp\ncp .env.example .env\n# Default values work for local paper-trading development — no edits required\n```\n\n### 2. Set up the engine\n\n```bash\ncd packages/engine\npython3.12 -m venv .venv\nsource .venv/bin/activate        # Windows: .venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n### 3. Run database migrations\n\n```bash\n# From packages/engine with the venv active\nalembic upgrade head\n```\n\n### 4. Start the engine\n\n```bash\nuvicorn sentinel.api:app --reload --port 8100\n```\n\nVerify it is running:\n\n```bash\ncurl http://localhost:8100/health\n# {\"status\": \"ok\", \"env\": \"paper\"}\n```\n\n### 5. Build and start the MCP server\n\nOpen a second terminal:\n\n```bash\ncd packages/mcp\nnpm install\nnpm run build\nnpm run dev     # stdio transport — for direct Claude Desktop integration\n```\n\n---\n\n## Connect Claude Desktop\n\nAdd the following to your Claude Desktop configuration file.\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nGet the correct path by running this in your terminal:\n```bash\necho \"$(pwd)/packages/mcp/dist/index.js\"\n```\n\nThen paste it into the config:\n\n```json\n{\n  \"mcpServers\": {\n    \"sentinel\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/sentinel-execution-mcp/packages/mcp/dist/index.js\"],\n      \"env\": {\n        \"ENGINE_BASE_URL\": \"http://localhost:8100\",\n        \"APP_ENV\": \"paper\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving. You should see a hammer icon (🔨) in the chat input — click it to confirm Sentinel's 40 tools are loaded.\n\n---\n\n## MCP Tools Reference\n\nSentinel exposes **40+ tools** across nine categories. The MCP server name is `sentinel`.\n\n| Category | Tool | Description |\n|---|---|---|\n| **Watchlist** | `watchlist.add` | Add symbols to the trading watchlist, optionally assigned to a group |\n| | `watchlist.remove` | Remove symbols; they will no longer appear in strategy scans |\n| | `watchlist.list` | List active symbols, optionally filtered by group |\n| | `watchlist.get` | Get details for a single symbol |\n| | `watchlist.groups` | List all named watchlist groups |\n| | `watchlist.update` | Update notes or group assignment for a symbol |\n| **Market Data** | `market.snapshot` | Latest quote and trade data for one or more symbols |\n| | `market.bars` | OHLCV bar history with configurable timeframe |\n| | `market.quote` | Real-time bid/ask spread for a symbol |\n| | `market.health` | Check market data provider connectivity |\n| **Regime** | `regime.evaluate` | Classify current market regime using ATR, ADX, RSI, Bollinger Width, Hurst Exponent, VWAP, and Price Efficiency |\n| | `regime.history` | Retrieve historical regime snapshots for a symbol |\n| **Strategy** | `strategy.scan` | Scan the watchlist for signals across one or more strategies |\n| | `strategy.signal` | Evaluate a single symbol against a specific strategy |\n| | `strategy.list` | List all registered strategies and their current state |\n| **Risk / Kill Switch** | `risk.validate_trade` | Run all 13+ risk checks against a proposed trade before submission |\n| | `risk.kill_switch_status` | Get the current state of all kill switches |\n| | `risk.kill_switch_enable` | Enable a kill switch globally, per-strategy, or per-symbol |\n| | `risk.kill_switch_disable` | Disable a kill switch (requires explicit reason) |\n| | `risk.exposure` | Current gross and net exposure summary |\n| | `risk.drawdown` | Current daily drawdown against configured limits |\n| **Portfolio** | `portfolio.status` | Full account overview: value, cash, equity, P&L, buying power |\n| | `portfolio.positions` | All open positions with unrealized P&L |\n| | `portfolio.history` | Closed position history with realized P&L |\n| **Execution** | `execution.paper_order` | Submit a paper trading order (market, limit, stop, stop-limit) |\n| | `execution.cancel_order` | Cancel a pending or partially filled order by ID |\n| | `execution.get_order` | Get the current state of a specific order |\n| | `execution.list_orders` | List orders filtered by status, symbol, or date range |\n| | `execution.reconcile` | Trigger a manual reconciliation between engine state and broker |\n| **Governance** | `governance.create_strategy` | Register a new strategy in `draft` state |\n| | `governance.promote_strategy` | Advance a strategy: Draft → Research → Backtest → Paper → Live |\n| | `governance.suspend_strategy` | Suspend a live or paper strategy immediately |\n| | `governance.list_strategies` | List all strategies with their current lifecycle state |\n| | `governance.evaluate_promotion` | Check whether a strategy meets criteria for promotion |\n| **Audit** | `audit.explain_trade` | Full human-readable explanation for a trade decision by audit event ID |\n| | `audit.recent_events` | Most recent audit events, filterable by symbol or strategy |\n| | `audit.trade_history` | Completed trade history with outcomes |\n| | `audit.decision_log` | Raw decision log entries for a time window |\n| | `audit.stats` | Aggregate statistics: win rate, average P&L, Sharpe proxy |\n| | `audit.export` | Export audit records as CSV for a date range |\n\nFull tool documentation with parameter schemas: [docs/mcp-tools.md](docs/mcp-tools.md)\n\n---\n\n## Environment Variables\n\n### Engine (`packages/engine/.env`)\n\n| Variable | Default | Description |\n|---|---|---|\n| `APP_ENV` | `paper` | `development`, `paper`, or `live` |\n| `DATABASE_URL` | `postgresql+asyncpg://sentinel:sentinel@localhost:5432/sentinel` | PostgreSQL connection string |\n| `REDIS_URL` | `redis://localhost:6379/0` | Redis connection string |\n| `MARKET_DATA_PROVIDER` | `mock` | `mock` (no credentials needed) or `alpaca` |\n| `ALPACA_API_KEY` | _(empty)_ | Required when `MARKET_DATA_PROVIDER=alpaca` |\n| `ALPACA_API_SECRET` | _(empty)_ | Required when `MARKET_DATA_PROVIDER=alpaca` |\n| `ALPACA_BASE_URL` | `https://paper-api.alpaca.markets` | Use `https://api.alpaca.markets` for live trading |\n| `MAX_POSITION_PCT` | `0.05` | Maximum position size as a fraction of account equity (5%) |\n| `MAX_DAILY_DRAWDOWN_PCT` | `0.02` | Hard daily loss limit (2%); trading halts if breached |\n| `MAX_GROSS_EXPOSURE_PCT` | `0.80` | Maximum gross exposure across all positions (80%) |\n| `MAX_CONCURRENT_POSITIONS` | `10` | Maximum number of simultaneously open positions |\n| `MAX_TRADE_RISK_PCT` | `0.01` | Maximum risk per individual trade (1%) |\n| `PAPER_FILL_LATENCY_MS` | `50` | Simulated fill latency in paper trading mode |\n| `SLIPPAGE_BPS` | `5` | Simulated slippage in basis points |\n| `SENTINEL_AUTH_ENABLED` | `true` | Set to `false` for local development only |\n| `SENTINEL_MASTER_KEY` | _(empty)_ | Generate with `python -m sentinel.auth.cli generate --name master --scopes admin` |\n| `SENTINEL_API_KEYS_JSON` | _(empty)_ | JSON array of additional client key records |\n\n### MCP Server (`packages/mcp/.env`)\n\n| Variable | Default | Description |\n|---|---|---|\n| `ENGINE_BASE_URL` | `http://localhost:8100` | Base URL of the running engine service |\n\nSee `.env.example` at the repo root for the complete annotated reference.\n\n---\n\n## Example Workflow (Paper Trading)\n\n```\n# 1. Add symbols\nwatchlist.add(symbols=[\"NVDA\", \"MSFT\", \"AAPL\"], group=\"tech\")\n\n# 2. Classify regime\nregime.evaluate(symbol=\"NVDA\", timeframe=\"1Day\")\n\n# 3. Scan for signals\nstrategy.scan(group=\"tech\", strategy=\"momentum_v1\")\n\n# 4. Validate before submitting\nrisk.validate_trade(symbol=\"NVDA\", side=\"buy\", qty=10, order_type=\"market\")\n\n# 5. Submit paper order\nexecution.paper_order(symbol=\"NVDA\", side=\"buy\", qty=10, order_type=\"market\")\n\n# 6. Review portfolio\nportfolio.status()\n\n# 7. Inspect the audit trail\naudit.recent_events(symbol=\"NVDA\", limit=1)\naudit.explain_trade(audit_event_id=\"evt-...\")\n```\n\n---\n\n## Running Tests\n\n### Engine (Python)\n\n```bash\ncd packages/engine\nsource .venv/bin/activate\npytest tests/ -v\n```\n\n### MCP Server (TypeScript)\n\n```bash\ncd packages/mcp\npnpm test\n```\n\n### Full CI (lint + type check + test)\n\n```bash\n# From repo root\nmake check\n```\n\n---\n\n## Repository Structure\n\n```\nsentinel-execution-mcp/\n├── packages/\n│   ├── engine/          # Python FastAPI trading engine\n│   │   ├── sentinel/    # Application source\n│   │   ├── tests/       # Pytest test suite\n│   │   └── alembic/     # Database migrations\n│   └── mcp/             # TypeScript MCP server\n│       └── src/\n│           └── tools/   # One file per tool category\n├── docker/              # Dockerfiles and docker-compose\n├── docs/                # Architecture, tool reference, risk model\n├── scripts/             # Setup and reset helpers\n└── .env.example         # Annotated environment variable reference\n```\n\n---\n\n## Safety Disclaimer\n\nThis software is for **paper trading and research only** unless you fully understand every component. Setting `APP_ENV=live` with real Alpaca credentials will place real orders with real money. The hard-coded risk limits are conservative defaults — verify they match your own risk tolerance before use. The authors accept no liability for financial losses.\n\n---\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 12188,
  "sha": "c6af2cc238e581e983ddba9a7688fdf94cd7e6cad7d18496ebfdf22515002f61",
  "repo_slug": "rohith1125/sentinel-execution-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rohith1125_sentinel_execution__881aad68/readme"
}