sentinel-execution-mcp

Sentinel Execution MCP

一个生产级算法交易控制平面，以 MCP 服务的形式提供——让 Claude 能够通过自然语言管理关注列表、分类市场状态、验证风险并提交模拟订单。

---

它是什么

Sentinel 是一个由两个软件包组成的单体仓库：

软件包	语言	作用
packages/engine	Python 3.12 / FastAPI	所有交易逻辑：风险检查、市场状态分类、订单生命周期、审计日志、策略治理
packages/mcp	TypeScript / Node 20	轻量 MCP 服务，通过 HTTP 将 40 多个工具路由至引擎。所有交易逻辑均不在此处。

Claude（或任何兼容 MCP 的 Agent）与 MCP 服务交互。MCP 服务与引擎交互。数据库和缓存由引擎管理。

---

架构

  Claude Desktop (or any MCP agent)
           │
           │  MCP protocol (stdio or SSE)
           ▼
  ┌─────────────────────────┐
  │   MCP Server            │  TypeScript · Zod validation · tool routing
  │   (packages/mcp)        │
  └────────────┬────────────┘
               │  HTTP REST (localhost:8100)
               ▼
  ┌─────────────────────────┐
  │   Engine API            │  Python · FastAPI · all trading logic
  │   (packages/engine)     │
  └──────────┬──────────────┘
             │
     ┌───────┴────────┐
     ▼                ▼
 PostgreSQL          Redis
 (orders,           (kill switch,
  positions,         rate limits,
  strategies,        cache)
  audit log)

如果引擎不可用，每次 MCP 工具调用都会立即返回错误。没有回退或部分执行。

---

快速开始（推荐使用 Docker）

最快的启动方式。需要 Docker 和 Node.js 20+。

# 1. Clone and configure
git clone https://github.com/rohith1125/sentinel-execution-mcp.git
cd sentinel-execution-mcp
cp .env.example .env          # defaults work out of the box — no edits needed

# 2. Start Postgres + Redis + engine (runs migrations automatically)
docker compose -f docker/docker-compose.yml up -d db redis engine

# Wait ~10 seconds, then verify the engine is healthy:
curl http://localhost:8100/health
# {"status": "ok", "provider": "mock", ...}

# 3. Build the MCP server (one-time)
cd packages/mcp
npm install
npm run build

然后将 Sentinel 添加到 Claude Desktop（参见下文的连接 Claude Desktop），并重启 Claude。就这么简单——全部 40 个工具现已启用。

---

手动设置（不使用 Docker）

如果你已经在本地运行 Postgres 和 Redis，请使用此方式。

前置条件：

依赖项	最低版本	说明
Python	3.12	引擎运行环境——使用 python3 --version 检查
Node.js	20	MCP 服务运行环境
PostgreSQL	15+	主数据存储
Redis	7+	紧急停止开关和缓存

1. 克隆并配置

git clone https://github.com/rohith1125/sentinel-execution-mcp.git
cd sentinel-execution-mcp
cp .env.example .env
# Default values work for local paper-trading development — no edits required

2. 设置引擎

cd packages/engine
python3.12 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

3. 运行数据库迁移

# From packages/engine with the venv active
alembic upgrade head

4. 启动引擎

uvicorn sentinel.api:app --reload --port 8100

确认引擎正在运行：

curl http://localhost:8100/health
# {"status": "ok", "env": "paper"}

5. 构建并启动 MCP 服务

打开第二个终端：

cd packages/mcp
npm install
npm run build
npm run dev     # stdio transport — for direct Claude Desktop integration

---

连接 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中。

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

在终端中运行以下命令，获取正确的路径：

echo "$(pwd)/packages/mcp/dist/index.js"

然后将其粘贴到配置文件中：

{
  "mcpServers": {
    "sentinel": {
      "command": "node",
      "args": ["/absolute/path/to/sentinel-execution-mcp/packages/mcp/dist/index.js"],
      "env": {
        "ENGINE_BASE_URL": "http://localhost:8100",
        "APP_ENV": "paper"
      }
    }
  }
}

保存后重启 Claude Desktop。你应该会在聊天输入框中看到锤子图标（🔨）——点击它，确认已加载 Sentinel 的 40 个工具。

---

MCP 工具参考

Sentinel 在九个类别中提供 40+ 个工具。MCP 服务名称为 sentinel。

类别	工具	描述
自选列表	watchlist.add	将代码添加到交易自选列表，可选择分配到某个分组
	watchlist.remove	移除代码；移除后，这些代码将不再出现在策略扫描中
	watchlist.list	列出活跃代码，可选择按分组筛选
	watchlist.get	获取单个代码的详细信息
	watchlist.groups	列出所有命名的自选列表分组
	watchlist.update	更新代码的备注或分组分配
市场数据	market.snapshot	一个或多个代码的最新报价和交易数据
	market.bars	可配置时间范围的 OHLCV 柱线历史数据
	market.quote	某个代码的实时买卖价差
	market.health	检查市场数据提供方的连接状态
市场状态	regime.evaluate	使用 ATR、ADX、RSI、布林带宽度、赫斯特指数、VWAP 和价格效率对当前市场状态进行分类
	regime.history	获取某个代码的历史市场状态快照
策略	strategy.scan	扫描自选列表，查找一个或多个策略的信号
	strategy.signal	根据特定策略评估单个代码
	strategy.list	列出所有已注册策略及其当前状态
风险 / 熔断开关	risk.validate_trade	提交交易前，对拟议交易执行全部 13+ 项风险检查
	risk.kill_switch_status	获取所有熔断开关的当前状态
	risk.kill_switch_enable	全局、按策略或按代码启用熔断开关
	risk.kill_switch_disable	禁用熔断开关（需要明确说明原因）
	risk.exposure	当前总敞口和净敞口摘要
	risk.drawdown	当前每日回撤与配置限额的对比
