Project Lore

io.github.tamas-fmPublished by GitHub account tamas-fmv0.1.1Updated Oct 24, 2026

A local-first MCP server that routes development tasks to authoritative project documentation.

VerifiedSTDIODesktop onlyFiles & StorageKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

A local-first MCP server that indexes a repository's documentation and routes coding tasks to the most relevant, authoritative documents.

What you can do
It scans a repository for Markdown, text, HTML, YAML, JSON, Mermaid and instruction files, classifies each by kind and authority, and builds a rebuildable local SQLite (FTS5) index updated by content hash. Three tools are exposed: route_task returns the ordered documents and sections to read first for a given development task, search_project_knowledge runs full-text search re-ranked by authority and status with freshness shown per result, and get_document_context returns sections and typed relationships of one document. Answers are bounded excerpts with exact source locations rather than whole files, and stale or superseded sources are flagged.
When to use it
Useful when an assistant needs to know why a project was designed a certain way, which document governs a task, or whether that knowledge is still current. It complements code-intelligence servers that answer where code is implemented and what depends on it. Best suited to repositories with meaningful written documentation, decisions, or constraints.
Requirements
Node.js 22 or later. Runs as a local stdio process via the npm package project-lore-mcp, either installed globally or run with npx. It needs a root path to the repository to index, and one configuration per repository. If external documentation roots are referenced, the client must be granted filesystem access to those paths. No accounts, API keys, or network access are required.
Before you install
The server is local-only by default with no network access, telemetry, or uploads, and the index under .project-lore/ is regenerable and safe to delete. It reads repository documentation, so indexing a repository exposes that content to the assistant as quoted excerpts. Document content is treated as untrusted data. Project-scoped configuration writes a .mcp.json file into the repository, and clients ask users to approve project-scoped servers before running them.

Installation

In SourceWeft

  1. Open Project Lore in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

project-lore-mcp

A local-first MCP server that routes coding agents to the smallest useful set of project documentation — decisions, intent, and constraints — with provenance and freshness.

Code-intelligence tools (such as codebase-memory-mcp) answer where is this implemented and what depends on it. This project answers the complementary questions: why was it designed this way, which document governs this task, and is that knowledge still current?

What it does

Point it at a repository (plus optional external documentation roots). It:

  1. discovers Markdown, text, HTML, YAML, JSON, Mermaid, and Claude instruction files;
  2. classifies each document by kind and authority (instructions → canonical → design → planning → historical → generated → proposed);
  3. extracts headings, sections, links, frontmatter, ADR status, and explicit "read first" / "supersedes" / task-routing relationships — deterministically, with recorded provenance (structural extraction applies to Markdown; other formats receive plain-text indexing);
  4. stores a rebuildable local index in SQLite (FTS5), updated incrementally by content hash;
  5. answers task and knowledge queries with bounded excerpts and exact source locations — never whole files, flagging stale or superseded sources instead of hiding them.

MCP tools

ToolPurpose
route_taskGiven a development task, return the ordered documents/sections to read first. Explicit manifest routes win over ranked search.
search_project_knowledgeFull-text search over documentation, re-ranked by authority and status; freshness is shown per result.
get_document_contextSections + typed relationships of one document, without returning the whole file.

Install and run

Requires Node.js ≥ 22.

bash
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 + statsproject-lore serve --root /path/to/your/repo   # stdio MCP server

Claude Code

Run this once from inside the repository you want to index:

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

For teams, commit a shared configuration instead:

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

The project scope uses a relative root (.) so it works on any checkout. Claude Code will ask each user to approve project-scoped servers before running them.

One repository, one configuration. Project Lore's command contains a fixed root path, so it always indexes one specific repository. Register it separately per repository rather than globally.

It coexists with codebase-memory-mcp — configure both; they own different questions. If your configuration references documentation outside the repository, Claude Code must be granted filesystem access to those paths (add them as additional working directories or approve the permission prompts).

Try the example

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

Configuration

Optional project-lore.config.yaml at the repository root:

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

See docs/configuration.md for the full reference and docs/concepts.md for the authority model.

Design principles

Store and retrieve documented intent conservatively. Derive structure automatically. Preserve provenance always.

  • Local-only by default. No network access, no telemetry, no uploads. The index is regenerable and safe to delete (.project-lore/, gitignored).
  • Deterministic before AI. v1 uses no LLM and no embeddings. Every stored relationship records how it was extracted; inferred data can never masquerade as documented fact.
  • Evidence, not instructions. Retrieved excerpts are quoted, bounded, and attributed. Document content is treated as untrusted data (see docs/provenance-and-trust.md).

Project status

v0.1.0 — first vertical slice. See docs/architecture.md, the ADRs in docs/adr/, and CONTRIBUTING.md.

License: MIT.

Source: README.md at commit 2841711

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts