@mrxkun/mcfast-mcp 4.1.14 → 4.2.0

package/README.md

@@ -29,7 +29,18 @@
 
 ---
 
-## 📦 Current Version: v4.1.10
+## 📦 Current Version: v4.2.0
+
+### What's New in v4.2.0 🎉
+- **Minor Version Release**: UI & system update for Project Bootstrapping.
+- **Configurable Bootstrap Mode**: Choose between `Local`, `Cloud`, and `Hybrid` analysis modes for new projects via Dashboard or Environment.
+- **Schema Update**: Added `bootstrap_mode` column to `user_settings`.
+
+### What's New in v4.1.18 🚀
+- **Local Project Scanner**: Zero-config bootstrap! Automatically understands project name, type, tech stack, and API routes without internet/API.
+- **Memory Compaction**: Automatic self-maintenance. Compacts old logs into `MEMORY.md` and trims archives when storage exceeds limits.
+- **100% MCP Compliance**: Fully audited stdio communication and lifecycle management (no more JSON-RPC corruption or EOF errors).
+- **Tool Enhancements**: `memory_get` now supports `type='intelligence'` and `type='compact'`.
 
 ### What's New in v4.1.10 🐛
 - **Bug Fixes**: Fixed `getCuratedMemories()` and `getIntelligenceStats()` missing methods
@@ -47,6 +58,7 @@
   - **Two-Tier Memory**: Daily logs + Curated memory
   - **Hybrid Search**: Vector 70% + BM25 30% for 90%+ accuracy
   - **File Watcher**: Auto-indexes files with debounced 1.5s delay
