AI_README MCP Server

AI_README MCP 服务

为 AI 助手提供项目记忆——代码无法告诉它们的约定、陷阱和来之不易的经验

📑 快速导航

• AI_README 与 CLAUDE.md
• 安装与设置
  • Claude Code
  • Cursor
  • GitHub Copilot
  • Claude Desktop
  • OpenClaw
  • 其他安装方式
• 快速开始
• 手动创建与编辑
• 配置（.aireadme.config.json）
• 验证与压缩 AI_README 文件
• 多层级 AI_README
• 可用的 MCP 工具

---

📋 概述

AI_README MCP 服务 是一个 Model Context Protocol（MCP）服务，为 AI 助手提供持久的、按目录划分的项目记忆——不仅包括编码约定，还包括那些在源代码中看不到的隐性故障陷阱和事后复盘经验。它会发现、路由并管理 AI_README.md 文件，确保积累一次的知识不会丢失，同一个 Bug 不会在六个月后再次出现。

兼容： GitHub Copilot（VSCode 1.102+）、Claude Code、Cursor、OpenClaw 及其他兼容 MCP 的 AI 工具。

---

🎯 问题

AI 助手每次会话开始时，都不记得上一次会话的内容。

它会重新阅读代码，重新推导能推导出的内容，然后再次做出同样错误的判断——因为那些本可以阻止它的推理，从未写在它能看到的地方。你纠正了它。会话结束。纠正也随之消失。

每个项目都会积累一些代码中看不到的知识：

• 💣 来之不易的经验——代码能显示你使用了哪个库，却不会显示你最初尝试过的另外三个库，也不会说明它们为何失败。
• 🕳️ 隐性故障陷阱——有些错误不会抛出异常，只会悄悄导致功能失效，而且一周内都没人发现。
• ⚰️ 刻意保留的特殊写法——那个看起来重复的字段、那个多余的 await、那个看似没必要的重试。每一处都不可或缺，但表面上看不出来。
• 🔁 反复出现的错误——AI 会“清理”掉变通方案，重新引入它原本要规避的那个 Bug。
• 🧠 只存在于某个人脑海中的知识——而那个人离开时，知识也会随之消失。

AI 阅读代码，只能看到它今天的行为。它看不到你已经尝试过什么、什么出了问题，或为什么否决了看似显而易见的做法。因此，它会信心十足地建议你做那件你早已知道不该做的事。

💡 解决方案

AI_README.md——一个按目录划分的记忆文件，用来记录代码无法表达的内容：约定，以及避免同一个 bug 再次出现的陷阱和复盘经验。

你可能经历过这样的对话：

你： 这个重试循环看起来多余，清理一下。 AI： 好了，已简化。 （三天后，那个不稳定的上传 bug 又出现了）

这个循环是在应对某个服务商的问题：它会在文件持久化之前就返回 200。这件事只存在于 Slack 讨论串和一位工程师的记忆中——对 AI 来说不可见，所以它删掉了。下个月，另一次会话又会把它删掉。

情况	防止问题发生的说明
AI 把变通方案“简化”回原本要避免的 bug	Retry loop is required — provider returns 200 before the file is durable
AI 选用了你已经迁移离开的库	Use date-fns, NOT moment — moment mutates in place and caused the timezone bug
AI 添加了一个 API 会静默忽略的字段	PATCH ignores unknown fields, returns 200 — always verify with a follow-up GET
AI“修正”了一个看起来古怪的排序方式	NULLs sort last via a boolean key, never NULLS LAST — unsupported on SQLite
AI 删除了一个“毫无意义”的 await	Must await — the handler commits, and the caller reads in the same transaction

模式总是一样的：某些东西看起来不对，但其实是有意为之，而原因存在于代码之外。

生产级单体代码库中的真实条目（20 个 AI_README 文件，5 层目录）

刻意写得简短——是为了让 AI 加载，而不是供人浏览。

