Savage Mcp

savage-mcp

KISS wrapper for MCP: fewer words, smaller image payloads, graph-shaped context.

Before/After • Install • What You Get • MCP Tools • Benchmarks • Links

---

A Codex-first MCP proxy and skill/plugin that compresses what agents read. Text becomes compact machine-ish prose. Images become either primitive cave-painting graphs or block-diagram scene graphs. The goal is simple: keep meaning, burn fewer tokens.

Before / After

| Normal answer | Savage answer | | --- | --- | | React render loop"The reason your React component is re-rendering is likely because you create a new object reference on each render. When that inline object is passed as a prop, React shallow comparison sees a different object every time, so the child renders again. Use useMemo to keep the reference stable."73 est. tokens | tg[React-cmp rerenderdiff-ref->child-rerender;fix:useMemo stable ref]26 est. tokens, 64% saved | | Auth expiry bug"Sure, the issue is most likely caused by authentication middleware not validating token expiry consistently. The comparison should reject tokens when exp is less than or equal to the current timestamp, and the error path should return 401 instead of falling through."67 est. tokens | tg[bug:auth-mw tok-expiry invalid;reject exp401/no-fallthrough]20 est. tokens, 70% saved |

Same fix. Less prose. Code, URLs, paths, identifiers, API names, and exact errors stay intact.

| Signal | Meaning | | --- | --- | | Text graph saved: 62% avg | Average reduction from the local text-to-graph compressor on ten short prose samples. This is the meaningful text mode for MCP context. | | Diagram image saved: 85% sample | Base64 image replaced by a small scene diagram graph. This is where MCP context savings get large. | | Technical tokens | Preserved exactly when they look like code, paths, URLs, API names, or errors. | | Shape | Graph nodes/edges, not parent/children trees. |

> [!IMPORTANT] > Text numbers are local estimates from examples/run_examples.js using format: "graph", not API billing records. Image numbers compare base64 chars with the generated graph payload.

Install

npm install -g savage-mcp

Wrap any stdio MCP server:

{
  "mcpServers": {
    "fs-savage": {
      "command": "npx",
      "args": [
        "savage-mcp",
        "--mode",
        "auto",
        "--image-mode",
        "diagram",
        "--",
        "npx",
        "@modelcontextprotocol/server-filesystem",
        "/tmp"
      ]
    }
  }
}

CLI:

savage-mcp [--mode auto|text|image|off] \
  [--text-level lite|balanced|ultra] \
  [--text-format prose|graph] \
  [--image-mode graph|svg|diagram|pass] \
  [--max-primitives 64] \
  [--min-image-bytes 4096] \
  --  [...args]

What You Get

| Feature | What | | --- | --- | | Text graph compression | KISS frames like tg[subject->action;fix:step] for safe prose fields and text content. | | Image primitives | image/png, jpeg, webp, etc. -> savage_graph_v1 nodes/edges/colors. | | Scene diagrams | Entity boxes + verb arrows -> savage_diagram_v1. | | Codex skill | plugins/savage and skills/savage for compact Codex replies. | | MCP utility tools | Local tools injected into upstream tools/list. | | Stats | Process-level byte counters for text/image savings. |

MCP Tools

savage-mcp adds these local tools:

| Tool | What | | --- | --- | | savage.text | Compress prose into compact KISS prose or text graph frames. Preserves code, URLs, paths, identifiers, API names, and exact errors. | | savage.image | Convert base64 image data into compact visual primitives, SVG, or diagram blocks. | | savage.diagram | Build a compact scene/block graph from labeled entities and verb relations. | | savage.payload | Compress safe text fields and image blocks inside a JSON payload. | | savage.stats | Return bytes saved by this proxy process. |

Tool-call variants:

{ "name": "savage.text", "arguments": { "text": "The database configuration response is very important.", "level": "ultra", "format": "graph" } }

{ "name": "savage.image", "arguments": { "data": "", "mimeType": "image/png", "format": "graph", "maxPrimitives": 24 } }

{
  "name": "savage.diagram",
  "arguments": {
    "items": [
      { "id": "person", "label": "person" },
      { "id": "mountain", "label": "mountain" }
    ],
    "relations": [
      { "from": "person", "to": "mountain", "verb": "climbs" }
    ]
  }
}

