ai-readme-mcp

v1.10.2

Published

a month ago

MCP server for managing AI_README.md files in projects

0High
0Medium
0Low

draco.cheng

mcp ai readme context claude copilot github-copilot cursor llm model-context-protocol vscode

AI_README MCP Server

Project memory for AI assistants — the conventions, traps, and hard-won lessons your code cannot tell them

📑 Quick Navigation

📋 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.

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

Create AI_README.md files in your project (root or specific directories)
Record conventions and hard-won lessons - especially anything that fails silently
Commit to git - the knowledge outlives the person who earned it
AI pulls the relevant ones before planning or editing - including before a file is opened
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.

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:

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:

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

{
  "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

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:

## 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 <file>."). 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

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

## 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 <file>."). 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

Open VSCode Settings (Ctrl+,)
Search for "MCP"
Click "Edit in settings.json"
Add the MCP server configuration

Option 2: Manual Configuration

Add to your VSCode settings.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:

## 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 <file>."). 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

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

## 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 <file>."). 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)

openclaw mcp set ai-readme-manager '{"command":"npx","args":["ai-readme-mcp@latest"]}'

Option 2: Edit config file directly

Add to ~/.openclaw/openclaw.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:

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:

## 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 <file>."). 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:

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

npm install -g ai-readme-mcp@latest

Then configure:

{
  "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

# 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:

Never use emoji in code or comments.

Use Tailwind CSS, not inline styles.
Always use TypeScript strict mode.

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:

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

{
  "excludePatterns": ["**/legacy/**", "**/docs/**"]
}

excludePatterns is a single "I don't care about this path" knob, applied two ways:

The scanner skips these directories (no AI_README inside them gets indexed).
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:

{
  "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):

{
  "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.

🏗️ 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

# 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:

# 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:

{
  "mcpServers": {
    "ai-readme-manager": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/ai-readme-mcp/dist/index.js"]
    }
  }
}

For Cursor or Claude Desktop:

{
  "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 - Get started in 10 minutes
Contributing Guide - How to contribute
Project Specification - Complete technical specification

🛠️ Available MCP Tools

`discover_ai_readmes`

Scans your project and discovers all AI_README.md files.

// 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.

// 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.

// 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:

// 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.

// 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:

// 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:

AI assistant runs init_ai_readme
Receives detailed instructions for each empty file
Follows instructions:
- Uses Glob to scan directory
- Reads 2-5 key source files
- Analyzes tech stack, patterns, conventions
Uses update_ai_readme to populate each file
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.

// 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.

// 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.