ai-readme-mcp 0.4.1 → 0.4.3

package/README.md

@@ -20,9 +20,9 @@ When working with AI assistants (like Claude, GPT, or other AI coding tools), yo
 
 - ❌ **Inconsistent code style** - AI generates code that doesn't match your project's conventions
 - ❌ **Repeated instructions** - You have to tell the AI the same rules over and over
-- ❌ **Team inconsistency** - Different team members get different AI outputs
+- ❌ **Team inconsistency** - Different team members get different AI outputs, leading to fragmented code quality
 - ❌ **Context loss** - AI forgets your project's specific patterns and best practices
-- ❌ **Outdated documentation** - Project conventions change, but documentation lags behind
+- ❌ **No single source of truth** - Team conventions exist in Slack messages, PRs, and people's heads, not in a format AI can use
 
 ## 💡 The Solution
 
@@ -32,13 +32,15 @@ Think of it as:
 - 📖 A "style guide" that AI reads before writing code
 - 🎓 An "onboarding document" that teaches AI your project's conventions
 - 🔧 A "configuration file" for AI behavior in your codebase
+- 🤝 A **"team contract"** that ensures every developer's AI assistant follows the same standards
 
 ### How It Works
 
 1. **Create** `AI_README.md` files in your project (root or specific directories)
 2. **Document** your conventions: coding standards, architecture patterns, naming rules, testing requirements
-3. **AI reads it automatically** before making changes - ensuring consistent, high-quality output
-4. **Keep it in sync** - AI can update the README as your project evolves
+3. **Commit to git** - Share conventions with your entire team
+4. **AI reads it automatically** before making changes - ensuring every team member's AI follows the same rules
+5. **Keep it in sync** - AI can update the README as your project evolves
 
 ### What This MCP Server Does
 
@@ -58,6 +60,7 @@ This MCP (Model Context Protocol) server automates the entire workflow:
 
 - 🔍 **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
 - 🔄 **Update & Sync** - AI can both read and update AI_README files
 - ✅ **Validation & Quality** - Ensure README consistency with token limits and structure checks
@@ -66,100 +69,54 @@ This MCP (Model Context Protocol) server automates the entire workflow:
 
 ---
 
-## 🚀 Installation
+## 🚀 Installation & Setup
 
-**Option 1: Using npx (Recommended)**
-
-No installation needed! Just configure and use via npx:
-
-```json
-{
-  "mcpServers": {
-    "ai-readme-manager": {
-      "command": "npx",
-      "args": ["-y", "ai-readme-mcp"]
-    }
-  }
-}
-```
+### For Claude Code (VSCode Extension)
 
-The `-y` flag automatically accepts the npx prompt.
+**Step 1: Add MCP Server**
 
-**Option 2: Global Installation**
+In your project directory, run:
 
 ```bash
-npm install -g ai-readme-mcp
+claude mcp add --scope project ai-readme-manager npx -- ai-readme-mcp
 ```
 
-Then configure:
+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
 {
-  "mcpServers": {
-    "ai-readme-manager": {
-      "command": "ai-readme-mcp"
-    }
-  }
+  "enableAllProjectMcpServers": true
 }
 ```
 
-**Option 3: Local Development**
-
-> **Note:** Use this method if you want to modify or contribute to the source code.
-
-```bash
-# Clone this repository to a permanent location
-git clone https://github.com/Draco-Cheng/ai-readme-mcp.git ~/ai-readme-mcp
-cd ~/ai-readme-mcp
-
-# Install and build
-npm install
-npm run build
-```
+**Step 3: Auto-approve MCP Tools (Optional but Recommended)**
 
-Then see configuration section below for manual setup.
+To avoid "Yes/No" prompts every time and enable "Yes, Do not ask again" option, add the tools to your allow list.
 
-### Configuration for Claude Code (VSCode Extension)
-
-**Option 1: Using CLI (Recommended)**
-
-In your project directory, run:
-
-```bash
-# If you cloned to ~/ai-readme-mcp:
-claude mcp add --transport stdio ai-readme-manager --scope project -- node ~/ai-readme-mcp/dist/index.js
-
-# Or use absolute path:
-claude mcp add --transport stdio ai-readme-manager --scope project -- node /path/to/ai-readme-mcp/dist/index.js
-```
-
-This creates a `.mcp.json` file in your project root.
-
-**Option 2: Manual Configuration**
-
-Create `.mcp.json` in your project root:
+In `.claude/settings.local.json`, add:
 
 ```json
 {
-  "mcpServers": {
-    "ai-readme-manager": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["/absolute/path/to/ai-readme-mcp/dist/index.js"]
-    }
-  }
+  "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"
+    ]
+  },
+  "enableAllProjectMcpServers": true
 }
 ```
 
-Replace `/absolute/path/to/ai-readme-mcp` with your actual installation path.
-
-**Path examples:**
-- **Windows:** `"C:\\Users\\YourName\\ai-readme-mcp\\dist\\index.js"`
-- **macOS/Linux:** `"~/ai-readme-mcp/dist/index.js"` or `"/home/username/ai-readme-mcp/dist/index.js"`
-
-> 💡 **Tip:** Clone to a permanent location like `~/ai-readme-mcp` so the path stays consistent across projects.
+> **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.
 
-**Verify Installation:**
+**Step 4: Verify Installation**
 
 ```bash
 claude mcp get ai-readme-manager
