Knowerage

Knowerage — AI 分析カバレッジ管理

リンク： GitHub · Glama MCP listing · npm @mtimma/knowerage

クイックスタート

要件： Node.js 18 以降 — npx が PATH に含まれている必要があります（npm に付属しており、Node に含まれています）。

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 内ではなく、コントラクトのドキュメントで別途指定されています（メタデータスキーマ）。

MCP ツール

ツール	目的
knowerage_create_or_update_doc	分析ドキュメントを作成／更新
knowerage_parse_doc_metadata	フロントマターを解析して検証
knowerage_reconcile_record	1件の分析レコードを調整
knowerage_reconcile_all	全件を再スキャン／再構築
knowerage_get_file_status	分析済み範囲と未分析範囲
knowerage_list_stale	古いレコードや問題のあるレコードを一覧表示
knowerage_list_registry	レジストリの全スナップショット（registry.json と同じ形式、キー順）
knowerage_get_tree	ツリー／グループ別のカバレッジ
registry_export_report	スナップショットをエクスポート（JSON/YAML/TXT/HTML）
knowerage_generate_bundle	選択した分析結果を分割してエクスポート（toc*.md、combined*.md、manifest.json）

プロジェクト構成

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 コーディングアシスタントを使用して作成または改良されています。設計、セキュリティ上重要な動作、リリースについては人間がレビューしています。