条目	存在的原因
Manifest name CANNOT be localized - browser fetches it once at install with no Accept-Language, and the installed home-screen name is frozen	如果发布时写错，每个现有安装都会一直显示错误名称。任何部署都无法修复。
Order.items needs a NEW list assigned - an in-place mutation is invisible to the ORM and silently dropped at flush	用直觉方式编写不会报错，却什么也不会保存。
Column stays nullable, never backfilled - stamping the current time at deploy invalidates every existing session	看起来只是无害的数据清理，实际上会导致全站用户被强制登出。
search_products returns the SKU list, not a count - given a bare count the model invents plausible SKUs	它和这类问题通常一样，是在事故复盘中发现的。

代码展示了修复方式，却从不展示促使我们修复的故障。

工作原理

1. 在项目中创建 AI_README.md 文件（位于根目录或特定目录）
2. 记录约定和来之不易的经验——尤其是任何会静默失败的情况
3. 提交到 git——这些知识会比获得它们的人留存得更久
4. AI 会在规划或编辑之前提取相关文件——包括打开文件之前
5. AI 会写回内容——通过经过验证的渠道，及时记录经验

此 MCP 服务的功能

• 🔍 自动发现项目中的所有 AI_README.md 文件
• 🎯 路由上下文——为正在编辑的代码提供相关的父目录链
• 🚀 引导式初始化——init_ai_readme 会扫描空文件并引导填充
• ✏️ 在工作流中捕获经验——发现陷阱时，update_ai_readme 会立即记录
• ✅ 审核每次写入——包括验证、冲突检测和质量评分
• 🗜️ 保持内容精炼——通过压缩和拆分来落实 token 预算

结果： 六个月后，一个从未看过复盘记录的 AI 不会再次引入同一个 bug。

---

🆚 AI_README 与 CLAUDE.md

“我不能直接写个 CLAUDE.md 吗？” — 对于约定，通常可以。区别在于知识从何而来。

CLAUDE.md 由人提前编写。这适用于你已经知道的规则：该调用哪些工具、如何运行测试。

但成熟代码库中最有价值的知识，并非可以提前知道。没人会在第一天就写下 “kube-proxy 会在 Traefik 填入 XFF 之前改写源地址，因此 externalTrafficPolicy 必须设为 Local”。这是凌晨 2 点才学到的——而和你一起学到这一点的，正是 AI。AI_README 会在那一刻记录下来，并通过一个会审核写入内容的渠道完成。

	CLAUDE.md	AI_README
典型内容	你提前知道的指令	在弄坏东西的过程中吸取的教训
编写者	人类，提前编写	AI，在发现问题时编写
写入方式	自由编辑文本	仅限 update_ai_readme
写入时审核	无	验证 + 冲突检测 + 质量评分
令牌预算	不受管理——持续增长，直到挤占代码空间	tokenBudget，支持压缩 / 拆分 / 重写
嵌套	支持	支持
子目录规则	在该目录中工作前不会进入上下文	按需检索，适用于任何路径

经过审核的写入方式能防止文件内容逐渐过时。其中最重要的是冲突检测：如果请求与已记录的经验相矛盾，AI 会停下来询问，而不是悄悄改写规则——这恰恰能防止它把变通方案“修复”回原本要避免的 bug。

按需检索弥补了规划时的信息缺口。两种格式都支持嵌套，但只有在 AI 于某个子目录中工作时，该目录的规则才会进入上下文。get_context_for_file 会在打开文件之前，返回任意路径对应的完整父级链——因此在改变计划仍然代价低廉时，就能发现冲突。

支撑这一说法的实验

根目录中的 CLAUDE.md 加上 apps/frontend/CLAUDE.md，其中包含一条规则：“仅使用 CSS Modules”：

• **会话开始时，没有打开任何文件：**AI 只列出了根目录文件的内容。前端规则不在上下文中。
• **要求它在不读取文件的情况下规划该目录中的重构：*它无法说出应采用哪种样式方案——用它自己的话说，选择一种“就属于编造”——并将“apps/frontend/ 是否有自己的 CLAUDE.md”*列入需要检查的事项。它推测该文件可能存在，却看不到其中的内容。

