tiny-context — efficient file tools by AVRG3

tiny-context — 用于文档搜索、SQL 和 JSON 导出变更的 MCP 工具

了解文件内容，无需读取文件。 八种本地、确定性的 MCP 工具，可让 AI Agent 概述、搜索、切分、查询、聚类、比较差异、验证和提取文件内容——包括 PDF、DOCX、PPTX 和 XLSX——并且只返回所需内容，每个响应都会附带节省量说明。

按任务查找工具，查看示例输入 · 实际工具架构 · 安装。由 AVRG3 构建。

专为希望减少文件任务操作步骤的 Agent 设计：

• 解释大型错误日志： summarize_log 返回重复错误、计数和时间范围，无需将每一行日志都放入上下文。
• 回答电子表格问题： query_table 对 CSV/XLSX/Parquet 执行 SQL，并返回查询结果，而非源数据行。
• 查找 PDF 或 Office 文档中的段落： query_file 返回按相关度排序的匹配项；read_section 读取已知位置。仅在需要大纲时使用 file_map。
• 比较 JSON/JSONL 导出文件： diff_files 会按明确的 ID 匹配并记录模式、匹配项、顺序、问题或库存，即使行顺序打乱，也能报告实际变更。选择状态/数量等字段；获取精确的指定范围计数，以及有界的变更前后预览。规范与示例。

衡量完整任务： 工具响应可能比源文件小得多，但启动、验证和 Agent 的额外交互仍会耗费时间。结果取决于任务和客户端。Agent 对比，包含性能退化案例 · 首次对比历史记录。

下方的整文件读取基准衡量的是另一种基线；其节省量不能用来预测能力强的 Agent 的表现。

查找 tiny-context

已列入官方 MCP 注册表，名称为 io.github.Warddamn/tiny-context，并拥有 Glama 资料页。目录索引由外部控制；在 Agent 能调用该服务之前，客户端仍须先连接服务。

0.2.0 新增：按 ID 比较记录

diff_files 现在支持 mode: "records"，可用于 JSON/JSONL/NDJSON 快照，支持显式指定 key 指针以及可选的 fields/records_path。遇到有歧义的 ID 和精度损失时会拒绝处理；out 会将每项变更保存为 JSONL，且不会替换现有文件。工具仍为八个；不新增依赖，也不调用模型。示例与限制 · 与现有正确脚本的基准对比 · 真实 Agent 检查。

这样可以避免将未变更的记录发送给模型，但仍会在本地读取两个文件。对于小文件和现有的正确脚本，后者可能成本更低、速度更快。

安全控制（0.1.1 引入）

使用下方当前的安装按钮/配置升级旧版安装，然后重新连接服务。已固定版本的现有安装不会自动更新。

SQL 仅接受针对所提供表的一条只读查询。外部文件/网络访问和 SQL 写入命令均已禁用；导出必须指定 out，且绝不会替换现有文件。输入/导出大小上限为 64 MB；查询工作进程的默认截止时间为 15 秒，并对引擎/JavaScript 内存设有上限。这些控制并非操作系统安全沙箱。

对于问题，直接使用 query_file；对于已知位置，使用 read_section；只有在需要大纲时才使用 file_map。重复读取文档时会复用缓存，最多缓存八个文件、16 MB 序列化解析数据，缓存时间为 30 秒，并且每次命中时都会检查文件身份和修改元数据。可选的 Read 钩子仍会构建大纲并启动独立进程；它可能增加工作量，并非必需。处理小型文本和精确字符串搜索时，通常只需使用内置工具。工具会带来启动/验证开销，并不能保证每项任务的总成本都会降低。

tiny-context 0.3.0 新增：可复用文档配置

为文档的标签和检查项保存一次配置，然后对重复出现的表单/报告使用 extract 批量提取。支持 TXT/Markdown、DOCX 和文本层 PDF；无需训练、调用模型或自动推断。缺失或有歧义的字段会返回 needs_review，且不会返回部分值。配置保留在本地，每份新文档都会重新解析并检查。保存并复用配置 · 设置、批处理和预先准备脚本的测量结果。

响应更短，并不能证明账单更低。 早期的键控比较试验速度更快，但在两次配对运行中，成本分别高出约 33% 和 3%。配置是为重复工作提供的可选功能，并非廉价的单次读取或现有正确脚本的替代品。缩短描述后，其工具定义总载荷略小于 0.2.0。Agent/设置/缓存成本仍取决于客户端。已保存配置的试验及其限制说明了最初多一次调用的问题及修正后的结果。

