Lore Mcp

LORE Type-Aware Architectural Memory for AI Coding

v0.1.6 ·

·

·

---

> LORE is a plugin-based code archaeology engine for TypeScript projects. It parses your AST, maps dependencies, detects circular deps, tracks async chains, scores type safety, and feeds architectural intelligence to AI coding assistants through the Model Context Protocol (MCP).

Built by EliotShift · Battle-tested on 16 real-world projects · 100% pass rate.

---

Why LORE?

AI coding assistants write fast, but they lack architectural memory. They can't remember:

• Which files are tightly coupled
• Where circular dependencies live
• Which types are spreading across boundaries
• Which files change too often (hotspots)
• What the architectural layers are

LORE solves this by giving your AI assistant a deep understanding of your codebase architecture — through CLI analysis and MCP server integration.

---

Features

13 Analyzers

| # | Analyzer | What It Does | |---|----------|-------------| | 1 | AST Parser | Full TypeScript/TSX parsing with ts-morph + regex hybrid | | 2 | Dependency Graph | Maps all imports, exports, re-exports across your project | | 3 | Circular Dependency Detector | Finds cycles and ranks them by severity | | 4 | Dependency Direction Checker | Enforces layer rules (e.g., no controller → DB imports) | | 5 | Shannon Entropy | Complexity scoring per file (simple → very-complex) | | 6 | Hotspot Analysis | Git-churn detection — files that change too often | | 7 | Import Impact Analyzer | Shows the blast radius of every import | | 8 | Type Safety Scorer | Grades your any usage, explicit types, strictness | | 9 | Hidden Coupling Detector | Finds implicit dependencies through shared types | | 10 | AI Recommendations | Prioritized fix suggestions (P0–P3) | | 11 | Tooling Config Checker | Validates ESLint, Prettier, tsconfig settings | | 12 | Breaking Change Detector | Flags high-risk deprecation patterns | | 13 | Architectural Gap Finder | Identifies missing abstractions and patterns |

MCP Integration (8 Tools + 3 Resources)

Expose LORE to Claude Desktop, VS Code, Cursor, or any MCP client:

| Tool | Description | |------|-------------| | analyze | Full project analysis — scores, violations, complexity, hotspots | | get-scores | Health scores: overall, type safety, tooling, architecture | | get-violations | Circular deps, layer violations, architectural gaps | | get-recommendations | AI improvement suggestions (P0–P3) | | get-hotspots | Files with high git churn (red/yellow/green) | | get-entropy | Shannon entropy complexity report | | query-file | File imports, exports, consumers, complexity | | analyze_architecture | Deep TS analysis: framework, layers, async chains, type flow |

| Resource | Description | |----------|-------------| | lore://analysis | Latest analysis results (JSON) | | lore://architecture | Deep architecture graph (JSON) | | lore://config | Environment and cache status (JSON) |

CLI Commands

lore [path]                   Analyze project (default: cwd)
lore analyze [path]           Explicit analysis
lore init                     Extract architectural decisions
lore status                   View decisions by category
lore diff                     Diff against saved baseline
lore doctor                   Environment + tooling check
lore doctor --fix             Auto-fix project setup
lore ignore                   List/manage ignore patterns
lore watch                   Watch + re-analyze on change
lore mcp inspect             Inspect MCP server setup
lore mcp config              Claude Desktop config snippet
lore version                  Show version

---

Documentation

> Website: eliotshift.github.io/lore-mcp

| Page | Description | |------|-------------| | Landing Page | Full feature overview, badges, and quick start | | Installation Guide | npm, npx, and Docker installation | | Command Reference | All CLI commands: init, status, doctor, watch, diff, etc. | | MCP Integration | Claude Desktop, Cursor, and Windsurf setup | | Examples | Real-world analysis of Express, NestJS, Next.js, and more | | FAQ | Common questions answered |

---

Quick Start

Install

npm install -g lore-mcp