**为什么这种优势会不断累积：**约定大致固定不变，但只要项目存在，经验就会持续累积——每一条经验都对应一个无法以相同方式再次出现的 bug。随着 AI 起草越来越多的工作，稳定性就不再那么依赖某个模型的推理能力，而更多取决于在需要时能否获取来之不易的知识——即使助手从未见过这个代码库、明天就不会记得今天的事，也无法读取记录决策过程的 Slack 讨论串。

约定让 AI 的输出保持一致。记录下来的经验让它不再回退。

**两者都用。**本项目同时提供两者：让此服务正常运行的规则——“在任何与代码相关的任务开始前调用 get_context_for_file”——放在 CLAUDE.md 中，因为它必须在任何 MCP 工具运行前生效。CLAUDE.md 驱动工作流；AI_README 保存项目教给你的内容。

---

✨ 功能

• 🔍 自动发现 - 扫描并索引项目中的所有 AI_README.md 文件
• 🎯 智能上下文路由 - 根据文件路径查找相关的 README 内容
• 🤝 团队一致性 - 每位团队成员的 AI 助手都从 git 读取相同的规范，确保代码质量统一
• 🚀 引导式初始化 - init_ai_readme 工具会扫描空文件，并引导 AI 填充内容
• 💣 记录来之不易的经验 - 一旦遇到陷阱，就立即记录下来，避免修复被悄悄撤销
• 🛑 冲突检测 - 如果请求与已记录的经验相矛盾，AI 会停止并询问，而不是覆盖已有内容
• 🔄 更新与同步 - AI 既可以读取，也可以更新 AI_README 文件
• ✅ 验证与质量 - 通过令牌限制和结构检查确保 README 内容一致
• 🗜️ 自动压缩 - compress_ai_readme 会自动移除填充内容和冗长表达，在不丢失信息的前提下降低令牌占用
• 🏗️ 支持单体仓库 - 可在不同文件夹层级放置 AI_README.md 文件；工具会自动查找并使用最相关的文件
• 📦 轻松集成 - 与 Cursor、Claude Code 及其他 MCP 客户端无缝协作

---

🚀 安装与设置

适用于 Claude Code（VSCode 扩展）

💡 模型推荐： 为获得最佳体验，请使用更大的模型（Sonnet 或 Opus），它们遵循指令的能力更强，也更可靠地触发 MCP 工具。Haiku 等较小的模型可能无法在适当的时候稳定调用工具。

步骤 1：添加 MCP 服务

在项目目录中运行：

claude mcp add --scope project ai-readme-manager npx -- ai-readme-mcp@latest

这会创建一个使用 npx 运行此软件包的 .mcp.json 文件，无需安装或配置路径！

步骤 2：启用项目 MCP 服务

在项目中创建或编辑 .claude/settings.local.json：

{
  "enableAllProjectMcpServers": true
}

步骤 3：自动批准 MCP 工具（可选，但推荐）

若要避免每次都出现“Yes/No”提示，并启用“Yes, Do not ask again”选项，请将这些工具添加到允许列表。

在 .claude/settings.local.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
}

注意： 如果没有此配置，每次 Claude 使用这些工具时都会提示你批准，并且不会显示“Do not ask again”选项。

步骤 4：验证安装

claude mcp get ai-readme-manager

你应该会看到 Status: ✓ Connected

步骤 5：添加 CLAUDE.md 指令

将以下内容添加到项目的 CLAUDE.md，确保 Claude 在每项编码任务开始前都会调用 MCP 工具：

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

为什么这很重要： 如果没有 CLAUDE.md，Claude 可能会跳过 MCP 工具调用，导致生成的代码忽略项目规范。此步骤对于可靠地触发工具至关重要。

适用于 Cursor

添加到 Cursor 的 MCP 配置文件：

