Jarroba Tools

Jarroba Tools MCP

本地 MCP 服务（stdio），为 AI 提供 Jarroba Tools 中确定性的工具，让它通过计算得出答案，而不是凭空编造。 所有操作都在你的机器上运行：宿主会将服务作为子进程启动，并通过 stdin/stdout 与其通信。无需网络、端点或账户。

这些工具复用与 Web 应用相同的逻辑——使用服务层，不包含 Angular——因此不存在需要保持同步的第二套实现。

四个软件包，因为上下文并非免费

如果客户端会预先加载所有工具定义（Cursor 和大多数其他客户端；关闭 Tool Search 的 Claude Code），加载全部 140 个工具需要约 53,800 个上下文 token，而你还没输入任何内容。这是 Claude Code 自己统计的数量：在 0.1.7 上使用 /context 测量（120 个工具：41,996 个 token），并通过 npm run tokens 推算得出。Claude Code 默认开启的 Tool Search 只会在即将使用某个工具时加载其定义：这种情况下，整个目录只需要几百个 token。GitHub 的官方 MCP 服务是这个问题的典型例子；Cursor 的上限约为 40 个工具。包含 140 个工具的目录并不代表“更完整”，而是成本更高——模型的选择也会变差，因为大型目录的常见问题不是缺少工具，而是它选中了旁边的那个工具。

所以，请选择你真正需要的：

软件包	工具	上下文	用途
@jarroba/mcp-logs	12	约 5,500 个 token	读取超出上下文容量的日志
@jarroba/mcp-tests	4	约 1,700 个 token	审核测试，包括你自己的测试
@jarroba/mcp-calc	5	约 1,600 个 token	处理带单位的数学计算、方程和表格
@jarroba/mcp	140	约 53,800 个 token	全部工具

这四个软件包都来自同一套源码。筛选由 JARROBA_MCP_DOMAINS 环境变量控制，每个二进制文件都会设置自己的默认值，而不是限制：安装 mcp-logs 后，如果还想使用通用工具，可设置 JARROBA_MCP_DOMAINS=logs,core。领域包括：core、calc、diagram、kg、db、ai、logs、queue、project、tests、api、chip、chem、access、archsim、security、experiments、payroll。

新的补充，而非替代方案：Tool Search

自 2026 年 1 月起，Claude Code 默认会延迟加载完整的工具架构，只有在模型决定搜索时才会加载。Anthropic 表示，在他们自己的基准测试中，这能显著减少大型目录的上下文占用。这并不意味着上面的软件包拆分毫无意义：延迟加载时，工具名称和服务自身的 instructions 仍会在会话开始时加载，因此包含 103 个工具的服务仍比包含 11 个工具的服务占用更多基线上下文；而且并非所有 MCP 客户端都会自动延迟加载（有些需要调用方明确选择启用某个工具；较旧的客户端或其他客户端则一律预先加载所有工具）。这也是为什么这里的每个服务现在都会设置简洁的 instructions 字段——在延迟加载模式下，该字段是唯一能告诉模型何时需要在这里搜索的文本。

安装

// Claude Desktop (claude_desktop_config.json), Cursor, Cline, VS Code…
{ "mcpServers": {
    "jarroba-logs":  { "command": "npx", "args": ["-y", "@jarroba/mcp-logs"] },
    "jarroba-tests": { "command": "npx", "args": ["-y", "@jarroba/mcp-tests"] }
} }

# Claude Code
claude mcp add jarroba-logs -- npx -y @jarroba/mcp-logs

npx 会将软件包下载到你的机器上，并在本地运行。不会上传任何内容。

---

这里真正不同的地方

这个目录中的大部分工具都用于模型容易算错的算术问题。其中有两部分则完全不同。

阅读超出上下文容量的日志

日志工具接受文件路径，而不仅仅是粘贴的文本。这正是它们的意义：生产环境或 CI 日志有几十或几百 MB，永远无法塞进一次工具调用中——但服务在 Node 中运行，因此可以自行打开文件，只返回能容纳的内容。调试 CI 失败的 Agent 无法通读日志；它可以针对日志提问。

