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