aidex-mcp 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to AiDex will be documented in this file.
 
+## [1.6.0] - 2026-02-01
+
+### Added
+- **Auto CLAUDE.md instructions**: `aidex setup` now installs AI instructions in `~/.claude/CLAUDE.md`
+  - Tells Claude to auto-run `aidex_init` when no `.aidex/` exists
+  - Provides tool usage guide (prefer AiDex over Grep/Glob)
+  - `aidex unsetup` cleanly removes the instructions block
+- **Idempotent setup**: Re-running `aidex setup` updates existing config without errors
+
+## [1.5.2] - 2026-02-01
+
+### Fixed
+- **`aidex setup` for Claude Code**: Uses `claude mcp add --scope user` instead of editing settings.json directly
+- Claude Desktop, Cursor, Windsurf still use JSON config editing
+
 ## [1.5.1] - 2026-01-31
 
 ### Fixed

package/build/commands/setup.d.ts

@@ -1,7 +1,8 @@
 /**
  * AiDex Setup - Auto-register as MCP server in AI clients
  *
- * Supports: Claude Code, Claude Desktop, Cursor, Windsurf
+ * Supports: Claude Code (via CLI), Claude Desktop, Cursor, Windsurf
+ * Also installs CLAUDE.md instructions for Claude Code/Desktop.
  */
 export declare function setupMcpClients(): void;
 export declare function unsetupMcpClients(): void;

package/build/commands/setup.js

@@ -1,35 +1,89 @@
 /**
  * AiDex Setup - Auto-register as MCP server in AI clients
  *
- * Supports: Claude Code, Claude Desktop, Cursor, Windsurf
+ * Supports: Claude Code (via CLI), Claude Desktop, Cursor, Windsurf
+ * Also installs CLAUDE.md instructions for Claude Code/Desktop.
  */
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
 import { homedir, platform } from 'os';
+import { execSync } from 'child_process';
 // ============================================================
-// MCP Server Entry
+// MCP Server Entry (for JSON-based clients)
 // ============================================================
 const AIDEX_MCP_ENTRY = {
     command: 'aidex',
     args: []
 };
 // ============================================================
