Claude Praetorian MCP

🚀 claude-praetorian-mcp

這是一個適用於 Claude Code 的 模型上下文協議（MCP） 服務器，可對上下文進行高效壓縮。通過將網絡研究、任務輸出和對話內容壓縮成美觀、結構化的快照，能節省 90% 以上的令牌。

🚀 快速開始

安裝要求

• Claude Code

安裝命令

npm install -g claude-praetorian-mcp

不同方式配置

從 shell 配置

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% 以上的令牌，並能通過 "頻繁的有意壓縮" 輕鬆刷新上下文。

目前，它按項目運行，並通過以下工具（以及一個皇家衛兵圖標 ⚜️）將工件保存到 {$project}/.claude/praetorian 目錄：

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
└────────────────────────────────────────────────────────────────────┘

狀態指示

• 創建 - 新的壓縮內容已保存
• 合併 - 更新了現有的壓縮內容（標題相似度 >70%）
• 搜索 - 返回搜索結果（關鍵詞匹配）
• 最近 - 列出最近的壓縮內容（按更新時間排序）

💻 使用示例

基礎用法

Praetorian 設計用於大量、頻繁的使用。壓縮得越多，節省的令牌就越多。

壓縮時機

• ✅ 每次 WebFetch 之後
• ✅ 每個任務/子代理完成之後
• ✅ 讀取多個文件之後
• ✅ 做出決策之後
• ✅ 在長時間對話期間（主動壓縮）
• ✅ 在上下文使用率超過 60% 之前

實際使用示例

下一次會話：restore() 加載約 1000 個令牌。可立即恢復，無需重新進行研究。

🔧 技術細節

工作原理

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 文件（比 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 服務器（標準輸入輸出）

貢獻代碼

• 分叉倉庫並創建功能分支
• 在提交 PR 之前，使用多種壓縮類型進行測試
• 遵循 TypeScript 嚴格模式和 MCP 協議

📄 許可證

本項目採用 MIT 許可證。

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