# AI_README MCP Server
> Project memory for AI assistants — the conventions, traps, and hard-won lessons your code cannot tell them
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
## 📑 Quick Navigation
- [AI_README vs. CLAUDE.md](#-ai_readme-vs-claudemd)
- [Installation & Setup](#-installation--setup)
- [For Claude Code](#for-claude-code-vscode-extension)
- [For Cursor](#for-cursor)
- [For GitHub Copilot](#for-github-copilot-vscode-1102)
- [For Claude Desktop](#for-claude-desktop-application)
- [For OpenClaw](#for-openclaw)
- [Alternative Installation Methods](#alternative-installation-methods)
- [Quick Start](#-quick-start)
- [Manual Creation & Editing](#️-manual-creation--editing)
- [Configuration (`.aireadme.config.json`)](#️-configuration-aireadmeconfigjson)
- [Validate & Compress AI_README Files](#️-validate--compress-ai_readme-files)
- [Multi-Level AI_README](#multi-level-ai_readme-not-just-for-monorepos)
- [Available MCP Tools](#️-available-mcp-tools)
---
## 📋 Overview
**AI_README MCP Server** is a Model Context Protocol (MCP) server that gives AI assistants a persistent, per-directory memory of your project — not just its coding conventions, but the silent-failure traps and post-mortem lessons that are invisible in the source. It discovers, routes, and manages `AI_README.md` files so that knowledge earned once is not lost, and the same bug is not reintroduced six months later.
**Works with:** GitHub Copilot (VSCode 1.102+), Claude Code, Cursor, OpenClaw, and other MCP-compatible AI tools.
---
## 🎯 The Problem
**Your AI assistant starts every session with no memory of the last one.**
It re-reads the code, re-derives what it can, and re-makes the same wrong call — because the reasoning that would have stopped it was never written anywhere it can see. You correct it. The session ends. The correction is gone.
Every project accumulates knowledge that **is not visible in the code**:
- 💣 **Hard-won lessons** - The code shows which library you use. It does not show the three you tried first, or why they failed.
- 🕳️ **Silent-failure traps** - Some mistakes throw no error. They just quietly stop working, and nobody notices for a week.
- ⚰️ **Deliberate oddities** - That duplicated-looking field, that extra `await`, that retry that seems unnecessary. Each one is load-bearing, and none of them look it.
- 🔁 **Mistakes that repeat** - The AI "cleans up" the workaround, reintroducing the exact bug it was working around.
- 🧠 **Knowledge that lives in one person's head** - and leaves with them.
An AI reading your code sees **what it does today**. It cannot see what you already tried, what broke, or why the obvious approach was rejected. So it confidently suggests the thing you learned not to do.
## 💡 The Solution
**AI_README.md** - a per-directory memory file holding what the code cannot say: conventions, plus the traps and post-mortem lessons that stop the same bug being reintroduced.
You have probably had this conversation:
> **You:** This retry loop looks redundant, clean it up.
> **AI:** Done, simplified.
> *(three days later, the flaky upload bug is back)*
The loop was working around a provider that returns `200` before the file is durable. That lived in a Slack thread and one engineer's memory — invisible to the AI, so it removed it. Next month a different session removes it again.
| The situation | The line that prevents it |
|---|---|
| AI "simplifies" a workaround back into the bug it was avoiding | `Retry loop is required — provider returns 200 before the file is durable` |
| AI picks the library you already migrated off | `Use date-fns, NOT moment — moment mutates in place and caused the timezone bug` |
| AI adds a field the API silently ignores | `PATCH ignores unknown fields, returns 200 — always verify with a follow-up GET` |
| AI "fixes" an odd-looking sort | `NULLs sort last via a boolean key, never NULLS LAST — unsupported on SQLite` |
| AI removes a "pointless" `await` | `Must await — the handler commits, and the caller reads in the same transaction` |
The pattern is always the same: **something looks wrong but is deliberate**, and the reason lives outside the code.
Real entries from a production monorepo (20 AI_README files, 5 directory levels)
Terse by design — written for an AI to load, not a human to browse.
| Entry | Why it exists |
|---|---|
| `Manifest name CANNOT be localized - browser fetches it once at install with no Accept-Language, and the installed home-screen name is frozen` | Ship it wrong and every existing install keeps the wrong name. No deploy fixes it. |
| `Order.items needs a NEW list assigned - an in-place mutation is invisible to the ORM and silently dropped at flush` | The natural way to write it throws no error and saves nothing. |
| `Column stays nullable, never backfilled - stamping the current time at deploy invalidates every existing session` | Looks like harmless data hygiene. Is a site-wide forced logout. |
| `search_products returns the SKU list, not a count - given a bare count the model invents plausible SKUs` | Found the way these things usually are: in an incident review. |
The code shows the fix, never the failure that motivated it.
### How It Works
1. **Create** `AI_README.md` files in your project (root or specific directories)
2. **Record** conventions and hard-won lessons - especially anything that fails silently
3. **Commit to git** - the knowledge outlives the person who earned it
4. **AI pulls the relevant ones** before planning or editing - including before a file is opened
5. **AI writes back** - lessons get recorded on the spot, through a validated channel
### What This MCP Server Does
- 🔍 **Auto-discovers** all AI_README.md files in your project
- 🎯 **Routes context** - the relevant parent chain for the code being edited
- 🚀 **Guided initialization** - `init_ai_readme` scans for empty files and guides population
- ✏️ **Captures lessons in-flow** - the moment a trap is found, `update_ai_readme` records it
- ✅ **Reviews every write** - validation, conflict detection, quality scoring
- 🗜️ **Keeps it dense** - token budget enforcement with compression and splitting
**Result:** the same bug does not get reintroduced six months later by an AI that never saw the post-mortem.
---
## 🆚 AI_README vs. CLAUDE.md
> **"Can't I just write a CLAUDE.md?"** — For conventions, often yes. The difference is **where the knowledge comes from**.
CLAUDE.md is written by a human, up front. That fits rules you already know: which tools to call, how to run the tests.
But the knowledge worth most in a mature codebase isn't knowable up front. Nobody writes *"kube-proxy rewrites the source address before Traefik fills XFF, so `externalTrafficPolicy` must be `Local`"* on day one. That's learned at 2am — and the one who learned it alongside you was the AI. AI_README captures it in that moment, through a channel that reviews the write.
| | CLAUDE.md | AI_README |
|---|---|---|
| **Typical content** | Instructions you know in advance | Lessons learned by breaking things |
| **Authored by** | Humans, up front | AI, at the moment of discovery |
| **Write path** | Free-form text editing | `update_ai_readme` only |
| **Review on write** | None | Validation + conflict detection + quality score |
| **Token budget** | Unmanaged — grows until it crowds out code | `tokenBudget`, with compress / split / rewrite |
| **Nesting** | Yes | Yes |
| **Subdirectory rules** | Not in context until you work in that directory | Retrieved on demand, for any path |
**The reviewed write path** is what keeps the file from rotting. Most important is conflict detection: if a request contradicts a recorded lesson, the AI **stops and asks** instead of quietly rewriting the rule — which is exactly what stops it "fixing" a workaround back into the bug it was avoiding.
**On-demand retrieval** closes a planning-time gap. Both formats nest, but a subdirectory's rules only reach the AI once it works in that directory. `get_context_for_file` returns the full parent chain for any path, before a file is opened — so conflicts surface while changing course is still cheap.
The experiment behind that claim
A root `CLAUDE.md` plus `apps/frontend/CLAUDE.md` holding one rule, "use CSS Modules only":
- **At session start, nothing opened:** the AI listed only the root file's contents. The frontend rule was not in context.
- **Asked to plan a refactor in that directory without reading files:** it could not name a styling approach — picking one "would be an invention", in its own words — and listed *"whether `apps/frontend/` has its own CLAUDE.md"* among what it would need to check. It inferred the file might exist but could not see inside it.
**Why this compounds:** conventions are roughly fixed, but lessons accumulate for as long as the project lives — each one a bug that cannot return the same way twice. As AI drafts more of the work, stability depends less on any single model's reasoning and more on whether hard-won knowledge is reachable when it's needed — by an assistant that never saw this codebase, won't remember today tomorrow, and can't read the Slack thread where the decision was made.
Conventions make AI output *consistent*. Recorded lessons make it *not regress*.
**Use both.** This project ships both: the rule that makes this server work — *"call `get_context_for_file` before any code-related task"* — lives in CLAUDE.md, because it must apply before any MCP tool runs. **CLAUDE.md drives the workflow; AI_README holds what the project taught you.**
---
## ✨ Features
- 🔍 **Automatic Discovery** - Scan and index all AI_README.md files in your project
- 🎯 **Smart Context Routing** - Find relevant README content based on file paths
- 🤝 **Team Consistency** - Every team member's AI assistant reads the same conventions from git, ensuring uniform code quality
- 🚀 **Guided Initialization** - `init_ai_readme` tool scans for empty files and guides AI through population
- 💣 **Captures Hard-Won Lessons** - records the trap the moment you hit it, so the fix is never quietly undone
- 🛑 **Conflict Detection** - if a request contradicts a recorded lesson, the AI stops and asks instead of overwriting it
- 🔄 **Update & Sync** - AI can both read and update AI_README files
- ✅ **Validation & Quality** - Ensure README consistency with token limits and structure checks
- 🗜️ **Auto-Compression** - `compress_ai_readme` removes filler language and verbose phrases automatically, reducing token footprint without losing information
- 🏗️ **Monorepo Support** - Place AI_README.md files at different folder levels; the tool automatically finds and uses the most relevant one
- 📦 **Easy Integration** - Works seamlessly with Cursor, Claude Code, and other MCP clients
---
## 🚀 Installation & Setup
### For Claude Code (VSCode Extension)
> **💡 Model Recommendation:** For the best experience, use larger models (Sonnet or Opus) which have stronger instruction-following capabilities and more reliably trigger MCP tools. Smaller models like Haiku may not consistently call the tools when appropriate.
**Step 1: Add MCP Server**
In your project directory, run:
```bash
claude mcp add --scope project ai-readme-manager npx -- ai-readme-mcp@latest
```
This creates a `.mcp.json` file that uses `npx` to run the package - no installation or path configuration needed!
**Step 2: Enable Project MCP Servers**
Create or edit `.claude/settings.local.json` in your project:
```json
{
"enableAllProjectMcpServers": true
}
```
**Step 3: Auto-approve MCP Tools (Optional but Recommended)**
To avoid "Yes/No" prompts every time and enable "Yes, Do not ask again" option, add the tools to your allow list.
In `.claude/settings.local.json`, add:
```json
{
"permissions": {
"allow": [
"mcp__ai-readme-manager__discover_ai_readmes",
"mcp__ai-readme-manager__get_context_for_file",
"mcp__ai-readme-manager__update_ai_readme",
"mcp__ai-readme-manager__validate_ai_readmes",
"mcp__ai-readme-manager__init_ai_readme",
"mcp__ai-readme-manager__compress_ai_readme"
]
},
"enableAllProjectMcpServers": true
}
```
> **Note:** Without this configuration, you'll be prompted for approval every time Claude uses these tools, and the "Do not ask again" option won't appear.
**Step 4: Verify Installation**
```bash
claude mcp get ai-readme-manager
```
You should see `Status: ✓ Connected`
**Step 5: Add `CLAUDE.md` Instructions**
Add the following to your project's `CLAUDE.md` to ensure Claude consistently calls the MCP tools before every code task:
```markdown
## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `mcp__ai-readme-manager__get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `mcp__ai-readme-manager__init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `mcp__ai-readme-manager__update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `mcp__ai-readme-manager__update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `mcp__ai-readme-manager__update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See ."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `mcp__ai-readme-manager__update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.
```
> **Why this matters:** Without `CLAUDE.md`, Claude may skip calling the MCP tools, causing it to generate code that ignores your project's conventions. This step is essential for reliable tool triggering.
### For Cursor
Add to Cursor's MCP configuration file:
- **Windows:** `%APPDATA%\Cursor\User\mcp.json`
- **macOS/Linux:** `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"ai-readme-manager": {
"command": "npx",
"args": ["ai-readme-mcp@latest"]
}
}
}
```
After configuring, restart Cursor completely.
**Add `AGENTS.md` Instructions**
Add the following to your project's `AGENTS.md` to ensure Cursor consistently uses the MCP tools before every code task:
```markdown
## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See ."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.
```
### For GitHub Copilot (VSCode 1.102+)
**Requirements:**
- VSCode 1.102 or later
- GitHub Copilot & Copilot Chat extensions installed
**Option 1: Using VSCode Settings UI**
1. Open VSCode Settings (Ctrl+,)
2. Search for "MCP"
3. Click "Edit in settings.json"
4. Add the MCP server configuration
**Option 2: Manual Configuration**
Add to your VSCode `settings.json`:
```json
{
"github.copilot.chat.mcp.servers": {
"ai-readme-manager": {
"command": "npx",
"args": ["ai-readme-mcp@latest"]
}
}
}
```
After configuring, restart VSCode and you'll see the MCP tools available in GitHub Copilot Chat!
**Add `.github/copilot-instructions.md` Instructions**
Create `.github/copilot-instructions.md` in your project to ensure Copilot consistently uses the MCP tools before every code task:
```markdown
## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See ."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.
```
### For Claude Desktop Application
Add to `claude_desktop_config.json`:
- **Windows:** `%APPDATA%\claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/config.json`
- **Linux:** `~/.config/claude/config.json`
```json
{
"mcpServers": {
"ai-readme-manager": {
"command": "npx",
"args": ["ai-readme-mcp@latest"]
}
}
}
```
**Add `CLAUDE.md` Instructions**
Add the following to your project's `CLAUDE.md` to ensure Claude Desktop consistently uses the MCP tools before every code task:
```markdown
## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See ."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.
```
### For OpenClaw
> **Perfect for vibe coding / iterative AI development** — OpenClaw users often run AI agents in tight loops to build or refactor code. Without persistent context, each iteration risks breaking conventions set in previous rounds. `ai-readme-mcp` gives your agent a stable memory of project rules across every loop.
**Option 1: CLI (Recommended)**
```bash
openclaw mcp set ai-readme-manager '{"command":"npx","args":["ai-readme-mcp@latest"]}'
```
**Option 2: Edit config file directly**
Add to `~/.openclaw/openclaw.json`:
```json
{
"mcp": {
"servers": {
"ai-readme-manager": {
"command": "npx",
"args": ["ai-readme-mcp@latest"]
}
}
}
}
```
After configuring, restart OpenClaw to load the new MCP server. Verify with:
```bash
openclaw mcp list
```
**Add skill instructions**
To ensure OpenClaw's agent consistently reads project conventions before each code change, add the following to your skill or system prompt:
```markdown
## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See ."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.
```
> **Why this matters for iterative agents:** In agentic loops, each iteration is a fresh context. Without `AI_README.md`, the agent has no memory of decisions made in previous rounds — leading to style drift, conflicting patterns, and regressions. `ai-readme-mcp` acts as the persistent memory layer that keeps every loop grounded in the same conventions.
### Alternative Installation Methods
The above methods use `npx` (recommended). If you prefer other approaches, you can use these configurations in your MCP config file:
- **Claude Code:** `.mcp.json` (project root)
- **Cursor:** `%APPDATA%\Cursor\User\mcp.json` (Windows) or `~/.cursor/mcp.json` (macOS/Linux)
- **Claude Desktop:** `claude_desktop_config.json` (see paths above)
**Option 1: Using npx (Recommended)**
No installation needed! Just configure and use via npx:
```json
{
"mcpServers": {
"ai-readme-manager": {
"command": "npx",
"args": ["ai-readme-mcp@latest"]
}
}
}
```
> The `-y` flag automatically accepts the npx prompt. The `@latest` ensures you always get the newest version.
**Option 2: Global Installation**
Install once globally, use everywhere:
```bash
npm install -g ai-readme-mcp@latest
```
Then configure:
```json
{
"mcpServers": {
"ai-readme-manager": {
"command": "ai-readme-mcp"
}
}
}
```
> **Pros:** Faster startup (no npx download). **Cons:** Need to manually update when new versions release.
> **Don't forget:** After configuring the MCP server, add the instructions file for your AI tool — see the setup section for your specific client above (`CLAUDE.md`, `AGENTS.md`, or `.github/copilot-instructions.md`).
---
## 🚀 Quick Start
Use the `init_ai_readme` tool to automatically scan and populate empty AI_README files:
**Step 1:** Create empty AI_README.md files where needed
```bash
# Example: Create empty AI_READMEs in different directories
touch AI_README.md
touch apps/backend/AI_README.md
touch apps/frontend/AI_README.md
```
**Step 2:** Trigger the initialization
In your AI assistant (Claude Code, Cursor, etc.), simply say:
> "Please use the init_ai_readme MCP tool for this project"
**What happens:**
- 🔍 Scans your project for empty AI_README files
- 📝 Creates root-level AI_README if none exist
- 📋 Provides detailed step-by-step instructions for each file
- 🤖 AI assistant will then:
- Explore relevant directories
- Analyze your codebase (tech stack, patterns, conventions)
- Populate each AI_README with relevant documentation
**When to use `init_ai_readme`:**
- First time setting up AI_README in your project
- After creating new empty AI_README.md files in subdirectories
- When `get_context_for_file` detects empty AI_README files
- To batch-process multiple empty AI_README files
---
## ✏️ Manual Creation & Editing
You can always create and edit AI_README.md files yourself - **no tools required**. There's no required format; AI treats it as plain text, so even a single line works!
This is your project's documentation. Feel free to edit it anytime - whether you're setting up for the first time, adding new conventions, or correcting something the AI wrote.
**Simple examples that work perfectly:**
```markdown
Never use emoji in code or comments.
```
```markdown
Use Tailwind CSS, not inline styles.
Always use TypeScript strict mode.
```
```markdown
This is a Next.js 14 app with App Router.
Use server components by default.
Database: Prisma + PostgreSQL.
```
**Key point:** Write whatever helps AI understand your preferences. A few clear sentences are often better than lengthy documentation.
**Best Practices:**
- Keep it concise (< 400 tokens is ideal)
- Focus on conventions, not documentation
- Update as your project evolves - add new rules whenever you notice AI doing something wrong
- Review AI-made updates with `git diff AI_README.md` and edit freely
- Use AI to help maintain it, but you're always the final editor
---
## ⚙️ Configuration (`.aireadme.config.json`)
Most projects need no config — the defaults target tight, AI-optimized files (< 400 tokens). But large monorepos often have directories whose conventions genuinely don't compress that far. Drop a `.aireadme.config.json` at your project root to raise the budget:
```json
{
"tokenBudget": 800
}
```
**`tokenBudget` is the single knob.** Set it and *everything* scales with it — the quality-score thresholds, the "drifting / needs-rewrite" nudges, and the numbers printed in the over-budget prompts. You don't set five numbers; you set one.
> **It's a target, not a hard cap.** A file is never rejected or truncated for going over `tokenBudget` — crossing it earns a light "tighten this up" nudge, and validation only flags an *error* at double the budget. So a 420-token file under an 800 budget is perfectly fine.
| Tier | Formula | @ 400 (default) | @ 800 |
|---|---|---|---|
| Excellent | ½ × tokenBudget | 200 | 400 |
| Good (the target) | 1 × tokenBudget | 400 | 800 |
| Warning | 1.5 × tokenBudget | 600 | 1200 |
| Error | 2 × tokenBudget | 800 | 1600 |
Omitting the file is identical to `{ "tokenBudget": 400 }` — existing projects see no change. Advanced overrides (`tokenLimits`, `rules`, `sectionSplitThreshold`) are still accepted and win over the derived values when set explicitly.
> Tip: prefer raising `tokenBudget` only when content is genuinely irreducible. If a single section dominates an over-budget file, the tool will suggest *splitting* it into a child-directory `AI_README.md` instead — that keeps each file tight without inflating the budget.
### Excluding directories
By default the scanner skips `node_modules`, `.git`, `dist`, `build`, `.next`, and `coverage`. To always ignore extra directories (e.g. generated code, a `legacy/` tree, or a `docs/` folder you don't want the agent to consult conventions for), add `excludePatterns`:
```json
{
"excludePatterns": ["**/legacy/**", "**/docs/**"]
}
```
`excludePatterns` is a single "I don't care about this path" knob, applied two ways:
1. The scanner skips these directories (no AI_README inside them gets indexed).
2. `get_context_for_file` short-circuits when the file you're editing matches — no AI_README context (not even root) is injected. The tool returns a one-line note instead. This avoids forcing a heavy root AI_README on agents editing `docs/` or other non-code paths.
Built-in ignores (`node_modules` etc.) stay excluded on top of yours — you can't accidentally start scanning them. (Passing `excludePatterns` directly to a tool call still overrides the config for that one call.)
### Validation rules (optional)
Two rules are worth overriding for some teams:
```json
{
"rules": {
"allowCodeBlocks": true,
"requireSections": ["## Conventions", "## Cross-directory dependencies"]
}
}
```
- **`allowCodeBlocks`** (default `false`) — code fences are flagged by default because they burn tokens. Set `true` if a snippet genuinely belongs in your AI_README.
- **`requireSections`** (default none) — warn when a listed section heading is missing, e.g. to enforce a house template across every AI_README.
### Guidance level
The tool descriptions and the guidance appended to `get_context_for_file` are sent to the model **every turn**. If this server dominates your context budget, switch to `medium` — it trims the descriptions ~80% and drops the AI_README-writing guide from every read (that guidance still lives on `update_ai_readme`, where it's actually needed):
```json
{
"guidanceLevel": "medium"
}
```
- **`high`** (default) — the full "call this every time" prompting. Best for smaller / less compliant models that need a push to call the tools.
- **`medium`** — much smaller footprint. Best for capable models (Opus/Sonnet) where the extra tokens are pure cost.
> **Read once at startup** from the `.aireadme.config.json` at the server's working directory, so a change needs a server restart to take effect. (Tool descriptions ship before any tool call, so this is the one setting read from cwd rather than a per-call `projectRoot`.) It only controls the server's prompt overhead — not what your AI_README files say or how validation behaves.
---
## 🗜️ Validate & Compress AI_README Files
Keep your AI_README files concise and token-efficient with a single prompt to your AI assistant:
> Validate and compress all AI_README files using `validate_ai_readmes` and `compress_ai_readme`.
The AI will automatically run the full cycle: `validate_ai_readmes` → `compress_ai_readme` (dry-run preview) → apply → re-validate.
---
## Multi-Level AI_README (Not Just for Monorepos!)
**The power of this tool is multi-level documentation** - not just for monorepos, but for **any project** that wants to organize conventions by module or feature.
**Why multi-level?**
- 🎯 **Avoid bloated root README** - Keep each README focused and concise
- 📍 **Precise context** - AI gets only the relevant conventions for the code it's working on
- 🔧 **Flexible organization** - Organize by feature, module, or any structure that makes sense
Simply place `AI_README.md` files at different folder levels:
```
my-monorepo/
├── AI_README.md # Root-level conventions (applies to all)
├── apps/
│ ├── frontend/
│ │ ├── AI_README.md # Frontend-specific conventions
│ │ └── src/components/Button.tsx
│ └── backend/
│ ├── AI_README.md # Backend-specific conventions
│ └── src/api/users.ts
└── packages/
└── shared/
├── AI_README.md # Shared library conventions
└── src/utils.ts
```
**Smart Empty README Handling:**
- 📝 Create empty `AI_README.md` files in subdirectories where you need specific conventions
- 🚀 Run `init_ai_readme` tool (just tell your AI: "Please initialize AI_README files")
- 🤖 AI automatically analyzes each directory and populates conventions
- 🔗 For subdirectories with parent READMEs, generates differential content (only module-specific conventions)
- 📋 For root directories, generates full project analysis
When AI works on a file, it automatically gets:
- The **most relevant** AI_README (closest parent directory)
- Plus the **root-level** AI_README (for project-wide standards)
For example, when editing `apps/frontend/src/components/Button.tsx`:
- ✅ Gets `apps/frontend/AI_README.md` (React component standards)
- ✅ Gets root `AI_README.md` (project-wide Git, testing conventions)
### Test the Integration
Restart your IDE, then ask your AI assistant:
> "I'm about to create a new component. What conventions should I follow?"
The AI will automatically retrieve your AI_README context!
For detailed setup instructions, see [Quick Start Guide](./docs/QUICK_START.md).
---
## 🏗️ Project Structure
```
ai-readme-mcp/
├── src/
│ ├── index.ts # MCP Server entry point
│ ├── tools/ # MCP Tools implementation
│ ├── core/ # Core logic (scanner, router, updater)
│ ├── types/ # TypeScript type definitions
│ └── utils/ # Utility functions
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── fixtures/ # Test fixtures
└── docs/ # Documentation
```
## 🛠️ Development
### Prerequisites
- Node.js 18+
- npm/pnpm/yarn
- TypeScript 5+
### Setup
```bash
# Clone the repository
git clone https://github.com/Draco-Cheng/ai-readme-mcp.git
cd ai-readme-mcp
# Install dependencies
npm install
# Run type checking
npm run typecheck
# Run tests
npm test
# Build the project
npm run build
# Development mode with watch
npm run dev
```
### Local Development Configuration
If you're developing or modifying the source code, configure your MCP client to use your local build:
**For Claude Code - Add with CLI:**
```bash
# Linux/macOS:
claude mcp add --transport stdio ai-readme-manager --scope project -- node ~/ai-readme-mcp/dist/index.js
# Windows:
claude mcp add --transport stdio ai-readme-manager --scope project -- node C:\Users\YourName\ai-readme-mcp\dist\index.js
```
**For Claude Code - Manual `.mcp.json`:**
```json
{
"mcpServers": {
"ai-readme-manager": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/ai-readme-mcp/dist/index.js"]
}
}
}
```
**For Cursor or Claude Desktop:**
```json
{
"mcpServers": {
"ai-readme-manager": {
"command": "node",
"args": ["/absolute/path/to/ai-readme-mcp/dist/index.js"]
}
}
}
```
**Path examples:**
- **Windows:** `"C:\\Users\\YourName\\ai-readme-mcp\\dist\\index.js"` (use `\\` for escaping)
- **macOS/Linux:** `"/home/username/ai-readme-mcp/dist/index.js"`
---
## 📚 Documentation
- **[Quick Start Guide](./docs/QUICK_START.md)** - Get started in 10 minutes
- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute
- [Project Specification](./docs/SPEC.md) - Complete technical specification
---
## 🛠️ Available MCP Tools
### `discover_ai_readmes`
Scans your project and discovers all AI_README.md files.
```typescript
// Parameters
{
projectRoot: string; // Required: Project root directory
excludePatterns?: string[]; // Optional: Glob patterns to exclude
}
// Returns
{
projectRoot: string;
totalFound: number;
readmeFiles: Array<{
path: string;
scope: string;
level: number;
patterns: string[];
}>;
lastUpdated: string;
}
```
### `get_context_for_file`
Gets relevant AI_README context for a specific file path.
```typescript
// Parameters
{
projectRoot: string; // Required: Project root directory
filePath: string; // Required: File path relative to root
includeRoot?: boolean; // Optional: Include root README (default: true)
excludePatterns?: string[]; // Optional: Glob patterns to exclude
}
// Returns
{
filePath: string;
totalContexts: number;
contexts: Array<{
path: string;
relevance: 'root' | 'direct' | 'parent';
distance: number;
content: string;
}>;
formattedPrompt: string; // Ready-to-use formatted context
}
```
### `update_ai_readme`
Update an AI_README.md file with specified operations.
```typescript
// Parameters
{
readmePath: string; // Required: Path to AI_README.md file
projectRoot: string; // Required: Project root (config is read from here)
operations: Array<{ // Required: Update operations to perform
type: 'append' | 'prepend' | 'replace' | 'insert-after' | 'insert-before';
content: string; // Content to add or replace
section?: string; // Section heading (for insert operations)
searchText?: string; // Text to search for (for replace)
}>;
}
// Returns
{
success: boolean;
readmePath: string;
changes: Array<{
operation: string;
section?: string;
linesAdded: number;
linesRemoved: number;
}>;
summary: string; // Includes reminder to use git diff
error?: string; // Error message if failed
}
```
**Note:** Changes are written directly to the file. Use Git for version control:
- Review changes: `git diff AI_README.md`
- Undo changes: `git checkout AI_README.md`
- Commit changes: `git add AI_README.md && git commit -m "Update AI_README"`
**Example Usage:**
```typescript
// Append new section
{
readmePath: "apps/frontend/AI_README.md",
operations: [{
type: "append",
content: "## Performance\n- Use React.memo for expensive components"
}]
}
// Insert after specific section
{
readmePath: "AI_README.md",
operations: [{
type: "insert-after",
section: "## Coding Conventions",
content: "### Code Style\n- Use TypeScript strict mode\n- Prefer const over let"
}]
}
// Replace specific text
{
readmePath: "AI_README.md",
operations: [{
type: "replace",
searchText: "Run tests with npm test",
content: "Run tests with: `npm test` or `npm run test:watch`"
}]
}
```
### `init_ai_readme`
Initialize and populate empty AI_README files in your project.
```typescript
// Parameters
{
projectRoot: string; // Required: Project root directory
excludePatterns?: string[]; // Optional: Glob patterns to exclude
targetPath?: string; // Optional: Specific directory to initialize
}
// Returns
{
success: boolean;
message: string;
readmesToInitialize: string[]; // Paths to empty AI_README files
instructions: string; // Detailed step-by-step guide for populating
}
```
**Features:**
- 🔍 Scans project for empty or missing AI_README files
- 📝 Creates root-level AI_README if none exist
- 📋 Generates detailed step-by-step instructions for each file
- 🎯 Can target specific directories with `targetPath` parameter
- 🤖 Guides AI through analysis: tech stack, patterns, conventions
**Example Usage:**
```typescript
// Initialize all empty AI_READMEs in project
{
projectRoot: "/path/to/project"
}
// Initialize only in specific directory
{
projectRoot: "/path/to/project",
targetPath: "apps/backend"
}
```
**Typical Workflow:**
1. AI assistant runs `init_ai_readme`
2. Receives detailed instructions for each empty file
3. Follows instructions:
- Uses `Glob` to scan directory
- Reads 2-5 key source files
- Analyzes tech stack, patterns, conventions
4. Uses `update_ai_readme` to populate each file
5. Verifies with `get_context_for_file` or `validate_ai_readmes`
### `validate_ai_readmes`
Validate all AI_README.md files in your project for quality and token efficiency.
```typescript
// Parameters
{
projectRoot: string; // Required: Project root directory
excludePatterns?: string[]; // Optional: Glob patterns to exclude
config?: { // Optional: Custom validation config
tokenBudget?: number; // Single knob; derives the tiers below (default: 400)
rules?: {
requireH1?: boolean;
requireSections?: string[];
allowCodeBlocks?: boolean;
maxLineLength?: number;
};
tokenLimits?: {
excellent?: number; // Default: 200
good?: number; // Default: 400
warning?: number; // Default: 600
error?: number; // Default: 800
};
};
}
// Returns
{
valid: boolean;
totalFiles: number;
results: Array<{
path: string;
valid: boolean;
tokens: number;
rating: 'excellent' | 'good' | 'needs-improvement' | 'too-long';
issues: string[];
suggestions: string[];
}>;
summary: string;
}
```
**Validation Features**:
- Token counting for AI consumption optimization
- Structure validation (H1 heading, sections)
- Line length checks (default: 100 chars)
- Code block detection (disabled by default for strict mode)
- Quality ratings based on token count
**Default Token Limits (Strict Mode)**:
- 🌟 Excellent: < 200 tokens
- ✅ Good: < 400 tokens
- ⚠️ Needs improvement: < 600 tokens
- ❌ Too long: > 800 tokens
### `compress_ai_readme`
Compress an AI_README.md file using deterministic filler-language removal. No LLM call — pure regex transforms.
```typescript
// Parameters
{
readmePath: string; // Required: Absolute path to AI_README.md file
projectRoot: string; // Required: Project root (config is read from here)
dryRun?: boolean; // Optional: Preview changes without writing (default: false)
}
// Returns
{
success: boolean;
readmePath: string;
summary: string; // Human-readable summary with token diff
tokensBefore: number;
tokensAfter: number;
reductionPercent: number;
changes: Array<{
line: number;
original: string;
compressed: string;
patterns: string[]; // Filler patterns that were removed
}>;
written: boolean; // false if dryRun or no changes found
}
```
**What it removes (prose only — code blocks are never touched):**
- Filler words: `just`, `really`, `basically`, `actually`, `simply`, `essentially`
- Verbose phrases: `in order to` → `to`, `utilize` → `use`, `make sure to` → `ensure`
- Hedging: `you should`, `remember to`, `it might be worth`, `please note that`
- Fluff connectives: `furthermore`, `additionally`, `in addition`, `moreover`
**Output may contain sentence fragments — this is intentional.** Token-efficient format is valid for AI_README files.
**Typical Workflow:**
1. Run `validate_ai_readmes` — note any `filler-language` warnings
2. Run `compress_ai_readme` with `dryRun: true` to preview
3. Run again without `dryRun` to apply
4. Re-run `validate_ai_readmes` to confirm improvement
---
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Related Resources
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Claude Code MCP Documentation](https://docs.claude.com/en/docs/claude-code/mcp)
## 📧 Contact
- GitHub Issues: https://github.com/Draco-Cheng/ai-readme-mcp/issues
- Project Link: https://github.com/Draco-Cheng/ai-readme-mcp