project-lore

project-lore-mcp

コーディングエージェントを、プロジェクトのドキュメントのうち有用な最小限のもの（決定事項、意図、制約）へ、その出典と鮮度を示しながら案内する、ローカルファーストの MCP サーバーです。

codebase-memory-mcp などのコードインテリジェンスツールは、これはどこに実装されていて、何が依存しているかに答えます。このプロジェクトはそれを補完する問い、つまり、なぜこのように設計されたのか、このタスクではどのドキュメントが基準となるのか、そしてその知識は今も最新なのかに答えます。

できること

リポジトリ（および必要に応じて外部ドキュメントのルート）を指定します。次の処理を行います。

1. Markdown、テキスト、HTML、YAML、JSON、Mermaid、Claude の指示ファイルを検出します。
2. 各ドキュメントを種類と権威性（指示 → 正規 → 設計 → 計画 → 履歴 → 生成 → 提案）で分類します。
3. 見出し、セクション、リンク、フロントマター、ADR のステータス、「最初に読む」／「置き換える」／タスクへのルーティングに関する明示的な関係を、出典情報を記録しながら決定論的に抽出します（構造の抽出は Markdown に適用され、その他の形式はプレーンテキストとしてインデックス化されます）。
4. 再構築可能なローカルインデックスを SQLite（FTS5）に保存し、コンテンツハッシュを使って差分更新します。
5. **上限付きの抜粋と正確な出典箇所（ファイル全体は決して返しません）**を使って、タスクや知識に関するクエリに回答し、古くなったソースや置き換えられたソースを隠すのではなく、その旨を示します。

MCP ツール

ツール	目的
route_task	開発タスクを指定すると、最初に読むべきドキュメント／セクションを順番に返します。明示的なマニフェストのルートが、ランキング検索より優先されます。
search_project_knowledge	ドキュメント全文を検索し、権威性とステータスに基づいて再ランキングします。各結果の鮮度が表示されます。
get_document_context	ファイル全体を返さずに、1 つのドキュメントのセクションと型付きの関係を返します。

インストールと実行

Node.js ≥ 22 が必要です。

npm install -g project-lore-mcp   # or npx -y project-lore-mcp (no install needed)
project-lore index --root /path/to/your/repo   # one-shot index + stats
project-lore serve --root /path/to/your/repo   # stdio MCP server

Claude Code

インデックスを作成するリポジトリ内で、次のコマンドを一度実行します。

# Personal setup — stored in your local Claude Code config, not committed
claude mcp add project-lore --scope local -- \
  npx -y project-lore-mcp serve --root "$PWD"

チームで使う場合は、代わりに共有設定をコミットします。

# Shared setup — writes .mcp.json into the repository
claude mcp add project-lore --scope project -- \
  npx -y project-lore-mcp serve --root .

プロジェクトスコープでは相対ルート（.）を使用するため、どのチェックアウトでも動作します。 Claude Code は、プロジェクトスコープのサーバーを実行する前に、各ユーザーに承認を求めます。

1 つのリポジトリにつき、1 つの設定です。 Project Lore のコマンドには固定のルートパスが含まれているため、常に特定の 1 つのリポジトリをインデックス化します。グローバルに登録するのではなく、リポジトリごとに個別に登録してください。

codebase-memory-mcp と併用できます。両方を設定してください。それぞれが異なる問いを担当します。設定でリポジトリ外のドキュメントを参照する場合、Claude Code にそれらのパスへのファイルシステムアクセスを許可する必要があります（追加の作業ディレクトリとして追加するか、権限の確認を承認してください）。

サンプルを試す

npm run index:example        # index examples/documented-project
npm run serve:example        # serve it over stdio

設定

リポジトリのルートに project-lore.config.yaml を任意で配置できます。

sources:
  - id: repository
    type: directory
    path: .
    authority: canonical
  - id: design-handoff
    type: directory
    path: ../product-docs      # explicit opt-in external root
    authority: design
classification:
  rules:
    - pattern: "docs/legacy/**"
      authority: historical

全項目のリファレンスはdocs/configuration.md、権威性モデルはdocs/concepts.mdを参照してください。

設計原則

文書化された意図を慎重に保存し、取得します。構造は自動的に導き出します。出典情報は常に保持します。

• デフォルトではローカルのみです。 ネットワークアクセス、テレメトリー、アップロードはありません。インデックスは再生成でき、安全に削除できます（.project-lore/、gitignore 対象）。
• AI より決定論を優先します。 v1 では LLM も埋め込みも使用しません。保存される関係にはすべて抽出方法が記録されるため、推測データが文書化された事実を装うことはありません。
• 指示ではなく根拠を示します。 取得した抜粋は引用され、範囲が限定され、出典が明記されます。ドキュメントの内容は信頼できないデータとして扱われます（docs/provenance-and-trust.mdを参照）。

プロジェクトの状況

v0.1.0 — 最初の垂直スライスです。docs/architecture.md、docs/adr/ 内の ADR、および CONTRIBUTING.mdを参照してください。

ライセンス：MIT。