tiny-tools

Small, local-first tools that AI agents install with one config line and actually use to cut their time and token spend — starting with tiny-context, an MCP server that lets an agent know things about files (PDF, DOCX, XLSX, CSV, logs, code) without reading them.

Before → after, measured on this repo's fixtures (read both columns together — the first is the ceiling, the second is what a capable coding agent actually gains):

Method and full tables: Benchmarks · Does it actually help?

Why: reducing tokens-per-step and wall-clock-per-step is what lets an agent take more steps before its context degrades. It's a capability multiplier, not just a cost saving.

Install

The server runs locally over stdio; every client below launches the same command, npx -y -p @tinytools/context tiny-context-mcp.

Claude Code

claude mcp add tiny-context -- npx -y -p @tinytools/context tiny-context-mcp

Codex CLI (writes [mcp_servers.tiny-context] to ~/.codex/config.toml)

codex mcp add tiny-context -- npx -y -p @tinytools/context tiny-context-mcp

Cursor — .cursor/mcp.json, or click the Install in Cursor badge above

{ "mcpServers": { "tiny-context": { "command": "npx", "args": ["-y", "-p", "@tinytools/context", "tiny-context-mcp"] } } }

VS Code — .vscode/mcp.json (note the servers key), or click the Install in VS Code badge above

{ "servers": { "tiny-context": { "type": "stdio", "command": "npx", "args": ["-y", "-p", "@tinytools/context", "tiny-context-mcp"] } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json

{ "mcpServers": { "tiny-context": { "command": "npx", "args": ["-y", "-p", "@tinytools/context", "tiny-context-mcp"] } } }

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)

{ "mcpServers": { "tiny-context": { "command": "npx", "args": ["-y", "-p", "@tinytools/context", "tiny-context-mcp"] } } }

Then paste the snippet below into CLAUDE.md / AGENTS.md / .cursorrules so the agent reaches for the tools at the right moments. Claude Code users can also add the Read guard hook, which turns that choice into a rule.

Related MCP server: Agent Helper

Privacy

• No telemetry. Nothing is counted, phoned home or reported — not installs, not calls, not errors.

• No network calls from any tool. All eight tools read local files and return text; nothing here calls a model or an API.

• Files never leave the device. The server talks MCP over stdio to a client on the same machine; there is no upload path.

• The only optional network use is at install time, when npm downloads the optional @duckdb/node-api native dependency (needed only by query_table). Install with npm install --omit=optional to skip it; every other tool still works.

Packages

Agent usage snippet (all installed packages)

## tiny-context (installed MCP)
- Before reading any file > 20 KB, or ANY PDF/DOCX/XLSX/PPTX: call `file_map` first, then `query_file` / `read_section` for the part you need. Do not Read whole large files.
- Questions about CSV/TSV/XLSX/Parquet data ("total by…", "how many rows…"): `query_table` with SQL (table is `t`). Never load raw rows into context.
- Logs: `summarize_log` first (add `focus: "errors"`); Grep/`extract` only afterwards, for the exact message it surfaced.
- Comparing two files, including office formats: `diff_files` (summary mode) instead of reading both.
- Verifying JSON/CSV/YAML/HTML/Markdown you just wrote: `validate_file`. Pulling emails/URLs/IDs/jq values out of files: `extract`.
- Small plain-text files (< 20 KB, e.g. notes, configs, short docs): just Read them and answer — do NOT also call file_map/query_file on a file you have already read. Grep is right for an exact string in one text file.

Benchmarks — tiny-context

17 tasks · 7,415,930 naive tokens → 9,169 tool tokens · 99.9% saved overall · median 34ms per call

Fixtures (generated locally, seeded): sales.csv 5.2 MB · app.log 2.8 MB · contract.pdf 206 KB · handbook.docx 29 KB (100,000 rows · 50,000 lines · 100 pages · ~18k words) · src/ 37 TypeScript files. · Generated 2026-09-19; re-run with npm run bench.

Full table and method: bench/RESULTS.md. Tool-selection evals: evals/RESULTS.md. Read the next section before quoting the 99.9%.

Does it actually help? (measured honestly)

The benchmark above compares against reading whole files. A capable agent with a shell doesn't do that — so we also ran the same 12 tasks through headless Claude Code in four conditions with identical built-ins (Bash, Read, Grep, Glob) allowed:

Same answers either way. With the tools: ~20% fewer tokens, ~50% less wall-clock, fewer turns — because one call replaces a loop of shell probes, and every turn carries ~24k tokens of fixed context. The 99.9% figure applies to agents that cannot run a shell or open the file at all. Full table and method: evals/COMPARISON.md; what we concluded from it: PROPOSALS.md.

Size

Install size: 134.7 MB (108 packages) — 21.9 MB without DuckDB, which only query_table needs. Largest: @duckdb/node-bindings-darwin-arm64 112.1 MB · zod 5.9 MB · @modelcontextprotocol/sdk 4.1 MB · unpdf 2.0 MB. Measured 2026-09-19 by npm run bench.

Design rules every tool follows

Whole jobs, not endpoints · files in, summaries out · safe output defaults (never overwrite an input; -1, -2 on collision) · errors that teach (what went wrong and what to do next) · deterministic and stateless · descriptions written as prompts (USE WHEN / PREFER OVER / DOES NOT / EXAMPLE / RETURNS) · validate before working · batches report per file · every response bounded (≤ ~4,000 tokens) · a savings line on every response · ≤ 8 tools per server · absolute paths in responses.

Develop

npm install
npm test          # builds, then vitest (shared + context unit, MCP stdio integration, CLI)
npm run bench     # fixtures + benchmark table → bench/RESULTS.md, embedded in READMEs
npm run evals     # headless Claude Code tool-selection evals → evals/RESULTS.md

Node ≥ 20, TypeScript, ESM. See ENV.md, PROGRESS.md, DECISIONS.md. MIT.

Built by AVRG3 · MIT