lens-mcp

Soulfield Lens — MCP 服务

长时间运行的作业可以先调用 validation_submit，再通过新的 MCP 连接调用 validation_receipt。在本地保存返回的作业 ID 和候选内容的 SHA-256。轮询超时后，使用该 ID 获取结果；不要再次提交内容。待处理、失败、过期和不完整的作业均不授予通过资格。若提交结果不确定且未返回 ID，不得自动重试。现有的 validate_content 工具保持不变。离线恢复和 Rights 保留测试样例见 test/validation-jobs.test.cjs。

通过 MCP 工具对 AI 生成的文本进行由外向内的验证。

每个 AI 工具都会询问写出答案的同一个模型，答案是否有用。它会说有用。Soulfield Lens 则采用由外向内的方式：由独立模型通过固定关卡检查你的输出。它检查文本，而不会撰写文本。此软件包可将该关卡集成到 Claude Code、Cursor 及其他兼容 MCP 的 Agent 中，从而在生成输出的过程中对其进行验证。

该关卡采用失败即关闭策略：边界情况会返回 UNKNOWN，不会悄然放行。由于没有生成步骤，它无法编造自己的说法，只能进行检查。但它仍可能误判；这正是边界情况返回 UNKNOWN，而不是自信地给出肯定答复的原因。

这是围绕托管 Lens API（api.soulfield.one）建立的本地 stdio 边界。它会将对代码库的访问保留在调用方的机器上，只向 API 关卡发送完成的文本内容。

它提供两个层级。关卡层级（3 个工具）只需 API 密钥。验证器层级（7 个工具）增加了一个本地编排入口，以及可选的 lens-kit 跨文件检查和缺陷记忆功能，后两者无法由单文档关卡完成。跳过本地证据输入，关卡层级仍会像以往一样正常工作。

安装前先试用

免密演示端点运行相同的关卡——每个 IP 每天可运行几次，无需注册：

curl -s https://api.soulfield.one/v1/demo \
  -H 'content-type: application/json' \
  -d '{"text": "<paste the AI output you are about to ship>"}'

安装

npm install -g @soulfield/lens-mcp

也可以不安装直接运行：npx @soulfield/lens-mcp。

Claude Code

claude mcp add soulfield-lens \
  -e SOULFIELD_API_BASE=https://api.soulfield.one \
  -e SOULFIELD_API_KEY=<your-key> \
  -- npx @soulfield/lens-mcp

任意 MCP 客户端（JSON 配置）

{
  "mcpServers": {
    "soulfield-lens": {
      "command": "npx",
      "args": ["@soulfield/lens-mcp"],
      "env": {
        "SOULFIELD_API_BASE": "https://api.soulfield.one",
        "SOULFIELD_API_KEY": "<your-key>"
      }
    }
  }
}

生产环境调用需要 API 密钥——请通过 [email protected] 申请。lens_health 无需密钥即可使用。

工具

关卡层级 — 托管 API，开箱即用

工具	功能	身份验证
validate_content	对文本运行由外向内的关卡。返回通过/失败状态、评分、各维度结果，以及附带推理说明的违规详情。可选参数 domain（general、finance、marketing、legal、seo、agency）和 context（受众/目的）。	需要密钥
scrub_pii	在服务器端扫描结构化 PII 和机密信息，包括电子邮件、英国/美国电话号码、信用卡号、美国 SSN、英国 NI/UTR 号码、数据库连接字符串，以及常见的 API 密钥/凭据模式。返回清理后的文本（将每个匹配项替换为类型标记）以及发现项。基于模式，不调用大模型。目标是结构化标识符；不会检测个人姓名或自由格式 PII，对结构化格式的覆盖尽力而为，并非穷尽。	需要密钥
lens_health	检查 Lens API 是否正常运行。返回状态和版本。	无

验证器层级 — 本地运行；一致性检查需要 lens-kit