• Windows： %APPDATA%\Cursor\User\mcp.json
• macOS/Linux： ~/.cursor/mcp.json

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

完成配置后，彻底重启 Cursor。

添加 AGENTS.md 指令

将以下内容添加到项目的 AGENTS.md，确保 Cursor 在每项编码任务开始前都会使用 MCP 工具：

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

适用于 GitHub Copilot（VSCode 1.102+）

要求：

• VSCode 1.102 或更高版本
• 已安装 GitHub Copilot 和 Copilot Chat 扩展

选项 1：使用 VSCode 设置界面

1. 打开 VSCode 设置（Ctrl+,）
2. 搜索“MCP”
3. 点击“在 settings.json 中编辑”
4. 添加 MCP 服务配置

选项 2：手动配置

添加到 VSCode 的 settings.json：

{
  "github.copilot.chat.mcp.servers": {
    "ai-readme-manager": {
      "command": "npx",
      "args": ["ai-readme-mcp@latest"]
    }
  }
}

完成配置后，重启 VSCode，即可在 GitHub Copilot Chat 中使用 MCP 工具！

添加 .github/copilot-instructions.md 指令

在项目中创建 .github/copilot-instructions.md，确保 Copilot 在每项编码任务开始前都会使用 MCP 工具：

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

适用于 Claude Desktop Application

添加到 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"]
    }
  }
}

添加 CLAUDE.md 指令

将以下内容添加到项目的 CLAUDE.md，确保 Claude Desktop 在每项编码任务开始前都会一致地使用 MCP 工具：

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

适用于 OpenClaw

非常适合氛围编码 / 迭代式 AI 开发——OpenClaw 用户通常会让 AI Agent 在紧密循环中构建或重构代码。如果没有持久上下文，每次迭代都有可能破坏前几轮确立的约定。ai-readme-mcp 会为 Agent 提供稳定的项目规则记忆，贯穿每次循环。

选项 1：命令行（推荐）

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

选项 2：直接编辑配置文件

添加到 ~/.openclaw/openclaw.json：

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

配置完成后，重启 OpenClaw 以加载新的 MCP 服务。使用以下命令验证：

openclaw mcp list

添加技能指令

为确保 OpenClaw 的 Agent 在每次代码变更前都会一致地读取项目约定，请将以下内容添加到技能或系统提示词中：

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

迭代式 Agent 为何需要这一点： 在 Agent 循环中，每次迭代都是一个全新的上下文。如果没有 AI_README.md，Agent 就无法记住前几轮做出的决定，导致风格偏移、模式冲突和回归问题。ai-readme-mcp 充当持久记忆层，让每次循环都遵循相同的约定。

其他安装方式

以上方法使用 npx（推荐）。如果你更喜欢其他方式，可以在 MCP 配置文件中使用以下配置：

• Claude Code： .mcp.json（项目根目录）
• Cursor： %APPDATA%\Cursor\User\mcp.json（Windows）或 ~/.cursor/mcp.json（macOS/Linux）
• Claude Desktop： claude_desktop_config.json（参见上述路径）

选项 1：使用 npx（推荐）

无需安装！只需配置并通过 npx 使用：

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

-y 标志会自动接受 npx 提示。@latest 可确保你始终获取最新版本。

选项 2：全局安装

全局安装一次，到处使用：

npm install -g ai-readme-mcp@latest

然后进行配置：

{
  "mcpServers": {
    "ai-readme-manager": {
      "command": "ai-readme-mcp"
    }
  }
}

优点： 启动更快（无需通过 npx 下载）。缺点： 发布新版本时需要手动更新。

别忘了： 配置 MCP 服务后，为 AI 工具添加指令文件——请参阅上方针对具体客户端的设置部分（CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md）。

---

🚀 快速开始

使用 init_ai_readme 工具自动扫描并填充空的 AI_README 文件：

步骤 1： 在需要的位置创建空的 AI_README.md 文件

