@everstateai/mcp 1.3.12 → 1.3.13

package/README.md

@@ -178,15 +178,38 @@ npx @everstateai/mcp --version                 # Check installed version
 This proxy is intentionally minimal. It:
 
 1. **On startup**: Auto-detects your project from `.everstate.json` or API
-2. **On tool list**: Fetches tool definitions from the Everstate API
-3. **On tool call**: Forwards the call to the Everstate API with your projectId
-4. **Returns**: Responses to Claude/Cursor/etc.
+2. **Auto-session**: First tool call auto-starts a session (no explicit `sync()` needed)
+3. **On tool list**: Fetches tool definitions from the Everstate API (5 core tools by default)
+4. **On tool call**: Forwards the call to the Everstate API with your projectId
+5. **Returns**: Responses to Claude/Cursor/etc.
 
 All business logic, tool schemas, and data operations live server-side. Benefits:
 
 - **Instant updates** - New features without npm updates
 - **Feature gating** - Tools enabled by your API key tier
 - **Security** - All authentication and metering server-side
+- **Auto-session detection** - Proxy tracks idle time, auto-syncs after 5 minutes of inactivity
+
+## Core Tools (5)
+
+| Tool | Purpose |
+|------|---------|
+| `sync` | Start session, load context (auto-called) |
+| `done` | End session with summary (auto-called on session end) |
+| `recall` | Search past sessions, decisions, gotchas |
+| `log` | Record progress, decisions, gotchas, blockers |
+| `everstate` | Meta-tool for 100+ actions via `namespace.action` |
+
+## Automatic Features
+
+These work via hooks installed during setup:
+
+| Feature | Hook | Description |
+|---------|------|-------------|
+| Auto-progress | PostToolUse (Edit/Write/Bash) | File edits and commands logged automatically |
+| Gotcha warnings | PreToolUse (Edit/Write) | Relevant gotchas surface before editing flagged files |
+| Task sync | PostToolUse (TodoWrite) | TodoWrite list syncs with dashboard |
+| Auto-done | Stop/SessionEnd | Session auto-saved when conversation ends |
 
 ## Troubleshooting
 

package/dist/index.js