**版本说明：**验证器层级将在 1.1.0 中推出。如果 npm view @soulfield/lens-mcp version 仍报告 1.0.0，说明注册表尚未同步到此代码库；此时运行 npx @soulfield/lens-mcp 只能获得关卡层级的三个工具。期间请从源代码安装。

内容编排：validate_artifact 将在 1.2.0 中推出。其有限范围的本地证据搜索已内置于此 MCP 软件包。请求的一致性检查仍需要 lens-kit。 值得了解的副作用： 每次调用验证器层工具，都会在其工作目录中的 RUNS.md 追加一行——这是工具包有意设计的运行记录。该目录由 cwd 参数指定；如果省略，则使用服务自身的 cwd，因此如果你在意记录保存的位置，请明确传入 cwd。敏感标志值会在记录中脱敏（--deny <redacted>），因此拒绝词条不会落盘。

前置条件： 执行 pip install lens_kit（Apache-2.0，github.com/mrhpython/lens-kit），或将 LENS_KIT_BIN 设为其路径。若未安装，这六个工具会返回 UNKNOWN 并附带错误——绝不会静默通过。无需 API 密钥：它们在本地运行，且不会调用大模型。

为什么它们在本地运行，而不运行于托管 API： 它们会读取你磁盘上的文件路径。若托管端点接受任意本地路径，那将是文件泄露途径，而非一项功能。使用 stdio 时，路径属于你自己的计算机，因此此功能仅在这里才安全——也正因如此，它不会加入托管 API。

工具	功能	退出语义
validate_artifact	读取一个本地制品，仅在明确许可的证据根目录中搜索，运行所请求的一致性检查，并且只将制品文本发送到 API 审核关口。它会将结果标记为 gate-only 或 evidence-preflight+gate。字面匹配只能表明来源位置，并非证明；在给出完整验证器裁定前，必须由另一个验证器 Agent 阅读并判定。	一致性违规 → FAIL；证据不完整／检查出错 → UNKNOWN；否则 → PENDING_AGENT_REVIEW
lens_consistency_leaks	扫描文件，查找拒绝列表词条（不区分大小写的字面匹配）。在不可逆发布前，对每个面向客户的文件运行此工具：可捕获残留在待发布文案中的真实客户名称、内部代号或禁用绝对路径。凭据扫描器不会找到这些内容，因为这里没有任何凭据。不识别否定语境： 为了声明不使用某个禁用短语而引用它，与直接断言该短语完全相同，都会匹配。	命中可证明该字符串存在——请据此判定结论
lens_consistency_numbers	检查摘要中的每个数字字面量是否确实出现在它所概述的正文中。可捕获凭空捏造的数字。注意事项： 仅进行字面匹配，不做推导计算；而被标记为已被取代的数字（“取代约 471 的估算值”）也会像过时数字一样触发标记。请审核，不要自动信任。	违规／无异常
lens_consistency_markers	检查来源中的证据标记是否保留在每种渲染输出中——防止格式转换时丢失限定说明或引用。与上面的 leaks 不同，此工具区分大小写：TRIPWIRE 不会匹配 Tripwire，若没有内容被删除，也会被判定为已删除。注意事项： 有意进行的子集渲染也会导致标记计数偏少。	违规／无异常
选择拒绝词和标记。 这三项是警报线索，不是裁判——在对本项目自身副本进行实时运行时，它们触发了六次标记，但没有发现真正的缺陷，且涉及三种不同的误报类型（否定、已被取代的数字、大小写）。这是预期的行为，也正因如此，原则是裁定，绝不自动应用。拒绝词最好是无论在何种上下文中都不正确的字符串——例如真实的客户端名称、内部代号——而不是你不会提出的主张，因为这些主张可能会合理地出现在免责声明中。标记最好在源文件和渲染结果中的大小写保持一致时使用。
lens_catches_relevant	在验证前读取缺陷库：针对某种制品类型的既往具名缺陷，并按出现频率从高到低排列。达到阈值的模式会标记为 [PROMOTE]——它们重复出现得足够频繁，值得设为固定检查项。	—
lens_catches_add	记录具名缺陷，以便下次捕获：错误所在、通用模式、后续规则。按设计会拒绝常规检查——只记录真正的缺陷。	—
lens_catches_stats	按模式统计重复次数，并提供晋级建议。告诉你下一步该强化什么。	—