+  - **Local Bootstrapping**: Zero-config initial project scan logic.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrxkun/mcfast-mcp",
-  "version": "4.1.14",
+  "version": "4.2.0",
   "description": "Ultra-fast code editing with WASM acceleration, fuzzy patching, multi-layer caching, and 8 unified tools. v4.1.12: Implement proper MCP stdio transport lifecycle and cleanup to prevent zombie processes.",
   "type": "module",
   "bin": {

package/src/index.js

@@ -8,7 +8,10 @@
 // CRITICAL: Suppress ALL console output in MCP mode to prevent JSON parsing errors
 // MCP protocol requires stdout to contain ONLY JSON-RPC messages
 
-// ANSI Color Codes for Terminal Output (MUST be defined before any usage)
+import os from 'os';
+import crypto from 'crypto';
+
+// ANSI Color Codes for Terminal Output
 const colors = {
     reset: '\x1b[0m',
     bold: '\x1b[1m',
@@ -23,17 +26,11 @@ const colors = {
     bgBlack: '\x1b[40m',
 };
 
-// Override console.log - suppress in MCP mode
-const originalConsoleLog = console.log;
-console.log = function (...args) {
-    // Suppressed in MCP mode
-};
-
-// Keep console.error enabled for debugging and MCP logging
-// const originalConsoleError = console.error;
-// console.error = function(...args) {
-//     // Suppressed in MCP mode
-// };
+// MCP SPEC: stdout must contain ONLY JSON-RPC messages.
+// Redirect console.log to stderr so native module warnings (prebuild-install, etc.)
+// don't corrupt the JSON-RPC stream.
+const _origConsoleLog = console.log;
+console.log = (...args) => process.stderr.write(args.join(' ') + '\n');
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -81,8 +78,11 @@ const execAsync = promisify(exec);
 
 // ============================================================================
 // LOCK FILE MECHANISM - Prevent multiple instances running simultaneously
+// Use home directory to avoid permission issues in project root or systems where CWD is /
 // ============================================================================
-const LOCK_FILE_PATH = path.join(process.cwd(), '.mcfast', '.mcp-instance.lock');
+const LOCK_DIR = path.join(os.homedir(), '.mcfast', 'locks');
+const projectHash = crypto.createHash('md5').update(process.cwd()).digest('hex');
+const LOCK_FILE_PATH = path.join(LOCK_DIR, `${projectHash}.lock`);
 let lockFileHandle = null;
 
 async function acquireLock() {
@@ -568,13 +568,13 @@ function prettyLogResult(toolName, success, latencyMs, summary) {
 
 // Token validation moved to request handlers for better UX (prevents server crash)
 if (!TOKEN) {
-    console.error("⚠️ Warning: MCFAST_TOKEN is missing. Tools will fail until configured.");
+    console.error("⚠️  Warning: MCFAST_TOKEN is missing. Tools that call the cloud API will fail.");
 }
 
 const server = new Server(
     {
         name: "mcfast",
-        version: "1.3.0",
+        version: "4.1.15",
     },
     {
         capabilities: {
@@ -3448,86 +3448,91 @@ async function handleHealthCheck() {
 }
 
 /**
- * Start Server
+ * MCP Server Startup
+ * Following MCP spec: https://spec.modelcontextprotocol.io/specification/
+ *
+ * Lifecycle order per MCP spec:
+ *   1. Acquire lock (prevent duplicate instances)
+ *   2. Create transport
+ *   3. Register signal/error handlers
+ *   4. Start background tasks (memory engine)
+ *   5. Call server.connect(transport) — this MUST be last
+ *   6. Process remains alive via stdio loop managed by SDK
  */
 
-// Acquire lock before starting - prevents multiple instances
-const lockAcquired = await acquireLock();
-if (!lockAcquired) {
-    console.error(`${colors.red}[ERROR]${colors.reset} Failed to acquire lock. Another mcfast-mcp instance may be running.`);
-    console.error(`${colors.yellow}[HINT]${colors.reset} Delete ${LOCK_FILE_PATH} if you're sure no other instance is running.`);
-    process.exit(1);
-}
-
-const transport = new StdioServerTransport();
-
-// NOTE: Do NOT add process.stdin.on('end') handler here.
-// VSCode and some MCP clients send ephemeral EOF / half-close signals during
-// the initialize handshake, which would cause premature gracefulShutdown
-// before the server has a chance to respond, resulting in the
-// "Error: calling 'initialize': EOF" error.
-//
-// The MCP SDK's StdioServerTransport already manages transport lifecycle.
-// Only handle unrecoverable stdout errors.
-process.stdout.on('error', (err) => {
-    if (err.code === 'EPIPE' || err.code === 'ERR_STREAM_DESTROYED') {
-        console.error('[MCP] stdout closed, shutting down:', err.code);
-        gracefulShutdown('stdout.error');
-    }
-});
-
-// Pre-initialize memory engine in background
-backgroundInitializeMemoryEngine().catch(err => {
-    console.error(`${colors.yellow}[Memory]${colors.reset} Background init error: ${err.message}`);
-    // Don't exit - continue without memory
-});
-
-// Graceful shutdown handler
+// Graceful shutdown - defined BEFORE any signal handlers reference it
 async function gracefulShutdown(signal) {
-    console.error(`${colors.yellow}[Shutdown]${colors.reset} Received ${signal}, cleaning up...`);
+    // Guard: avoid re-entrant shutdown calls
+    if (gracefulShutdown._running) return;
+    gracefulShutdown._running = true;
 
-    const SHUTDOWN_TIMEOUT = 5000; // 5 seconds per MCP best practices
+    console.error(`[mcfast] Shutting down (${signal})...`);
+
+    const SHUTDOWN_TIMEOUT_MS = 5000; // MCP recommendation
 
     try {
         await Promise.race([
             (async () => {
-                // Stop memory engine
                 if (memoryEngine && memoryEngineReady) {
-                    await memoryEngine.cleanup();
+                    await memoryEngine.cleanup().catch(() => { });
                 }
-
-                // Flush audit queue
                 const auditQ = getAuditQueue();
-                await auditQ.destroy();
-
-                // Release lock
+                await auditQ.destroy().catch(() => { });
                 await releaseLock();
             })(),
-            new Promise(resolve => setTimeout(resolve, SHUTDOWN_TIMEOUT))
+            new Promise(resolve => setTimeout(resolve, SHUTDOWN_TIMEOUT_MS))
         ]);
-
-        console.error(`${colors.green}[Shutdown]${colors.reset} Cleanup complete`);
-    } catch (error) {
-        console.error(`${colors.red}[Shutdown]${colors.reset} Error during cleanup: ${error.message}`);
+        console.error('[mcfast] Shutdown complete.');
+    } catch (err) {
+        console.error('[mcfast] Error during shutdown:', err.message);
     }
 
-    // Always exit (even if cleanup fails) to prevent zombie processes
     process.exit(0);
 }
+gracefulShutdown._running = false;
 
+// Signal handlers (registered before server.connect)
 process.on('SIGINT', () => gracefulShutdown('SIGINT'));
 process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
 
-// Protect against zombie processes - handle unexpected errors
+// MCP SPEC: stdout must never receive non-JSON-RPC data.
+// Only shut down on actual unrecoverable stdout errors, NOT on stdin 'end'.
+// stdin 'end' can be a transient event during handshake in some MCP clients.
+process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE' || err.code === 'ERR_STREAM_DESTROYED') {
+        gracefulShutdown('stdout.EPIPE');
+    }
+});
+
+// Catch unhandled errors - log but DO NOT exit on every unhandled rejection
+// (memory scan errors etc. shouldn't kill the whole server)
 process.on('uncaughtException', (err) => {
-    console.error('[MCP] Uncaught exception:', err);
-    gracefulShutdown('uncaughtException');
+    console.error('[mcfast] Uncaught exception:', err.message);
+    // Only exit for truly fatal errors
+    if (err.code === 'ERR_USE_AFTER_CLOSE' || err.code === 'ERR_SERVER_DESTROYED') {
+        gracefulShutdown('uncaughtException');
+    }
 });
 
-process.on('unhandledRejection', (reason, promise) => {
-    console.error('[MCP] Unhandled rejection:', reason);
-    gracefulShutdown('unhandledRejection');
+process.on('unhandledRejection', (reason) => {
+    // Log but don't exit — background tasks (memory, scan) may reject harmlessly
+    console.error('[mcfast] Unhandled rejection:', reason?.message || reason);
 });
 
+// Acquire instance lock
+const lockAcquired = await acquireLock();
+if (!lockAcquired) {
+    console.error(`[mcfast] FATAL: Could not acquire lock. Delete ${LOCK_FILE_PATH} if no other instance is running.`);
+    process.exit(1);
+}
+
+// Start background memory initialization (non-blocking)
+backgroundInitializeMemoryEngine().catch(err => {
+    console.error('[mcfast] Memory init error (non-fatal):', err.message);
+});
+
+// Connect to MCP transport — MUST be the last startup step per MCP spec
+const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("mcfast MCP v1.0.0 running on stdio");
+
+console.error(`[mcfast] MCP server v4.1.15 ready (pid=${process.pid})`);

package/src/memory/bootstrap/project-scanner.js

@@ -0,0 +1,328 @@
+/**
+ * Local Project Scanner (Bootstrap)
+ * Tự động scan dự án mới không cần API/internet.
+ * Chạy lần đầu khi chưa có "Project Context" trong MEMORY.md
+ *
+ * Phân tích:
+ *   - package.json / pyproject.toml / Cargo.toml / go.mod / pom.xml
+ *   - README.md (nếu có)
+ *   - Cấu trúc thư mục
+ *   - Tech stack detection từ dependencies
+ *   - Entry points
+ *   - API routes (Next.js / Express / FastAPI patterns)
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+const IGNORED_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', '.next', '.nuxt',
+    '.turbo', 'coverage', '.mcfast', '__pycache__', 'target',
+    '.gradle', 'vendor', '.venv', 'venv', '.cache'
+]);
+
+export class ProjectScanner {
+    constructor(projectPath) {
+        this.projectPath = projectPath;
+    }
+
+    /**
+     * Full scan — returns a structured project overview object
+     */
+    async scan() {
+        const [
+            packageInfo,
+            readme,
+            structure,
+            entryPoints,
+            routes,
+            techStack
+        ] = await Promise.all([
+            this.readPackageFile(),
+            this.readReadme(),
+            this.buildStructure(3),
+            this.detectEntryPoints(),
+            this.detectRoutes(),
+            null // will compute after packageInfo
+        ]);
+
+        const stack = this.detectTechStack(packageInfo, structure);
+
+        return {
+            name: packageInfo?.name || path.basename(this.projectPath),
+            description: packageInfo?.description || null,
+            version: packageInfo?.version || null,
+            license: packageInfo?.license || null,
+            type: this.detectProjectType(packageInfo, structure),
+            technologies: stack,
+            entryPoints,
+            apiRoutes: routes,
+            structure,
+            readme: readme ? readme.substring(0, 1500) : null,  // cap size
+            generatedAt: new Date().toISOString()
+        };
+    }
+
+    /**
+     * Read main package descriptor (package.json, pyproject.toml, etc.)
+     */
+    async readPackageFile() {
+        // Node.js
+        try {
+            const content = await fs.readFile(
+                path.join(this.projectPath, 'package.json'), 'utf-8'
+            );
+            return JSON.parse(content);
+        } catch { }
+
+        // Try workspace root if monorepo
+        try {
+            const entries = await fs.readdir(this.projectPath, { withFileTypes: true });
+            const pkgDirs = entries.filter(e => e.isDirectory() && !IGNORED_DIRS.has(e.name));
+            for (const dir of pkgDirs.slice(0, 5)) {
+                try {
+                    const content = await fs.readFile(
+                        path.join(this.projectPath, dir.name, 'package.json'), 'utf-8'
+                    );
+                    return JSON.parse(content); // return first found
+                } catch { }
+            }
+        } catch { }
+
+        return null;
+    }
+
+    /**
+     * Read README file
+     */
+    async readReadme() {
+        const candidates = ['README.md', 'Readme.md', 'readme.md', 'README.txt'];
+        for (const name of candidates) {
+            try {
+                return await fs.readFile(path.join(this.projectPath, name), 'utf-8');
+            } catch { }
+        }
+        return null;
+    }
+
+    /**
+     * Build directory structure tree
+     */
+    async buildStructure(maxDepth = 3, dir = this.projectPath, depth = 0, prefix = '') {
+        if (depth >= maxDepth) return '';
+        const lines = [];
+        try {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            const filtered = entries
+                .filter(e => !IGNORED_DIRS.has(e.name) && !e.name.startsWith('.'))
+                .sort((a, b) => {
+                    if (a.isDirectory() && !b.isDirectory()) return -1;
+                    if (!a.isDirectory() && b.isDirectory()) return 1;
+                    return a.name.localeCompare(b.name);
+                })
+                .slice(0, 20); // limit entries per dir
+
+            for (let i = 0; i < filtered.length; i++) {
+                const e = filtered[i];
+                const isLast = i === filtered.length - 1;
+                lines.push(prefix + (isLast ? '└── ' : '├── ') + e.name + (e.isDirectory() ? '/' : ''));
+                if (e.isDirectory()) {
+                    const sub = await this.buildStructure(
+                        maxDepth,
+                        path.join(dir, e.name),
+                        depth + 1,
+                        prefix + (isLast ? '    ' : '│   ')
+                    );
+                    if (sub) lines.push(sub);
+                }
+            }
+        } catch { }
+        return lines.join('\n');
+    }
+
+    /**
+     * Detect entry points
+     */
+    async detectEntryPoints() {
+        const candidates = [
+            'src/index.ts', 'src/index.js', 'src/main.ts', 'src/main.js',
+            'src/app.ts', 'src/app.js', 'index.ts', 'index.js',
+            'server.ts', 'server.js', 'main.py', 'app.py', 'main.go',
+            'app/layout.tsx', 'app/page.tsx', 'pages/index.tsx', 'pages/index.js'
+        ];
+        const found = [];
+        for (const f of candidates) {
+            try {
+                await fs.access(path.join(this.projectPath, f));
+                found.push(f);
+            } catch { }
+        }
+        return found;
+    }
+
+    /**
+     * Detect API routes (Next.js App Router, Pages Router, Express)
+     */
+    async detectRoutes() {
+        const routes = [];
+
+        // Next.js App Router: app/api/**/route.ts
+        const appApiDir = path.join(this.projectPath, 'app', 'api');
+        const appRoutes = await this.scanRouteDir(appApiDir, 'app/api');
+        routes.push(...appRoutes);
+
+        // Next.js Pages Router: pages/api/**
+        const pagesApiDir = path.join(this.projectPath, 'pages', 'api');
+        const pagesRoutes = await this.scanRouteDir(pagesApiDir, 'pages/api');
+        routes.push(...pagesRoutes);
+
+        // src/routes (Express-style)
+        const srcRoutesDir = path.join(this.projectPath, 'src', 'routes');
+        const srcRoutes = await this.scanRouteDir(srcRoutesDir, 'src/routes');
+        routes.push(...srcRoutes);
+
+        return routes.slice(0, 30);
+    }
+
+    async scanRouteDir(dir, prefix) {
+        const routes = [];
+        try {
+            const walk = async (d, rel) => {
+                const entries = await fs.readdir(d, { withFileTypes: true }).catch(() => []);
+                for (const e of entries) {
+                    if (e.isDirectory()) {
+                        await walk(path.join(d, e.name), `${rel}/${e.name}`);
+                    } else if (/\.(ts|js)$/.test(e.name)) {
+                        routes.push(`${rel}/${e.name}`);
+                    }
+                }
+            };
+            await walk(dir, prefix);
+        } catch { }
+        return routes;
+    }
+
+    /**
+     * Detect tech stack from package.json dependencies
+     */
+    detectTechStack(packageJson, structure) {
+        const stack = {
+            languages: [],
+            frameworks: [],
+            databases: [],
+            testing: [],
+            tools: []
+        };
+
+        const deps = {
+            ...(packageJson?.dependencies || {}),
+            ...(packageJson?.devDependencies || {})
+        };
+        const depNames = Object.keys(deps);
+
+        // Languages
+        if (depNames.some(d => d === 'typescript' || d === 'ts-node')) stack.languages.push('TypeScript');
+        if (packageJson) stack.languages.push('JavaScript');
+        if (structure?.includes('main.py') || structure?.includes('app.py')) stack.languages.push('Python');
+        if (structure?.includes('main.go')) stack.languages.push('Go');
+        if (structure?.includes('Cargo.toml')) stack.languages.push('Rust');
+
+        // Frameworks
+        if (depNames.includes('next')) stack.frameworks.push('Next.js');
+        if (depNames.includes('react')) stack.frameworks.push('React');
+        if (depNames.includes('vue')) stack.frameworks.push('Vue.js');
+        if (depNames.includes('express')) stack.frameworks.push('Express');
+        if (depNames.includes('fastify')) stack.frameworks.push('Fastify');
+        if (depNames.includes('hono')) stack.frameworks.push('Hono');
+        if (depNames.includes('nuxt')) stack.frameworks.push('Nuxt');
+        if (depNames.includes('svelte')) stack.frameworks.push('Svelte');
+        if (depNames.includes('electron')) stack.frameworks.push('Electron');
+
+        // Databases
+        if (depNames.some(d => /pg|postgres|postgresql/.test(d))) stack.databases.push('PostgreSQL');
+        if (depNames.some(d => /mysql|mysql2/.test(d))) stack.databases.push('MySQL');
+        if (depNames.includes('better-sqlite3') || depNames.includes('sqlite3')) stack.databases.push('SQLite');
+        if (depNames.some(d => /mongoose|mongodb/.test(d))) stack.databases.push('MongoDB');
+        if (depNames.some(d => /redis|ioredis/.test(d))) stack.databases.push('Redis');
+        if (depNames.includes('prisma') || depNames.includes('@prisma/client')) stack.databases.push('Prisma ORM');
+        if (depNames.includes('drizzle-orm')) stack.databases.push('Drizzle ORM');
+
+        // Testing
+        if (depNames.includes('jest') || depNames.includes('@jest/core')) stack.testing.push('Jest');
+        if (depNames.includes('vitest')) stack.testing.push('Vitest');
+        if (depNames.includes('playwright') || depNames.includes('@playwright/test')) stack.testing.push('Playwright');
+        if (depNames.includes('cypress')) stack.testing.push('Cypress');
+
+        // Tools
+        if (depNames.includes('turbo') || structure?.includes('turbo.json')) stack.tools.push('Turborepo');
+        if (depNames.includes('vite')) stack.tools.push('Vite');
+        if (depNames.includes('webpack')) stack.tools.push('Webpack');
+        if (structure?.includes('docker-compose')) stack.tools.push('Docker');
+
+        return stack;
+    }
+
+    /**
+     * Detect project type
+     */
+    detectProjectType(packageJson, structure) {
+        if (structure?.includes('app/page.tsx') || structure?.includes('app/layout.tsx')) return 'Next.js App';
+        if (packageJson?.dependencies?.next) return 'Next.js';
+        if (packageJson?.dependencies?.electron) return 'Electron App';
+        if (packageJson?.dependencies?.react) return 'React App';
+        if (packageJson?.dependencies?.express || packageJson?.dependencies?.fastify) return 'Node.js API';
+        if (structure?.includes('main.py')) return 'Python App';
+        if (structure?.includes('Cargo.toml')) return 'Rust Project';
+        if (structure?.includes('go.mod')) return 'Go Project';
+        const name = packageJson?.name || '';
+        if (name.includes('mcp') || name.includes('mcfast')) return 'MCP Server';
+        return 'Node.js Project';
+    }
+
+    /**
+     * Generate MEMORY.md Project Context section from scan result
+     */
+    buildMemorySection(scan) {
+        const date = new Date().toISOString().split('T')[0];
+        const lines = [
+            `<!-- Auto-generated by mcfast local scanner on ${date} -->`,
+            `- **${date}** Project: **${scan.name}**`,
+            `  - Type: ${scan.type}`,
+        ];
+
+        if (scan.description) lines.push(`  - Description: ${scan.description}`);
+        if (scan.version) lines.push(`  - Version: ${scan.version}`);
+
+        const { languages, frameworks, databases, testing, tools } = scan.technologies;
+        if (languages.length) lines.push(`  - Languages: ${[...new Set(languages)].join(', ')}`);
+        if (frameworks.length) lines.push(`  - Frameworks: ${frameworks.join(', ')}`);
+        if (databases.length) lines.push(`  - Databases: ${databases.join(', ')}`);
+        if (testing.length) lines.push(`  - Testing: ${testing.join(', ')}`);
+        if (tools.length) lines.push(`  - Tools: ${tools.join(', ')}`);
+
+        if (scan.entryPoints.length) {
+            lines.push(`  - Entry Points: ${scan.entryPoints.join(', ')}`);
+        }
+
+        if (scan.apiRoutes.length) {
+            lines.push(`  - API Routes (${scan.apiRoutes.length}): ${scan.apiRoutes.slice(0, 5).join(', ')}${scan.apiRoutes.length > 5 ? ` ...+${scan.apiRoutes.length - 5} more` : ''}`);
+        }
+
+        if (scan.readme) {
+            // Extract first paragraph of README as summary
+            const firstPara = scan.readme
+                .replace(/^#+.*\n/gm, '')
+                .replace(/!\[.*?\]\(.*?\)/g, '')
+                .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+                .split('\n\n')[0]
+                .trim();
+            if (firstPara && firstPara.length > 20) {
+                lines.push(`  - README summary: ${firstPara.substring(0, 300)}`);
+            }
+        }
+
+        return lines.join('\n');
+    }
+}
+
+export default ProjectScanner;