honesty-mcp

honesty-mcp

在浏览器中试用这些工具包 → · 属于 honesty kits，这是一个为 AI 产品所作声明提供的小型检查工具合集。

一个 MCP（Model Context Protocol）服务，可将十一款已构建完成、零运行时依赖的“honesty SDK”TypeScript 库作为工具提供，供任何兼容 MCP 的编码 Agent（Claude Code、Claude Desktop 或其他 MCP 客户端）在构建或审计产品时调用 — 包括基于依据的引用检查、证据佐证评级、收益／变更不变性检查（经过场景测试，并非针对每种可能输入的形式化证明）、信任／真实性评分、来源声明验证、声明注册表、防篡改审计链，以及推荐／决策评级和引擎与人工之间的差异分析；此外，还为两款不符合“检查此内容”形式的运行时库工具包提供脚手架。

本服务刻意保持轻量：每个工具都由一个 Zod 输入模式和一个处理程序组成，处理程序会导入并调用所封装工具包中未经修改的实际导出内容。它不会重新实现任何底层逻辑。

快速开始

claude mcp add honesty-mcp -- npx -y honesty-mcp

接下来，让你的编码 Agent 对一份草稿答案及其来源运行 check_grounding。每个句子都会被标记为有依据、占位内容、无依据或无效（即引用的来源未包含在证据中）。它只检查结构，不会判断来源是否真实。

默认列出十三个工具。三个会运行 Agent 发送的 JavaScript 代码的路径默认关闭；除非设置 HONESTY_MCP_ENABLE_CODE_EXEC=1。请先阅读关于代码执行工具的说明。

安装

honesty-mcp 已发布到 npm，并将其十一个同系列的“honesty SDK”工具包作为普通注册表依赖项封装（使用 semver 范围，而非本地 file: 路径）— npm install（或直接使用 npx）会从公共注册表解析所有依赖项，无需事先检出其他内容。

最快的运行方式，无需安装：

npx honesty-mcp

或者将其添加到项目中：

npm install honesty-mcp

添加到 MCP 客户端

Claude Code：

claude mcp add honesty-mcp -- npx -y honesty-mcp

其他任何读取 mcpServers 配置的 MCP 客户端（Claude Desktop 的 claude_desktop_config.json 也使用相同格式）：

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

其中三个工具会运行调用 Agent 发送的 JavaScript 代码，因此默认关闭。要使用它们，请将环境变量 HONESTY_MCP_ENABLE_CODE_EXEC=1 添加到服务的环境中（请先阅读关于代码执行工具的说明）：

claude mcp add -e HONESTY_MCP_ENABLE_CODE_EXEC=1 honesty-mcp -- npx -y honesty-mcp

{
  "mcpServers": {
    "honesty-mcp": {
      "command": "npx",
      "args": ["-y", "honesty-mcp"],
      "env": { "HONESTY_MCP_ENABLE_CODE_EXEC": "1" }
    }
  }
}

该服务使用 stdio 传输 — 从 stdin 读取 JSON-RPC 请求，并将响应写入 stdout；只向 stderr 输出一行启动横幅日志，以确保 stdout 始终是干净的 JSON-RPC 通道。这是 Claude Code、Claude Desktop 以及大多数本地／CLI MCP 客户端集成所期望的本地运行服务传输方式；它不是 HTTP 服务，也没有可供浏览的端口。

在 MCP 注册表中列出

honesty-mcp 还附带一个 server.json（已通过官方架构验证），因此可以使用名称 io.github.lkopietz3-byte/honesty-mcp 列入官方 MCP 注册表。列入注册表是维护者在此软件包发布到 npm 后手动执行的一次性步骤，不会作为此仓库 CI 或 npm publish 的一部分运行。以下是注册表自身文档中的确切命令 （发布指南， CLI 参考）：

# 1. Install the publisher CLI (macOS/Linux)
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
sudo mv mcp-publisher /usr/local/bin/

# 2. Log in with GitHub (proves ownership of the io.github.lkopietz3-byte namespace)
mcp-publisher login github

# 3. Publish (validates server.json against the schema, then submits it)
mcp-publisher publish