安装

**兼容 MCPB 的客户端：**从 Agent bundle 发布页下载适用于你操作系统的捆绑包，并在客户端中打开。darwin = macOS，win32 = Windows，linux = Linux。每个捆绑包都包含 x64 和 arm64 的依赖项；仍需 Node.js 20+ 运行时（部分客户端会提供）。这些捆绑包未经签名，注册表中提供了 SHA-256 哈希值。macOS、Linux 和 Windows 的下载大小分别约为 77 MiB、96 MiB 和 34 MiB。全部八个工具都已在 macOS、Linux 和 Windows 上通过解压后的捆绑包进行测试；并非所有 CPU/OS 组合或客户端界面都经过测试。

**其他 MCP 客户端：**使用下面的现有命令。这些命令只会下载当前计算机所需的依赖项。

**需要 Node.js 20+。无需 npm 账户或令牌。**使用下面发布的 GitHub 版本。npm 包尚未发布；这些命令不依赖该包。服务通过 stdio 在本地运行。首次启动时，请留出下载依赖项的时间。

Claude Code

claude mcp add tiny-context -- npx -y -p https://github.com/Warddamn/tiny-tools/releases/download/context-v0.3.0/tiny-context-standalone-0.3.0.tgz tiny-context-mcp

Codex CLI（将 [mcp_servers.tiny-context] 写入 ~/.codex/config.toml）

codex mcp add tiny-context -- npx -y -p https://github.com/Warddamn/tiny-tools/releases/download/context-v0.3.0/tiny-context-standalone-0.3.0.tgz tiny-context-mcp

Cursor — .cursor/mcp.json，或点击上方的 Install in Cursor 徽章

{ "mcpServers": { "tiny-context": { "command": "npx", "args": ["-y", "-p", "https://github.com/Warddamn/tiny-tools/releases/download/context-v0.3.0/tiny-context-standalone-0.3.0.tgz", "tiny-context-mcp"] } } }

VS Code — .vscode/mcp.json（注意 servers 键），或点击上方的 Install in VS Code 徽章

{ "servers": { "tiny-context": { "type": "stdio", "command": "npx", "args": ["-y", "-p", "https://github.com/Warddamn/tiny-tools/releases/download/context-v0.3.0/tiny-context-standalone-0.3.0.tgz", "tiny-context-mcp"] } } }

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

{ "mcpServers": { "tiny-context": { "command": "npx", "args": ["-y", "-p", "https://github.com/Warddamn/tiny-tools/releases/download/context-v0.3.0/tiny-context-standalone-0.3.0.tgz", "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", "https://github.com/Warddamn/tiny-tools/releases/download/context-v0.3.0/tiny-context-standalone-0.3.0.tgz", "tiny-context-mcp"] } } }

然后将 docs/AGENT_USAGE.md 粘贴到你的 CLAUDE.md / AGENTS.md / .cursorrules 中，让 Agent 在合适的时候调用这些工具。Claude Code 用户还可以添加 Read guard hook，这是一项可选的、更严格的策略。请先使用代码片段；该 hook 并未改善测得的对比结果。

TINY_TOOLS_DEBUG=1 会将每次调用记录到 stderr。

与你的 Agent 试用

设置完成后，重启或重新连接客户端。确认 tiny-context 已连接并提供八个工具。然后使用三个完整示例，分别处理 CSV 问题、PDF 条款和错误日志，并查看预期答案。

Claude Code 插件：/plugin marketplace add Warddamn/tiny-tools，然后运行 /plugin install tiny-context@tiny-tools。该插件同时包含服务和任务选择指南。请选择此方式或手动配置 MCP，以避免重复的服务。

隐私

• **工具不会收集遥测数据。**服务不会发送使用报告或分析数据。
• 工具会处理本地文件，并将选定的文本返回给 MCP 客户端。它们不会调用模型，也不会自行上传文件；客户端可能会根据其设置，将这些文本发送给模型提供商。
• 首次启动时会使用 npm 下载发布版本和第三方依赖项，其中包括用于 query_table 的可选 DuckDB。这不是离线安装程序。GitHub 和 npm 会各自统计下载次数；这些统计并不代表 Agent 或用户的数量。

它取代了什么

