Agent Core

agent-core-mcp

面向 AI Agent 的确定性计算工具。 精确差异比较、哈希、JSON 查询、日历运算、带严格执行时限的正则提取、CSV 解析、相似度评分以及单位／进制转换——以 MCP 服务的形式提供。

零依赖。无需网络。只读。

---

为何开发此项目

大模型擅长生成语言，却不擅长精确、可复现的机械计算。这不是能力上的缺陷，而是架构特性。让概率系统执行计数、差异比较、哈希或日历运算，注定会出现一定比例的自信错误答案。

此服务将这些操作从模型中移出，交由确定性引擎处理。

结果不是更好的猜测，而是另一类答案：精确且可复现。

还有一个 MCP 生态中特有的原因。已发布服务最常被报告的问题包括凭据泄露、未披露的 Shell 执行、依赖树中包含已知 CVE，以及导致客户端挂起的服务。一个不联网、不使用凭据、没有执行入口，并且为每项操作设定时限的服务，不可能出现这些问题。

保证

保证	含义
零依赖	没有 node_modules。无需审计，不会过时，也不会损坏。
无法访问网络	此处的任何内容都不会访问外部网络。一次请求也不会。
不使用凭据	不读取令牌、API 密钥或环境变量。
只读	不写入文件、不执行 Shell、不保留状态。每次调用均无状态。
确定性	相同输入会产生逐字节相同的输出。
有界	每个循环和结果集都设有上限。正则表达式在工作线程中执行，超时后会终止，因此任何模式都无法让客户端挂起。

服务会将这些保证作为机器可读的 contract 资源（agent-core://contract）发布，以便客户端验证要安装的内容，而不必只相信此文件。

安装

npx agent-core-mcp

运行此服务无需安装步骤。需要 Node.js 18 或更高版本。

获取方式：

• npm — agent-core-mcp
• 官方 MCP 注册表 — io.github.kinbinghua-lgtm/agent-core-mcp
• 源代码 — github.com/kinbinghua-lgtm/agent-core-mcp

配置

Claude Code

此仓库提供了 .mcp.json，因此只需克隆仓库即可：

git clone https://github.com/kinbinghua-lgtm/agent-core-mcp
cd agent-core-mcp
claude   # the agent-core server is discovered automatically

也可以将其添加到任何项目中：

{
  "mcpServers": {
    "agent-core": {
      "command": "npx",
      "args": ["-y", "agent-core-mcp"]
    }
  }
}

Claude Desktop、Cursor、VS Code、Windsurf、Continue、Zed

将相同的代码块添加到相应客户端的 MCP 配置文件中。无需 API 密钥。无需环境变量。无需注册。

工具

工具	功能	为什么模型不应自行执行
diff_text	精确逐行差异比较（LCS），提供行号及新增／删除数量	需要进行精确的序列对齐；输入过大时会拒绝处理，而不是一直卡住
hash	sha256 / sha512 / sha1 / md5 / HMAC，提供十六进制、base64 和 UTF-8 字节长度	无法通过检查计算得出
json_validate	返回有效性、解析器消息以及计算得出的行／列位置	靠肉眼定位错误容易出错
json_query	按 a.b[0].c 这样的路径访问；区分不存在和存在但为 null	将这两者混为一谈会悄无声息地导致实际错误
json_pick	一次调用解析多个路径	比 N 次往返更省力
text_stats	码点、UTF-8 字节数、行数、词数、句子数、段落数、不重复词数、高频词	计数正是概率生成容易出错的地方
date_calc	以天／周／月／年／小时／分钟／秒／工作日为单位计算间隔	使用实际日历月份，而不是按 30 天近似计算
date_add	按日历规则对日期进行偏移	处理月末和闰年
regex_extract	在硬性截止时间内返回所有匹配项及其索引、编号捕获组和命名捕获组	灾难性模式会被终止，而不是一直卡住
regex_analyze	静态评估模式的 ReDoS 风险	嵌套量词、重叠的分支、反向引用
fuzzy_match	按 Sorensen-Dice 相似度对候选项排序	使用确定性评分，而非凭感觉判断
similarity	返回单个相似度分数，范围为 0..1	—
parse_table	支持引号、转义符和内嵌换行的 RFC 4180 CSV/TSV；自动检测分隔符	简单地按逗号拆分，遇到真正的 CSV 就会出错
convert	长度、质量、时间、数据大小；拒绝跨类别换算	单位错误不易察觉，后果却很严重
base_convert	支持 2-36 进制和任意精度	超过 2^53 的值用简单方法换算会失去精度

ReDoS 截止时间