• log_analyze — 格式、事件数量（40 行的堆栈跟踪算一个事件）、级别、时间范围、已解析出根本原因的错误、最常见的模式。
• log_reduce — 将日志裁剪到指定字符数，同时保留完整跟踪的错误、错误发生前的时间窗口，以及只出现过一次的内容。重复项会折叠为 [xN]。
• log_patterns — 将日志行归并为模板（Drain）：“connected to 10.0.0.1”和“connected to 10.0.0.7”会被视为同一条消息。还会返回罕见模式，而这通常正是你想找的。
• log_trends — 回答从什么时候开始出现，将每种模式与自身比较，而非与总量比较。返回激增的模式、新出现的模式，以及不再出现的模式——最后一种情况不会触发任何地方的计数器，却往往是更坏的消息。
• log_around — 某个时刻附近还发生了什么。之前开始的事件可能是原因；之后发生的通常是结果。
• log_distinguish — 找出一组事件（默认是错误）与其余事件不同之处：其中占比过高的字段=值对，例如所有失败共同使用的版本。
• log_stacktrace — 支持 Java/JVM、Python、Node、Go、.NET、Rust、Ruby、PHP：返回 Caused by 链、根本原因，以及你的代码中的第一个堆栈帧。
• log_lint — 检查日志是否编写规范：是否打印了密钥、是否有一行内容刷满文件、时间戳是否缺少时区、时钟是否倒退、是否缺少请求 ID。
• log_convert — 支持 JSON / logfmt / syslog 5424 / CSV / OpenTelemetry / ECS，并会预先说明转换会丢失哪些内容。
• log_rotation — 按时间顺序排列轮转日志。轮转编号与时间顺序相反，而且按字母顺序排列时，app.log.10 会排在 app.log.9 前面。先使用此工具，否则你会按倒序阅读。
• log_profile_check / log_profile_suggest — 可复用的配置，用于描述团队日志的格式。check 会返回每个错误及其确切字段，方便模型自行修正。

与调用者唱反调的工具

当 Agent 被要求“让测试通过”时，有两条路可选：诊断错误，或放宽匹配器／删除断言／跳过测试用例。第二条路更省事。更好的模型无法解决这个问题，在提示词中客气地请求也无济于事——需要一个独立于模型的评判者。目录中只有这一部分专门用于反驳调用者。用它检查你自己的工作。

• test_audit — 逐个分析测试文件，说明它实际断言了什么：哪些断言检查值，哪些只检查某项是否存在，哪些没有断言，哪些已禁用——每个判定都附有证据。支持 TypeScript、JavaScript、Python、Java、Go。
• test_diff_audit — 比较两个版本，并判断修改是否削弱了安全网：放宽匹配器、断言消失、测试用例不再运行。
• test_cases — 根据类型列出值得编写的测试用例，说明适用的技术及其原因（如果没有排序关系，边界值就毫无意义，因此布尔值不适用），并列出时间有限时最值得优先编写的五个用例。
• test_debt — 列出所有已禁用的测试及其禁用时长，数据来自 git blame。覆盖率报告中不会显示这些测试，因为对测试运行器而言，它们并不存在。

它不会轻易指责：如果它无法识别某个匹配器，就会返回**“indeterminate”**，绝不会说“没有断言”。如果团队自定义了 expect()，请在 dialects 中声明。

---

目录中的其他工具

可通过 @jarroba/mcp 使用，也可通过扩展 JARROBA_MCP_DOMAINS 使用。 图表（diagram，8 个） — JTD 是一种供 AI 编写图表的 JSON 格式。diagram_svg 会在纯 Node 环境中渲染图表，让模型能够真正看到绘图；增量构建器（diagram_new / _add / _preview）让它可以分步构建并循环查看，这是它判断自身输出的唯一方式。 mermaid_validate 会对 Mermaid 代码运行Mermaid 自带的解析器（与网页端使用的版本相同），并返回包含行号、列号和预期标记的错误信息——模型编写的 Mermaid 可能无法渲染（未加引号的括号、将 end 用作 ID、饼图中的 %），看到解析器的错误后，它们就能自行修复。它只负责解析；解析器作为单独的文件提供，首次使用时才会加载，因此在此之前不会产生任何开销。