package.json 的 mcpName 字段（io.github.lkopietz3-byte/honesty-mcp） 必须与 server.json 的 name 字段完全一致——注册表会据此验证 npm 软件包和注册表条目属于同一发布者（参见 package-types.mdx，“所有权验证”）。

工具

9 个内容检查套件，12 个工具（套件 1–9：提供真实内容或数据，即可获得结构化判定）：

工具	封装对象	一句话用途
check_grounding	grounding-kit	逐句检查 AI 生成文本中的引用结构：未引用的主张、诚实的占位符，以及标记缺失或证据在词汇上不匹配的引用。仅检查结构；不会验证证据是否属实。词语重叠匹配器会拒绝一些忠实的改述，也会在大部分词语重叠时接受错误数字或被否定的主张，因此应将 invalid 理解为“交由人工处理”。
corroborate_evidence	corroboration-kit	根据不同来源报告证据方向（支持 / 反驳 / 混合 / 无）和分级判定，而不是统计票数。从 corroboration-kit 0.3 起，来源按独立来源计数（同一网站的多个页面只算一个来源，除非你声明了 origin）。不会验证来源是否独立，而且 confirmed 可能表示“已确认存在反驳证据”，因此应先看方向。
check_payout_invariance	payout-invariance-kit	针对你提供的场景，检查排名引擎的输出是否会随付费方支付金额的变化而变化（runtime 模式，默认关闭，除非设置 HONESTY_MCP_ENABLE_CODE_EXEC=1），或你发送的源文本中是否出现付款标识符（static-imports 模式，始终可用；不会读取磁盘上的文件）。静态匹配要求完整单词：commission 不会匹配 commissionRate，因此请列出完整名称，或从 payout-invariance-kit 0.3 起传入 matchIdentifierParts: true。这并非对所有可能的付款配置进行的形式化证明。
check_mutation_invariance	mutation-invariance-kit	默认关闭，除非设置 HONESTY_MCP_ENABLE_CODE_EXEC=1（否则不会列出此工具）。针对你提供的场景，检查决策 / 评分 / 排名函数的输出是否依赖其声称不依赖的变量（受保护属性、地理位置、价格，或你指定的任何变量）。这并非对所有可能输入进行的形式化证明。
score_trust_identified	trust-core（identified）	根据已知且身份明确的贡献者（评论者账号、评分者、检查员）为实体评分，并将证据不足的情况向先验值收缩。若没有加权证据，则返回先验值，并将置信度标记为 insufficient，而不是实测分数。
assess_anonymous_authenticity	trust-core（anonymous）	根据未标注来源 / 抓取的情绪表达看起来有多自然进行评分，并针对两种特定模式（来源集中、情绪异常一致）进行启发式折减。它不会检测伪造或验证独立性，也不是情绪排名（强烈负面的语料得分低于正面语料），且当没有信号具有权重时不会报告分数（trustScore: null）。
check_provenance_claims	provenance-kit	标记未得到适当来源等级支持、暗示确定性的措辞（“（已验证）”“有保证”）。默认短语列表较短（11 个短语），且短语按单词前缀匹配。
check_claims_registry	claims-registry-kit	根据关联证据和最后验证日期，将面向公众的主张归类为当前 / 过时 / 未验证。从 claims-registry-kit 0.4 起，TODO 之类的占位符引用会被标记为未验证，且年龄限制精确到毫秒。
append_audit_entry	audit-chain-kit	向哈希链防篡改审计日志追加一条记录。
verify_audit_chain	audit-chain-kit	从创世状态独立重新验证哈希链（空链在未检查任何内容时视为有效）；始终能检测篡改和断链；通过 expectedMinLength 检测普通的尾部删除；只有使用 anchor 才能检测截断后重新追加（或完全重写）；仅使用 expectedMinLength 无法检测截断后重新追加。
grade_decision	advice-ledger-kit	根据前后观察日志，对一组建议与决策进行评分，按曝光情况对齐，为每个时间窗口分别设置下限，并提供机器可读的拒绝代码。holding 要求曝光组中的不良结果数量低于 refuteThreshold，且其不良率低于基线（精确比较，不使用四舍五入后的 badRate；从 advice-ledger-kit 0.2 起，相同的不良率也视为持稳）；任一条件不满足时均为 not-holding。反驳阈值是固定数量，而非比例（详见工具说明）。
compute_divergence	advice-ledger-kit	衡量引擎与人工意见不一致的频率；若存在后续结果，则分别报告引擎正确 / 人工正确的数量，不会混合统计。可选的自定义 groupBySource 输入默认关闭，除非设置 HONESTY_MCP_ENABLE_CODE_EXEC=1。
2 个脚手架工具（agent-receipt-kit、cost-governor-kit——它们是项目安装并导入到自身运行时代码中的运行时库，而不是像其他内容那样按需检查；为什么用“检查此内容”的形式会造成误解，请参阅 src/tools/agentReceiptScaffold.ts / costGovernorScaffold.ts 中的代码注释）：

