Knowerage — AI 分析覆盖率管理

本地优先的 MCP 服务器，用于跟踪遗留代码的分析覆盖率和新鲜度。

源码： github.com/MTimma/knowerage

快速开始

要求： Node.js 18 或更高版本 — npx 必须在你的 PATH 中（它随 npm 一起提供，而 npm 包含在 Node 中）。

Related MCP server: Atlas

MCP 服务器配置

在你的 MCP 主机期望定义服务器配置的地方注册 Knowerage（例如，某些客户端使用 .cursor/mcp.json 或 .vscode/mcp.json；其他客户端使用环境变量或 UI——请遵循你所使用主机的文档）。使用相同的服务器条目格式：

{
  "mcpServers": {
    "knowerage": {
      "command": "npx",
      "args": ["@mtimma/knowerage"],
      "env": {
        "KNOWERAGE_WORKSPACE_ROOT": "${workspaceFolder}",
        "KNOWERAGE_AUTO_FULL_RECONCILE": "true"
      }
    }
  }
}

如果你的主机不展开 ${workspaceFolder} 变量，请将其替换为你的项目根目录。

KNOWERAGE_AUTO_FULL_RECONCILE 是可选的：当未设置、为空或不是真值时，文件监视器默认为关闭。设置为 1、true、yes 或 on（修剪空格，不区分大小写）以启用。当开启时，服务器会监视 knowerage/ 目录，并在短暂的防抖动后，在文件系统发生更改时运行 knowerage_reconcile_all。这与在每次 MCP 工具调用后运行完整对账不同——它仅对 knowerage/ 下的文件更改做出反应。监视器会忽略对 registry.json 的注册表写入，因此保存操作不会导致循环。

如何使用 Knowerage

配置好 MCP 服务器后，你可以用正常的句子与你的助手交流。你不需要记住工具名称。

分析或记录代码

指出你关心的文件、类或行为。例如：

• 使用 Knowerage 分析 main.java 中的逻辑算法工作流。

• 分析 ETL 服务中的数据实体对账和版本控制逻辑。

助手会在 knowerage/analysis/ 下创建或更新 markdown 文件，并在 knowerage/registry.json 中记录覆盖率（见下文的工作原理）。

覆盖率和差距（同一项目，后续聊天或其他智能体）

当你树中已经有分析内容时，你可以询问：

• 以百分比计算，我们的分析覆盖了多少代码？

• 这个代码库的哪一部分尚未分析？

Knowerage 会根据注册表和覆盖率辅助工具（例如概览、每个文件的状态和陈旧列表）来回答这些问题，而不是对仓库进行模糊的猜测。

其他方法

通过 npm 安装

npx @mtimma/knowerage

或从源码构建

cargo build --release
./target/release/knowerage-mcp

工作原理

1. AI 智能体创建带有 YAML 前置元数据的分析 .md 文件，声明源文件和覆盖的代码行范围

2. 注册表 (knowerage/registry.json) 通过 SHA-256 哈希跟踪分析记录以确保新鲜度

3. MCP 工具公开创建、对账、查询和导出操作

4. 智能体说“分析 X” → 自动运行完整工作流（创建 → 对账 → 记录）

注册表文件格式 (knowerage/registry.json)

磁盘上的格式是一个 JSON 对象，其键是分析路径（字符串）。每个值都是一条记录（参见 contracts/contracts.md）。包含两条记录的完整示例如 examples/registry.sample.json 所示。

flowchart TB
  subgraph file["knowerage/registry.json"]
    O["Top-level JSON object"]
    O --> K["Each key: analysis markdown path, e.g. knowerage/analysis/.../topic.md"]
    K --> V["Value: one RegistryRecord"]
  end

  subgraph rec["RegistryRecord fields"]
    ap["analysis_path · source_path"]
    cr["covered_ranges: [[start,end], ...]"]
    h["analysis_hash · source_hash (sha256:… )"]
    t["record_created_at · record_updated_at (ISO 8601)"]
    st["status: fresh | stale_doc | stale_src | missing_src | dangling_doc"]
  end

  V --> rec

分析 .md 文件的元数据在合同文档（元数据模式）中单独指定，而不是在 registry.json 内部。

MCP 工具

项目结构

knowerage/                  # Created per-project
├── analysis/              # Analysis markdown files
│   └── **/*.md
└── registry.json          # Coverage registry

src/                       # Rust MCP server
├── main.rs
├── lib.rs
├── types.rs
├── parser.rs
├── registry.rs
├── mcp.rs
├── security.rs
└── export.rs

文档

• 用户入门 — 设置、配置、典型用法

• INSTRUCTIONS.md — MCP 智能体指令

• Rust 实践

• JS 实践

• 合同 — 模式和 API 合同（注册表 + 前置元数据）

• 注册表 JSON 示例 — registry.json 内容示例

安全性

• 所有路径均针对工作区根目录进行验证

• 拒绝路径遍历 (..)

• 注册表原子写入（防崩溃）

• 分析文件或报告中不包含任何机密信息

• 基于 SHA-256 哈希的新鲜度检查（在 git pull 后依然有效）

许可证

MIT — 版权所有 Martins Timma。

本项目的部分内容由生成式 AI 编码助手编写或优化。设计、安全敏感行为和发布均经过人工审核。