数据库（db，9 个） — 通过在临时 PostgreSQL（pglite）中执行 DDL，将 SQL 文本转换为真实的架构，而不是用正则表达式猜测：转换 MySQL/SQLite/SQL Server/Oracle 转储、审查设计、生成文档或实体类。其中 3 个工具关注的是数据，而非结构：实际能返回行的联接路径、数据所支持的外键（通过计数得出，而非猜测），以及能发现静默故障的行级安全检查——还可以在回滚的事务中模拟特定角色实际能看到的内容。db_query_check 会针对你的架构运行查询——检查查询能否运行、返回哪些列和类型；如果提供 compareWith，还会找出两个查询结果不同的最小数据集（例如含有 NULL 的 NOT IN），并附上相应的 INSERT 语句。db_migration_measure 会在你的架构上运行迁移，并测量每条语句实际获取的锁（pg_locks）、是否会重写表或完整扫描表，并生成更安全的版本（CONCURRENTLY、NOT VALID + VALIDATE、lock_timeout…）——而不是猜测锁级别。传入应用的 queries 后，它还会指出迁移会破坏或改变哪些查询。

知识图谱（kg，4 个） — 提供 SPARQL 1.1、SHACL，以及构建于 Oxigraph 之上的“语义即代码”层（WASM，无需服务），让“收入”这类指标根据约定一致的定义计算，而不是根据某人随意编写的查询计算。

AI 相关的 AI 工具（ai，6 个） — 这些工具具有确定性且不依赖模型，因此在此特别有用：AI 可以审查自己的系统提示词、准备 RAG 语料库、检查自己的回答中的声明和来源、验证刚编写的评估套件，或审计它正在考虑安装的 MCP 服务目录；还可以根据先前批准的 tools/list，发现“暗度陈仓”（批准后发生变化的工具），而无需消耗模型调用。在推荐训练数据中学到的实践之前，practice_check 会根据一份带日期的登记表，告知 AI 该实践是否仍然适用、被什么取代、从何时开始以及可信度如何；结合它的知识截止日期，只会报告之后发生的变化。

项目工作坊（project，10 个） — 模拟 make 而不实际运行，并说明每个目标为何需要重新构建；将真实的 make 日志与预测结果对比（模拟结果显示“已缓存”，实际却重新构建，说明存在未声明的依赖项）；无需 git 即可运行 git check-ignore -v，还会指出 git 和 Docker 对同一文件意见不一致的地方，以及哪些 Docker 层会因更改而失效。dora_metrics 会根据 gh run list JSON（以及用于计算前置时间的 git log）计算四项 DORA 指标，说明每次失败部署为何计为失败，并根据 2019-2024 年每份 State of DevOps 报告对团队进行分类——如果报告中的表格无法确定结果，就会标记为“有歧义”。maven_plan 会在不运行 Maven 的情况下说明 mvn <command> 在项目中会执行哪些操作——包括 reactor 顺序、逐阶段执行内容，以及每个目标的来源（打包配置、你的 pom、父级或配置文件）——并逐个目标与真实的 mvn 日志核对；gradle_plan 会读取 --dry-run 输出，并给出每项任务对应的 Maven 操作。 化学与固态（chem，12）——这是整个服务的典型案例。模型会编造铬的电子排布，在电离时从错误的轨道移除电子，还会混淆键能（D0）与势阱深度（De）。这里通过具有实测预期结果和测试的服务解决这些问题。对于溶液：计算任意酸、碱和盐混合物的精确 pH，并附上教科书公式及其误差（chem_ph）；计算滴定的当量点和最佳指示剂（chem_titration）；判断盐是否会沉淀以及能溶解多少（chem_solubility）。每个常数都附有测得该常数的论文。

排队与消息代理（queue，8）——Erlang B 和 M/M/c：需要多少资源、人们要等多久、多少请求会被拒绝。还提供模拟来交叉验证公式。此外，还包含模型凭空计算时容易出错、从 RabbitMQ 和 Kafka 移植而来，并根据真实的 4.0.5/4.3.6 和 4.3.1 代理校准的代理计算：RabbitMQ 交换机将消息路由到哪些队列，以及原因（rabbit_route）；AWS SNS 筛选策略是否允许消息通过（sns_filter，依据 AWS 文档）；Kafka 键会落入哪个分区（kafka_partition，使用 murmur2 并展示计算过程）；以及消费者组如何分配分区（kafka_assign：range、roundrobin、sticky、cooperative-sticky）。

