CodeLore MCP

Stop burning tokens re-reading whole codebases. CodeLore maintains curated, two-perspective docs for LLMs to inspect targeted project knowledge instantly.

Every topic is documented from two perspectives:

• internal.md: How the code works under the hood.
• usage.md: How to use it (API contracts, code snippets, recipes).

⚡ Key Highlights

• 4-Level Hierarchy: Project → Category (technology) → Chapter (feature) → Topic (doc unit).
• Source Freshness Engine: SHA-256 fingerprinting tracks your source files. If code changes on disk, CodeLore flags drift automatically.
• Strict Search Gating: search_docs hard-blocks queries on out-of-sync domains to prevent LLMs from reading stale indexes.
• Token-Saving Resync: resync(action: "mark_valid") updates fingerprints after manual verification without rewriting doc bodies.
• Soft-Delete Archive: remove moves entities to archive with a 30-day auto-expiry sweep. archive shelves indefinitely. restore recovers anytime.

🛠️ MCP Tools

| Tool | Purpose | |---|---| | get_project_map | Start here. One call returns full TOC, doc sizes, and sync badges. | | search_docs | BM25 fuzzy full-text search over doc bodies (gated if domain is out-of-sync). | | read_doc | Read internal, usage, or both docs for a topic with drift warnings. | | write_doc | Write doc bodies (replace/append) with optional source_files tracking (absolute paths). | | resync | Re-verify fingerprints or mark valid (mark_valid, recheck, update_sources). | | list_projects | Quick list of all registered projects and sync badges. | | register_project | Register or update a project definition. | | define_category | Define technology category (e.g. angular, dotnet). | | define_chapter | Define functional chapter (e.g. components, pages). | | define_topic | Define topic unit; auto-creates internal.md and usage.md stubs. | | remove | Move project/category/chapter/topic to archive (30-day auto-deletion). | | archive | Move entity to permanent archive without expiration. | | restore | Restore archived entity back to the live tree. | | status | Full storage dashboard: root path, project stats, sync counts, archive status. |

🚀 Quick Start

Add to Claude Code (user scope):

claude mcp add --scope user codelore -- npx -y codelore-mcp

Or add to any .mcp.json:

{
  "mcpServers": {
    "codelore": {
      "command": "npx",
      "args": ["-y", "codelore-mcp"]
    }
  }
}

Storage Location

Docs live in ~/.codelore by default. To set a custom directory, pass --root:

{
  "mcpServers": {
    "codelore": {
      "command": "npx",
      "args": ["-y", "codelore-mcp", "--root", "D:\\docs\\.codelore"]
    }
  }
}

🛠️ Development

npm install
npm run build      # Compile TypeScript to dist/
npm run dev        # Run with tsx live

📄 License

MIT © Paul Benchea