工具	封装对象	一句话用途
scaffold_agent_receipts	agent-receipt-kit	说明适用于 AI Agent 的“签发数据包 / 验证声明”授权模式，包含安装步骤、入门代码片段，以及（可选）针对真实套件运行的实时接受 / 拒绝示例。
scaffold_cost_governor	cost-governor-kit	说明调用前的预估支出检查、缓存感知定价计算（默认缓存读取费率为 0.1x，可按模型通过 cacheReadPerMillion 覆盖），以及建议性的（非并发安全）先检查后提交用量计数模式（调用成功后若提交失败，则返回 commitError，而不是丢弃结果）；包含安装步骤、入门代码片段，以及（可选）实时示例。

总计 9 个套件、12 个内容检查工具槽位（payout-invariance-kit、audit-chain-kit 和 advice-ledger-kit 各有 2 个工具而非 1 个，因为每个套件都包含两个确实不同的操作——运行时检查与静态 grep、追加与验证、为单个决策评分与衡量整个群体的差异——将它们作为独立的单一用途 MCP 工具，比作为带模式切换的单个工具更清晰），再加上 2 个脚手架工具 = 共 14 个工具。

启用代码执行时共有 14 个工具。关闭代码执行时（默认设置），列表中不会列出 check_mutation_invariance，因此客户端会看到 13 个工具。

关于代码执行工具的说明

这些工具默认处于关闭状态。 check_payout_invariance（runtime 模式） 和 check_mutation_invariance 包装了 kit 函数，而这些函数的实际签名需要 一个真正的 JavaScript 函数（一个排名函数、一个 mutation 闭包）； MCP JSON 参数无法表示函数。这两个工具都接受作为源代码字符串的函数， 并在 src/lib/runFunctionJob.ts 于代码执行开关检查后启动的 worker 中， 通过 Function 构造函数构建真正的函数，然后将其传给未经修改的 kit 导出函数。（src/lib/buildFunction.ts 是同一个构建器的独立测试参考副本； 运行时不会调用它。）compute_divergence 的可选项 config.groupBySource 也通过相同机制，为 advice-ledger-kit 的 groupBy 配置函数提供支持，但只有调用方实际提供该选项时才会启用；省略它 （这是常见情况）完全不需要代码执行，因为该库自己的默认行为是按每个数据对的 group 字段分组。这相当于对该字符串执行 eval。

由于接收过恶意文本的 Agent 可能会被诱导发送代码，只有操作员在服务的环境中 设置 HONESTY_MCP_ENABLE_CODE_EXEC=1 后，服务才会提供这些路径。只有精确值 1 才会启用；任何其他值（true、yes、0、空值）都会使其保持关闭。 关闭时：

• check_mutation_invariance 不会注册，因此不会出现在 工具列表中。
• check_payout_invariance 仅以 static-imports 模式列出。
• compute_divergence 列出时不包含 groupBySource 输入，发送该输入会被拒绝。
• 服务的初始化结果会附带一条简短说明，指出该变量名。
• runFunctionJob（src/lib/runFunctionJob.ts）是唯一会运行调用方 JavaScript 的位置；它会拒绝启动 worker。错误信息会指出 HONESTY_MCP_ENABLE_CODE_EXEC。

其他所有工具均未改变。默认值由名为 CODE_EXEC_ENABLED_BY_DEFAULT 的常量定义，该常量位于 src/lib/codeExec.ts。