身份与 RBAC（access，4）——一种与供应商无关的身份与 RBAC 模型，可映射 Azure RBAC、AWS IAM/Organizations、GCP Resource Manager 或 Kubernetes RBAC，且每条规则都经过官方文档验证。access_check 会回答“此主体能否在此范围执行此操作，以及原因”，给出三值判定（允许／拒绝／不确定——未建模条件会影响结果时，判定为第三种），并逐步追踪由哪条规则作出判定；access_who_can 则针对一组候选主体回答相反的问题；access_diff 比较同一场景的两个版本（例如用户离职流程或移除角色分配），并报告哪些人获得或失去访问权限。场景通过 world 内联传入——无需同步维护服务端会话。cedar_check 则使用官方 Cedar 引擎运行 Cedar 策略（AWS Verified Permissions）：报告解析和架构错误，并针对每个请求给出允许／拒绝结果及作出判定的策略——能够区分缺少许可策略与最终生效的禁止策略。

架构模拟（archsim，2）——Architecture Simulator 对 archsim 格式的引擎（archsim.md，与 llms.txt 同目录）。archsim_validate 检查文档；archsim_simulate 运行模拟并返回吞吐量、p50/p95 响应延迟（到达第一个队列时结束）和处理延迟、可用性、瓶颈、每小时成本、各队列的积压延迟／“N 秒后填满”／静默丢失的消息，以及与工具 Report 相同的分析结果。队列主动拉取（消费者尽可能多地获取消息），缓存会缩短调用路径，负载均衡器会分配请求，服务会调用所有依赖项，自动扩缩容大约需要一分钟才能生效。可选的定时 phase 可模拟流量高峰、DDoS 攻击或 LLM 中断，展示最坏情况。

A/B 实验（experiments，3）——解决模型选错检验方法的问题。abtest_analyze 会使用正确的方法（z 检验或 Fisher 精确检验），提供区间、变体优于对照组的贝叶斯概率 P，以及采用 Holm/BH 校正的 A/B/n 分析，并始终检查样本比例失配；abtest_sample_size 规划所需访客数和天数（R 的 power.prop.test）；abtest_sequential 提供窥探数据时每次查看对应的边界（Pocock、O'Brien-Fleming、Lan-DeMets spending）。测试中的结果已与 R/ldbounds 参考值核对。 安全（security，10 项）——Agent 在采取行动前应检查的内容，使用与 Web 安全工具相同的引擎。hidden_text_scan 可查找模型实际上无法看到的指令（不可见 Unicode 标签字符、变体选择符和位编码、双向控制符、形近字母），并将其解码；paste_check 可在日志或 HAR 被贴进工单前找出其中的机密，指出每项机密所在的请求和标头，并返回已脱敏的副本；actions_audit 可发现可注入的 GitHub Actions 工作流、pull_request_target 检出操作和未固定版本的 Actions；headers_audit、email_auth_audit（SPF/DKIM/DMARC）和 saml_audit 会检查你粘贴的内容；agent_config_audit 会检查 Agent 自身的设置、MCP 配置、任务和指令文件，并优先列出无需任何人批准就会运行的内容；oauth_audit 会根据 RFC 9700 检查 /authorize URL 和／或粘贴的 openid-configuration（PKCE S256、state、nonce、PAR、重定向 URI、隐式授权和密码授权、id_token "none"……）；k8s_network_reach 会根据你的 NetworkPolicies 告诉你哪些 Pod 之间可以互相访问（只列出可连接的组合及其端口），并解释某个组合被阻止的原因；k8s_manifest_check 会说明集群是否会接受这些清单——根据你的 Kubernetes 版本对应的官方架构（1.33–1.37）检查未知字段并给出你可能想用的字段、错误类型、已移除的 API，以及各工作负载和命名空间的 Pod 安全标准。core 中的 jwt_decode 现在也会标记令牌中可能导致接受风险的内容：alg none、缺少 exp、kid 注入、标头中携带的密钥，以及在提供密钥时检测算法混淆和过短的 HMAC 密钥。只对你传入的内容进行静态分析：不会获取任何内容，也不会运行任何内容。