只为某一轮任务而读取整个文件的 Read/cat 调用；通过 ls+grep+head 循环来了解文件夹内容；只为统计一列而编写的脚本；遍历日志的 tail/grep 循环；打开内置工具完全无法读取的 PDF 和 Office 文件。

为什么

典型 Agent 的上下文窗口中约有 50% 被工具结果占用，其中大部分是只对某一轮任务有用的整文件读取；Agent 的工作负载以读取和审阅为主（已发布的测量结果中，检查约占 59%，编写约占 9%）；将中间数据排除在上下文之外，已显示可将 token 数最多减少 98%。这些工具让 Agent 无需读取文件也能了解文件内容。每个响应都有长度上限，并以一行节省量说明结尾。

降低每步的 token 消耗和耗时，能让 Agent 在上下文质量下降前执行更多步骤——这是一种能力倍增器，而不仅仅是节省成本。

基准测试

17 项任务 · 7,417,733 个朴素令牌 → 9,158 个工具令牌 · 总体节省 99.9% · 每次调用中位耗时 11ms

工具	任务	朴素令牌	工具令牌	节省	耗时
query_table	按地区统计总销售额（sales.csv）	1,370,762	75	99.99%	0.2s
query_table	有多少行的总计为负数（sales.csv）	1,370,762	37	99.99%	0.2s
query_table	有哪些列及其类型（sales.csv）	1,370,762	186	99.99%	0.2s
summarize_log	导致 5xx 激增的原因是什么（app.log）	731,145	380	99.9%	35ms
summarize_log	总结此日志（app.log）	731,145	698	99.9%	92ms
file_map	这份 100 页合同包含什么内容（contract.pdf）	72,055	2,065	97.1%	0.2s
query_file	合同在哪些部分讨论了终止条款（contract.pdf）	72,055	713	99.0%	14ms
read_section	读取有关终止条款的页面（100 页中的 2 页）（contract.pdf）	72,055	1,528	97.9%	4ms
file_map	概述这本 40 页的员工手册（handbook.docx）	31,699	483	98.5%	7ms
query_file	员工手册是否涵盖远程办公（handbook.docx）	31,699	310	99.0%	4ms
read_section	阅读员工手册中的 Termination 部分（handbook.docx）	31,699	1,166	96.3%	1ms
extract	提取员工手册中的所有电子邮件地址（handbook.docx）	31,699	51	99.8%	2ms
diff_files	两个版本的员工手册有哪些更改（handbook.docx ↔ handbook-v2.docx）	63,429	293	99.5%	5ms
file_map	此源代码树中包含什么内容（src/）	2,788	327	88.3%	3ms
file_map	此模块中有哪些函数（src/…/paths.ts）	1,607	259	83.9%	3ms
query_file	哪些函数调用了 resolveInputs（src/**/*.ts）	61,610	550	99.1%	11ms
validate_file	这个包含 10 万行的 CSV 格式是否正确（sales.csv）	1,370,762	37	99.99%	59ms

测试数据（本地生成，使用固定种子）：sales.csv 5.2 MB · app.log 2.8 MB · contract.pdf 206 KB · handbook.docx 29 KB（100,000 行 · 50,000 行日志 · 100 页 · 约 18k 个单词）· src/ 包含 38 个 TypeScript 文件。 · 生成于 2026-09-22；使用 npm run bench 重新运行。

测量方式贴近 Agent 的实际体验：朴素令牌 = 读取任务所需原始内容的令牌数（字节数/4）；工具令牌 = 工具完整响应的令牌数。测试数据由 bench/ 在本地生成。

**历史对比（2026-09-19，此补丁之前）：**通过无头 Claude Code 执行相同的 12 项任务，无论是否使用 tiny-context，答案都相同；工具令牌数减少约 20%、成本降低约 19%、耗时缩短约 50%，轮次从 4.3 降至 3.5，因为一次调用就能代替一轮 Shell 探查。请参阅归档文件 evals/COMPARISON-2026-09-19.md；当前结果见 evals/COMPARISON.md。

大小

安装大小：134.7 MB（108 个包）——不含 DuckDB 时为 21.9 MB，只有 query_table 需要 DuckDB。最大依赖项：@duckdb/node-bindings-darwin-arm64 112.1 MB · zod 5.9 MB · @modelcontextprotocol/sdk 4.1 MB · unpdf 2.0 MB。由 npm run bench 于 2026-09-22 测量。

各依赖项及其用途：