CLI Usage

# Analyze current project
lore

# Analyze a specific project
lore ./my-typescript-project

# Check environment and auto-fix
lore doctor --fix

# Watch for changes
lore watch --filter src/

# Diff from last baseline
lore diff

MCP Integration (Claude Desktop)

Add this to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Or if installed globally:

{
  "mcpServers": {
    "lore": {
      "command": "lore",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop, then ask:

> "Analyze my project architecture" → LORE runs analyze_architecture > "What are the circular dependencies?" → LORE runs get-violations > "Which files are hotspots?" → LORE runs get-hotspots > "What are the AI recommendations?" → LORE runs get-recommendations

---

Architecture

lore-mcp/
├── src/
│   ├── algorithm/          # LoreGraph, AST parser, async chain builder, type tracker
│   ├── algorithms/         # AI recommendations, hotspot analysis, entropy, scoring
│   ├── analyzer/           # Dependency parsers, circular deps, direction, imports
│   ├── commands/           # CLI: doctor, diff, ignore, init, status, watch
│   ├── core/               # Plugin system, pipeline runner, graph engine
│   ├── lib/                # Hidden coupling, gaps, middleware chain, ontology
│   ├── mcp/                # MCP server + architecture bridge
│   ├── output/             # Formatter, markdown, SARIF, logger
│   ├── plugins/built-in/   # 13 built-in analysis plugins
│   ├── storage/            # Cache and decision store
│   ├── types/              # TypeScript type definitions
│   ├── cli.ts              # CLI entry point
│   └── index.ts            # MCP server entry point
├── package.json
└── tsconfig.json

Plugin System

LORE uses a plugin-based architecture — every analyzer is a plugin:

interface LorePlugin {
  name: string;
  version: string;
  analyze(context: AnalysisContext): Promise;
}

Built-in plugins include: circular-deps, coupling-matrix, dep-direction, entropy, gaps, hidden-coupling, hotspot, import-impact, middleware-chain, breaking-changes, type-safety, tooling-config, ai-recommendations.

---

How It Works

1. Parse — LORE parses all .ts/.tsx files using a hybrid ts-morph + regex parser
2. Build Graph — Constructs a dependency graph with typed edges (import, type-ref, decorator, async-chain, implements, extends)
3. Run Plugins — 13 analyzers run in parallel through the plugin pipeline
4. Score — Computes health scores (type safety, tooling, architecture, overall 0–100)
5. Recommend — AI engine generates prioritized suggestions (P0 critical → P3 nice-to-have)
6. Serve — Results available via CLI output, MCP tools, or SARIF format

---

Validation

| Project | Files | Result | |---------|-------|--------| | Express | 42 | 100% Pass | | Next.js | 68 | 100% Pass | | Fastify | 55 | 100% Pass | | NestJS | 38 | 100% Pass | | Prisma | 45 | 100% Pass | | Zod | 35 | 100% Pass | | TypeORM | 60 | 100% Pass | + 9 more |

All 16 test projects: 100% pass rate, zero crashes.

---

Requirements

• Node.js >= 18.0.0
• TypeScript project (analyzes .ts and .tsx files)
• Git (optional, for hotspot analysis)
• ripgrep (optional, for faster file discovery)

---

Tech Stack

| Component | Technology | |-----------|-----------| | Language | TypeScript 5.5+ | | AST Parsing | ts-morph 21 | | Protocol | Model Context Protocol (MCP) SDK 1.0 | | Transport | Stdio (Claude Desktop / IDE compatible) | | Validation | Zod schemas | | Output | ANSI terminal, Markdown, SARIF |

---

License

MIT © 2025 EliotShift

---

LORE — Because your AI should understand your architecture, not just your code.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EliotShift
• Source: EliotShift/lore-mcp
• License: MIT
• Homepage: https://eliotshift.github.io/lore-mcp/

Install and usage instructions live in the source repository linked above.