sentinel-execution-mcp

Sentinel Execution MCP

MCP サーバーとして公開される、本番環境向けのアルゴリズム取引コントロールプレーンです。Claude が自然言語を通じてウォッチリストを管理し、市場レジームを分類し、リスクを検証して、ペーパー注文を送信できます。

---

概要

Sentinel は、2 つのパッケージで構成されるモノレポです。

パッケージ	言語	役割
packages/engine	Python 3.12 / FastAPI	すべての取引ロジック：リスクチェック、レジーム分類、注文ライフサイクル、監査ジャーナル、戦略ガバナンス
packages/mcp	TypeScript / Node 20	HTTP 経由でエンジンに 40 以上のツールをルーティングする、薄型の MCP サーバーです。ここには取引ロジックは一切ありません。

Claude（または MCP 互換のエージェント）が 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 サーバーをビルドして起動する

2 つ目のターミナルを開きます。

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 は9つのカテゴリにわたり40以上のツールを提供します。MCP サーバー名は sentinel です。

カテゴリ	ツール	説明
ウォッチリスト	watchlist.add	取引ウォッチリストにシンボルを追加します。任意でグループに割り当てられます
	watchlist.remove	シンボルを削除します。削除されたシンボルは戦略スキャンに表示されなくなります
	watchlist.list	アクティブなシンボルを一覧表示します。任意でグループによる絞り込みができます
	watchlist.get	単一のシンボルの詳細を取得します
	watchlist.groups	名前付きウォッチリストグループをすべて一覧表示します
	watchlist.update	シンボルのメモまたはグループ割り当てを更新します
市場データ	market.snapshot	1つ以上のシンボルの最新の気配値と取引データを取得します
	market.bars	時間枠を設定できる OHLCV バー履歴を取得します
	market.quote	シンボルのリアルタイムの買値／売値スプレッドを取得します
	market.health	市場データプロバイダーへの接続状態を確認します
レジーム	regime.evaluate	ATR、ADX、RSI、ボリンジャーバンド幅、ハースト指数、VWAP、価格効率を使用して、現在の市場レジームを分類します
	regime.history	シンボルの過去のレジームスナップショットを取得します
戦略	strategy.scan	1つ以上の戦略について、ウォッチリストをスキャンしてシグナルを検出します
	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	戦略を次の段階に進めます：ドラフト → リサーチ → バックテスト → ペーパー → ライブ
	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	1日の最大損失限度（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 を参照してください。