依赖项	用途	加载时机
@modelcontextprotocol/sdk	官方 MCP 服务/客户端（stdio）	启动时
zod	同一份 Schema 为库、CLI 和 MCP 提供驱动；参数说明定义于此	启动时
commander	CLI	仅 CLI
@tiny_tools_pw/shared	路径/Glob 解析、安全输出、错误指导、记录账本、文本提取（PDF 使用 unpdf，Office 文件使用 fflate + 正则表达式）	启动时；unpdf 延迟加载
@duckdb/node-api (可选，原生)	在 query_table 中对 CSV/TSV/Parquet/XLSX 执行 SQL	延迟加载，仅用于 query_table
ajv · yaml · fast-xml-parser	在 validate_file 中检查 JSON Schema · YAML · XML	延迟加载，按检查项加载

无需模型、无需二进制文件、无需联网。extract 在系统中存在 jq 时使用它，否则使用内置的路径子集。

Read 防护钩子（推荐）

工具描述和代码片段会让 Agent 选择 tiny-context。钩子则移除这个选择：当目标是 PDF/DOCX/PPTX/XLSX（Read 无法打开这些格式）或超过 20 KB 的文本文件时，它会拦截内置的 Read，阻止读取，并向 Agent 提供文件大纲以及准确的后续调用（read_section、query_file、query_table、summarize_log）。小文件以及已传入 offset/limit 的 Read 不受影响。钩子内部出现任何错误时，都会放行 Read。

Claude Code — 添加到 ~/.claude/settings.json（所有项目）或 .claude/settings.json（单个项目）：

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Read", "hooks": [ { "type": "command", "command": "tiny-context-read-guard", "timeout": 30 } ] }
    ]
  }
}

运行 npm i -g https://github.com/Warddamn/tiny-tools/releases/download/context-v0.3.0/tiny-context-standalone-0.3.0.tgz 后，tiny-context-read-guard 会出现在 PATH 中（也可以使用完整路径 hooks/read-guard.mjs）。阈值：TINY_CONTEXT_READ_GUARD_KB（默认值为 20）。实测效果：参见 evals/COMPARISON.md（hook 条件下完全不使用代码片段）。

工具

工具	一句话说明	相比内置功能的优势
file_map	不读取内容即可查看文件/目录大纲：标题、签名、工作表/列、幻灯片标题、页面、大小树	一次调用即可替代 ls+grep+head 循环；支持打开 Office/PDF 格式
query_file	在多个文件中检索排序后的段落（BM25 + 精确短语加权，或正则表达式），并提供准确位置	Grep 无法搜索 PDF/Office 文件，也无法跨文件排序；后续读取精准定位
read_section	仅读取定位到的部分：标题章节、页码范围、行范围、¶ 范围、工作表范围、幻灯片	Read 无法对 PDF/DOCX/XLSX/PPTX 分段读取；可配合 file_map/query_file 使用
query_table	对 CSV/TSV/Parquet/XLSX 执行 DuckDB SQL（表名为 t），报告总行数，并通过 out 将完整结果输出为 CSV	无需将数据载入上下文即可执行聚合；无需编写脚本
summarize_log	按模板聚类并提供计数、首次/最后时间、各一个样例；按级别计数；速率时间线	80k 行 → 约 300 个令牌；Grep 循环无法识别结构
diff_files	比较文档/表格变化、生成统一 diff，或比较带字段范围和完整报告的键控 JSON/JSONL 记录	即使导出记录顺序改变，也只返回一个有界结果；无需猜测 ID
validate_file	JSON/YAML/XML 解析 · CSV 结构 · JSON Schema · Markdown/HTML 内部链接 · 编码/BOM	一次调用，无需配置代码检查工具；确定性检查，无需重新读取
extract	正则表达式 / 内置类型（电子邮件、URL、日期、数字）/ 带位置和计数的 jq 值	Grep 无法打开 Office/PDF；在同一处完成去重、类型提取和 jq 查询

每个响应都包含：标题 · 有界负载（≤ 约 4,000 个令牌）· 注意事项（达到上限、跳过的文件）· Returned ~214 tokens · raw ≈ 48,200 tokens · 99.6% saved · 0.4s。

每条错误都会说明出错原因以及下一步操作（Input not found: … — accepts absolute paths and globs like './shots/*.png'；SQL 错误会包含表的列和类型）。

CLI