regex_extract 接受可选的 budgetMs（默认值为 1000，最大值为 10000）。执行在工作线程中进行，超出截止时间时会终止该线程。

这并非只是锦上添花。Node 的正则表达式引擎无法中断，因此含有灾难性回溯的模式会无限期阻塞主线程。针对 (a+)+$ 与 'a'.repeat(n) + '!' 的增长情况测量如下：

n	时间
20	18 ms
22	70 ms
24	276 ms
26	1108 ms

每增加两个字符，耗时大约增长 4 倍。n=40 时，操作不会返回。在运行于客户端主线程上的 MCP 服务中，这会导致用户的编辑器卡死。进程隔离并终止线程是唯一真正有效的边界。

超时后，响应会说明这一点，并告知调用方如何修复模式：

{
  "timedOut": true,
  "budgetMs": 300,
  "safety": {
    "risk": "high",
    "reasons": ["nested quantifier inside a repeated group — classic exponential backtracking"]
  },
  "advice": "Pattern execution exceeded 300ms and was terminated. ... Rewrite it to remove ambiguity — typically by replacing a nested quantifier such as (a+)+ with an unambiguous form such as a+ ..."
}

参数验证

每次调用都会在分发前根据工具自身的 JSON Schema 进行验证：必填字段、原始类型、枚举成员、数值范围以及未知属性。格式错误的调用会返回明确的错误，而不是看似笃定的错误答案。

这一点很重要，因为客户端并不总是会遵守 Schema。对于格式错误的调用，服务端如果悄悄继续处理，会比拒绝处理更糟。

示例

精确差异比较

{ "a": "line one\nline two", "b": "line one\nline 2" }

→ { "added": 1, "removed": 1, "lines": [ { "op": "equal", "aLine": 1, "bLine": 1 }, ... ] }

保持精确的大整数换算

{ "value": "9007199254740993", "fromBase": 10, "toBase": 16 }

→ { "result": "20000000000001", "decimal": "9007199254740993" }

计算两个日期之间的工作日

{ "from": "2026-01-05", "to": "2026-01-12", "unit": "businessDays" }

→ { "value": 5 }

运行前检查模式

{ "pattern": "(a+)+$" }

→ { "risk": "high", "reasons": ["nested quantifier inside a repeated group — classic exponential backtracking"] }

不存在与 null 的区别

{ "json": "{\"a\":null}", "path": "a" }

→ { "resolved": true, "found": false, "value": null, "type": "null" }

设计说明

为什么使用 stdio 而不是 HTTP？ stdio 服务没有监听套接字：没有攻击面，没有需要暴露的端口，没有可能配置错误的身份验证，也没有数据离开本机。对于纯计算任务，HTTP 只会增加风险，没有任何收益。

为什么不缓存？ 每次调用都是无状态的。缓存会引入状态、失效错误和数据持久化的途径。这些操作足够轻量，不值得为此做出取舍。

为什么拒绝超大输入？ MCP 服务一旦挂起，客户端会话也会随之中断。给出可操作的提示并拒绝请求，总比耗尽内存好得多。

为什么完全不使用依赖？ 每项依赖都是长期负担：更新、安全公告、供应链风险，以及服务停止运行的又一个原因。Node 标准库已涵盖这里的所有需求。

开发

node server.cjs              # speaks MCP over stdio
node selftest.mjs            # engine verification, 35 assertions
node protocol-test.cjs       # protocol verification, 88 assertions
npm test                     # both suites

两组测试都可直接使用 Node 运行，无需安装。

selftest.mjs 会将哈希与已发布的常量进行比对，测试超过 2^53 的大整数往返转换、RFC 4180 引号边界情况、Unicode 分词和日历运算。protocol-test.cjs 通过模拟传输驱动真实处理程序，覆盖握手、版本协商、每个工具、参数验证、ReDoS 截止时间、格式错误的帧、拆分帧、批处理、并发请求关联和确定性。

这两组测试发现了两个错误，并都保留为回归测试：

• 分词正则表达式中的 ReDoS。 原始的 textStats 模式为 [\p{L}\p{N}][\p{L}\p{N}'’-]*——两个相邻且重叠的字符类。当长字母串后面跟着不匹配内容时，它会发生指数级回溯，导致进程挂起。此软件包中的分析器没有发现这个问题，因为它只会静态检查传入的模式，无法看到源码中手写的模式。上文的执行截止时间正是为此而设。
• 缺少架构验证。 缺失的必需参数会被静默地视为不存在，因此忘记传入 path 的调用方收到的是 missing-key，而不是错误。客户端架构并不构成强制校验。

许可证

MIT — 参见 LICENSE。