Image Modes

| Mode | Output | Best For | | --- | --- | --- | | graph | savage_graph_v1 rectangles, colors, adjacency edges | Deterministic visual simplification; cave-painting primitive feel. | | svg | Compact SVG made from primitive cells | Visual preview when the client can render SVG. | | diagram | savage_diagram_v1 labeled boxes + verb arrows | Semantic block scheme: person --climbs--> mountain. | | pass | Original image block | When binary fidelity matters more than context size. |

Example image receipt from the generated sample scene:

| Payload | Chars | Mode | Saved | | --- | ---: | --- | ---: | | Base64 PNG | 3752 | original | - | | Primitive graph | 3347 | savage_graph_v1 | 11% | | Scene diagram | 562 | savage_diagram_v1 | 85% |

Scene diagram output:

person --climbs--> mountain
sun --lights--> mountain

> [!NOTE] > diagram mode is deterministic. If you want labels like person, mountain, and climbs, pass scene labels/relations in the tool call. Without labels, the wrapper can only emit visual regions, not claim object recognition.

Benchmarks

Measured by the local example runner with the current compressor and a simple UTF-8 byte/4 token estimate.

| Task | Normal est. toks | Savage graph est. toks | Saved | | --- | ---: | ---: | ---: | | Explain React re-render bug | 73 | 26 | 64% | | Fix token expiry middleware | 67 | 20 | 70% | | Set up PostgreSQL pool | 62 | 13 | 79% | | Explain MCP stdio wrapper | 54 | 18 | 67% | | Refactor callback API | 49 | 23 | 53% | | Compare monolith and services | 52 | 22 | 58% | | Review PR security risk | 51 | 27 | 47% | | Docker build optimization | 52 | 17 | 67% | | Debug race condition | 51 | 28 | 45% | | Implement error boundary | 49 | 15 | 69% | | Average | 56 | 21 | 62% |

Savage Receipts

Memory-style files, same runner:

| File | Original est. toks | Savage graph est. toks | Saved | | --- | ---: | ---: | ---: | | agent-instructions.md | 50 | 17 | 66% | | mcp-server-notes.md | 46 | 21 | 54% | | image-policy.md | 46 | 9 | 80% | | release-checklist.md | 51 | 11 | 78% | | codex-style.md | 43 | 18 | 58% | | Average | 47 | 15 | 67% |

> [!TIP] > Graph text mode is intentionally more aggressive than prose mode. Use --text-format prose when readability matters more than savings; use graph for MCP context size.

Graph Shapes

Text graph frame:

tg[React-cmp rerenderdiff-ref->child-rerender;fix:useMemo stable ref]

Primitive image graph:

{
  "v": 1,
  "kind": "savage_graph_v1",
  "nodes": [{ "id": "n0", "t": "rect", "bbox": [0, 0, 0.1, 0.1], "color": "#8ecae6", "score": 0.9 }],
  "edges": [{ "a": "n0", "b": "n1", "r": "adj", "w": 0.42 }],
  "meta": { "mimeType": "image/png", "width": 192, "height": 128 }
}

Scene diagram graph:

{
  "v": 1,
  "kind": "savage_diagram_v1",
  "nodes": [{ "id": "person", "t": "box", "label": "person" }],
  "edges": [{ "a": "person", "b": "mountain", "r": "verb", "label": "climbs" }]
}

Links

• [README benchmark source](examples/run_examples.js)
• [Generated example results](examples/generated/results.json)
• [Codex plugin manifest](plugins/savage/.codex-plugin/plugin.json)
• [Savage skill](skills/savage/SKILL.md)
• [MCP proxy source](src/savage-mcp/index.js)
• GitHub repo

Limits

• No hidden vision model. Semantic diagrams need caller-supplied labels.
• Unsupported image MIME blocks pass through unchanged.
• Compression avoids rewriting code-like tokens; exact technical strings win over extra savings.

Source & license

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

• Author: denzasikora-lab
• Source: denzasikora-lab/savage-mcp
• License: MIT
• Homepage: https://github.com/denzasikora-lab/savage-mcp#readme

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