@@ -135,6 +135,22 @@ async function runMcpServer() {
     const INITIAL_PROJECT_ID = process.env.EVERSTATE_PROJECT_ID;
     // Session state - persists projectId across tool calls within this proxy instance
     let sessionProjectId = INITIAL_PROJECT_ID;
+    // Auto-session state: track last tool call time and whether sync has been called
+    let lastToolCallTime = 0;
+    let sessionSynced = false;
+    const AUTO_SYNC_IDLE_MS = 5 * 60 * 1000; // 5 minutes
+    // Context window tracking
+    // Claude's context window is ~200K tokens (~800K chars).
+    // We track cumulative MCP response sizes as a proxy for context growth.
+    // MCP responses are typically the largest context consumers since user messages
+    // and Claude's own output are smaller relative to tool results.
+    const CONTEXT_WINDOW_CHARS = 800_000; // ~200K tokens * 4 chars/token
+    const CONTEXT_WARNING_THRESHOLD = 0.75; // 75%
+    const CONTEXT_CRITICAL_THRESHOLD = 0.90; // 90%
+    let cumulativeResponseChars = 0;
+    let toolCallCount = 0;
+    let contextWarningIssued = false;
+    let contextCriticalIssued = false;
     if (!API_KEY) {
         console.error("EVERSTATE_API_KEY environment variable is required");
         console.error("");
@@ -199,6 +215,236 @@ async function runMcpServer() {
             console.error("[Everstate] Could not auto-detect project:", error);
         }
     }
+    function readBatchConfig() {
+        let dir = process.cwd();
+        const root = path.parse(dir).root;
+        while (dir !== root) {
+            const configPath = path.join(dir, ".everstate.json");
+            if (fs.existsSync(configPath)) {
+                try {
+                    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+                    if (config.batchSync) {
+                        const interval = config.batchSync.intervalSeconds ?? 30;
+                        const MAX_INTERVAL = 300; // 5 minutes max — prevents stale data loss on crash
+                        return {
+                            enabled: config.batchSync.enabled ?? false,
+                            intervalSeconds: Math.min(Math.max(interval, 5), MAX_INTERVAL),
+                        };
+                    }
+                }
+                catch { /* continue */ }
+            }
+            dir = path.dirname(dir);
+        }
+        return { enabled: false, intervalSeconds: 30 };
+    }
+    const batchConfig = readBatchConfig();
+    const BUFFER_DIR = path.join(process.cwd(), ".claude");
+    const BUFFER_PATH = path.join(BUFFER_DIR, ".batch-buffer.json");
+    const MAX_RETRIES = 3;
+    const MAX_BUFFER_SIZE = 200;
+    const BUFFER_STALE_MS = 60 * 60 * 1000; // 1 hour
+    function emptyBuffer() {
+        return { version: 1, lastFlushAt: null, lastFlushResult: null, entries: [], failed: [] };
+    }
+    function readBuffer() {
+        try {
+            if (fs.existsSync(BUFFER_PATH)) {
+                const buf = JSON.parse(fs.readFileSync(BUFFER_PATH, "utf8"));
+                // Discard stale entries on startup
+                const cutoff = Date.now() - BUFFER_STALE_MS;
+                buf.entries = buf.entries.filter(e => new Date(e.queuedAt).getTime() > cutoff);
+                buf.failed = (buf.failed || []).slice(-50);
+                return buf;
+            }
+        }
+        catch { /* corrupted file, start fresh */ }
+        return emptyBuffer();
+    }
+    function writeBuffer(buffer) {
+        try {
+            if (!fs.existsSync(BUFFER_DIR))
+                fs.mkdirSync(BUFFER_DIR, { recursive: true });
+            const tmpPath = BUFFER_PATH + ".tmp";
+            fs.writeFileSync(tmpPath, JSON.stringify(buffer, null, 2));
+            fs.renameSync(tmpPath, BUFFER_PATH);
+        }
+        catch (err) {
+            console.error("[Everstate] Failed to write buffer:", err);
+        }
+    }
+    function addToBuffer(toolName, args) {
+        const buffer = readBuffer();
+        if (buffer.entries.length >= MAX_BUFFER_SIZE) {
+            // Drop oldest entries
+            const dropped = buffer.entries.splice(0, buffer.entries.length - MAX_BUFFER_SIZE + 1);
+            console.error(`[Everstate] Buffer full, dropped ${dropped.length} oldest entries`);
+        }
+        buffer.entries.push({
+            id: `buf_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+            queuedAt: new Date().toISOString(),
+            toolName,
+            arguments: args,
+            retryCount: 0,
+        });
+        writeBuffer(buffer);
+    }
+    // Tools that MUST execute immediately (return data the agent needs)
+    const IMMEDIATE_TOOLS = new Set([
+        "sync", "done", "recall", "status",
+        "ask_user", "check_user_response",
+        "everstate_list_projects", "everstate_switch_project", "everstate_current_project",
+        "list_projects", "switch_project", "current_project",
+    ]);
+    // Meta-tool action prefixes that must execute immediately (reads/interactive)
+    const IMMEDIATE_META_PREFIXES = [
+        "help", "session.", "search.", "context.", "heal.", "quality.",
+        "google.", "inbound.", "files.", "git.", "team.",
+        "work.get_", "work.list_", "work.search_", "work.get_portfolio",
+        "decisions.list", "decisions.get",
+        "gotchas.list", "gotchas.get",
+        "admin.get_", "admin.list_", "admin.check_", "admin.validate_", "admin.export_",
+        "project.", "progress.list", "progress.get",
+    ];
+    function isBatchable(toolName, args) {
+        if (IMMEDIATE_TOOLS.has(toolName))
+            return false;
+        if (toolName === "everstate") {
+            const action = args.action || "";
+            for (const prefix of IMMEDIATE_META_PREFIXES) {
+                if (action === prefix || action.startsWith(prefix))
+                    return false;
+            }
+            return true;
+        }
+        // Core tools: log is batchable, everything else is immediate by default
+        if (toolName === "log")
+            return true;
+        return false;
+    }
+    function generateSyntheticResponse(toolName, args) {
+        if (toolName === "log") {
+            const msg = args.message || "";
+            const type = args.type || "progress";
+            const labels = {
+                achievement: "Achievement logged",
+                progress: "Progress recorded",
+                note: "Note saved",
+                warning: "Warning recorded",
+            };
+            return `${labels[type] || "Logged"} (queued for sync): ${msg.substring(0, 120)}${msg.length > 120 ? "..." : ""}`;
+        }
+        if (toolName === "everstate") {
+            const action = args.action || "";
+            return `Queued for sync: ${action}`;
+        }
+        return `Queued for sync: ${toolName}`;
+    }
+    async function flushBuffer() {
+        const buffer = readBuffer();
+        if (buffer.entries.length === 0)
+            return;
+        const count = buffer.entries.length;
+        console.error(`[Everstate] Flushing ${count} buffered items...`);
+        let success = 0;
+        let failed = 0;
+        const remaining = [];
+        const failedEntries = [...(buffer.failed || [])];
+        // Try batch endpoint first
+        try {
+            const res = await fetch(`${API_BASE}/mcp/batch-execute`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${API_KEY}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    calls: buffer.entries.map(e => ({
+                        name: e.toolName,
+                        arguments: e.arguments,
+                    })),
+                }),
+            });
+            if (res.ok) {
+                success = count;
+            }
+            else if (res.status === 404) {
+                // Batch endpoint not deployed yet — fall back to individual calls
+                for (const entry of buffer.entries) {
+                    try {
+                        const r = await fetch(`${API_BASE}/mcp/execute`, {
+                            method: "POST",
+                            headers: {
+                                Authorization: `Bearer ${API_KEY}`,
+                                "Content-Type": "application/json",
+                            },
+                            body: JSON.stringify({
+                                name: entry.toolName,
+                                arguments: entry.arguments,
+                            }),
+                        });
+                        if (r.ok) {
+                            success++;
+                        }
+                        else {
+                            entry.retryCount++;
+                            if (entry.retryCount >= MAX_RETRIES) {
+                                failedEntries.push(entry);
+                                failed++;
+                            }
+                            else {
+                                remaining.push(entry);
+                            }
+                        }
+                    }
+                    catch {
+                        entry.retryCount++;
+                        if (entry.retryCount >= MAX_RETRIES) {
+                            failedEntries.push(entry);
+                            failed++;
+                        }
+                        else {
+                            remaining.push(entry);
+                        }
+                    }
+                }
+            }
+            else {
+                // Server error — keep all entries for retry
+                for (const entry of buffer.entries) {
+                    entry.retryCount++;
+                    if (entry.retryCount >= MAX_RETRIES) {
+                        failedEntries.push(entry);
+                        failed++;
+                    }
+                    else {
+                        remaining.push(entry);
+                    }
+                }
+            }
+        }
+        catch {
+            // Network error — keep all entries for retry
+            for (const entry of buffer.entries) {
+                entry.retryCount++;
+                if (entry.retryCount >= MAX_RETRIES) {
+                    failedEntries.push(entry);
+                    failed++;
+                }
+                else {
+                    remaining.push(entry);
+                }
+            }
+        }
+        buffer.entries = remaining;
+        buffer.failed = failedEntries.slice(-50);
+        buffer.lastFlushAt = new Date().toISOString();
+        buffer.lastFlushResult = { success, failed };
+        writeBuffer(buffer);
+        if (success > 0 || failed > 0) {
+            console.error(`[Everstate] Flush: ${success} sent, ${failed} failed, ${remaining.length} retrying`);
+        }
+    }
     // Create MCP server
     const server = new Server({ name: "everstate", version: "1.3.0" }, { capabilities: { tools: {} } });
     // Fetch tool definitions from cloud
@@ -228,6 +474,54 @@ async function runMcpServer() {
         if (sessionProjectId && !enrichedArgs.projectId && !hasProjectIdInParams) {
             enrichedArgs.projectId = sessionProjectId;
         }
+        // Auto-session: trigger sync if this is the first tool call or idle > 5 minutes
+        const now = Date.now();
+        const isIdle = lastToolCallTime > 0 && (now - lastToolCallTime) > AUTO_SYNC_IDLE_MS;
+        const needsSync = !sessionSynced || isIdle;
+        const isSyncCall = name === "sync" || name === "done";
+        // Flush buffer before auto-sync (idle means buffered items are sitting stale)
+        if (needsSync && isIdle && batchConfig.enabled) {
+            await flushBuffer();
+        }
+        if (needsSync && !isSyncCall && sessionProjectId) {
+            try {
+                console.error(`[Everstate] Auto-sync: ${!sessionSynced ? 'first tool call' : 'idle > 5min'}`);
+                await fetch(`${API_BASE}/mcp/execute`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${API_KEY}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        name: "sync",
+                        arguments: { projectId: sessionProjectId, mode: "minimal" },
+                    }),
+                });
+                sessionSynced = true;
+            }
+            catch {
+                // Non-critical: don't block tool call if auto-sync fails
+                console.error("[Everstate] Auto-sync failed, continuing...");
+            }
+        }
+        if (isSyncCall) {
+            sessionSynced = true;
+        }
+        lastToolCallTime = now;
+        // Force-flush buffer before done() so session summary reflects all progress
+        if (name === "done" && batchConfig.enabled) {
+            await flushBuffer();
+        }
+        // Batch sync: buffer batchable write operations instead of calling API immediately
+        if (batchConfig.enabled && isBatchable(name, enrichedArgs)) {
+            const syntheticResponse = generateSyntheticResponse(name, enrichedArgs);
+            addToBuffer(name, enrichedArgs);
+            const bufSize = readBuffer().entries.length;
+            console.error(`[Everstate] Batched: ${name} (buffer: ${bufSize} items)`);
+            return {
+                content: [{ type: "text", text: syntheticResponse }],
+            };
+        }
         const res = await fetch(`${API_BASE}/mcp/execute`, {
             method: "POST",
             headers: {
@@ -237,12 +531,84 @@ async function runMcpServer() {
             body: JSON.stringify({ name, arguments: enrichedArgs }),
         });
         if (!res.ok) {
+            // Read the response body for the actual error message
+            let errorDetail = `${res.status} ${res.statusText}`;
+            try {
+                const errorBody = await res.json();
+                const msg = errorBody?.content?.[0]?.text;
+                if (msg)
+                    errorDetail = msg;
+            }
+            catch {
+                // Body not JSON, use status text
+            }
             return {
-                content: [{ type: "text", text: `API error: ${res.status} ${res.statusText}` }],
+                content: [{ type: "text", text: errorDetail }],
                 isError: true,
             };
         }
         const result = (await res.json());
+        // Track context growth from MCP responses
+        toolCallCount++;
+        const responseText = result.content?.map((c) => c.text || '').join('') || '';
+        cumulativeResponseChars += responseText.length;
+        // Also count the request args as they're in context too
+        const requestChars = JSON.stringify(enrichedArgs).length;
+        cumulativeResponseChars += requestChars;
+        const contextUsage = cumulativeResponseChars / CONTEXT_WINDOW_CHARS;
+        const contextPercent = Math.round(contextUsage * 100);
+        // Force-flush buffer when context is running low — session may end abruptly
+        if (contextUsage >= CONTEXT_WARNING_THRESHOLD && batchConfig.enabled) {
+            flushBuffer().catch(() => { }); // Non-blocking
+        }
+        // Append context warning to tool response
+        if (contextUsage >= CONTEXT_CRITICAL_THRESHOLD && !contextCriticalIssued) {
+            contextCriticalIssued = true;
+            const warning = `\n\n---\n` +
+                `**CONTEXT CRITICAL (${contextPercent}% estimated usage)**\n\n` +
+                `This session's context window is nearly full. You should:\n` +
+                `1. Call \`done\` with a detailed summary and next steps\n` +
+                `2. Tell the user to start a new session — Everstate will restore context automatically\n\n` +
+                `Continuing will lead to context compaction which loses conversation detail.\n` +
+                `---`;
+            if (result.content?.[0]?.text) {
+                result.content[0].text += warning;
+            }
+        }
+        else if (contextUsage >= CONTEXT_WARNING_THRESHOLD && !contextWarningIssued) {
+            contextWarningIssued = true;
+            const warning = `\n\n---\n` +
+                `**CONTEXT WARNING (${contextPercent}% estimated usage)**\n\n` +
+                `This session is consuming context quickly (~${toolCallCount} tool calls, ~${Math.round(cumulativeResponseChars / 4000)}K tokens estimated).\n` +
+                `Consider wrapping up soon. When ready:\n` +
+                `1. Call \`done\` with a summary of what was accomplished and what's next\n` +
+                `2. Suggest the user start a new session — Everstate will pick up where you left off\n` +
+                `---`;
+            if (result.content?.[0]?.text) {
+                result.content[0].text += warning;
+            }
+            // Log the warning to Everstate for analytics
+            try {
+                await fetch(`${API_BASE}/mcp/execute`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${API_KEY}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        name: "log",
+                        arguments: {
+                            projectId: sessionProjectId,
+                            type: "warning",
+                            message: `Context window at ${contextPercent}% estimated usage after ${toolCallCount} tool calls (~${Math.round(cumulativeResponseChars / 4)} tokens in MCP responses)`,
+                        },
+                    }),
+                });
+            }
+            catch {
+                // Non-critical
+            }
+        }
         // Update session state based on tool results
         if (name === "switch_project" || name === "everstate_switch_project") {
             const data = result.data || result.project;
@@ -258,20 +624,52 @@ async function runMcpServer() {
         // For sync calls, check for npm package updates and prepend notice
         if (name === "sync" && result.content?.[0]?.text) {
             try {
-                const latestVersion = await checkNpmVersion();
-                if (latestVersion) {
+                const versionInfo = await checkNpmVersion();
+                if (versionInfo) {
                     const { getMcpProxyVersion: getVersion } = await import("./setup/version.js");
                     const currentVersion = getVersion();
-                    if (currentVersion !== "0.0.0" && latestVersion !== currentVersion && compareVersionStrings(currentVersion, latestVersion) < 0) {
-                        const updateNotice = `> **Update available:** @everstateai/mcp ${currentVersion} → ${latestVersion}\n` +
-                            `> Run \`npx @everstateai/mcp update-all\` to update.\n\n`;
+                    if (currentVersion !== "0.0.0" && versionInfo.version !== currentVersion && compareVersionStrings(currentVersion, versionInfo.version) < 0) {
+                        // Build update notice with optional changelog
+                        let updateNotice = `> **Update available:** @everstateai/mcp ${currentVersion} → ${versionInfo.version}\n`;
+                        if (versionInfo.changelog) {
+                            updateNotice += `> _What's new: ${versionInfo.changelog}_\n`;
+                        }
+                        updateNotice += `> Auto-updating in background... (disable with \`everstate({ action: "admin.settings", params: { autoUpdate: false } })\`)\n\n`;
                         result.content[0].text = updateNotice + result.content[0].text;
+                        // Trigger auto-update in background (non-blocking)
+                        autoUpdateNpmPackage(versionInfo.version).catch(() => { });
                     }
                 }
             }
             catch {
                 // Non-critical, continue without update notice
             }
+            // Check for MEMORY.md coexistence and add note if found
+            try {
+                const fs = await import('fs');
+                const path = await import('path');
+                const projectDir = process.cwd();
+                const memoryPaths = [
+                    path.join(projectDir, 'MEMORY.md'),
+                    path.join(projectDir, '.claude', 'MEMORY.md'),
+                ];
+                const hasMemoryMd = memoryPaths.some(p => fs.existsSync(p));
+                if (hasMemoryMd && result.content?.[0]?.text) {
+                    const memoryNote = `> **Note:** MEMORY.md detected. MEMORY.md = your personal notes (local). Everstate = shared project memory (cloud, cross-tool). They complement each other.\n\n`;
+                    // Insert after any update notice but before the main content
+                    const text = result.content[0].text;
+                    const headerMatch = text.match(/^(# Everstate Session Sync\n\n)/);
+                    if (headerMatch) {
+                        result.content[0].text = headerMatch[1] + memoryNote + text.slice(headerMatch[1].length);
+                    }
+                    else {
+                        result.content[0].text = memoryNote + text;
+                    }
+                }
+            }
+            catch {
+                // Non-critical
+            }
         }
         return result;
     });
@@ -286,15 +684,27 @@ async function runMcpServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("Everstate MCP Proxy connected to", API_BASE);
+    // Start batch sync flush timer if enabled
+    if (batchConfig.enabled) {
+        console.error(`[Everstate] Batch sync: ON (flush every ${batchConfig.intervalSeconds}s)`);
+        setInterval(async () => {
+            try {
+                await flushBuffer();
+            }
+            catch (err) {
+                console.error("[Everstate] Flush error:", err);
+            }
+        }, batchConfig.intervalSeconds * 1000);
+    }
 }
-// Cache npm version check (once per MCP server lifetime, max every 4 hours)
-let cachedLatestVersion = null;
+let cachedVersionInfo = null;
 let lastNpmCheck = 0;
 const NPM_CHECK_INTERVAL = 4 * 60 * 60 * 1000; // 4 hours
+let autoUpdateInProgress = false;
 async function checkNpmVersion() {
     const now = Date.now();
-    if (cachedLatestVersion && now - lastNpmCheck < NPM_CHECK_INTERVAL) {
-        return cachedLatestVersion;
+    if (cachedVersionInfo && now - lastNpmCheck < NPM_CHECK_INTERVAL) {
+        return cachedVersionInfo;
     }
     try {
         const controller = new AbortController();
@@ -306,9 +716,9 @@ async function checkNpmVersion() {
         if (res.ok) {
             const data = (await res.json());
             if (data.version) {
-                cachedLatestVersion = data.version;
+                cachedVersionInfo = { version: data.version, changelog: data.changelog };
                 lastNpmCheck = now;
-                return data.version;
+                return cachedVersionInfo;
             }
         }
     }
@@ -317,6 +727,46 @@ async function checkNpmVersion() {
     }
     return null;
 }
+/**
+ * Auto-update the npm package if enabled and a new version is available.
+ * This runs in the background and doesn't block tool calls.
+ */
+async function autoUpdateNpmPackage(latestVersion) {
+    if (autoUpdateInProgress)
+        return;
+    // Check if auto-update is disabled
+    const fs = await import('fs');
+    const path = await import('path');
+    const settingsPath = path.join(process.env.HOME || '', '.everstate', 'settings.json');
+    try {
+        if (fs.existsSync(settingsPath)) {
+            const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+            if (settings.autoUpdate === false) {
+                return; // User has disabled auto-updates
+            }
+        }
+    }
+    catch {
+        // If we can't read settings, proceed with auto-update
+    }
+    autoUpdateInProgress = true;
+    console.error(`[Everstate] Auto-updating to v${latestVersion}...`);
+    try {
+        const { execSync } = await import('child_process');
+        // Use npm to update the package globally or locally depending on how it's installed
+        execSync('npm install -g @everstateai/mcp@latest', {
+            stdio: 'pipe',
+            timeout: 60000, // 1 minute timeout
+        });
+        console.error(`[Everstate] Successfully updated to v${latestVersion}. Restart your AI tool to use the new version.`);
+    }
+    catch (error) {
+        console.error(`[Everstate] Auto-update failed: ${String(error)}. Run 'npx @everstateai/mcp update-all' manually.`);
+    }
+    finally {
+        autoUpdateInProgress = false;
+    }
+}
 function compareVersionStrings(a, b) {
     const aParts = a.split(".").map(Number);
     const bParts = b.split(".").map(Number);