Claude Praetorian MCP

🚀 claude-praetorian-mcp

このプロジェクトは、Claude Codeにおけるコンテキストを積極的に圧縮するためのModel Context Protocol (MCP)サーバーです。ウェブリサーチ、タスク出力、会話を美しく構造化されたスナップショットに圧縮することで、90%以上のトークンを節約できます。

このプロジェクトは、HumanLayerのDexter Horthyによるthis talkや、彼のチームによるACE: Advanced Context Engineering for Coding Agents、12-Factor Agents、そして最近リリースされたTOON (Token-Oriented Object Notation) Formatに触発されています。

🚀 クイックスタート

Claude Codeを使用して、このサーバーを使い始めることができます。

📦 インストール

必要条件

• Claude Code

コマンドラインからのインストール

npm install -g claude-praetorian-mcp

シェルからの設定

claude mcp add claude-praetorian-mcp -- bunx claude-praetorian-mcp

Claude内からの設定（再起動が必要）

Add this to our global mcp config: bunx claude-praetorian-mcp

Install this mcp: https://github.com/Vvkmnn/claude-praetorian-mcp

手動で設定可能なmcp.jsonからの設定（Cursor、Windsurfなど）

{
  "mcpServers": {
    "praetorian": {
      "command": "bunx",
      "args": ["claude-praetorian-mcp"],
      "env": {}
    }
  }
}

✨ 主な機能

コンテキストの圧縮

MCPサーバーを使用して、コンテキストを積極的に圧縮します。構造化された増分スナップショットを生成することで、90%以上のトークンを節約し、"頻繁な意図的な圧縮"によってコンテキストを簡単に更新できます。

praetorian_compact

TOON形式を使用して（増分的に）コンテキストを圧縮し、アクティビティから最も価値のあるトークンを取得します。

⚜️ praetorian_compact type=<type> title=<title>
  > "ACE Framework research - save 1,450 tokens"
  > "Icon rendering bug investigation - compact the findings"
  > "Database architecture decisions - preserve the rationale"
  > "WebFetch results from authentication docs"
  > "Task output from explore subagent - code structure analysis"

⚜️ compact | Created

┌─ ⚜️  ────────────────────────────────────────────────── Created ─┐
│ Compacted: "ACE Framework Research" • 1,450 tokens saved
│ Type: web_research • ID: cpt_1765245902396_nxetoc
└───────────────────────────────────────────────────────────────────┘

⚜️ compact | Merged

┌─ ⚜️  ───────────────────────────────────────────────────── Merged ─┐
│ Compacted: "Authentication Patterns" • 890 tokens saved
│ Type: decisions • ID: cpt_1765245903512_xk9mp1
│ Merged with: cpt_1765245903512_xk9mp1
└────────────────────────────────────────────────────────────────────┘

praetorian_restore

必要に応じて、TOONトークンを現在のコンテキストに注入することで、コンテキストを検索して復元します。

⚜️ praetorian_restore query=<query>
  > "What did we learn about authentication?"
  > "Find the Docker container debugging session"
  > "Show recent architecture decisions"
  > "Search for MCP server implementation patterns"
  > "" (empty = recent compactions)

⚜️ restore | Search

┌─ ⚜️  ───────────────────────────────────────────────────── Search ─┐
│ Found 2 compactions
│ Query: "authentication"
└────────────────────────────────────────────────────────────────────┘

⚜️ restore | Recent

┌─ ⚜️  ───────────────────────────────────────────────────── Recent ─┐
│ Found 3 compactions
└────────────────────────────────────────────────────────────────────┘

ステータスインジケーター

• Created - 新しい圧縮が保存されました。
• Merged - 既存の圧縮が更新されました（タイトルの類似度が70%以上）。
• Search - 検索結果が返されました（キーワードマッチング）。
• Recent - 最近の圧縮がリストされました（更新時間順）。

💻 使用例

基本的な使用法

Praetorianは、頻繁に大量に使用することを想定して設計されています。圧縮を行うほど、トークンを節約できます。

圧縮のタイミング

• ✅ 毎回のWebFetchの後
• ✅ 毎回のタスク/サブエージェントの完了後
• ✅ 複数のファイルを読み込んだ後
• ✅ 決定を行った後
• ✅ 長い会話中（積極的な圧縮）
• ✅ コンテキストが60%以上になる前

実際のセッション例

次のセッションでは、restore()を使用して約1,000トークンを読み込みます。即座に再開でき、再調査の必要がありません。

🔧 技術詳細

動作原理

claude-praetorian-mcpの動作原理は以下の通りです。

                        claude-praetorian-mcp
              ======================================


  praetorian_compact (write)
  --------------------------

  INPUT ──> VALIDATE ──> DETECT ──> MERGE ──> ENCODE ──> INDEX ──> OUTPUT
              │            │          │         │          │
              │            │          │         │          └─ words -> IDs
              │            │          │         └─ .toon (30-60% smaller)
              │            │          └─ dedupe arrays, combine objects
              │            └─ Jaccard similarity > 70% = auto-merge
              └─ Zod schemas (CompactInput, Compaction)


  praetorian_restore (read)
  -------------------------

                      ┌─────────┐
  QUERY ──> SEARCH ───┤         ├──> DECODE ──> OUTPUT
                      │  INDEX  │
  (none) ──> RECENT ──┤         │
                      └─────────┘


  Storage: .claude/praetorian/
  ----------------------------

  index.json          Inverted word index + compaction metadata
  compactions/*.toon  TOON-encoded compaction files

核心的な最適化

• TOON形式: YAML/JSONよりも30-60%少ないトークンです。
• Zodバリデーション: 本番環境でも安全なランタイム型チェックです。
• Jaccard類似度: タイトルのマッチングによるスマートな重複排除（70%以上の閾値）。
• 転置インデックス: ベクトル埋め込みを使用せずに高速なキーワード検索ができます。
• スマートマージ: 重複を避けて類似した圧縮を結合します。

ファイルアクセス

• 保存先: <project>/.claude/praetorian/
• TOON形式: .toonファイル（YAML/XMLよりも40%少ないバイト数）
• データベース依存なし（データベース呼び出しやファイルシステムを使用しません）
• マシン内で完結します。

📚 ドキュメント

開発環境のセットアップ

git clone https://github.com/Vvkmnn/claude-praetorian-mcp && cd claude-praetorian-mcp
npm install && npm run build

パッケージの要件

• Node.js: >=20.0.0 (ESモジュール)
• npm: >=10.0.0 (package-lock v3)
• ランタイム: @modelcontextprotocol/sdk, @toon-format/toon, zod
• 外部データベース不要 - bunxで動作します。

開発ワークフロー

npm run build          # TypeScriptのコンパイル
npm run watch          # tsc --watchによるウォッチモード
node dist/index.js     # MCPサーバーを直接実行 (stdio)

コントリビュートの方法

• リポジトリをフォークし、機能ブランチを作成します。
• PRを提出する前に、複数の圧縮タイプでテストします。
• TypeScriptのstrictモードとMCPプロトコルに従います。

📄 ライセンス

MIT

Tiberius Claudius Caesar Augustus Germanicus - Declared emperor by his Praetorian Guard