这两个层级互为补充，而非二选一。门禁没有工具，也无法访问文件——这正是它能独立检查的原因，也正因如此，它无法发现分散在两个文件中的矛盾。验证器层级可以查看磁盘；门禁负责评分。两者应配合使用：用本地工具收集基础证据，将文本交给门禁，并且绝不要把门禁的 FAIL 争辩成 PASS。完整协议：docs/VALIDATOR-AGENT.md。

一个本地入口

validate_artifact 通过一次调用明确划定边界：

{
  "artifact_path": "output/candidate.md",
  "evidence_roots": ["reports", "output/proof"],
  "evidence_queries": [
    {
      "claim": "measured-result",
      "query": "113/113 rows scored",
      "case_sensitive": true
    }
  ],
  "domain": "agency",
  "context": "Internal technical handoff"
}

响应包含 evidence_scope、files_read、searches_and_commands、claims_verified 和 claims_unverified。claims_verified 按设计为空：grep 只能证明文本存在于某个源文件位置，不能证明该主张属实。独立的验证器 Agent 必须阅读定位到的证据，对照多个文件进行推理，并附上最终的完整验证收据。

证据文件内容和本地绝对路径绝不会添加到 API 请求中。目录搜索会跳过 .git、node_modules、符号链接和二进制文件；超出配置的安全限制时则会安全失败。

每次运行你能获得什么： 收据——检查了什么、通过了什么、暂缓了什么，以及原因。它是机器可读的，不是徽章。我们不会为你的数据提供保证准确率：评分无法在不同模型、数据集和运行时之间通用；如果某个工具声称能在从未见过的数据上达到固定指标，那它所作的正是这个门禁旨在捕捉的主张。

长输入

长度约为 4,000 个字符及以上的输入会作为异步任务提交，并自动轮询直至完成，因此单次长内容验证不会因请求超时而中断。短输入则使用快速同步路径。无需配置。

配置（环境变量）

变量	默认值	用途
SOULFIELD_API_BASE	http://localhost:8002	Lens API 基础 URL。托管服务请使用 https://api.soulfield.one，也可以使用你自己的部署。
SOULFIELD_API_KEY	—	validate_content 和 scrub_pii 必需。
SOULFIELD_VALIDATE_TIMEOUT_MS	180000	同步路径的单次请求超时时间。
SOULFIELD_VALIDATE_BUDGET_MS	600000	异步轮询循环的总墙钟时间预算。
SOULFIELD_ASYNC_MIN_CHARS	4000	启用异步路径的输入长度阈值。
LENS_KIT_BIN	lens-kit	验证器层级使用的 lens-kit CLI 路径。仅当它不在 PATH 中时才需要设置。
LENS_KIT_TIMEOUT_MS	120000	验证器层级命令的超时时间。超时后判定为 UNKNOWN，绝不会判定为通过。

产品的其他部分

这个封装是基于同一引擎的多个入口之一：

• 免费单项输出审计 — api.soulfield.one/audit。审计功能就是演示。
• 接入使用（SDK 停止钩子和中间件）— api.soulfield.one/developers。
• 拥有它 — 工具包：透镜、编译器、自我改进循环、验证器 Agent，采用 Apache-2.0 许可证。使用你自己的数据训练它。公共仓库：github.com/mrhpython/lens-kit — 克隆仓库，运行 pip install -e ".[dev]"，测试套件即可离线运行，无需密钥。安装它也会启用上文所述的验证器层级。

我们用这个软件包提供的同一套标准审核自己的营销文案。

许可证

MIT — 详见 LICENSE。（lens-kit 产品采用单独的 Apache-2.0 许可证。）