tiny-context map ./src
tiny-context map ./report.docx
tiny-context query ./contract.pdf "termination notice" -n 5
tiny-context read ./contract.pdf --pages 3-5
tiny-context read ./spec.md --heading Installation
tiny-context read ./book.xlsx --sheet Sales --range A1:F20
tiny-context table ./sales.csv "SELECT region, SUM(total) FROM t GROUP BY 1"
tiny-context log ./app.log --focus errors --since 2h
tiny-context diff ./v1.docx ./v2.docx
tiny-context validate ./out/data.json --schema ./schema.json
tiny-context extract ./docs/*.pdf --kind emails
tiny-context extract ./data.json --jq ".items[].name"

成功时退出代码为 0；否则在 stderr 中输出引导式错误并以 1 退出。tiny-context tools 会列出 MCP 工具。

工具参考

file_map

path（文件或目录）· depth?（默认值为 2，最大值为 8）。Markdown/DOCX → 标题树，含行/¶ 和词数；代码 → 函数/类/方法签名及行号 + 导入项（按语言使用正则表达式：TS/JS、Python、Go、Rust、Java/Kotlin/C#/C/C++、Ruby、PHP、Swift、shell、SQL）；XLSX → 工作表、标题行、行/列数；PPTX → 幻灯片标题；PDF → 页面、大纲、每页首行；CSV → 列 + 行数；JSON → 结构；日志 → 级别 + 范围；目录 → 带大小标注的树（跳过 node_modules、.git、dist 等，并提供计数）。

query_file

path 或 paths[]（支持 glob）· query · regex? · max_results?（默认值为 8，上限为 30）· context_lines?（默认值为 2）。按 BM25 对约 700 字符的段落排序，并对精确短语加权；每个匹配项均显示 file · location (heading path) 和简短摘录。无法读取的输入会列在 skipped: 下，其余输入仍会继续处理。

read_section

path · locator = {heading} | {pages:"3-5"} | {lines:"120-180"} | {paras:"88-95"} | {sheet, range:"A1:F20" | "10-40"} | {slide: 4 | "2-5"} · max_tokens?（2000，上限 8000）。达到上限时，响应会准确指出从哪个定位符继续。

query_table

path（csv/tsv/parquet/xlsx/json）· sql（表 t）· max_rows?（50，上限 200）· out?（完整结果的 CSV 路径）· sheet?（xlsx）。达到上限前会报告结果总行数。错误信息会包含列名和类型。

summarize_log

path · focus?（errors | warnings | 关键词/正则表达式）· since?（ISO 或 2h/30m/3d）· max_clusters?（15，上限 50）。分组前会屏蔽数字/十六进制值/UUID/IP/路径/URL/电子邮件；可识别 ISO、YYYY/MM/DD、syslog、Apache CLF 和 epoch 时间戳。

diff_files

a · b · mode?（summary | unified | records）· max_hunks?（20，上限 100）。摘要模式：两个表格（csv/xlsx）→ 按行添加/删除/更改（在首列值唯一时以首列匹配）；否则，对提取的文本进行 patience diff。记录模式：JSON/JSONL/NDJSON 需要提供 key JSON Pointers；可选 fields、records_path 和用于生成完整 JSONL 报告的 out。完整记录约定。

validate_file

path · schema?（JSON Schema，draft-07 或 2020-12）。按扩展名检查：json/jsonl · yaml · xml/svg · csv/tsv · md/html 中的链接、锚点和图片；始终检查：BOM、无效 UTF-8、NUL 字节、混合换行符。

extract

已保存的配置文件：profile + 批量 paths，可选 out（完整 JSONL 报告）。最多支持 100 个反复使用的带标签 TXT/Markdown、DOCX 或文本层 PDF 文件。无需训练；每次都会检查必需锚点/字段。请先在有大小限制的预览中查看结果行。配置文件格式和示例。其他提取模式如下：

path 或 paths[] · 以下选一：pattern（+ ignore_case?）| kind（emails urls dates numbers）| jq · max_matches?（100，上限 500）· dedupe?（true）。安装了 jq 时使用系统二进制；回退实现支持 .a.b、.items[]、.items[2].name、.["k"]、keys、length、values、.. 和 | 链。

限制（如实说明）

不使用嵌入向量——query_file 采用关键词排序。代码大纲基于正则表达式。没有文本层的 PDF（扫描件）会报告 NO TEXT LAYER；OCR 不在支持范围内。query_table 会将一个文件视为一张表（不支持联接）。这里的所有功能都不会调用网络或模型。

许可证：MIT。

---

由 AVRG3 构建 · MIT