brevix-shrink 0.4.0

package/README.md

@@ -0,0 +1,48 @@
+# brevix-shrink
+
+> MCP middleware proxy that compresses tool/prompt/resource descriptions to save tokens.
+
+`brevix-shrink` sits between an MCP client (Claude Desktop, Claude Code, Cursor, etc.) and an upstream MCP server. It intercepts `tools/list`, `prompts/list`, `resources/list`, and `resources/templates/list` responses, then runs Brevix's compression rules on description-style fields. Code, URLs, identifiers, and error quotes are preserved.
+
+Why: MCP servers ship verbose descriptions for every tool. Those descriptions are loaded into the model's input on every session. Compressing them once at the proxy saves input tokens for the whole session lifetime.
+
+## Install
+
+```bash
+npm install -g brevix-shrink
+# or run on demand
+npx brevix-shrink <upstream> [args...]
+```
+
+## Usage
+
+Wrap any MCP server command:
+
+```bash
+brevix-shrink npx -y @modelcontextprotocol/server-filesystem /tmp
+```
+
+Register in Claude Desktop / Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "fs-shrunk": {
+      "command": "npx",
+      "args": ["-y", "brevix-shrink", "npx", "-y",
+               "@modelcontextprotocol/server-filesystem", "/tmp"]
+    }
+  }
+}
+```
+
+## Configuration
+
+| Env var | Default | Effect |
+|---------|---------|--------|
+| `BREVIX_SHRINK_FIELDS` | `description,prompt,instructions` | Comma-separated field names to compress |
+| `BREVIX_SHRINK_DEBUG` | unset | Log proxy events to stderr |
+
+## License
+
+MIT

package/compress.js

@@ -0,0 +1,99 @@
+// Minimal output-prose compressor for MCP description fields.
+// Mirrors Brevix's full-mode rule set, kept tiny for proxy hot-path use.
+// Does NOT touch code, URLs, error quotes, or technical identifiers.
+
+const CODE_FENCE = /```[\s\S]*?```/g;
+const INLINE_CODE = /`[^`\n]+`/g;
+const URL_RE = /(https?:\/\/\S+|www\.\S+)/g;
+const ERROR_QUOTE = /"[^"\n]*(?:Error|Exception|Warning|Failed|Traceback)[^"\n]*"/gi;
+
+const PLEASANTRIES = [
+  /\b(?:i(?:'d| would| am| ?'m)?\s+(?:be\s+)?)?(?:happy|glad|pleased|delighted)\s+to\s+(?:help|assist|explain|show|walk|guide|take a look)\b[^.!?]*[.!?]/gi,
+  /\b(?:sure|certainly|of course|absolutely|gladly)\b[,!.\s]+/gi,
+  /\b(?:great|good|excellent)\s+(?:question|point|catch|observation)\b[!.\s]*/gi,
+  /\bhope (?:this|that) helps\b[!.\s]*/gi,
+  /\bplease (?:note|be aware|keep in mind)\s+(?:that\s+)?/gi,
+];
+const HEDGES = [
+  /\bit\s+(?:seems|appears|looks|might be|could be)\s+(?:that|like)?\s*/gi,
+  /\bi\s+(?:think|believe|suppose|guess|assume)\s+(?:that\s+)?/gi,
+  /\bin my opinion\b,?\s*/gi,
+  /\bgenerally speaking\b,?\s*/gi,
+];
+const VERBOSE = [
+  [/\bin order to\b/gi, "to"],
+  [/\bdue to the fact that\b/gi, "because"],
+  [/\bat this point in time\b/gi, "now"],
+  [/\bin the event that\b/gi, "if"],
+  [/\bfor the purpose of\b/gi, "to"],
+  [/\bmake use of\b/gi, "use"],
+  [/\bin spite of the fact that\b/gi, "though"],
+  [/\ba large number of\b/gi, "many"],
+  [/\bthe majority of\b/gi, "most"],
+  [/\bprior to\b/gi, "before"],
+  [/\bsubsequent to\b/gi, "after"],
+];
+const FILLER = /\b(?:just|really|basically|actually|simply|very|quite|perhaps|maybe|essentially|literally|obviously|clearly|definitely|absolutely)\b/gi;
+const ARTICLES = /\b(?:a|an|the)\b/gi;
+
+export function compressProse(text) {
+  if (!text || typeof text !== "string") return text;
+  const stash = [];
+  const stashFn = (m) => {
+    const k = `__BRVX_${stash.length}__`;
+    stash.push(m);
+    return k;
+  };
+  let t = text
+    .replace(CODE_FENCE, stashFn)
+    .replace(INLINE_CODE, stashFn)
+    .replace(URL_RE, stashFn)
+    .replace(ERROR_QUOTE, stashFn);
+
+  for (const re of PLEASANTRIES) t = t.replace(re, "");
+  for (const re of HEDGES) t = t.replace(re, "");
+  for (const [re, rep] of VERBOSE) t = t.replace(re, rep);
+  t = t.replace(FILLER, "");
+  t = t.replace(ARTICLES, "");
+  t = t.replace(/ {2,}/g, " ").replace(/ +([,.;:!?])/g, "$1").replace(/^[,;:\s]+/gm, "").trim();
+
+  for (let i = stash.length - 1; i >= 0; i--) {
+    t = t.replace(`__BRVX_${i}__`, stash[i]);
+  }
+  return t;
+}
+
+const SHRINK_FIELDS = (process.env.BREVIX_SHRINK_FIELDS || "description,prompt,instructions")
+  .split(",")
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+export function shrinkRecord(rec) {
+  if (!rec || typeof rec !== "object") return rec;
+  for (const key of Object.keys(rec)) {
+    const val = rec[key];
+    if (SHRINK_FIELDS.includes(key) && typeof val === "string") {
+      rec[key] = compressProse(val);
+    } else if (Array.isArray(val)) {
+      rec[key] = val.map(shrinkRecord);
+    } else if (val && typeof val === "object") {
+      rec[key] = shrinkRecord(val);
+    }
+  }
+  return rec;
+}
+
+const SHRINK_RESULTS_FOR = new Set([
+  "tools/list",
+  "prompts/list",
+  "resources/list",
+  "resources/templates/list",
+]);
+
+export function maybeShrinkResponse(req, response) {
+  if (!response || !req || !req.method) return response;
+  if (!SHRINK_RESULTS_FOR.has(req.method)) return response;
+  if (!response.result) return response;
+  shrinkRecord(response.result);
+  return response;
+}

package/index.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// brevix-shrink — stdio MCP proxy that compresses tools/list, prompts/list,
+// and resources/list response descriptions to save tokens.
+//
+// Usage:
+//   npx brevix-shrink <upstream-command> [args...]
+//   e.g. npx brevix-shrink npx -y @modelcontextprotocol/server-filesystem /tmp
+//
+// Env:
+//   BREVIX_SHRINK_FIELDS=description,prompt   override fields to compress
+//   BREVIX_SHRINK_DEBUG=1                     log to stderr
+
+import { spawn } from "node:child_process";
+import { maybeShrinkResponse } from "./compress.js";
+
+const DEBUG = process.env.BREVIX_SHRINK_DEBUG === "1";
+const log = (...a) => DEBUG && process.stderr.write(`[brevix-shrink] ${a.join(" ")}\n`);
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  process.stderr.write(
+    "brevix-shrink: missing upstream command.\n" +
+      "Usage: brevix-shrink <command> [args...]\n"
+  );
+  process.exit(2);
+}
+
+const [cmd, ...rest] = args;
+const child = spawn(cmd, rest, { stdio: ["pipe", "pipe", "inherit"] });
+
+child.on("exit", (code) => process.exit(code ?? 0));
+child.on("error", (err) => {
+  process.stderr.write(`brevix-shrink: failed to start upstream: ${err.message}\n`);
+  process.exit(127);
+});
+
+// Track in-flight requests so we know which response method we're shrinking.
+const pending = new Map();
+
+const lineSplit = (chunk, buf) => {
+  buf.value += chunk.toString("utf8");
+  const out = [];
+  let idx;
+  while ((idx = buf.value.indexOf("\n")) !== -1) {
+    out.push(buf.value.slice(0, idx));
+    buf.value = buf.value.slice(idx + 1);
+  }
+  return out;
+};
+
+// Client → child: forward verbatim, but remember each request's method.
+const reqBuf = { value: "" };
+process.stdin.on("data", (chunk) => {
+  for (const line of lineSplit(chunk, reqBuf)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      child.stdin.write("\n");
+      continue;
+    }
+    try {
+      const msg = JSON.parse(trimmed);
+      if (msg && msg.id !== undefined && msg.method) {
+        pending.set(msg.id, msg);
+        log("→", msg.method, msg.id);
+      }
+    } catch {
+      /* not json — passthrough */
+    }
+    child.stdin.write(line + "\n");
+  }
+});
+process.stdin.on("end", () => child.stdin.end());
+
+// Child → client: compress tools/list etc. responses.
+const respBuf = { value: "" };
+child.stdout.on("data", (chunk) => {
+  for (const line of lineSplit(chunk, respBuf)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      process.stdout.write("\n");
+      continue;
+    }
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      process.stdout.write(line + "\n");
+      continue;
+    }
+    if (msg && msg.id !== undefined && pending.has(msg.id)) {
+      const req = pending.get(msg.id);
+      pending.delete(msg.id);
+      maybeShrinkResponse(req, msg);
+      log("←", req.method, msg.id, "(shrunk)");
+    }
+    process.stdout.write(JSON.stringify(msg) + "\n");
+  }
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "brevix-shrink",
+  "version": "0.4.0",
+  "description": "MCP middleware proxy that compresses tools/list, prompts/list, and resources/list responses to save tokens. Sister project to Brevix.",
+  "bin": {
+    "brevix-shrink": "./index.js"
+  },
+  "main": "index.js",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Yash Koladiya <yashkoladiya123@gmail.com>",
+  "homepage": "https://github.com/Yash-Koladiya30/brevix",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yash-Koladiya30/brevix.git",
+    "directory": "mcp-servers/brevix-shrink"
+  },
+  "bugs": {
+    "url": "https://github.com/Yash-Koladiya30/brevix/issues"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "compression",
+    "tokens",
+    "brevix",
+    "proxy",
+    "model-context-protocol"
+  ],
+  "files": [
+    "index.js",
+    "compress.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}