# Example: Create empty AI_READMEs in different directories
touch AI_README.md
touch apps/backend/AI_README.md
touch apps/frontend/AI_README.md

步骤 2： 触发初始化

在 AI 助手（Claude Code、Cursor 等）中，只需说：

“请在此项目中使用 init_ai_readme MCP 工具”

执行内容：

• 🔍 扫描项目中的空 AI_README 文件
• 📝 如果不存在根目录级别的 AI_README，则创建一个
• 📋 为每个文件提供详细的分步说明
• 🤖 AI 助手随后会：
  • 探索相关目录
  • 分析代码库（技术栈、模式、约定）
  • 在每个 AI_README 中填充相关文档

适用情况：

• 首次在项目中设置 AI_README 时
• 在子目录中创建新的空 AI_README.md 文件后
• get_context_for_file 检测到空的 AI_README 文件时
• 批量处理多个空的 AI_README 文件时

---

✏️ 手动创建与编辑

你随时可以自行创建和编辑 AI_README.md 文件——无需任何工具。没有规定的格式；AI 会将其视为纯文本，因此即使只有一行也可以！

这是你项目的文档。你可以随时编辑——无论是首次设置、添加新约定，还是纠正 AI 写下的内容。

简单且行之有效的示例：

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.

要点： 写下任何有助于 AI 理解你偏好的内容。几句清晰的话通常胜过冗长的文档。

最佳实践：

• 保持简洁（理想情况下少于 400 个令牌）
• 专注于约定，而非文档
• 随着项目发展而更新——每当发现 AI 做错事时，就添加新规则
• 使用 git diff AI_README.md 查看 AI 所做的更新，并随意编辑
• 使用 AI 帮助维护，但最终编辑者始终是你

---

⚙️ 配置（.aireadme.config.json）

大多数项目无需配置——默认设置面向精简、针对 AI 优化的文件（少于 400 个令牌）。但大型单体仓库通常有些目录的约定确实无法压缩到那么短。在项目根目录中放置一个 .aireadme.config.json，即可提高预算：

{
  "tokenBudget": 800
}

tokenBudget 是唯一需要调整的参数。 设置它后，所有内容都会随之调整——质量评分阈值、“偏离 / 需要重写”的提醒，以及超预算提示中显示的数字。你无需设置五个数字，只需设置一个。

这是目标，而非硬性上限。 文件超过 tokenBudget 时不会被拒绝或截断——超出预算只会触发轻微的“精简一下”提醒，验证也只会在达到预算两倍时标记为错误。因此，800 个令牌预算下的 420 个令牌文件完全没问题。

级别	公式	@ 400（默认值）	@ 800
优秀	½ × tokenBudget	200	400
良好（目标值）	1 × tokenBudget	400	800
警告	1.5 × tokenBudget	600	1200
错误	2 × tokenBudget	800	1600

省略该文件与 { "tokenBudget": 400 } 完全相同——现有项目不会有任何变化。仍然接受高级覆盖项（tokenLimits、rules、sectionSplitThreshold）；显式设置时，它们的优先级高于派生值。

提示：只有在内容确实无法再精简时，才建议提高 tokenBudget。如果超预算文件中有一个部分占了大部分内容，工具会建议将其拆分到子目录中的 AI_README.md，这样既能保持每个文件精简，也无需增加预算。

排除目录

默认情况下，扫描器会跳过 node_modules、.git、dist、build、.next 和 coverage。如需始终忽略其他目录（例如生成的代码、legacy/ 目录树，或不希望 Agent 查阅其中约定的 docs/ 文件夹），请添加 excludePatterns：

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

excludePatterns 是唯一的“我不关心此路径”设置，会以两种方式生效：

1. 扫描器会跳过这些目录（不会索引其中的 AI_README）。
2. 当正在编辑的文件匹配时，get_context_for_file 会直接短路——不会注入任何 AI_README 上下文（甚至包括根目录中的内容）。工具会改为返回一行提示。这样可以避免 Agent 编辑 docs/ 或其他非代码路径时，被迫加载内容庞大的根目录 AI_README。

