claude-praetorian-mcp
An Model Context Protocol (MCP) server for aggressive context compaction in Claude Code. Save 90%+ tokens by compacting web research, task outputs, and conversations into structured snapshots.

Potencia tu agente
Instalación del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
Aún no hay una versión empaquetada en el registro. Sigue el README del repositorio.
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
An Model Context Protocol (MCP) server for aggressive context compaction in Claude Code. Save 90%+ tokens by compacting web research, task outputs, and conversations into structured snapshots.

⚜️ An MCP server for context compaction and recycling in Claude Code
Inspired by this talk by Dexter Horthy from HumanLayer, and his team's work on ACE: Advanced Context Engineering for Coding Agents, 12-Factor Agents & the TOON (Token-Oriented Object Notation) Format.
Requirements:
From shell:
claude mcp add claude-praetorian-mcp -- npx claude-praetorian-mcp
From inside Claude (restart required):
Add this to our global mcp config: npx claude-praetorian-mcp
Install this mcp: https://github.com/Vvkmnn/claude-praetorian-mcp
From any manually configurable mcp.json: (Cursor, Windsurf, etc.)
{
"mcpServers": {
"claude-praetorian-mcp": {
"command": "npx",
"args": ["claude-praetorian-mcp"],
"env": {}
}
}
}
There is no npm install required -- no external databases or services, only flat files.
However, if npx resolves the wrong package, you can force resolution with:
npm install -g claude-praetorian-mcp
Optionally, install the skill to teach Claude when to proactively use praetorian:
npx skills add Vvkmnn/claude-praetorian-mcp --skill claude-praetorian --global
# Optional: add --yes to skip interactive prompt and install to all agents
This makes Claude automatically compact after research, subagent tasks, and before context resets. The MCP works without the skill, but the skill improves discoverability.
For full automation with hooks, install from the claude-emporium marketplace:
/plugin marketplace add Vvkmnn/claude-emporium
/plugin install claude-praetorian@claude-emporium
The claude-praetorian plugin provides:
Hooks (targeted, fires only at high-value moments):
Commands: /praetorian-compact, /praetorian-restore, /praetorian-search
Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs.
MCP server for aggressive context compaction. Generates structured incremental snapshots to yield 90%+ token savings and easily refresh context with "frequent intentional compaction".
Runs project by project, saves artifacts to {$project}/.claude/praetorian (with a royal guard ⚜️):
praetorian_compact(Incrementally) compact context using the TOON format to get the most valuable tokens from an activity.
⚜️ 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
└───────────────────────────────────────────────────────────────────┘
{
"type": "web_research",
"title": "ACE Framework Research",
"source": "https://github.com/humanlayer/ace-fca",
"key_insights": [
"Frequent intentional compaction saves 90%+ tokens",
"TOON format is 30-60% smaller than JSON/YAML",
"Compaction should happen after every expensive operation"
],
"refs": ["ace-fca.md:42 - compaction strategy", "toon-spec.md:1 - format definition"],
"recommendations": ["Compact after every WebFetch", "Use type='decisions' for architecture choices"]
}
⚜️ compact | Merged
┌─ ⚜️ ───────────────────────────────────────────────────── Merged ─┐
│ Compacted: "Authentication Patterns" • 890 tokens saved
│ Type: decisions • ID: cpt_1765245903512_xk9mp1
│ Merged with: cpt_1765245903512_xk9mp1
└────────────────────────────────────────────────────────────────────┘
{
"type": "decisions",
"title": "Authentication Patterns",
"decisions": [
{ "chose": "JWT with refresh tokens", "over": ["sessions", "API keys"], "reason": "Stateless, works across microservices" },
{ "chose": "httpOnly cookies", "over": ["localStorage"], "reason": "XSS protection" }
],
"refs": ["src/middleware/auth.ts:45 - token validation", "src/routes/login.ts:23 - refresh flow"],
"anti_patterns": ["Never store tokens in localStorage", "Never skip CSRF on cookie-based auth"]
}
praetorian_restoreSearch and restore context by injecting TOON tokens back into current context as needed.
⚜️ 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"
└────────────────────────────────────────────────────────────────────┘
{
"compactions": [
{
"id": "cpt_1765245903512_xk9mp1",
"type": "decisions",
"title": "Authentication Patterns",
"relevance": 0.85,
"key_insights": ["JWT with refresh tokens", "httpOnly cookies for XSS protection"],
"refs": ["src/middleware/auth.ts:45", "src/routes/login.ts:23"]
},
{
"id": "cpt_1765245902396_nxetoc",
"type": "web_research",
"title": "OAuth2 Best Practices",
"relevance": 0.72,
"key_insights": ["PKCE flow for public clients", "Token rotation every 15min"]
}
],
"total": 2
}
⚜️ restore | Recent
┌─ ⚜️ ───────────────────────────────────────────────────── Recent ─┐
│ Found 3 compactions
└────────────────────────────────────────────────────────────────────┘
Status indicators:
Praetorian is designed for heavy, frequent use. The more you compact, the more you save.
When to compact:
Real-world example session:
Next session: restore() loads ~1,000 tokens. Instant resume, no re-research.
⚜️ claude-praetorian-mcp
════════════════════════
compact (save) restore (load)
────────────── ──────────────
INPUT QUERY
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Zod │ │ Inverted│
│Validate │ │ Index │
└────┬────┘ └────┬────┘
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Jaccard │ │ TOON │
│ >70% ? │ │ Decode │
└──┬───┬──┘ └────┬────┘
│ │ │
new│ │match ▼
│ │ OUTPUT
▼ ▼
┌─────────┐
│ TOON │
│ Encode │
└────┬────┘
│
▼
┌─────────┐
│ Index │
│ Update │
└────┬────┘
│
▼
OUTPUT
storage: .claude/praetorian/
────────────────────────────
index.json word index + metadata
compactions/*.toon encoded compaction files
Core optimizations:
Design principles:
.claude/praetorian/File access:
<project>/.claude/praetorian/.toon files (encoded compactions) + index.json (word index + metadata)git clone https://github.com/Vvkmnn/claude-praetorian-mcp && cd claude-praetorian-mcp
npm install && npm run build
npm test
Package requirements:
@modelcontextprotocol/sdk, @toon-format/toon, zodnpxDevelopment workflow:
npm run build # TypeScript compilation with executable permissions
npm run dev # Watch mode with tsc --watch
npm run start # Run the MCP server directly
npm run lint # ESLint code quality checks
npm run lint:fix # Auto-fix linting issues
npm run format # Prettier formatting (src/)
npm run format:check # Check formatting without changes
npm run typecheck # TypeScript validation without emit
npm run test # Lint + type check
npm run prepublishOnly # Pre-publish validation (build + lint + format:check)
Git hooks (via Husky):
.ts files with Prettier and ESLintContributing:
Learn from examples:
⚜️ An MCP server for context compaction and recycling in Claude Code
Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Claude Praetorian se ejecuta localmente por stdio.
Última comprobación: 2026-10-28. ⚜️ An MCP server for context compaction and recycling in Claude Code