Ottorev — Review MCP Server

Ottorev — Review MCP Server

工程助手所需的记忆。这个本地 stdio MCP 服务会在 SQLite 中针对精确的 CAD 修订版记录名称、备注、标签和决策，让助手能够接续上次的工作——记住某个面是配合表面、某个公差标注很严格，或者评审结论是暂缓，以及支撑该结论的要求。

它绝不会打开 CAD 文件：它只存储调用方提供的修订版，并在回忆时进行比对，因此即使笔记本电脑上没有 CAD 软件，也没有运行其他服务，它仍然可以工作。

快速开始

需要 Node.js 26+ 和 npm。在此仓库中：

npm install
npm run build
REVIEW_MCP_DB_PATH=/absolute/path/to/review.db npm start

适用于任何 MCP 客户端：

{
  "mcpServers": {
    "review": {
      "command": "node",
      "args": ["/absolute/path/to/review-mcp-server/dist/src/index.js"],
      "env": { "REVIEW_MCP_DB_PATH": "/absolute/path/to/review.db" }
    }
  }
}

REVIEW_MCP_DB_PATH 默认为 ./review-mcp.db；父目录会自动创建。记录会在重启后保留——请将数据库作为应用数据妥善保护和备份。

工具

工具	行为
remember	针对一组实体保存一个命名特征（再次记忆时会替换）或一条匿名备注（再次记忆时会追加），并附带标签。返回 replaced，以便调用方判断发生了哪种情况。
recall	按构件、实体、自由文本或标签检索；根据提供的当前修订版将每条记录标记为过时。请使用分页以完整检索。
remember_decision	保存对某个修订版作出的处置决定及其依据——每项要求检查对应一行，列明来源、证据、状态和工程师的判断。再次记忆相同主题时会替换原记录。
recall_decisions	按时间倒序返回决策；如果决策属于其他修订版，则会标记为过时。entity_id 筛选条件仅匹配所提供的修订版。
forget	删除命名特征、按实体删除匿名备注，或按主题删除决策。操作幂等。

结果包含结构化内容和文本；工具失败时会设置 MCP isError。 写入会更改本地记录；客户端控制何时请求这些变更。 此服务还会提供可与几何服务组合使用的工程评审提示词，而核心记录操作可独立运行。

构件与主体语义

输入构件包含 revision（sha256: 加 64 个小写十六进制数字）、 format: "step"，以及可选的 URI 和单位：

{
  "revision": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "uri": "file:///work/part.step",
  "format": "step",
  "units": "mm"
}

请提供生成方给出的实际修订版本；示例摘要仅作说明。 URI 用于按定位符对记录分组；没有 URI 时，修订版本就是查找键。

uri 接受 URI 或普通文件系统路径，因为调用方通常手头只有路径：

{ "uri": "/work/part.step" }

这两种写法指向相同的记录：路径会先标准化为 file: URI，然后才会存储或匹配任何内容。相对路径基于服务的工作目录解析。标准化过程不会打开文件，因此即使此服务无法读取某个构件，也可以为它写入记录。

实体筛选条件限定于修订版本；文本或标签筛选条件则不受此限。 在不同修订版本中，实体 ID 表示不同的几何体，因此 recall 和 recall_decisions 只会在为所提供修订版本写入的记录中匹配 entity_id，并且要求完全匹配——face:3 不会匹配 face:30。名称、备注、主体和标签会跨修订版本匹配，这样才能找到较早的记录；每条结果都会说明它是否为 stale。

每条返回的记录都包含一个构件引用、其实体 ID，以及 ID 方案。在该方案和修订版本之外，实体 ID 没有明确含义。

决策记录

审查会命名或标注几何体。审查产生的另一种内容是决策：关于某个修订版本的处置，以及其所依据的依据。

每个依据项对应一项要求检查，并需自行给出答案：

字段	内容
requirement	必须满足的条件，表述方式应便于核验
source	要求的来源：model-pmi、drawing、shop-spec、supplier-cert、standard、prior-decision、engineer-stated 或 assistant-proposed
sourceDetail	读者可据此查阅的条款、备注编号或文档
evidence	按原样报告的值，并附上其出处
state	satisfied、violated、unresolved、conflicting 或 not-applicable
question	unresolved 和 conflicting 时必填：需要什么信息才能解决问题
faces	此修订版本中该项涉及的几何体；始终存在，若该项涉及整个零件则为空
verdict	工程师作出的 accepted / rejected 判断；若工程师给出了理由，也应附上

unresolved 和 conflicting 是一等结果：包含这些状态的决策，是对当前工作进展的完整记录，而不是未能作出决策。若依据项无法自行给出答案，就会被拒绝——例如没有 source，或状态为 unresolved / conflicting 却没有 question。

有三项特性比形式更重要：

• 决策绑定到修订版本。 修订版本是其键的一部分，因此相同主体在相同修订版本下会被找回，而不会再次处理；针对不同修订版本作出的决策会标记为 stale: true 返回，并仍携带其所属的修订版本。
• 面 ID 不会跨修订版本沿用。 OCCT 中的拓扑命名问题尚未解决，此 API 不会假装解决了它：entity_id 筛选条件只会匹配生成该 ID 的修订版本。
• 裁定决定要求是否达成一致。 记录 verdict 后，助手提出的一条意见就会成为工程师接受或拒绝的意见——这条记录反映了助手实际获得了多少认可。

已存储的决策是调用方自己的陈述：按其所述的要求，以及按其引用的证据。本服务从不进行测量，因此找回的决策记录的是已得出的结论，而不是测量缓存——数值仍以 Geometry 为准。

限制

Review 保存作者提供的上下文：与某个构件修订版绑定的名称、备注和标签，以及其所依据的要求。它不保存已验证的测量数据、完整且不可变的审计历史或权威审批记录，也不会计算几何数据、运行仿真或判断可制造性。是否过时依据调用方提供的修订版来判断；Review 不会打开 CAD 文件。

数据库没有架构迁移：数据库是工作文件，表结构一旦变更，就必须删除该文件。服务器会报告版本不匹配，而不会猜测如何转换。

开发

需要 Node.js 26+ 和 just。Nix flake 和 .envrc 会提供工具链；修改其中任一文件后，请运行 direnv allow。

Recipe	用途
just setup	安装依赖项。
just dev	通过 stdio 运行 TypeScript。
just build	编译到 dist/。
just test	运行单元测试。
just lint	运行 oxlint。
just fmt	使用 Prettier 重写格式。
just fmt-check	检查格式。
just typecheck	运行 tsc --noEmit。
just check	fmt-check + lint + typecheck + test。
just clean	删除编译输出，但保留数据库。

服务器日志以按行分隔的 pino JSON 格式写入 stderr。MCP_LOG_LEVEL (debug|info|warn|error)、MCP_LOG_FORMAT=human 和 MCP_TRACE_ID 可调整日志；类似机密的字段会被隐藏。

打包

npm pack 会先构建，并将编译后的运行时代码、包元数据和本 README 打包进去。 测试和源映射文件不会包含在内。安装打包文件，使用兼容的 MCP 客户端检查 review-mcp 可执行文件。服务器同时支持两个协议版本：标准 MCP 主机协商使用的 2025-11-25 握手，以及通过 server/discover 提供的 2026-07-28 信封。

许可证

MIT。第三方声明：THIRD_PARTY_NOTICES.md。