投资组合	portfolio.status	完整账户概览：价值、现金、权益、盈亏、购买力
	portfolio.positions	所有未平仓头寸及未实现盈亏
	portfolio.history	已平仓头寸历史记录及已实现盈亏
执行	execution.paper_order	提交模拟交易订单（市价、限价、止损、止损限价）
	execution.cancel_order	按 ID 取消待处理或部分成交的订单
	execution.get_order	获取特定订单的当前状态
	execution.list_orders	按状态、代码或日期范围筛选并列出订单
	execution.reconcile	手动触发引擎状态与经纪商之间的对账
治理	governance.create_strategy	以 draft 状态注册新策略
	governance.promote_strategy	推进策略：Draft → Research → Backtest → Paper → Live
	governance.suspend_strategy	立即暂停实盘或模拟策略
	governance.list_strategies	列出所有策略及其当前生命周期状态
	governance.evaluate_promotion	检查策略是否符合晋级条件
审计	audit.explain_trade	根据审计事件 ID，提供交易决策的完整可读说明
	audit.recent_events	最近的审计事件，可按代码或策略筛选
	audit.trade_history	已完成交易的历史记录及结果
	audit.decision_log	指定时间范围内的原始决策日志条目
	audit.stats	汇总统计数据：胜率、平均盈亏、夏普比率近似值
	audit.export	将指定日期范围内的审计记录导出为 CSV

包含参数架构的完整工具文档：docs/mcp-tools.md

---

环境变量

引擎（packages/engine/.env）

变量	默认值	说明
APP_ENV	paper	development、paper 或 live
DATABASE_URL	postgresql+asyncpg://sentinel:sentinel@localhost:5432/sentinel	PostgreSQL 连接字符串
REDIS_URL	redis://localhost:6379/0	Redis 连接字符串
MARKET_DATA_PROVIDER	mock	mock（无需凭据）或 alpaca
ALPACA_API_KEY	(empty)	当 MARKET_DATA_PROVIDER=alpaca 时必需
ALPACA_API_SECRET	(empty)	当 MARKET_DATA_PROVIDER=alpaca 时必需
ALPACA_BASE_URL	https://paper-api.alpaca.markets	实盘交易请使用 https://api.alpaca.markets
MAX_POSITION_PCT	0.05	持仓规模上限，占账户权益的比例（5%）
MAX_DAILY_DRAWDOWN_PCT	0.02	每日硬性亏损限额（2%）；触及限额时停止交易
MAX_GROSS_EXPOSURE_PCT	0.80	所有持仓的总敞口上限（80%）
MAX_CONCURRENT_POSITIONS	10	同时持有的未平仓头寸数量上限
MAX_TRADE_RISK_PCT	0.01	单笔交易的风险上限（1%）
PAPER_FILL_LATENCY_MS	50	模拟纸面交易模式下的成交延迟
SLIPPAGE_BPS	5	以基点为单位的模拟滑点
SENTINEL_AUTH_ENABLED	true	仅用于本地开发时设为 false
SENTINEL_MASTER_KEY	(empty)	使用 python -m sentinel.auth.cli generate --name master --scopes admin 生成
SENTINEL_API_KEYS_JSON	(empty)	其他客户端密钥记录的 JSON 数组

MCP 服务（packages/mcp/.env）

变量	默认值	说明
ENGINE_BASE_URL	http://localhost:8100	正在运行的引擎服务的基本 URL

完整的注释说明请参阅仓库根目录下的 .env.example。

---

工作流示例（纸面交易）

# 1. Add symbols
watchlist.add(symbols=["NVDA", "MSFT", "AAPL"], group="tech")

# 2. Classify regime
regime.evaluate(symbol="NVDA", timeframe="1Day")

# 3. Scan for signals
strategy.scan(group="tech", strategy="momentum_v1")

# 4. Validate before submitting
risk.validate_trade(symbol="NVDA", side="buy", qty=10, order_type="market")

# 5. Submit paper order
execution.paper_order(symbol="NVDA", side="buy", qty=10, order_type="market")

# 6. Review portfolio
portfolio.status()

# 7. Inspect the audit trail
audit.recent_events(symbol="NVDA", limit=1)
audit.explain_trade(audit_event_id="evt-...")

---

运行测试

引擎（Python）

cd packages/engine
source .venv/bin/activate
pytest tests/ -v

MCP 服务（TypeScript）

cd packages/mcp
pnpm test

完整 CI（lint + 类型检查 + 测试）

# From repo root
make check

---

仓库结构

sentinel-execution-mcp/
├── packages/
│   ├── engine/          # Python FastAPI trading engine
│   │   ├── sentinel/    # Application source
│   │   ├── tests/       # Pytest test suite
│   │   └── alembic/     # Database migrations
│   └── mcp/             # TypeScript MCP server
│       └── src/
│           └── tools/   # One file per tool category
├── docker/              # Dockerfiles and docker-compose
├── docs/                # Architecture, tool reference, risk model
├── scripts/             # Setup and reset helpers
└── .env.example         # Annotated environment variable reference

---

安全免责声明

除非你完全了解每个组件，否则本软件仅用于纸面交易和研究。使用真实 Alpaca 凭据将 APP_ENV=live 设为实盘模式，会使用真实资金下达真实订单。硬编码的风险限额是较为保守的默认值——使用前请确认它们符合你自己的风险承受能力。作者对任何财务损失概不负责。

---

许可证

MIT。请参阅 LICENSE。