内置忽略项（如 node_modules）仍会在你设置的项目之外继续排除——你无法意外开始扫描这些目录。（直接在工具调用中传入 excludePatterns，仍会覆盖该次调用的配置。）

验证规则（可选）

有两条规则值得部分团队覆盖：

{
  "rules": {
    "allowCodeBlocks": true,
    "requireSections": ["## Conventions", "## Cross-directory dependencies"]
  }
}

• allowCodeBlocks（默认值为 false）——默认会标记代码围栏，因为它们会消耗令牌。如果某个代码片段确实应该放在 AI_README 中，请设为 true。
• requireSections（默认无）——如果缺少列出的章节标题，则发出警告；例如，可用于强制所有 AI_README 使用统一模板。

指导级别

工具描述以及附加到 get_context_for_file 的指导内容会在每一轮发送给模型。如果此服务占用了过多上下文预算，请切换到 medium——它会将描述缩减约 80%，并在每次读取时省去 AI_README 编写指南（该指导仍保留在 update_ai_readme 中，而那里才是它真正需要的地方）：

{
  "guidanceLevel": "medium"
}

• high（默认）——完整的“每次都调用此工具”提示。最适合需要推动其调用工具的小型模型或不太遵循指令的模型。
• medium——占用的上下文少得多。最适合能力较强的模型（Opus/Sonnet），因为额外的 token 只会增加成本。

在启动时从服务工作目录中的 .aireadme.config.json 读取一次，因此更改后需要重启服务才能生效。（工具描述会在任何工具调用之前发送，因此这是唯一一个从当前工作目录读取、而非按次调用的 projectRoot 读取的设置。）它只控制服务提示词的额外开销，不影响 AI_README 文件的内容或验证行为。

---

🗜️ 验证并压缩 AI_README 文件

只需向 AI 助手发送一条提示词，即可让 AI_README 文件保持简洁且节省 token：

使用 validate_ai_readmes 和 compress_ai_readme 验证并压缩所有 AI_README 文件。

AI 会自动运行完整流程：validate_ai_readmes → compress_ai_readme（预览，不实际应用）→ 应用 → 再次验证。

---

多层级 AI_README（不仅适用于单体仓库！）

此工具的强大之处在于支持多层级文档——不仅适用于单体仓库，也适用于任何希望按模块或功能组织规范的项目。

为什么采用多层级结构？

• 🎯 避免根目录 README 臃肿——让每个 README 都聚焦且简洁
• 📍 精准上下文——AI 只会获取与当前处理代码相关的规范
• 🔧 灵活组织——可按功能、模块或任何合适的结构组织

只需在不同文件夹层级放置 AI_README.md 文件：

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

智能处理空 README：

• 📝 在需要特定规范的子目录中创建空的 AI_README.md 文件
• 🚀 运行 init_ai_readme 工具（只需告诉 AI：“请初始化 AI_README 文件”）
• 🤖 AI 会自动分析每个目录并填充规范
• 🔗 对于存在父级 README 的子目录，会生成差异化内容（仅包含模块专属规范）
• 📋 对于根目录，会生成完整的项目分析

AI 处理文件时，会自动获取：

• 最相关的 AI_README（最近的父目录）
• 以及根目录级别的 AI_README（项目范围内的标准）

例如，编辑 apps/frontend/src/components/Button.tsx 时：

• ✅ 获取 apps/frontend/AI_README.md（React 组件规范）
• ✅ 获取根目录的 AI_README.md（项目范围内的 Git 和测试规范）

测试集成

重启 IDE，然后询问 AI 助手：

“我准备创建一个新组件。应该遵循哪些规范？”

AI 会自动检索 AI_README 上下文！

详细设置说明请参阅快速入门指南。

---

🏗️ 项目结构

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

🛠️ 开发

前置条件

• Node.js 18+
• npm/pnpm/yarn
• TypeScript 5+

设置

# 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

本地开发配置