通用（core，32 项）——CIDR/子网划分、使用真实分词器进行令牌计数（OpenAI 的分词器，以及本地运行的 Qwen3 和 Mistral，还有经测量得出的 Claude 估算值）、哈希、JWT 解码、正则表达式（以及静态 ReDoS 检查 regex_redos_check）、电子表格公式审计（spreadsheet_audit：重新计算 .xlsx/.ods 并标记过期值和循环引用）、按键值对任意大小的 CSV 进行差异比较（csv_diff：找出缺失、多余或已更改的行，以及具体变更列）、时间戳、cron、颜色、WCAG 对比度、chmod、JSON 差异、单位（kB 与 KiB）、汉明距离、IEEE-754、数字进制、程序员计算器、semver、格式转换、Unicode，以及 json_schema_validate（根据真实的 JSON Schema 验证 JSON 文档，支持 draft 2020-12/2019-09/07，并提供每个错误的 JSON Pointer——用于检查你自己的结构化输出）。

base_convert（支持 2–64 进制和本地化名称）不在这里：它的服务依赖 LOCALE_ID。number_bases 已支持 2/8/10/16 进制。

---

隐私与坦诚的威胁模型

传输方式为 stdio，且一切都在本地运行。 没有服务端、没有网络、没有遥测。

有两件事值得事先了解，以免事后才发现：

• 接受路径的工具会读取调用进程有权读取的任何内容。 这正是其用途——它让 200 MB 的 CI 日志也能用于回答问题——而在本地 stdio 部署中，服务以你的身份运行，因此路径指向的是你自己的文件。但在提示词注入的情况下，调用方不再可信，所以应如实看待这一点：这些工具与启动它们的进程拥有同等权限。
• 工具返回的内容会进入模型的上下文。 含有恶意文本的日志文件，和网页一样，都是间接提示词注入渠道。这里没有任何机制会对其进行清理，也不可能做到。

每个工具都声明 MCP annotations，以便宿主应用实施分级确认：几乎所有工具都为 readOnlyHint: true, openWorldHint: false。例外情况也如实声明——接受路径的工具为 openWorldHint: true（结果来自磁盘，而非参数），而 diagram_render 是唯一一个会写入文件的工具。请注意，注解只是提供给 UI 的提示，绝非安全机制：规范本身就说明，客户端不得信任自己尚未决定信任的服务端提供的注解。

jarroba.com 上的文章：独立的远程服务

搜索和阅读 jarroba.com 上的文章不包含在这些软件包中，这是有意为之：它需要网络，而这里的所有内容都在本地运行。该网站将其作为独立的远程 MCP 服务提供（Streamable HTTP、JSON 响应、只读、无需账户）：

https://jarroba.com/wp-json/jarroba/v1/mcp

两个工具：jarroba_search（按文本、语言、类别或系列搜索，或获取最新文章）和 jarroba_article（提供摘要、链接及 CC BY-NC-SA 3.0 署名信息）。它按 IP 限流。 在 Claude Code 中：claude mcp add --transport http jarroba https://jarroba.com/wp-json/jarroba/v1/mcp。 与上述软件包不同，你在那里搜索的内容会发送到 jarroba.com。

开发

cd mcp
npm install
npm run typecheck     # types for the server and its tests
npm test              # smoke: starts the server and calls the tools (222 checks)
npm run test:paquete  # packs, INSTALLS outside the repo, and checks all three packages (~2 min)
npm run catalogo      # the per-domain tool counts, derived

npm test 和 npm run test:paquete 不能互换，这个教训让我们付出了 7 个工具的代价。 npm test 会在检出目录中使用 tsx 运行服务，旁边还有 node_modules——因此从结构上说，它不可能发现只有在安装后才会出现的问题：构建包没有复制的资源、内联依赖在磁盘上查找自身文件、相对于仓库解析的路径。曾经有213 项检查通过，但发布包中的 7 个 db_* 工具已损坏，而且这个故障还会终止进程，也就是说，会结束整个会话。test:paquete 会打包并安装到临时目录，然后与已安装的二进制文件交互；每个外部依赖都有一个用例——最后还会检查会话是否仍在运行，因为会终止进程的工具会报告成功（它有响应），却让其余 84 个工具全部失效。

添加工具：导入其服务、注册它，并在 src/catalogo.ts 中将它添加到所属领域——如果注册的工具没有声明所属领域，服务将拒绝启动；这也能确保本 README 中的数量准确无误。

许可证

MIT — 详见 LICENSE。