claude-praetorian

The claude-praetorian-mcp MCP server provides aggressive context compaction for Claude Code conversations, research, and task outputs by generating structured, incremental snapshots. It saves meaningful decisions and findings into compact TOON-formatted pods, aiming to reduce context size by 90%+ while preserving essential rationale and references. The server operates project-by-project, writing artifacts to the project directory under .claude/praetorian and can be triggered automatically via Claude skills or manual commands. You can use the included commands to compact after web research, subagent tasks, or before context resets, and to restore context when needed.

Key capabilities include: (1) praetorian_compact for incrementally compacting a given activity into a snapshot with type, title, and insights, (2) praetorian_restore to search and re-inject relevant TOON tokens into the current context, and (3) optional integration hooks with Claude Code via the Claude Emprorium marketplace and the claude-praetorian skill to automatically trigger compaction at high-value moments. The server is designed to work without external databases or services, relying on flat files for storage when applicable.

Prerequisites:

• Node.js 20+ (npm comes with Node.js)
• Basic shell access

Installation options:

• No npm install required: use npx to run the MCP directly
• Optional global install if you want guaranteed resolution in environments where npx may pick the wrong package

From shell (recommended):

# Run the MCP directly without installation
claude mcp add claude-praetorian-mcp -- npx claude-praetorian-mcp

If npx resolves the wrong package, you can force resolution by installing globally:

npm install -g claude-praetorian-mcp

Configuration example (mcp.json):

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

Notes:

• There is no npm install required for typical usage; npx will fetch the MCP on demand.
• If you need to customize runtime environment variables, add them under the env object in the configuration.
• For automatic discovery and integration with Claude, consider using the provided skill and plugin options described in the repository.

Tips and caveats:

• The MCP stores artifacts per project under {$project}/.claude/praetorian with a visible guard icon to indicate compacted snapshots.
• If you want Claude to proactively use compacted context, enable the claude-praetorian skill and/or the claude-emporium plugin integrations.
• The available MCP actions include: praetorian_compact (to generate a new compact snapshot), praetorian_restore (to recover and re-inject relevant context), and auxiliary commands exposed via the Claude plugin suite.
• If you encounter tokenization or TOON formatting issues, review the refs and slightly adjust the title/type to ensure the snapshot remains actionable and traceable.
• The plugin and skill are optional enhancements; the MCP server operates without them but improves discoverability and automation.