启用它并不会隔离代码。 代码仍可使用此进程对整个文件系统、网络和环境的 访问权限。这与 Agent 自行运行 node -e 或 vitest run 的信任模型相同， 并非为暴露给不可信、远程或对抗性输入而设计。仅当服务由可信的本地 Agent 驱动时才启用它，并且只能传入你编写或信任的代码。

static-imports 模式不会读取磁盘上的文件

check_payout_invariance 的 static-imports 模式会将 files 作为路径到文件内容的映射传入。若传入路径列表，则会报错。封装的工具包会读取传入的任何可读路径并返回匹配的行，这会让 Agent 能够逐行读取机器上的任意文件，因此本服务不会传递路径。要扫描文件，请让 Agent 读取文件并发送文本。

以上三项都会在设有超时限制的 worker_threads Worker 中运行 （src/lib/runFunctionJob.ts），而不是在服务器自己的主线程中运行。早期版本会在进程内同步调用构建好的函数，因此像 while (true) {} 这样的源代码会让 整个 stdio 服务永久阻塞，连同所有其他正在执行或之后发起的工具调用。现在，如果 Worker 未能在超时时间内完成（默认 10 秒，可通过 HONESTY_MCP_WORKER_TIMEOUT_MS 环境变量覆盖，单位为毫秒，取值范围为 1 到 2147483647），则会强制调用 terminate() 终止它，工具调用会返回清晰的超时错误，而不会一直挂起。所提供代码产生的控制台输出（console.log、console.error）会被捕获，并以 [honesty-mcp worker] 前缀写入服务器的 stderr，每次调用最多 16 KiB，因此不会写入承载 MCP 协议的 stdout。直接写入文件描述符 1 的代码（例如使用 fs.writeSync(1, ...)）不会被拦截，可能会破坏协议流；这也是它并非沙箱的原因之一。这不是沙箱——Worker 拥有此进程的全部操作系统级权限（文件系统、网络、环境变量），它只限制运行时间。它无法阻止调用方代码读取你的文件系统、发起网络请求，或执行此 Node 进程本身能够执行的任何其他操作。上述信任模型仍完全适用：只传入你编写或信任的代码，不要将此服务暴露给不受信任的、远程的或恶意的输入。

Kit 版本

此服务依赖每个封装 Kit 的较新版本线（package.json 中的范围）。下表列出了该版本线相较于 honesty-mcp 0.2.x 使用的 0.2 版本线所做的更改。启动时，每个工具都会读取已安装 Kit 的版本，根据该版本调整描述，并拒绝已安装的 Kit 会静默忽略的输入（例如，如果覆盖安装了 payout-invariance-kit 0.2，则会拒绝 matchIdentifierParts），而不是假装输入已生效。

Kit	版本	通过此服务产生的变化
grounding-kit	0.3.0	每个单元都带有 reasons，结果中会列出 nonClaims。判定结果可能朝两个方向变化（缩写后的句子边界、闭合引号和破折号；规则和表格分隔符不再作为单元）。
corroboration-kit	0.3.0	来源按独立源头计数。新增输入 origin、derivedFrom 和 inferOrigins；结果新增 groups。判定结果只会变得更严格。
payout-invariance-kit	0.3.0	新增输入 matchIdentifierParts；标识符会被去除首尾空白，并支持任意文字系统中的匹配；运行时排名函数未返回结果时会报错。
mutation-invariance-kit	0.3.0	对已变异输入进行原地编辑时会报错；同名场景会重命名为 name (2)。
trust-core	0.3.0	匿名评分发生变化（规模较小和仅有单一来源的语料得分会降低）；新增 config.fullCountWeight；日期在未来的证据会按无日期处理。
provenance-kit	0.3.0	判定结果可能朝两个方向变化（增加否定线索和断言惯用语，以及外形相似的字母）。自定义短语末尾的空格不再阻止前缀匹配。
claims-registry-kit	0.4.0	主张的年龄超过 maxAgeDays × 24 小时后即为过期（按精确毫秒计算）；占位符 evidenceRef 会被视为未经验证。
audit-chain-kit	0.3.0	验证结果新增 entriesChecked。
advice-ledger-kit	0.3.0	不良率完全相同时，结果为 not-holding（原先为 holding）。
agent-receipt-kit	0.3.0	仅脚手架：示例的结果新增 snapshot 和 uncoveredFactKeys。
cost-governor-kit	0.3.0	仅脚手架：指导内容提及较新的 admission-control API。