如果你正在开发或修改源代码，请将 MCP 客户端配置为使用本地构建：

Claude Code - 使用 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

Claude Code - 手动编辑 .mcp.json：

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

Cursor 或 Claude Desktop：

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

路径示例：

• Windows："C:\\Users\\YourName\\ai-readme-mcp\\dist\\index.js"（使用 \\ 进行转义）
• macOS/Linux："/home/username/ai-readme-mcp/dist/index.js"

---

📚 文档

• 快速入门指南 - 10 分钟快速上手
• 贡献指南 - 如何参与贡献
• 项目规范 - 完整的技术规范

---

🛠️ 可用的 MCP 工具

discover_ai_readmes

扫描项目并发现所有 AI_README.md 文件。

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

获取与指定文件路径相关的 AI_README 上下文。

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

使用指定操作更新 AI_README.md 文件。

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

**注意：**更改会直接写入文件。请使用 Git 进行版本控制：

• 查看更改：git diff AI_README.md
• 撤销更改：git checkout AI_README.md
• 提交更改：git add AI_README.md && git commit -m "Update AI_README"

使用示例：

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

初始化并填充项目中的空 AI_README 文件。

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

功能：

• 🔍 扫描项目，查找空白或缺失的 AI_README 文件
• 📝 如果不存在根目录级 AI_README，则创建一个
• 📋 为每个文件生成详细的分步说明
• 🎯 可使用 targetPath 参数指定目标目录
• 🤖 引导 AI 分析技术栈、模式和约定

使用示例：

// Initialize all empty AI_READMEs in project
{
  projectRoot: "/path/to/project"
}

// Initialize only in specific directory
{
  projectRoot: "/path/to/project",
  targetPath: "apps/backend"
}

典型工作流：

1. AI 助手运行 init_ai_readme
2. 接收每个空文件的详细说明
3. 按照说明操作：
   • 使用 Glob 扫描目录
   • 阅读 2-5 个关键源文件
   • 分析技术栈、模式和约定
4. 使用 update_ai_readme 填充每个文件
5. 使用 get_context_for_file 或 validate_ai_readmes 验证

validate_ai_readmes

验证项目中的所有 AI_README.md 文件的质量和令牌效率。

// 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;
}

验证功能：

• 统计令牌数，以优化 AI 使用效率
• 验证结构（H1 标题、章节）
• 检查行长度（默认：100 个字符）
• 检测代码块（严格模式下默认禁用）
• 根据令牌数评定质量

默认令牌限制（严格模式）：

• 🌟 优秀：< 200 个令牌
• ✅ 良好：< 400 个令牌
• ⚠️ 需要改进：< 600 个令牌
• ❌ 过长：> 800 个令牌

compress_ai_readme

使用确定性的填充语言移除规则压缩 AI_README.md 文件。不调用 LLM——仅进行正则表达式转换。

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

移除内容（仅限正文，不会改动代码块）：

• 填充词：just、really、basically、actually、simply、essentially
• 冗长表达：in order to → to、utilize → use、make sure to → ensure
• 含蓄表达：you should、remember to、it might be worth、please note that
• 冗余连接词：furthermore、additionally、in addition、moreover

**输出可能包含不完整的句子片段，这是有意为之。**令牌高效的格式适用于 AI_README 文件。

典型工作流：

1. 运行 validate_ai_readmes，注意任何 filler-language 警告
2. 使用 dryRun: true 运行 compress_ai_readme 以预览
3. 再次运行，不带 dryRun，以应用更改
4. 重新运行 validate_ai_readmes，确认改进效果

---

🤝 参与贡献

欢迎参与贡献！请随时提交 Pull Request。

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

🔗 相关资源

• Model Context Protocol 规范
• MCP TypeScript SDK
• Claude Code MCP 文档

📧 联系方式

• GitHub Issues：https://github.com/Draco-Cheng/ai-readme-mcp/issues
• 项目链接：https://github.com/Draco-Cheng/ai-readme-mcp