+// CLAUDE.md Instructions Block
+// ============================================================
+const CLAUDE_MD_START = '<!-- AIDEX-START -->';
+const CLAUDE_MD_END = '<!-- AIDEX-END -->';
+const CLAUDE_MD_BLOCK = `${CLAUDE_MD_START}
+## AiDex - Persistent Code Index (MCP Server)
+
+AiDex provides fast, precise code search through a pre-built index. **Always prefer AiDex over Grep/Glob for code searches.**
+
+### Auto-Init Rule
+
+**At the start of every session, check if \`.aidex/\` exists in the project directory.**
+- If \`.aidex/\` does NOT exist → **automatically run \`aidex_init\`** to create the index. Do not ask, just do it.
+- If \`.aidex/\` exists → use AiDex tools for all code searches.
+
+### When to Use AiDex (instead of Grep/Glob)
+
+| Task | Do NOT use | Use instead |
+|------|-----------|-------------|
+| Find a function/class/variable | \`Grep pattern="name"\` | \`aidex_query term="name"\` |
+| See all methods in a file | \`Read entire_file.cs\` | \`aidex_signature file="..."\` |
+| Explore multiple files | Multiple Read calls | \`aidex_signatures pattern="src/**"\` |
+| Project overview | Many Glob/Read calls | \`aidex_summary\` + \`aidex_tree\` |
+| What changed recently? | \`git log\` + Read | \`aidex_query term="X" modified_since="2h"\` |
+
+### Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`aidex_init\` | Index a project (creates \`.aidex/\`) |
+| \`aidex_query\` | Search by term (exact/contains/starts_with) |
+| \`aidex_signature\` | Get one file's classes + methods |
+| \`aidex_signatures\` | Get signatures for multiple files (glob) |
+| \`aidex_update\` | Re-index a single changed file |
+| \`aidex_summary\` | Project overview with entry points |
+| \`aidex_tree\` | File tree with statistics |
+| \`aidex_files\` | List project files by type |
+| \`aidex_session\` | Start session, detect external changes |
+| \`aidex_note\` | Read/write session notes |
+| \`aidex_viewer\` | Open interactive project tree in browser |
+
+### Why AiDex over Grep?
+
+- **~50 tokens** per search vs 2000+ with Grep
+- **Identifiers only** - no noise from comments/strings
+- **Persistent** - index survives between sessions
+- **Structure-aware** - knows methods, classes, types
+${CLAUDE_MD_END}`;
+// ============================================================
 // Client Detection
 // ============================================================
 function getClients() {
     const home = homedir();
     const plat = platform();
     const clients = [];
-    // Claude Code
+    // Claude Code - uses its own CLI for MCP management
     clients.push({
+        type: 'cli',
         name: 'Claude Code',
-        configPath: join(home, '.claude', 'settings.json'),
-        detectDir: join(home, '.claude')
+        detectCmd: 'claude --version',
+        addCmd: ['claude', 'mcp', 'add', '--scope', 'user', 'aidex', '--', 'aidex'],
+        removeCmd: ['claude', 'mcp', 'remove', '--scope', 'user', 'aidex']
     });
-    // Claude Desktop
+    // Claude Desktop - JSON config
     if (plat === 'win32') {
         const appData = process.env.APPDATA || join(home, 'AppData', 'Roaming');
         clients.push({
+            type: 'json',
             name: 'Claude Desktop',
             configPath: join(appData, 'Claude', 'claude_desktop_config.json'),
             detectDir: join(appData, 'Claude')
@@ -37,6 +91,7 @@ function getClients() {
     }
     else if (plat === 'darwin') {
         clients.push({
+            type: 'json',
             name: 'Claude Desktop',
             configPath: join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
             detectDir: join(home, 'Library', 'Application Support', 'Claude')
@@ -44,19 +99,22 @@ function getClients() {
     }
     else {
         clients.push({
+            type: 'json',
             name: 'Claude Desktop',
             configPath: join(home, '.config', 'Claude', 'claude_desktop_config.json'),
             detectDir: join(home, '.config', 'Claude')
         });
     }
-    // Cursor
+    // Cursor - JSON config
     clients.push({
+        type: 'json',
         name: 'Cursor',
         configPath: join(home, '.cursor', 'mcp.json'),
         detectDir: join(home, '.cursor')
     });
-    // Windsurf
+    // Windsurf - JSON config
     clients.push({
+        type: 'json',
         name: 'Windsurf',
         configPath: join(home, '.codeium', 'windsurf', 'mcp_config.json'),
         detectDir: join(home, '.codeium', 'windsurf')
@@ -64,7 +122,29 @@ function getClients() {
     return clients;
 }
 // ============================================================
-// Config Read/Write
+// CLI helpers
+// ============================================================
+function isCmdAvailable(cmd) {
+    try {
+        execSync(cmd, { stdio: 'pipe', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function runCmd(args) {
+    try {
+        const output = execSync(args.join(' '), { stdio: 'pipe', timeout: 10000 }).toString().trim();
+        return { success: true, output };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { success: false, error: msg };
+    }
+}
+// ============================================================
+// JSON Config Read/Write
 // ============================================================
 function readJsonConfig(filePath) {
     try {
@@ -92,83 +172,187 @@ function writeJsonConfig(filePath, data) {
     }
 }
 // ============================================================
-// Setup / Unsetup
+// CLAUDE.md Management
+// ============================================================
+function getClaudeMdPath() {
+    return join(homedir(), '.claude', 'CLAUDE.md');
+}
+function installClaudeMd() {
+    const mdPath = getClaudeMdPath();
+    const dir = dirname(mdPath);
+    // Ensure directory exists
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    let content = '';
+    if (existsSync(mdPath)) {
+        content = readFileSync(mdPath, 'utf8');
+        // Already has AiDex block? Replace it
+        if (content.includes(CLAUDE_MD_START)) {
+            const regex = new RegExp(`${CLAUDE_MD_START}[\\s\\S]*?${CLAUDE_MD_END}`, 'g');
+            content = content.replace(regex, CLAUDE_MD_BLOCK);
+            writeFileSync(mdPath, content, 'utf8');
+            return { success: true, action: 'updated' };
+        }
+        // Append to existing file
+        content = content.trimEnd() + '\n\n' + CLAUDE_MD_BLOCK + '\n';
+        writeFileSync(mdPath, content, 'utf8');
+        return { success: true, action: 'appended' };
+    }
+    // Create new file
+    writeFileSync(mdPath, CLAUDE_MD_BLOCK + '\n', 'utf8');
+    return { success: true, action: 'created' };
+}
+function uninstallClaudeMd() {
+    const mdPath = getClaudeMdPath();
+    if (!existsSync(mdPath)) {
+        return { success: true, removed: false };
+    }
+    let content = readFileSync(mdPath, 'utf8');
+    if (!content.includes(CLAUDE_MD_START)) {
+        return { success: true, removed: false };
+    }
+    const regex = new RegExp(`\\n?\\n?${CLAUDE_MD_START}[\\s\\S]*?${CLAUDE_MD_END}\\n?`, 'g');
+    content = content.replace(regex, '').trim();
+    if (content.length === 0) {
+        // File would be empty, but don't delete it - might have been user-created
+        writeFileSync(mdPath, '', 'utf8');
+    }
+    else {
+        writeFileSync(mdPath, content + '\n', 'utf8');
+    }
+    return { success: true, removed: true };
+}
+// ============================================================
+// Setup
 // ============================================================
+function setupCliClient(client) {
+    if (!isCmdAvailable(client.detectCmd)) {
+        return { status: `  - ${client.name} (not installed)`, registered: false };
+    }
+    const result = runCmd(client.addCmd);
+    if (result.success) {
+        return { status: `  ✓ ${client.name}`, registered: true };
+    }
+    // "already exists" is not an error
+    if (result.error && result.error.includes('already exists')) {
+        return { status: `  ✓ ${client.name} (already registered)`, registered: true };
+    }
+    return { status: `  ✗ ${client.name} (${result.error})`, registered: false };
+}
+function setupJsonClient(client) {
+    if (!existsSync(client.detectDir)) {
+        return { status: `  - ${client.name} (not installed)`, registered: false };
+    }
+    let data;
+    if (existsSync(client.configPath)) {
+        const config = readJsonConfig(client.configPath);
+        if (!config.success || !config.data) {
+            return { status: `  ✗ ${client.name} (${config.error})`, registered: false };
+        }
+        data = config.data;
+    }
+    else {
+        data = {};
+    }
+    if (!data.mcpServers || typeof data.mcpServers !== 'object') {
+        data.mcpServers = {};
+    }
+    data.mcpServers.aidex = { ...AIDEX_MCP_ENTRY };
+    const writeResult = writeJsonConfig(client.configPath, data);
+    if (!writeResult.success) {
+        return { status: `  ✗ ${client.name} (${writeResult.error})`, registered: false };
+    }
+    return { status: `  ✓ ${client.name} (${client.configPath})`, registered: true };
+}
 export function setupMcpClients() {
     const clients = getClients();
-    const results = [];
     let registered = 0;
     console.log('\nAiDex MCP Server Registration');
     console.log('==============================\n');
+    // Register with AI clients
+    console.log('  MCP Servers:');
     for (const client of clients) {
-        // Check if client is installed (detect directory exists)
-        if (!existsSync(client.detectDir)) {
-            results.push({ client: client.name, status: 'skipped', configPath: client.configPath });
-            console.log(`  - ${client.name} (not installed)`);
-            continue;
-        }
-        // Read existing config or start with empty object
-        let data;
-        if (existsSync(client.configPath)) {
-            const config = readJsonConfig(client.configPath);
-            if (!config.success || !config.data) {
-                results.push({ client: client.name, status: 'error', configPath: client.configPath, message: config.error });
-                console.log(`  ✗ ${client.name} (${config.error})`);
-                continue;
-            }
-            data = config.data;
-        }
-        else {
-            data = {};
-        }
-        if (!data.mcpServers || typeof data.mcpServers !== 'object') {
-            data.mcpServers = {};
-        }
-        data.mcpServers.aidex = { ...AIDEX_MCP_ENTRY };
-        const writeResult = writeJsonConfig(client.configPath, data);
-        if (!writeResult.success) {
-            results.push({ client: client.name, status: 'error', configPath: client.configPath, message: writeResult.error });
-            console.log(`  ✗ ${client.name} (${writeResult.error})`);
-            continue;
-        }
-        registered++;
-        results.push({ client: client.name, status: 'registered', configPath: client.configPath });
-        console.log(`  ✓ ${client.name} (${client.configPath})`);
+        const result = client.type === 'cli'
+            ? setupCliClient(client)
+            : setupJsonClient(client);
+        console.log(result.status);
+        if (result.registered)
+            registered++;
+    }
+    // Install CLAUDE.md instructions
+    console.log('\n  AI Instructions:');
+    const mdResult = installClaudeMd();
+    const mdPath = getClaudeMdPath();
+    if (mdResult.success) {
+        console.log(`  ✓ CLAUDE.md (${mdResult.action}: ${mdPath})`);
     }
     console.log(`\nRegistered AiDex with ${registered} client(s).\n`);
     if (registered > 0) {
         console.log('Restart your AI client(s) to activate AiDex.\n');
     }
 }
+// ============================================================
+// Unsetup
+// ============================================================
+function unsetupCliClient(client) {
+    if (!isCmdAvailable(client.detectCmd)) {
+        return { status: `  - ${client.name} (not installed)`, removed: false };
+    }
+    const result = runCmd(client.removeCmd);
+    if (result.success) {
+        return { status: `  ✓ Removed from ${client.name}`, removed: true };
+    }
+    else {
+        return { status: `  - ${client.name} (not registered)`, removed: false };
+    }
+}
+function unsetupJsonClient(client) {
+    if (!existsSync(client.detectDir)) {
+        return { status: `  - ${client.name} (not installed)`, removed: false };
+    }
+    if (!existsSync(client.configPath)) {
+        return { status: `  - ${client.name} (not registered)`, removed: false };
+    }
+    const config = readJsonConfig(client.configPath);
+    if (!config.success || !config.data) {
+        return { status: `  ✗ ${client.name} (${config.error})`, removed: false };
+    }
+    const data = config.data;
+    const servers = data.mcpServers;
+    if (!servers || !servers.aidex) {
+        return { status: `  - ${client.name} (not registered)`, removed: false };
+    }
+    delete servers.aidex;
+    const writeResult = writeJsonConfig(client.configPath, data);
+    if (!writeResult.success) {
+        return { status: `  ✗ ${client.name} (${writeResult.error})`, removed: false };
+    }
+    return { status: `  ✓ Removed from ${client.name}`, removed: true };
+}
 export function unsetupMcpClients() {
     const clients = getClients();
     let removed = 0;
     console.log('\nAiDex MCP Server Unregistration');
     console.log('================================\n');
+    // Unregister from AI clients
+    console.log('  MCP Servers:');
     for (const client of clients) {
-        if (!existsSync(client.configPath)) {
-            console.log(`  - ${client.name} (not installed)`);
-            continue;
-        }
-        const config = readJsonConfig(client.configPath);
-        if (!config.success || !config.data) {
-            console.log(`  ✗ ${client.name} (${config.error})`);
-            continue;
-        }
-        const data = config.data;
-        const servers = data.mcpServers;
-        if (!servers || !servers.aidex) {
-            console.log(`  - ${client.name} (not registered)`);
-            continue;
-        }
-        delete servers.aidex;
-        const writeResult = writeJsonConfig(client.configPath, data);
-        if (!writeResult.success) {
-            console.log(`  ✗ ${client.name} (${writeResult.error})`);
-            continue;
-        }
-        removed++;
-        console.log(`  ✓ Removed from ${client.name}`);
+        const result = client.type === 'cli'
+            ? unsetupCliClient(client)
+            : unsetupJsonClient(client);
+        console.log(result.status);
+        if (result.removed)
+            removed++;
+    }
+    // Remove CLAUDE.md instructions
+    console.log('\n  AI Instructions:');
+    const mdResult = uninstallClaudeMd();
+    if (mdResult.removed) {
+        console.log(`  ✓ Removed AiDex block from CLAUDE.md`);
+    }
+    else {
+        console.log(`  - CLAUDE.md (no AiDex block found)`);
     }
     console.log(`\nUnregistered AiDex from ${removed} client(s).\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aidex-mcp",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "MCP Server providing persistent code indexing for Claude Code",
   "main": "build/index.js",
   "bin": {