ai-readme-mcp 0.4.0 → 0.4.2

package/README.md

@@ -66,102 +66,54 @@ This MCP (Model Context Protocol) server automates the entire workflow:
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Installation & Setup
 
-### Installation
+### For Claude Code (VSCode Extension)
 
-**Option 1: Using npx (Recommended)**
+**Step 1: Add MCP Server**
 
-No installation needed! Just configure and use via npx:
+In your project directory, run:
 
-```json
-{
-  "mcpServers": {
-    "ai-readme-manager": {
-      "command": "npx",
-      "args": ["-y", "ai-readme-mcp"]
-    }
-  }
-}
+```bash
+claude mcp add --scope project ai-readme-manager npx -- ai-readme-mcp
 ```
 
-The `-y` flag automatically accepts the npx prompt.
-
-**Option 2: Global Installation**
+This creates a `.mcp.json` file that uses `npx` to run the package - no installation or path configuration needed!
 
-```bash
-npm install -g ai-readme-mcp
-```
+**Step 2: Enable Project MCP Servers**
 
-Then configure:
+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
-```
-
-Then see configuration section below for manual setup.
+**Step 3: Auto-approve MCP Tools (Optional but Recommended)**
 
-### Configuration for Claude Code (VSCode Extension)
+To avoid "Yes/No" prompts every time and enable "Yes, Do not ask again" option, add the tools to your allow list.
 
-**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
@@ -169,14 +121,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
 {
@@ -189,43 +138,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
+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)
 
-Add to `claude_desktop_config.json`:
-
-**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
 {
@@ -238,36 +180,37 @@ 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"
     }
   }
 }
 ```
 
-### Create Your First AI_README
+> **Pros:** Faster startup (no npx download). **Cons:** Need to manually update when new versions release.
+
+---
+
+## Create Your First AI_README
 
 You have two main approaches to create and populate AI_README files:
 
-#### Option 1: Automated Initialization (Recommended)
+### Option 1: Automated Initialization (Recommended)
 
 Use the `init_ai_readme` tool to automatically scan and populate empty AI_README files:
 
@@ -306,7 +249,7 @@ Or more explicitly:
 - When `get_context_for_file` detects empty AI_README files
 - To batch-process multiple empty AI_README files
 
-#### Option 2: Manual Creation
+### Option 2: Manual Creation
 
 Create and write AI_README.md files yourself:
 
@@ -340,7 +283,9 @@ Write tests alongside source files
 - Update as your project evolves
 - Use AI to help maintain it
 
-### Multi-Level AI_README (Not Just for Monorepos!)
+---
+
+## 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.
 
@@ -442,6 +387,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
@@ -690,10 +680,10 @@ Validate all AI_README.md files in your project for quality and token efficiency
 
 We're actively working on new features:
 
-- **Watch Mode** - Auto-sync changes when AI_README files are modified
-- **Performance Optimization** - Caching and incremental updates
-- **VSCode Extension** - Visual interface for managing AI_README files
+- **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.0",
+  "version": "0.4.2",
   "description": "MCP server for managing AI_README.md files in projects",
   "type": "module",
   "bin": {

package/docs/templates/basic.md

@@ -1,55 +0,0 @@
-# {{PROJECT_NAME}}
-
-Brief description of this module or component.
-
-## Architecture
-
-- **Type:** [Library/Service/Application/Component]
-- **Language:** [TypeScript/JavaScript/Python/Java/Go/Rust/etc]
-- **Framework:** [React/Vue/Django/Spring/Gin/etc]
-
-## Directory Structure
-
-- Main entry: [path]
-- Core logic: [path]
-- Utilities: [path]
-
-## Coding Conventions
-
-### File Naming
-- [snake_case/camelCase/PascalCase/kebab-case]
-
-### Code Style
-- Formatting: [Prettier/Black/gofmt/rustfmt/etc]
-- Linting: [ESLint/Pylint/golangci-lint/Clippy/etc]
-
-### Important Patterns
-- Key architectural patterns or design decisions
-- Project-specific best practices
-- Common patterns to follow
-
-## Testing
-
-- **Framework:** [Jest/Pytest/JUnit/Go testing/etc]
-- **Run Command:** [command]
-- **Coverage Target:** [percentage or "not enforced"]
-
-## Dependencies
-
-### Key Libraries
-- [Library name] - Purpose and why used
-- [Library name] - Purpose and why used
-
-## Development Workflow
-
-- Installation: [command]
-- Dev mode: [command]
-- Build: [command]
-- Run: [command]
-
-## Important Notes
-
-- Critical information AI should know
-- Security considerations
-- Performance considerations
-- Known limitations or gotchas