@@ -167,14 +124,11 @@ claude mcp get ai-readme-manager
 
 You should see `Status: ✓ Connected`
 
-### Configuration for Cursor
+### For Cursor
 
 Add to Cursor's MCP configuration file:
-
-**Windows:** `%APPDATA%\Cursor\User\mcp.json`
-**macOS/Linux:** `~/.cursor/mcp.json`
-
-**Using npx (Recommended):**
+- **Windows:** `%APPDATA%\Cursor\User\mcp.json`
+- **macOS/Linux:** `~/.cursor/mcp.json`
 
 ```json
 {
@@ -187,43 +141,36 @@ Add to Cursor's MCP configuration file:
 }
 ```
 
-**If globally installed:**
+After configuring, restart Cursor completely.
 
-```json
-{
-  "mcpServers": {
-    "ai-readme-manager": {
-      "command": "ai-readme-mcp"
-    }
-  }
-}
-```
+### For Claude Desktop Application
 
-**For local development:**
+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": "node",
-      "args": ["/path/to/ai-readme-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "ai-readme-mcp"]
     }
   }
 }
 ```
 
-**Verify Installation:**
-
-After configuring, restart Cursor completely. The MCP server should be available to AI assistants in Cursor.
+### Alternative Installation Methods
 
-### Configuration for Claude Desktop Application
-
-Add to `claude_desktop_config.json`:
+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)
 
-**Windows:** `%APPDATA%\claude\claude_desktop_config.json`
-**macOS/Linux:** `~/.config/claude/config.json` or `~/Library/Application Support/Claude/config.json`
+**Option 1: Using npx (Recommended)**
 
-**Using npx (Recommended):**
+No installation needed! Just configure and use via npx:
 
 ```json
 {
@@ -236,31 +183,30 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-**If globally installed:**
+> The `-y` flag automatically accepts the npx prompt.
 
-```json
-{
-  "mcpServers": {
-    "ai-readme-manager": {
-      "command": "ai-readme-mcp"
-    }
-  }
-}
+**Option 2: Global Installation**
+
+Install once globally, use everywhere:
+
+```bash
+npm install -g ai-readme-mcp
 ```
 
-**For local development:**
+Then configure:
 
 ```json
 {
   "mcpServers": {
     "ai-readme-manager": {
-      "command": "node",
-      "args": ["/path/to/ai-readme-mcp/dist/index.js"]
+      "command": "ai-readme-mcp"
     }
   }
 }
 ```
 
+> **Pros:** Faster startup (no npx download). **Cons:** Need to manually update when new versions release.
+
 ---
 
 ## Create Your First AI_README
@@ -444,6 +390,51 @@ npm run build
 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
@@ -695,6 +686,7 @@ We're actively working on new features:
 - **Auto-populate Empty AI_README** - Automatically generate AI_README content when `get_context_for_file` detects empty files, reducing manual initialization steps
 - **Enhanced Tool Triggering** - Improve tool descriptions and prompts to ensure AI assistants trigger tools at the right moments with better precision and reliability
 - **CI/CD Integration** - GitHub Actions for automated README validation
+- **VSCode Extension** - Native VSCode extension with visual UI for managing AI_README files, offering a more integrated experience alongside the current MCP server
 
 Want to contribute? Check out our [Contributing Guide](./CONTRIBUTING.md)!
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-readme-mcp",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "MCP server for managing AI_README.md files in projects",
   "type": "module",
   "bin": {