Knowerage — AI分析網羅率管理

レガシーコードの分析網羅率と鮮度を追跡するローカルファーストのMCPサーバー。

ソース: github.com/MTimma/knowerage

クイックスタート

要件: Node.js 18以上 — npx が PATH に含まれている必要があります（Node.jsに含まれるnpmに同梱されています）。

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オブジェクト です。各値は1つの レコード です（contracts/contracts.md を参照）。2つのレコードを含む完全なサンプルは 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 内ではなく、contractsドキュメント（メタデータスキーマ）で個別に指定されます。

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 — copyright Martins Timma.

このプロジェクトの一部は、生成AIコーディングアシスタントを使用して作成または洗練されました。設計、セキュリティに敏感な動作、およびリリースについては人間によるレビューが適用されます。