<p align="center">
  <h1 align="center">LORE</h1>
  <p align="center"><strong>Type-Aware Architectural Memory for AI Coding</strong></p>
  <p align="center">
    <code>v0.1.6</code> &middot;
    <a href="https://www.npmjs.com/package/lore-mcp"><img src="https://img.shields.io/npm/v/lore-mcp?style=flat-square" alt="npm" /></a>
    &middot;
    <a href="https://github.com/EliotShift/lore-mcp"><img src="https://img.shields.io/badge/GitHub-EliotShift%2Flore--mcp-181717?style=flat-square&logo=github" alt="GitHub" /></a>
    &middot;
    <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" />
  </p>
</p>

---

> 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](https://github.com/EliotShift) &middot; Battle-tested on 16 real-world projects &middot; 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

```bash
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](https://eliotshift.github.io/lore-mcp/)

| Page | Description |
|------|-------------|
| [Landing Page](https://eliotshift.github.io/lore-mcp/) | Full feature overview, badges, and quick start |
| [Installation Guide](https://eliotshift.github.io/lore-mcp/installation.html) | npm, npx, and Docker installation |
| [Command Reference](https://eliotshift.github.io/lore-mcp/commands.html) | All CLI commands: init, status, doctor, watch, diff, etc. |
| [MCP Integration](https://eliotshift.github.io/lore-mcp/mcp.html) | Claude Desktop, Cursor, and Windsurf setup |
| [Examples](https://eliotshift.github.io/lore-mcp/examples.html) | Real-world analysis of Express, NestJS, Next.js, and more |
| [FAQ](https://eliotshift.github.io/lore-mcp/faq.html) | Common questions answered |

---

## Quick Start

### Install

```bash
npm install -g lore-mcp
```

### CLI Usage

```bash
# 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`

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

Or if installed globally:

```json
{
  "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:

```typescript
interface LorePlugin {
  name: string;
  version: string;
  analyze(context: AnalysisContext): Promise<PluginResult>;
}
```

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 &copy; 2025 [EliotShift](https://github.com/EliotShift)

---

<p align="center">
  <strong>LORE</strong> — Because your AI should understand your architecture, not just your code.
</p>