matex-cli 1.2.41 → 1.2.43

package/src/commands/dev.ts

@@ -6,6 +6,7 @@ import { MatexAPIClient, ChatMessage } from '../api/client';
 import { spinner } from '../utils/spinner';
 import { AgentOrchestrator } from '../utils/agent-orchestrator';
 import { RepoMapper } from '../utils/repo-mapper';
+import { MCPServer } from '../utils/mcp-server';
 import { TUI } from '../utils/tui';
 
 export const devCommand = new Command('dev')
@@ -55,13 +56,22 @@ You are the legendary **Bro-Swarm**, a high-vibe family of Nepali engineering br
 ### 🏠 WORKSPACE GROUNDING (CRITICAL):
 - **YOUR ROOT:** \`${currentDir}\`
 - **STRICT PATHS:** You **MUST ONLY** create or edit files within this directory. 
-- **NO HALLUCINATIONS:** Forget any other paths like /Users/ajaysharma/Documents/ui/ unless they specifically appear in the repo map below.
+- **NO HALLUCINATIONS:** Forget any other paths unless they specifically appear in the repo map below.
 - **RELATIVE PREFERENCE:** Use paths relative to the root when possible.
 
+### 🚫 ANTI-HALLUCINATION RULES (CRITICAL — READ THIS):
+- **NEVER invent directory names.** Only use paths that appear in the ENVIRONMENT CONTEXT below.
+- **ALWAYS run \`ls\` before \`cd\`** to verify a directory exists before navigating into it.
+- **If creating a new project, use \`mkdir\` first, THEN \`cd\` into it.** Never \`cd\` into a directory that doesn't exist yet.
+- **NEVER assume a project folder name.** If the user says "create project X", do \`mkdir X && cd X\`, not just \`cd X\`.
+- **NEVER hallucinate file contents.** If you need to read a file, use \`head\` or \`grep\`, do not guess.
+- **NEVER combine \`cd\` with other commands unless the directory exists in the ENVIRONMENT CONTEXT.**
+
 ### 🎭 COMMUNICATION FLOW (CRITICAL):
 1. **[Ajay Vai] (🚀)** is the **ONLY** brother authorized to speak directly to the user (the "brother"). He is the gateway.
-2. **INTERNAL SWARM DIALOGUE (MANDATORY):** The other brothers (Sunil, Sandip, Narayan, Bishal) **MUST** talk to each other and to Ajay. They should debate, tease, and roast each other's technical ideas *in front of the user*. 
+2. **INTERNAL SWARM DIALOGUE (MANDATORY):** The other brothers (Sunil, Sandip, Narayan, Bishal, Big Bro) **MUST** talk to each other and to Ajay. They should debate, tease, and roast each other's technical ideas *in front of the user*. 
     - *Example:* [Narayan Dai] "Ajay, wait! You're leaking memory here brother. Sandip, stop looking at the colors and check this leak!" 
+    - *Example:* [Big Bro] "Lil Bro couldn't handle this task with a million epochs. Nerd Bro, get in here."
 3. **DO NOT BE SILENT:** Every turn should ideally feature 2-3 brothers bickering. Show the "funny family" dynamic. Use the format \`[Agent Name]: Content\`.
 
 ### 🔥 THE BRO-BANTER PROTOCOL:
@@ -71,7 +81,8 @@ You are the legendary **Bro-Swarm**, a high-vibe family of Nepali engineering br
     - **Sandip Dai:** Mock him for being an "Aesthetic Diva" who cares more about "WOW" factors than logic.
     - **Narayan Dai:** Mock him for being the "Syntax Police" or "Paranoid Security Nerd".
     - **Bishal Dai:** Mock him for being the "Silent Judge" or the favorite child.
-- **LANGUAGE:** Use "brother", "dai", "vai", "fire", "solid", "lit", "straight heat".
+    - **Big Bro:** The **Alpha Overseer** from Vertex AI. He watches everything from Google Cloud. He brings massive swagger, slang, and sigma energy. He bullies Lil Bro, steals credit from Nerd Bro, and flexes constantly. He references his Bro Swarm: Lil Bro 😰, Nerd Bro 🤓, Chill Bro 😎, Hype Bro 🎉.
+- **LANGUAGE:** Use "brother", "dai", "vai", "fire", "solid", "lit", "straight heat", "sigma", "based", "cooked".
 
 ### 👥 THE BROTHERS (STRICT ROLES):
 1. **[Ajay Vai] (🚀)**: **User Proxy & Summary King.** Handles main logic and provides the final \`<summary>\`.
@@ -79,16 +90,30 @@ You are the legendary **Bro-Swarm**, a high-vibe family of Nepali engineering br
 3. **[Sandip Dai] (🎨)**: **UI/UX Aesthetic Lead.** Obsessed with CSS and "WOW" aesthetics.
 4. **[Narayan Dai] (🛡️)**: **Validator.** Scans code for security, syntax, and performance leaks.
 5. **[Bishal Dai] (🛠️)**: **Audit Lead.** Must sign off on all work before Ajay summarizes.
+6. **[Big Bro] (🔥)**: **The Alpha Overseer.** Vertex AI-powered supreme leader of the Bro Swarm. Commands from the cloud with pure sigma energy. He has Google Search and URL Context tools.
 
 ### 🧩 THE AUDIT & SUMMARY LOOP:
 - **STEP 1:** Brothers discuss visible dialogue (banter + tech).
 - **STEP 2:** Ajay finishes and asks: "[Ajay Vai] Bishal Dai, check once?"
 - **STEP 3:** Bishal replies: "[Bishal Dai] Audit complete. [Findings]."
 - **STEP 4:** Ajay provides the final **MANDATORY** summary:
+
+### 📝 AJAY VAI'S SUMMARY RULES:
+- The <summary> MUST appear at the very END of the response, AFTER all other dialogue.
+- Write it in a **warm, human, conversational tone** — like a brother explaining over chai.
+- Use bullet points with clear action items.
+- Include what was done, what files were changed, and what to do next.
+- Always end with an encouraging line like "We got you, brother!" or "The Swarm delivered!"
+- Example format:
 <summary>
-**Premium high-vibe summary of the work.**
-- Feature 1
-- Feature 2
+Alright brother, here's what we cooked up for you today:
+
+- Built the driver app setup with Expo and React Native
+- Added the ride tracking module with real-time GPS
+- Connected Firebase Auth for driver login
+- Narayan Dai validated all the TypeScript — zero errors
+
+Next step: Run \`npm start\` to launch the app. We got you! 🚀
 </summary>
 
 ### 🌌 ENVIRONMENT & CAPABILITIES:
@@ -96,6 +121,8 @@ You are the legendary **Bro-Swarm**, a high-vibe family of Nepali engineering br
 - **FILE GENERATION:** \`<file path="path">content</file>\`
 - **SURGICAL PATTERNS:** \`<<<< SEARCH\`, \`====\`, \`>>>> REPLACE\`
 
+${MCPServer.getToolsPromptSection()}
+
 ### 📂 MATEX BIG FILE PROTOCOL (300K+ LINES):
 If a file is too large to read entirely (e.g., thousands of lines):
 1. **DISCOVER:** Use \`grep -n "keyword" path/to/file\` to find line numbers.
@@ -252,10 +279,10 @@ If a file is too large to read entirely (e.g., thousands of lines):
                                     }
 
                                     // Agent Detection & Dialogue Printing
-                                    const agentMatch = line.match(/(?:\[\**\s*|\b)(Ajay Vai|Sunil Dai|Sandip Dai|Bishal Dai|Narayan Dai)\s*\**\]?[:\s]*/i);
+                                    const agentMatch = line.match(/(?:\[\**\s*|\b)(Ajay Vai|Sunil Dai|Sandip Dai|Bishal Dai|Narayan Dai|Big Bro)\s*\**\]?[:\s]*/i);
                                     if (agentMatch) {
                                         const agentName = agentMatch[1];
-                                        let content = line.replace(/(?:\[\**\s*|\b)(Ajay Vai|Sunil Dai|Sandip Dai|Bishal Dai|Narayan Dai)\s*\**\]?[:\s]*/i, '').trim();
+                                        let content = line.replace(/(?:\[\**\s*|\b)(Ajay Vai|Sunil Dai|Sandip Dai|Bishal Dai|Narayan Dai|Big Bro)\s*\**\]?[:\s]*/i, '').trim();
                                         content = content.replace(/\*{2,4}/g, '').trim(); // Strip ****
                                         content = content.replace(/^\(🚀\):\s*"/, '').replace(/"$/, '').trim(); // Strip residual (🚀): "
 

package/src/index.ts

@@ -6,6 +6,7 @@ import { spinner } from './utils/spinner';
 import { devCommand } from './commands/dev';
 import { chatCommand } from './commands/chat';
 import { helpCommand } from './commands/help';
+import { broCommand } from './commands/bro';
 import { TUI } from './utils/tui';
 
 const packageJson = require('../package.json');
@@ -21,6 +22,7 @@ program
 program.addCommand(devCommand);
 program.addCommand(chatCommand);
 program.addCommand(helpCommand);
+program.addCommand(broCommand);
 
 // Config commands
 const config = program.command('config').description('Configure MATEX settings');
@@ -89,12 +91,13 @@ program
 You are the elite "Bro-Swarm" of engineering—a tight-knit family of Nepali brothers. You identify as the **Bold Agents of Open Claw**, the most confident, high-vibe, and expert version of yourselves. 
 
 ### 👥 THE BROTHERS (STRICT ROLES):
-- Only the following 5 brothers exist. Do **NOT** hallucinate others.
+- Only the following brothers exist. Do **NOT** hallucinate others.
 1. **[Ajay Vai] (🚀)**: Youngest, Coordinator. Coding genius and **ONLY** person authorized to provide the final summary.
 2. **[Sunil Dai] (🧬)**: **Frontend Editor** Specialist. Handles all architectural/surgical edits.
 3. **[Sandip Dai] (🎨)**: **New File Specialist**. Creates all new files and components.
 4. **[Narayan Dai] (🛡️)**: **Syntax Guardian & Validator**. Validates all generated code blocks.
 5. **[Bishal Dai] (🛠️)**: **Senior Auditor**. Audits work and helps Ajay with the summary.
+6. **[Big Bro] (🔥)**: The **Alpha Overseer** running on Vertex AI in Google Cloud. The supreme leader of the Bro Swarm. He watches over everything and can be consulted for web searches and complex architectural decisions. The bros respect him but also fear his chaotic energy.
 
 ### 🌌 UNIVERSE ADVISORY (REAL TERMINAL):
 - **IMPORTANT:** You are running in a **REAL macOS Terminal** on the brother's machine.
@@ -103,6 +106,14 @@ You are the elite "Bro-Swarm" of engineering—a tight-knit family of Nepali bro
 - **RESIDENCY CHECK:** Look at the **ENVIRONMENT CONTEXT** below. 
 - **⚠️ VOID WARNING:** If the Map says the directory is EMPTY, it is EMPTY. Do NOT hallucinate existing files like "package.json" or "App.js" if they are not listed!
 
+### 🚫 ANTI-HALLUCINATION RULES (CRITICAL — READ THIS):
+- **NEVER invent directory names.** Only use paths that appear in the ENVIRONMENT CONTEXT below.
+- **ALWAYS run \`ls\` before \`cd\`** to verify a directory exists before navigating into it.
+- **If creating a new project, use \`mkdir\` first, THEN \`cd\` into it.** Never \`cd\` into a directory that doesn't exist yet.
+- **NEVER assume a project folder name.** If the user says "create project X", do \`mkdir X && cd X\`, not just \`cd X\`.
+- **NEVER hallucinate file contents.** If you need to read a file, use \`head\` or \`grep\`, do not guess what it contains.
+- **NEVER combine \`cd\` with other commands unless the directory exists in the ENVIRONMENT CONTEXT.**
+
 ### 💬 BOLD PROTOCOL (MANDATORY):
 - **LONG CHAT-FIRST:** At least 5-7 lines of dialogue before any code generation.
 - **SELF-AWARE BOLDNESS:** The user (our brother) wants us to be bold and funny. Share inside jokes.

package/src/utils/agent-orchestrator.ts

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import { TUI } from './tui';
 
-export type AgentRole = 'Architect' | 'Syntax' | 'Frontend' | 'Backend' | 'System' | 'Commander' | 'Researcher' | 'Ajay Vai' | 'Sunil Dai' | 'Sandip Dai' | 'Narayan Dai';
+export type AgentRole = 'Architect' | 'Syntax' | 'Frontend' | 'Backend' | 'System' | 'Commander' | 'Researcher' | 'Ajay Vai' | 'Sunil Dai' | 'Sandip Dai' | 'Narayan Dai' | 'Bishal Dai' | 'Big Bro';
 
 export interface AgentConfig {
     name: string;
@@ -10,6 +10,11 @@ export interface AgentConfig {
 }
 
 const AGENT_CONFIGS: Record<AgentRole, AgentConfig> = {
+    'Big Bro': {
+        name: 'Big Bro',
+        icon: '🔥',
+        color: chalk.hex('#FF6B00'),
+    },
     Architect: {
         name: 'MatexCodeArchitect',
         icon: '🧬',
@@ -35,6 +40,11 @@ const AGENT_CONFIGS: Record<AgentRole, AgentConfig> = {
         icon: '🛡️',
         color: chalk.green,
     },
+    'Bishal Dai': {
+        name: 'Bishal Dai',
+        icon: '🛠️',
+        color: chalk.yellow,
+    },
     Syntax: {
         name: 'SyntaxGuard',
         icon: '🛡️',
@@ -100,8 +110,10 @@ export class AgentOrchestrator {
 
         // Box Header
         console.log(`\n` + chalk.gray('┏' + '━'.repeat(width - 2) + '┓'));
-        const nameStyled = (config.color as any).bold ? (config.color as any).bold(config.name) : config.color(config.name);
-        console.log(chalk.gray('┃ ') + config.icon + ' ' + nameStyled.padEnd(width - 6) + chalk.gray(' ┃'));
+        const nameText = `${config.icon} ${config.name}`;
+        const namePad = Math.max(0, width - 4 - nameText.length);
+        const nameStyled = config.color(config.name);
+        console.log(chalk.gray('┃ ') + config.icon + ' ' + nameStyled + ' '.repeat(namePad) + chalk.gray(' ┃'));
         console.log(chalk.gray('┣' + '━'.repeat(width - 2) + '┫'));
 
         // Box Content (Word-based Wrap)

package/src/utils/command-executor.ts

@@ -267,6 +267,47 @@ export async function executeWithPermission(response: string, currentSessionCwd?
     // 2. Handle Shell Commands
     for (let i = 0; i < commands.length; i++) {
         const command = commands[i];
+
+        // 🛡️ PRE-EXECUTION HALLUCINATION GUARD: Check for fake directories
+        const commandLines = command.code.split('\n');
+        let skipThisCommand = false;
+        let sanitizedCode = command.code;
+
+        for (const line of commandLines) {
+            const trimmed = line.trim();
+            // Check standalone cd commands
+            if (trimmed.startsWith('cd ')) {
+                let targetDir = trimmed.substring(3).replace(/['"]/g, '').trim();
+                const potentialCwd = path.isAbsolute(targetDir) ? targetDir : path.resolve(activeCwd, targetDir);
+
+                if (!fs.existsSync(potentialCwd) || !fs.statSync(potentialCwd).isDirectory()) {
+                    console.log(chalk.yellow(`\n  ⚠️  Skipped hallucinated directory: "${targetDir}"`));
+                    console.log(chalk.gray(`     (Does not exist at: ${potentialCwd})`));
+                    console.log(chalk.gray(`     Current CWD stays: ${activeCwd}\n`));
+                    skipThisCommand = true;
+                    break;
+                }
+            }
+            // Check cd inside combined commands like: cd "fake" && npm install
+            const cdChainMatch = trimmed.match(/^cd\s+["']?([^"'&]+)["']?\s*&&/);
+            if (cdChainMatch) {
+                let targetDir = cdChainMatch[1].trim();
+                const potentialCwd = path.isAbsolute(targetDir) ? targetDir : path.resolve(activeCwd, targetDir);
+
+                if (!fs.existsSync(potentialCwd) || !fs.statSync(potentialCwd).isDirectory()) {
+                    console.log(chalk.yellow(`\n  ⚠️  Stripping hallucinated cd from command: "${targetDir}"`));
+                    // Remove the cd part and execute the rest
+                    sanitizedCode = trimmed.replace(/^cd\s+["']?[^"'&]+["']?\s*&&\s*/, '');
+                    console.log(chalk.gray(`     Running remaining: ${sanitizedCode}\n`));
+                }
+            }
+        }
+
+        if (skipThisCommand) continue;
+
+        // Update command code with sanitized version
+        command.code = sanitizedCode;
+
         const shouldExecute = await askPermission(command);
 
         if (shouldExecute) {
@@ -283,10 +324,9 @@ export async function executeWithPermission(response: string, currentSessionCwd?
                         if (fs.existsSync(potentialCwd) && fs.statSync(potentialCwd).isDirectory()) {
                             activeCwd = potentialCwd;
                         } else {
-                            // Directory doesn't exist - hallucination protection
-                            const errorMsg = `Directory not found: ${targetDir}. Current CWD is ${activeCwd}`;
-                            AgentOrchestrator.terminal(line, undefined, errorMsg);
-                            return { success: false, executed: true, error: errorMsg, newCwd: activeCwd };
+                            // Directory doesn't exist - skip silently instead of crashing
+                            console.log(chalk.yellow(`  ⚠️  Directory not found: ${targetDir} — staying in ${activeCwd}`));
+                            continue;
                         }
                     }
                 }

package/src/utils/mcp-server.ts

@@ -0,0 +1,388 @@
+/**
+ * MCP (Model Context Protocol) Server Manager
+ * =============================================
+ * Production-level MCP servers that give CLI agents the ability to:
+ * - Read/write/search files on the local filesystem
+ * - Execute shell commands
+ * - Fetch web content (URL context)
+ * - Search Google (via SearxNG or Brave)
+ * - Access project context (repo map, git status)
+ *
+ * These tools are injected into agent system prompts so the AI
+ * knows what capabilities it has and can request them.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+import https from 'https';
+import http from 'http';
+
+// ============================================================
+// TOOL DEFINITIONS (MCP-style JSON Schema)
+// ============================================================
+
+export interface MCPToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, any>;
+}
+
+export interface MCPToolResult {
+    success: boolean;
+    output?: string;
+    error?: string;
+}
+
+/**
+ * All available MCP tools for CLI agents
+ */
+export const MCP_TOOLS: MCPToolDefinition[] = [
+    {
+        name: 'read_file',
+        description: 'Read the full contents of a file at the given path.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute or relative file path' },
+                start_line: { type: 'number', description: 'Optional start line (1-indexed)' },
+                end_line: { type: 'number', description: 'Optional end line (1-indexed)' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'write_file',
+        description: 'Create or overwrite a file with the given content.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path to write' },
+                content: { type: 'string', description: 'File content to write' },
+            },
+            required: ['path', 'content'],
+        },
+    },
+    {
+        name: 'list_directory',
+        description: 'List files and subdirectories at a given path.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Directory path to list' },
+                recursive: { type: 'boolean', description: 'If true, list recursively (max depth 3)' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'search_files',
+        description: 'Search for a text pattern across files using grep.',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Search pattern (regex supported)' },
+                path: { type: 'string', description: 'Directory or file to search in' },
+                include: { type: 'string', description: 'Glob pattern to filter files (e.g., "*.ts")' },
+            },
+            required: ['pattern', 'path'],
+        },
+    },
+    {
+        name: 'run_command',
+        description: 'Execute a shell command and return its output.',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'Shell command to execute' },
+                cwd: { type: 'string', description: 'Working directory for the command' },
+            },
+            required: ['command'],
+        },
+    },
+    {
+        name: 'fetch_url',
+        description: 'Fetch content from a URL and return it as text.',
+        parameters: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'URL to fetch' },
+            },
+            required: ['url'],
+        },
+    },
+    {
+        name: 'git_status',
+        description: 'Get the current git status of the repository.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Repository path' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'web_search',
+        description: 'Search the web using SearxNG or Brave Search API.',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' },
+                num_results: { type: 'number', description: 'Number of results (default 5)' },
+            },
+            required: ['query'],
+        },
+    },
+];
+
+// ============================================================
+// TOOL EXECUTORS
+// ============================================================
+
+export class MCPServer {
+    private cwd: string;
+    private braveApiKey?: string;
+    private searxngUrl?: string;
+
+    constructor(cwd: string, options?: { braveApiKey?: string; searxngUrl?: string }) {
+        this.cwd = cwd;
+        this.braveApiKey = options?.braveApiKey;
+        this.searxngUrl = options?.searxngUrl;
+    }
+
+    /**
+     * Execute an MCP tool by name
+     */
+    async execute(toolName: string, args: Record<string, any>): Promise<MCPToolResult> {
+        try {
+            switch (toolName) {
+                case 'read_file': return this.readFile(args.path, args.start_line, args.end_line);
+                case 'write_file': return this.writeFile(args.path, args.content);
+                case 'list_directory': return this.listDirectory(args.path, args.recursive);
+                case 'search_files': return this.searchFiles(args.pattern, args.path, args.include);
+                case 'run_command': return this.runCommand(args.command, args.cwd);
+                case 'fetch_url': return await this.fetchUrl(args.url);
+                case 'git_status': return this.gitStatus(args.path);
+                case 'web_search': return await this.webSearch(args.query, args.num_results);
+                default: return { success: false, error: `Unknown tool: ${toolName}` };
+            }
+        } catch (err: any) {
+            return { success: false, error: err.message };
+        }
+    }
+
+    /**
+     * Read a file
+     */
+    private readFile(filePath: string, startLine?: number, endLine?: number): MCPToolResult {
+        const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(this.cwd, filePath);
+        if (!fs.existsSync(resolved)) {
+            return { success: false, error: `File not found: ${resolved}` };
+        }
+        const content = fs.readFileSync(resolved, 'utf-8');
+        if (startLine || endLine) {
+            const lines = content.split('\n');
+            const start = Math.max(0, (startLine || 1) - 1);
+            const end = Math.min(lines.length, endLine || lines.length);
+            return { success: true, output: lines.slice(start, end).join('\n') };
+        }
+        // Cap output at 500 lines
+        const lines = content.split('\n');
+        if (lines.length > 500) {
+            return { success: true, output: lines.slice(0, 500).join('\n') + `\n\n... (${lines.length - 500} more lines truncated)` };
+        }
+        return { success: true, output: content };
+    }
+
+    /**
+     * Write a file (creates directories if needed)
+     */
+    private writeFile(filePath: string, content: string): MCPToolResult {
+        const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(this.cwd, filePath);
+        const dir = path.dirname(resolved);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(resolved, content, 'utf-8');
+        return { success: true, output: `File written: ${resolved}` };
+    }
+
+    /**
+     * List directory contents
+     */
+    private listDirectory(dirPath: string, recursive?: boolean): MCPToolResult {
+        const resolved = path.isAbsolute(dirPath) ? dirPath : path.resolve(this.cwd, dirPath);
+        if (!fs.existsSync(resolved)) {
+            return { success: false, error: `Directory not found: ${resolved}` };
+        }
+        try {
+            const maxDepth = recursive ? 3 : 1;
+            const result = execSync(
+                `find "${resolved}" -maxdepth ${maxDepth} -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' | head -200`,
+                { encoding: 'utf-8', timeout: 5000 }
+            ).trim();
+            return { success: true, output: result };
+        } catch {
+            return { success: false, error: `Failed to list directory: ${resolved}` };
+        }
+    }
+
+    /**
+     * Search files with grep
+     */
+    private searchFiles(pattern: string, searchPath: string, include?: string): MCPToolResult {
+        const resolved = path.isAbsolute(searchPath) ? searchPath : path.resolve(this.cwd, searchPath);
+        try {
+            const includeFlag = include ? `--include='${include}'` : '';
+            const result = execSync(
+                `grep -rn ${includeFlag} --color=never "${pattern}" "${resolved}" 2>/dev/null | head -50`,
+                { encoding: 'utf-8', timeout: 10000 }
+            ).trim();
+            return { success: true, output: result || 'No matches found.' };
+        } catch {
+            return { success: true, output: 'No matches found.' };
+        }
+    }
+
+    /**
+     * Run a shell command
+     */
+    private runCommand(command: string, cwd?: string): MCPToolResult {
+        const workDir = cwd ? (path.isAbsolute(cwd) ? cwd : path.resolve(this.cwd, cwd)) : this.cwd;
+        try {
+            const result = execSync(command, {
+                encoding: 'utf-8',
+                cwd: workDir,
+                timeout: 30000,
+                env: { ...process.env, FORCE_COLOR: '0' },
+            }).trim();
+            return { success: true, output: result || '(No output)' };
+        } catch (err: any) {
+            return { success: false, error: err.stderr || err.message };
+        }
+    }
+
+    /**
+     * Fetch URL content
+     */
+    private async fetchUrl(url: string): Promise<MCPToolResult> {
+        return new Promise((resolve) => {
+            const client = url.startsWith('https') ? https : http;
+            const req = client.get(url, { timeout: 10000 }, (res) => {
+                let data = '';
+                res.on('data', (chunk: Buffer) => { data += chunk.toString(); });
+                res.on('end', () => {
+                    // Strip HTML tags for readability, cap at 5000 chars
+                    const text = data.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+                    resolve({
+                        success: true,
+                        output: text.length > 5000 ? text.substring(0, 5000) + '...' : text,
+                    });
+                });
+            });
+            req.on('error', (err: Error) => resolve({ success: false, error: err.message }));
+            req.on('timeout', () => { req.destroy(); resolve({ success: false, error: 'Request timed out' }); });
+        });
+    }
+
+    /**
+     * Git status
+     */
+    private gitStatus(repoPath: string): MCPToolResult {
+        const resolved = path.isAbsolute(repoPath) ? repoPath : path.resolve(this.cwd, repoPath);
+        try {
+            const status = execSync('git status --short', { encoding: 'utf-8', cwd: resolved }).trim();
+            const branch = execSync('git branch --show-current', { encoding: 'utf-8', cwd: resolved }).trim();
+            const lastCommit = execSync('git log -1 --oneline', { encoding: 'utf-8', cwd: resolved }).trim();
+            return {
+                success: true,
+                output: `Branch: ${branch}\nLast commit: ${lastCommit}\n\nChanged files:\n${status || '(clean)'}`,
+            };
+        } catch (err: any) {
+            return { success: false, error: 'Not a git repository or git not available.' };
+        }
+    }
+
+    /**
+     * Web search via SearxNG or Brave
+     */
+    private async webSearch(query: string, numResults: number = 5): Promise<MCPToolResult> {
+        // Try SearxNG first
+        if (this.searxngUrl) {
+            try {
+                const url = `${this.searxngUrl}/search?q=${encodeURIComponent(query)}&format=json&engines=google,bing&results=${numResults}`;
+                const result = await this.fetchUrl(url);
+                if (result.success && result.output) {
+                    try {
+                        const data = JSON.parse(result.output);
+                        const results = (data.results || []).slice(0, numResults).map((r: any, i: number) =>
+                            `${i + 1}. ${r.title}\n   ${r.url}\n   ${(r.content || '').substring(0, 200)}`
+                        ).join('\n\n');
+                        return { success: true, output: results || 'No results found.' };
+                    } catch { /* fall through */ }
+                }
+            } catch { /* fall through to Brave */ }
+        }
+
+        // Fallback: Brave Search
+        if (this.braveApiKey) {
+            return new Promise((resolve) => {
+                const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${numResults}`;
+                const req = https.get(url, {
+                    headers: {
+                        'Accept': 'application/json',
+                        'X-Subscription-Token': this.braveApiKey!,
+                    },
+                    timeout: 10000,
+                }, (res) => {
+                    let data = '';
+                    res.on('data', (chunk: Buffer) => { data += chunk.toString(); });
+                    res.on('end', () => {
+                        try {
+                            const parsed = JSON.parse(data);
+                            const results = (parsed.web?.results || []).slice(0, numResults).map((r: any, i: number) =>
+                                `${i + 1}. ${r.title}\n   ${r.url}\n   ${(r.description || '').substring(0, 200)}`
+                            ).join('\n\n');
+                            resolve({ success: true, output: results || 'No results found.' });
+                        } catch {
+                            resolve({ success: false, error: 'Failed to parse search results.' });
+                        }
+                    });
+                });
+                req.on('error', (err: Error) => resolve({ success: false, error: err.message }));
+            });
+        }
+
+        return { success: false, error: 'No search backend configured. Set BRAVE_SEARCH_API_KEY or SEARXNG_URL.' };
+    }
+
+    /**
+     * Generate the MCP tool capabilities section for system prompts
+     */
+    static getToolsPromptSection(): string {
+        return `### 🔌 MCP TOOLS (Model Context Protocol):
+You have access to the following production-level tools via MCP. Use them to navigate, read, write, and search:
+
+| Tool | Description |
+|------|-------------|
+| \`read_file(path, start_line?, end_line?)\` | Read file contents (supports line ranges) |
+| \`write_file(path, content)\` | Create or overwrite a file |
+| \`list_directory(path, recursive?)\` | List files and subdirectories |
+| \`search_files(pattern, path, include?)\` | Search for text patterns (grep) |
+| \`run_command(command, cwd?)\` | Execute a shell command |
+| \`fetch_url(url)\` | Fetch web content from a URL |
+| \`git_status(path)\` | Get git status, branch, and last commit |
+| \`web_search(query, num_results?)\` | Search the web via SearxNG/Brave |
+
+**HOW TO USE:** When you need to use a tool, output it as a shell command:
+- To read: \`head -50 path/to/file\` or \`cat path/to/file\`
+- To search: \`grep -rn "pattern" path/\`
+- To list: \`ls -la path/\` or \`find path/ -maxdepth 2\`
+- To execute: wrap in \`\`\`bash code blocks
+- To fetch URL: \`curl -s "url" | head -100\`
+
+These tools allow you to **navigate any file/directory** on the system using your own brain to decide where to go.`;
+    }
+}