test/kitCompat.test.ts 会针对已安装版本线运行相应分支。按照当前范围，始终使用较新的版本线，因此后续版本可以移除针对较旧版本线的检查。

诚实说明

• 此服务不会提供超出其所封装 Kit 文档已有内容的保证。 每个工具的描述都已根据其 Kit 自身 README 中的“Honest limits”/“Limits”部分进行核对，核对时所依据的是此分支构建所基于的同级 Kit 提交 — 有关此处任何一行工具描述或表格条目的完整细节，请阅读相应 Kit 的 README。如果 Kit 自身的限制说明日后发生变化，此服务的措辞可能再次与之不同步；此处不会自动重新核对。
• check_payout_invariance、check_mutation_invariance 和 compute_divergence 的 worker-thread 超时只限制时间，不限制行为 — 请参阅上文“关于代码执行工具的说明”。这不是沙箱，并且除非设置 HONESTY_MCP_ENABLE_CODE_EXEC=1，否则这些路径处于关闭状态。
• SERVER_VERSION（src/server.ts）和 package.json 中的 version 仍需手动递增。 现在，如果它们与 server.json 中的两个版本不一致，test/drift.test.ts 会报错，但不会自动为你递增版本。

开发

若要开发此服务本身（而不仅仅是使用它），请克隆仓库并从源代码构建：

git clone https://github.com/lkopietz3-byte/honesty-mcp.git
cd honesty-mcp
npm install          # resolves the 11 wrapped kits from the npm registry
npm run build         # compiles src/ -> dist/
npm start              # runs dist/index.js on stdio

npm run lint         # eslint . --max-warnings=0
npm run typecheck   # tsc --noEmit over src/ + test/
npm test             # vitest (code execution is switched on for the suite in
                      # vitest.config.mjs), spins up a real MCP Client/Server pair
                      # over the SDK's InMemoryTransport and calls tools
                      # end-to-end (see test/*.test.ts)
npm run build        # tsc -p tsconfig.build.json -- compiles src/ -> dist/
npm run smoke        # npm run build first, then node dist/smoke.js --
                      # a standalone script that does the same real
                      # client/server handshake, lists all tools, and
                      # calls one end-to-end
npm run verify       # lint + typecheck + test + build + smoke, in order
npm run audit:dependencies   # npm audit --package-lock-only --include=dev
                              # --ignore-scripts --audit-level=low

项目结构

src/
  index.ts                    entrypoint: connects the server to stdio
  server.ts                   createServer() -- builds the McpServer and registers every tool
  smoke.ts                    standalone smoke-test script (see npm run smoke)
  lib/
    result.ts                 CallToolResult helpers (jsonResult / errorResult)
    codeExec.ts               the HONESTY_MCP_ENABLE_CODE_EXEC switch and its default constant
    buildFunction.ts           reference copy of the source-to-function builder (tested; not called at runtime)
    runFunctionJob.ts          runs that function (or the divergence groupBySource case)
                               inside a worker_threads Worker with a bounded timeout
  tools/
    grounding.ts
    corroboration.ts
    payoutInvariance.ts
    mutationInvariance.ts
    trustIdentified.ts
    trustAnonymous.ts
    provenance.ts
    claimsRegistry.ts
    auditChain.ts               (append_audit_entry + verify_audit_chain)
    adviceLedger.ts              (grade_decision + compute_divergence)
    agentReceiptScaffold.ts
    costGovernorScaffold.ts
test/
  server.test.ts               end-to-end tests over a real in-memory MCP client/server pair,
                                covering every tool's known-good and known-bad input
  buildFunction.test.ts        unit tests for the source-string -> function builder
  runFunctionJob.test.ts       unit tests for the worker-thread job runner (normal jobs,
                                error propagation, timeout enforcement, env var parsing)
  workerTimeout.test.ts        end-to-end proof that the three code-execution tools stay
                                bounded by the worker-thread timeout instead of hanging
  codeExec.test.ts             the code-execution switch: unset, set, garbage values, other tools
  fileRead.test.ts             static-imports mode never reads a path the caller names
  drift.test.ts                versions and README tool list match the code