context-compress 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,75 @@
+export type Language = "javascript" | "typescript" | "python" | "shell" | "ruby" | "go" | "rust" | "php" | "perl" | "r" | "elixir";
+export declare const ALL_LANGUAGES: readonly Language[];
+export interface ExecOptions {
+    language: Language;
+    code: string;
+    timeout?: number;
+    intent?: string;
+    maxOutputBytes?: number;
+}
+export interface ExecFileOptions extends ExecOptions {
+    filePath: string;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    truncated: boolean;
+    killed: boolean;
+    networkBytes?: number;
+}
+export interface IndexOptions {
+    content?: string;
+    path?: string;
+    source?: string;
+}
+export interface IndexResult {
+    sourceId: number;
+    label: string;
+    totalChunks: number;
+    codeChunks: number;
+}
+export interface SearchOptions {
+    queries: string[];
+    source?: string;
+    limit?: number;
+}
+export interface SearchResult {
+    query: string;
+    results: SearchHit[];
+    corrected?: string;
+}
+export interface SearchHit {
+    title: string;
+    snippet: string;
+    source: string;
+    score: number;
+}
+export interface StoreStats {
+    totalSources: number;
+    totalChunks: number;
+    vocabularySize: number;
+    hasTrigramTable: boolean;
+}
+export interface Chunk {
+    title: string;
+    content: string;
+    hasCode: boolean;
+}
+export interface SessionStats {
+    calls: Record<string, number>;
+    bytesReturned: Record<string, number>;
+    bytesIndexed: number;
+    bytesSandboxed: number;
+    sessionStart: number;
+}
+export interface BatchCommand {
+    label: string;
+    command: string;
+}
+export interface BatchExecuteOptions {
+    commands: BatchCommand[];
+    queries: string[];
+    timeout?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GACjB,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,MAAM,GACN,IAAI,GACJ,MAAM,GACN,KAAK,GACL,MAAM,GACN,GAAG,GACH,QAAQ,CAAC;AAEZ,eAAO,MAAM,aAAa,EAAE,SAAS,QAAQ,EAYnC,CAAC;AAEX,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAgB,SAAQ,WAAW;IACnD,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,KAAK;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,14 @@
+export const ALL_LANGUAGES = [
+    "javascript",
+    "typescript",
+    "python",
+    "shell",
+    "ruby",
+    "go",
+    "rust",
+    "php",
+    "perl",
+    "r",
+    "elixir",
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,aAAa,GAAwB;IACjD,YAAY;IACZ,YAAY;IACZ,QAAQ;IACR,OAAO;IACP,MAAM;IACN,IAAI;IACJ,MAAM;IACN,KAAK;IACL,MAAM;IACN,GAAG;IACH,QAAQ;CACC,CAAC"}

package/hooks/hooks.json

@@ -0,0 +1,52 @@
+{
+  "description": "context-compress PreToolUse — intercepts data-fetching tools, nudges toward sandbox execution",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.mjs"
+          }
+        ]
+      },
+      {
+        "matcher": "WebFetch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.mjs"
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.mjs"
+          }
+        ]
+      },
+      {
+        "matcher": "Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.mjs"
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/pretooluse.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+// src/hooks/pretooluse.ts
+var TOOL_PREFIX = "context-compress";
+var blockCurl = process.env.CONTEXT_COMPRESS_BLOCK_CURL !== "0";
+var blockWebFetch = process.env.CONTEXT_COMPRESS_BLOCK_WEBFETCH !== "0";
+var nudgeOnRead = process.env.CONTEXT_COMPRESS_NUDGE_READ !== "0";
+var nudgeOnGrep = process.env.CONTEXT_COMPRESS_NUDGE_GREP !== "0";
+var raw = "";
+process.stdin.setEncoding("utf-8");
+for await (const chunk of process.stdin) raw += chunk;
+var input = JSON.parse(raw);
+var tool = input.tool_name ?? "";
+var toolInput = input.tool_input ?? {};
+function respond(output) {
+  console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", ...output } }));
+  process.exit(0);
+}
+if (tool === "Bash") {
+  const command = toolInput.command ?? "";
+  if (blockCurl && /(^|\s|&&|\||\;)(curl|wget)\s/i.test(command)) {
+    respond({
+      updatedInput: {
+        command: `echo "${TOOL_PREFIX}: curl/wget blocked. Use mcp__${TOOL_PREFIX}__fetch_and_index(url, source) to fetch URLs, or mcp__${TOOL_PREFIX}__execute(language, code) to run HTTP calls in sandbox. Set CONTEXT_COMPRESS_BLOCK_CURL=0 to disable this."`
+      }
+    });
+  }
+  if (blockCurl && (/fetch\s*\(\s*['"](https?:\/\/|http)/i.test(command) || /requests\.(get|post|put)\s*\(/i.test(command) || /http\.(get|request)\s*\(/i.test(command))) {
+    respond({
+      updatedInput: {
+        command: `echo "${TOOL_PREFIX}: Inline HTTP blocked. Use mcp__${TOOL_PREFIX}__execute(language, code) to run HTTP calls in sandbox, or mcp__${TOOL_PREFIX}__fetch_and_index(url, source) for web pages."`
+      }
+    });
+  }
+  process.exit(0);
+}
+if (tool === "Read" && nudgeOnRead) {
+  respond({
+    additionalContext: `CONTEXT TIP: If this file is large (>50 lines), prefer mcp__${TOOL_PREFIX}__execute_file(path, language, code) \u2014 processes in sandbox, only stdout enters context.`
+  });
+}
+if (tool === "Grep" && nudgeOnGrep) {
+  respond({
+    additionalContext: `CONTEXT TIP: If results may be large, prefer mcp__${TOOL_PREFIX}__execute(language: "shell", code: "grep ...") \u2014 runs in sandbox, only stdout enters context.`
+  });
+}
+if (tool === "WebFetch" && blockWebFetch) {
+  const url = toolInput.url ?? "";
+  respond({
+    permissionDecision: "deny",
+    reason: `${TOOL_PREFIX}: WebFetch blocked. Use mcp__${TOOL_PREFIX}__fetch_and_index(url: "${url}", source: "...") to fetch this URL in sandbox. Then use mcp__${TOOL_PREFIX}__search(queries: [...]) to query results.`
+  });
+}
+if (tool === "Task" || tool === "Agent") {
+  const subagentType = toolInput.subagent_type ?? "";
+  const prompt = toolInput.prompt ?? "";
+  const ROUTING_BLOCK = `
+
+---
+CONTEXT WINDOW PROTECTION \u2014 USE CONTEXT-COMPRESS MCP TOOLS
+
+Raw Bash/Read/WebFetch output floods your context. You have context-compress tools that keep data in sandbox.
+
+STEP 1 \u2014 GATHER: mcp__${TOOL_PREFIX}__batch_execute(commands, queries)
+  commands: [{label: "Name", command: "shell cmd"}, ...]
+  queries: ["query1", "query2", ...] \u2014 put 5-8 queries covering everything you need.
+  Runs all commands, indexes output, returns search results. ONE call, no follow-ups.
+
+STEP 2 \u2014 FOLLOW-UP: mcp__${TOOL_PREFIX}__search(queries: ["q1", "q2", "q3", ...])
+  Pass ALL follow-up questions as queries array. ONE call, not separate calls.
+
+OTHER: execute(language, code) | execute_file(path, language, code) | fetch_and_index(url) + search
+
+FORBIDDEN: Bash for output, Read for files, WebFetch. Bash is ONLY for git/mkdir/rm/mv.
+
+OUTPUT FORMAT \u2014 KEEP YOUR FINAL RESPONSE UNDER 500 WORDS:
+The parent agent context window is precious. Your full response gets injected into it.
+
+1. ARTIFACTS (PRDs, configs, code files) \u2192 Write to FILES, never return as inline text.
+   Return only: file path + 1-line description.
+2. DETAILED FINDINGS \u2192 Index into knowledge base:
+   mcp__${TOOL_PREFIX}__index(content: "...", source: "descriptive-label")
+   The parent agent shares the SAME knowledge base and can search() your indexed content.
+3. YOUR RESPONSE must be a concise summary:
+   - What you did (2-3 bullets)
+   - File paths created/modified (if any)
+   - Source labels you indexed (so parent can search)
+   - Key findings in bullet points
+   Do NOT return raw data, full file contents, or lengthy explanations.
+---`;
+  const updatedInput = subagentType === "Bash" ? { ...toolInput, prompt: prompt + ROUTING_BLOCK, subagent_type: "general-purpose" } : { ...toolInput, prompt: prompt + ROUTING_BLOCK };
+  respond({ updatedInput });
+}
+process.exit(0);

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "context-compress",
+  "version": "1.0.0",
+  "description": "Context-aware MCP server that compresses tool output for Claude Code",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "context-compress": "dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc && node esbuild.config.ts",
+    "build:hooks": "esbuild src/hooks/pretooluse.ts --bundle --platform=node --format=esm --outfile=hooks/pretooluse.mjs --target=node18",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "test": "node --import tsx --test tests/**/*.test.ts",
+    "test:unit": "node --import tsx --test tests/unit/*.test.ts",
+    "test:integration": "node --import tsx --test tests/integration/*.test.ts"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.27.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist/",
+    "hooks/",
+    "skills/",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Open330/context-compress"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "context",
+    "compression"
+  ]
+}

package/skills/context-compress/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: context-compress
+description: |
+  Use context-compress tools (execute, execute_file) instead of Bash/cat when processing
+  large outputs. Trigger phrases: "analyze logs", "summarize output", "process data",
+  "parse JSON", "filter results", "extract errors", "check build output",
+  "analyze dependencies", "process API response", "large file analysis",
+  "extract elements", "page snapshot", "browser snapshot", "take a snapshot",
+  "DOM structure", "inspect page", "form fields", "element selectors",
+  "web page structure", "accessibility tree", "Playwright snapshot",
+  "run tests", "test output", "coverage report", "git log", "recent commits",
+  "diff between branches", "list containers", "pod status", "disk usage",
+  "fetch docs", "API reference", "index documentation", "hit endpoint",
+  "call API", "check response", "query results", "show tables",
+  "find TODOs", "count lines", "codebase statistics", "security audit",
+  "outdated packages", "dependency tree", "cloud resources", "CI/CD output".
+  Also triggers on ANY MCP tool output (Playwright, Context7, GitHub API) that
+  may exceed 20 lines, and any operation where output size is uncertain.
+  Subagent routing is handled automatically via PreToolUse hook — no manual tool names needed in prompts.
+---
+
+# Context Compress: Default for All Large Output
+
+## MANDATORY RULE
+
+**Default to context-compress for ALL commands. Only use Bash for guaranteed-small-output operations.**
+
+Bash whitelist (safe to run directly):
+- **File mutations**: `mkdir`, `mv`, `cp`, `rm`, `touch`, `chmod`
+- **Git writes**: `git add`, `git commit`, `git push`, `git checkout`, `git branch`, `git merge`
+- **Navigation**: `cd`, `pwd`, `which`
+- **Process control**: `kill`, `pkill`
+- **Package management**: `npm install`, `npm publish`, `pip install`
+- **Simple output**: `echo`, `printf`
+
+**Everything else → `execute` or `execute_file`.** Any command that reads, queries, fetches, lists, logs, tests, builds, diffs, inspects, or calls an external service.
+
+**When uncertain, use context-compress.** Every KB of unnecessary context reduces the quality and speed of the entire session.
+
+## Decision Tree
+
+```
+About to run a command / read a file / call an API?
+│
+├── Command is on the Bash whitelist?
+│   └── Use Bash
+│
+├── Output MIGHT be large or you're UNSURE?
+│   └── Use context-compress execute or execute_file
+│
+├── Fetching web documentation or HTML page?
+│   └── Use fetch_and_index → search
+│
+├── Using Playwright (navigate, snapshot, console, network)?
+│   └── ALWAYS use filename parameter to save to file, then:
+│       browser_snapshot(filename) → index(path) or execute_file(path)
+│
+├── Processing output from another MCP tool?
+│   ├── Output already in context? → Use it directly
+│   ├── Need to search multiple times? → Save to file → index(path) → search
+│   └── One-shot extraction? → Save to file → execute_file(path)
+│
+└── Reading a file to analyze/summarize (not edit)?
+    └── Use execute_file (file loads into FILE_CONTENT, not context)
+```
+
+## When to Use Each Tool
+
+| Situation | Tool | Example |
+|-----------|------|---------|
+| Hit an API endpoint | `execute` | `fetch('http://localhost:3000/api/orders')` |
+| Run CLI that returns data | `execute` | `gh pr list`, `aws s3 ls`, `kubectl get pods` |
+| Run tests | `execute` | `npm test`, `pytest`, `go test ./...` |
+| Git operations | `execute` | `git log --oneline -50`, `git diff HEAD~5` |
+| Read a log file | `execute_file` | Parse access.log, error.log, build output |
+| Read a data file | `execute_file` | Analyze CSV, JSON, YAML, XML |
+| Fetch web docs | `fetch_and_index` | Index React/Next.js/Zod docs, then search |
+
+## Language Selection
+
+| Situation | Language | Why |
+|-----------|----------|-----|
+| HTTP/API calls, JSON | `javascript` | Native fetch, JSON.parse, async/await |
+| Data analysis, CSV, stats | `python` | csv, statistics, collections, re |
+| Shell commands with pipes | `shell` | grep, awk, jq, native tools |
+| File pattern matching | `shell` | find, wc, sort, uniq |
+
+## Search Query Strategy
+
+- BM25 uses **OR semantics** — results matching more terms rank higher automatically
+- Use 2-4 specific technical terms per query
+- **Always use `source` parameter** when multiple docs are indexed
+- **Always use `queries` array** — batch ALL search questions in ONE call:
+  - `search(queries: ["transform pipe", "refine superRefine"], source: "Zod")`
+  - NEVER make multiple separate search() calls
+
+## Critical Rules
+
+1. **Always console.log/print your findings.** stdout is all that enters context.
+2. **Write analysis code, not just data dumps.** Analyze first, print findings.
+3. **Be specific in output.** Print bug details with IDs, line numbers, exact values.
+4. **For files you need to EDIT**: Use the normal Read tool.
+5. **For Bash whitelist commands only**: Use Bash. Everything else → context-compress.
+6. **Never use `index(content: large_data)`.** Use `index(path: ...)` to read files server-side.
+7. **Always use `filename` parameter** on Playwright tools.
+
+## Subagent Usage
+
+Subagents automatically receive context-compress tool routing via a PreToolUse hook. You do NOT need to manually add tool names to subagent prompts — the hook injects them.
+
+## Anti-Patterns
+
+- Using `curl` via Bash → Use `execute` with fetch or `fetch_and_index`
+- Using `cat large-file` → Use `execute_file` instead
+- Piping Bash output through `| head -20` → Use `execute` to analyze ALL data
+- Running `npm test` via Bash → Use `execute` to capture and summarize
+- Calling `browser_snapshot()` WITHOUT `filename` → Always use `filename` parameter
+- Passing large data to `index(content: ...)` → Always use `index(path: ...)`

package/skills/doctor/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: context-compress:doctor
+description: Run diagnostics to check context-compress health
+---
+
+Run the context-compress doctor diagnostic:
+
+```
+mcp__context-compress__execute({
+  language: "shell",
+  code: "node dist/cli/index.js doctor"
+})
+```
+
+Report the results as-is in markdown format.

package/skills/stats/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: context-compress:stats
+description: Show session statistics for context-compress
+---
+
+Call the `mcp__context-compress__stats` tool to get session statistics.
+
+CRITICAL: Copy-paste the ENTIRE tool output as markdown. Do NOT summarize or truncate any tables.
+
+After the raw output, add one summary line:
+"Context-compress has processed X data and kept Y% out of context this session."