# Claude Praetorian Mcp

> ⚜️ An MCP server for context compaction and recycling in Claude Code

- **Type:** MCP server
- **Install:** `agentstack add mcp-vvkmnn-claude-praetorian-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Vvkmnn](https://agentstack.voostack.com/s/vvkmnn)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Vvkmnn](https://github.com/Vvkmnn)
- **Source:** https://github.com/Vvkmnn/claude-praetorian-mcp
- **Website:** https://www.npmjs.com/package/claude-praetorian-mcp

## Install

```sh
agentstack add mcp-vvkmnn-claude-praetorian-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# claude-praetorian-mcp

An [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for aggressive context compaction in [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Save 90%+ tokens by compacting web research, task outputs, and conversations into structured snapshots.

[](https://www.npmjs.com/package/claude-praetorian-mcp) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](#) [](https://github.com/Vvkmnn/claude-praetorian-mcp)

---

Inspired by [this talk](https://www.youtube.com/watch?v=rmvDxxNubIg) by [Dexter Horthy](https://x.com/dexhorthy) from [HumanLayer](http://humanlayer.dev), and his team's work on [ACE: Advanced Context Engineering for Coding Agents](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md), [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) & the [`TOON` (Token-Oriented Object Notation) Format](https://toonformat.dev).

## install

**Requirements:**

[](https://claude.ai/code)

**From shell:**

```bash
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.)

```json
{
  "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:

```bash
npm install -g claude-praetorian-mcp
```

## [skill](.claude/skills/claude-praetorian)

Optionally, install the skill to teach Claude when to proactively use praetorian:

```bash
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.

## [plugin](https://github.com/Vvkmnn/claude-emporium)

For full automation with hooks, install from the [claude-emporium](https://github.com/Vvkmnn/claude-emporium) marketplace:

```bash
/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):

- Before EnterPlanMode → Restore prior compactions for this project
- Before context compaction → Save decisions/insights before context resets
- After WebFetch/WebSearch → Compact web research findings
- After SubagentStop → Compact subagent task results

**Commands:** `/praetorian-compact`, `/praetorian-restore`, `/praetorian-search`

Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs.

## features

[MCP server](https://modelcontextprotocol.io/) for aggressive context compaction. Generates **structured incremental snapshots** to yield 90%+ token savings and easily refresh context with ["frequent intentional compaction"](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md#slightly-smarter-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= 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
└───────────────────────────────────────────────────────────────────┘
```

```json
{
  "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
└────────────────────────────────────────────────────────────────────┘
```

```json
{
  "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_restore`

Search and restore context by injecting TOON tokens back into current context as needed.

```
⚜️ praetorian_restore 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"
└────────────────────────────────────────────────────────────────────┘
```

```json
{
  "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:**

- **Created** - New compaction saved
- **Merged** - Updated existing compaction (>70% title similarity via [Jaccard index](https://en.wikipedia.org/wiki/Jaccard_index))
- **Search** - Search results returned (keyword matching)
- **Recent** - Recent compactions listed (by updated time)

Praetorian is designed for **heavy, frequent use**. The more you compact, the more you save.

**When to compact:**

- [x] After every WebFetch
- [x] After every Task/subagent completes
- [x] After reading multiple files
- [x] After making decisions
- [x] During long conversations (proactive compaction)
- [x] Before context gets >60% full

**Real-world example session:**

| Compaction            | Before     | After     | Saved            |
| --------------------- | ---------- | --------- | ---------------- |
| Web research (3 URLs) | 4,500      | 300       | **4,200**        |
| Subagent outputs (2)  | 3,500      | 300       | **3,200**        |
| Architecture debates  | 5,000      | 300       | **4,700**        |
| Hook research         | 1,500      | 150       | **1,350**        |
| **Total**             | **14,500** | **1,050** | **13,450 (93%)** |

Next session: `restore()` loads ~1,000 tokens. Instant resume, no re-research.

## methodology

How [claude-praetorian-mcp](https://github.com/Vvkmnn/claude-praetorian-mcp) [works](https://github.com/Vvkmnn/claude-praetorian-mcp/tree/master/src):

```
              ⚜️  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:**

- [TOON format](https://toonformat.dev): 30-60% fewer tokens than YAML/JSON
- [Zod validation](https://github.com/Vvkmnn/claude-praetorian-mcp/blob/master/src/schemas.ts): Production-grade runtime type safety
- [Jaccard similarity](https://en.wikipedia.org/wiki/Jaccard_index): Smart deduplication via title matching (>70% threshold)
- [Inverted index](https://en.wikipedia.org/wiki/Inverted_index): Fast keyword search without vector embeddings
- [Smart merging](https://github.com/Vvkmnn/claude-praetorian-mcp/blob/master/src/storage/index.ts#L74): Combine similar compactions without duplication

**Design principles:**

- **Incremental** -- merge similar compactions via Jaccard similarity, don't replace
- **Token-minimal** -- TOON format for 30-60% fewer tokens than YAML/JSON
- **Project-scoped** -- each project stores in its own `.claude/praetorian/`
- **Flat files only** -- no databases, no external services
- **Offline** -- never leaves your machine, no network calls

**File access:**

- Stores in: `/.claude/praetorian/`
- Format: `.toon` files (encoded compactions) + `index.json` (word index + metadata)

## development

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

**Package requirements:**

- **Node.js**: >=20.0.0 (ES modules)
- **Runtime**: `@modelcontextprotocol/sdk`, `@toon-format/toon`, `zod`
- **Zero external databases** -- works with `npx`

**Development workflow:**

```bash
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):**

- **pre-commit**: Auto-formats staged `.ts` files with Prettier and ESLint

Contributing:

- Fork the repository and create feature branches
- Test with multiple compaction types before submitting PRs
- Follow TypeScript strict mode and [MCP protocol](https://modelcontextprotocol.io/specification) standards

Learn from examples:

- [Official MCP servers](https://github.com/modelcontextprotocol/servers) for reference implementations
- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) for best practices
- [Creating Node.js modules](https://docs.npmjs.com/creating-node-js-modules) for npm package development

## license

[MIT](LICENSE)

_**[A Roman Emperor AD 41](https://en.wikipedia.org/wiki/A_Roman_Emperor_AD_41)** by **[Lawrence Alma-Tadema](https://en.wikipedia.org/wiki/Lawrence_Alma-Tadema)** (1871). [Gratus](https://en.wikipedia.org/wiki/Praetorian_Guard) of the [Praetorian Guard](https://en.wikipedia.org/wiki/Praetorian_Guard) discovers [Claudius](https://en.wikipedia.org/wiki/Claudius) hiding behind a curtain and [declares him emperor](https://en.wikipedia.org/wiki/Claudius#Accession). [Walters Art Museum](https://art.thewalters.org/detail/637/a-roman-emperor-41-ad/), public domain._

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Vvkmnn](https://github.com/Vvkmnn)
- **Source:** [Vvkmnn/claude-praetorian-mcp](https://github.com/Vvkmnn/claude-praetorian-mcp)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/claude-praetorian-mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-vvkmnn-claude-praetorian-mcp
- Seller: https://agentstack.voostack.com/s/vvkmnn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.