@cachly-dev/mcp-server 0.10.124 → 0.10.126

package/dist/src/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { jwtExpiryMs, checkJwt, handleApiError, diagnoseAuth, planAuthHeal, readClientCredentialsFromEnv, buildClientCredentialsBody, clientCredentialsTokenUrl } from './auth.js';
 import { cachlyUrl } from './cachly-url.js';
+import { nutzungsSchluessel } from './werkzeug-nutzung.js';
+import { istLieferung, lieferSchluessel, tokenDerAntwort, hatTreffer, trefferSchluessel } from './geliefert.js';
 import { notify } from './notifier.js';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
@@ -47,7 +49,7 @@ const _isMain = process.argv[1] != null &&
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ErrorCode, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { Redis } from 'ioredis';
 // ── Config ────────────────────────────────────────────────────────────────────
 // Mutable so the `setup`/`init` CLI can honor a `--api-url` flag for self-hosting.
@@ -593,6 +595,28 @@ export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp,
 // ── Connection pool ───────────────────────────────────────────────────────────
 /** Reuse Redis connections across tool calls (keyed by instance_id). */
 const pool = new Map();
+/**
+ * Reconnect exactly ONCE, then give up.
+ *
+ * The old policy was `retryStrategy: () => null` — fail fast, never reconnect.
+ * Measured cost of that policy (2026-08-16, one working session): the FIRST
+ * brain call after every idle stretch died with "Connection is closed", the
+ * retyped second call worked. Five times in one day, every time the same
+ * shape. Cause: the pooled socket goes half-open while idle (NAT/LB drops the
+ * TCP session silently); the next command writes into a dead pipe, and with
+ * reconnects disabled the error goes straight to the user instead of into one
+ * quick reconnect.
+ *
+ * One retry after 200 ms heals exactly that case. Anything beyond one attempt
+ * still fails fast — the "no reconnect loops in MCP context" concern the old
+ * policy protected stays protected: a genuinely down instance costs one extra
+ * 200 ms attempt, not a loop.
+ *
+ * Exported for the test that pins this behaviour down.
+ */
+export function reconnectOnce(times) {
+    return times <= 1 ? 200 : null;
+}
 async function getConnection(instance_id) {
     if (!instance_id) {
         // With auto-provisioning, this only happens when the API was briefly
@@ -680,7 +704,11 @@ async function getConnection(instance_id) {
         lazyConnect: true,
         enableReadyCheck: true,
         connectTimeout: 8000,
-        retryStrategy: () => null, // fail fast, no reconnect loops in MCP context
+        retryStrategy: reconnectOnce,
+        // One in-flight command survives exactly one reconnect (see reconnectOnce).
+        maxRetriesPerRequest: 1,
+        // Detect half-open sockets while idle instead of at the next command.
+        keepAlive: 15000,
     });
     // Drop the client from the pool AND close its socket on error/end, so a
     // mid-session Redis drop doesn't leak sockets across reconnects. disconnect()
@@ -768,7 +796,7 @@ import { appendLedgerEntry, readLedger, defaultLedgerPath } from './ambient-ledg
 import { loadAmbientMemory, saveAmbientMemory } from './ambient-memory.js';
 import { buildAmbientDeps } from './ambient-deps.js';
 import { resolveApiKey, saveApiKey } from './credentials.js';
-import { buildLessonsMarkdown, buildLessonsJsonl } from './brain-export.js';
+import { buildLessonsMarkdown, buildLessonsJsonl, vonRohLektion } from './brain-export.js';
 import { detectEditor as detectEditorImpl } from './editor.js';
 import { milestoneSent, markMilestoneSent } from './funnel-milestones.js';
 import { kostprobeUebrig, kostprobeVerbrauchen, kostprobeHinweis, schrankeNachKostproben, } from './kostprobe.js';
@@ -949,6 +977,49 @@ async function featureGate(name, instanceId) {
     }
     return { sperre: schrankeNachKostproben(name, pitch, UPGRADE_URL_FG) };
 }
+/**
+ * Einen Werkzeug-Aufruf zaehlen (GROW-046).
+ *
+ * Ein Hash je Brain, ein Feld je Werkzeugname. Gelesen wird das in
+ * `brain_metrics` — bewusst KEIN eigenes Werkzeug dafuer: ein 123. Werkzeug,
+ * um zu messen, dass es zu viele Werkzeuge gibt, waere die Pointe, die
+ * niemand will.
+ *
+ * Jeder Fehler wird geschluckt. Eine Messung, die den gemessenen Vorgang
+ * stoert, misst am Ende sich selbst.
+ */
+async function zaehleWerkzeug(instanceId, name) {
+    try {
+        const redis = await getConnection(instanceId);
+        await redis.hincrby(nutzungsSchluessel(instanceId), name, 1);
+    }
+    catch {
+        // still — siehe oben
+    }
+}
+/**
+ * Wie viel kam aus dem Gedaechtnis? — gezaehlt an der EINEN Stelle, durch die
+ * jede Antwort geht.
+ *
+ * Drei Zahlen, alle drei Summen: gelieferte Token, Abrufe, Abrufe mit Treffer.
+ * Keine davon braucht eine Annahme. Fire-and-forget wie die Werkzeugzaehlung —
+ * eine Statistik darf eine Antwort nie verzoegern und nie scheitern lassen.
+ */
+async function zaehleLieferung(instanceId, name, antwort) {
+    if (!istLieferung(name))
+        return;
+    try {
+        const redis = await getConnection(instanceId);
+        const treffer = hatTreffer(antwort);
+        await redis.incrby(lieferSchluessel(instanceId), treffer ? tokenDerAntwort(antwort) : 0);
+        await redis.hincrby(trefferSchluessel(instanceId), 'abrufe', 1);
+        if (treffer)
+            await redis.hincrby(trefferSchluessel(instanceId), 'treffer', 1);
+    }
+    catch {
+        // still — siehe oben
+    }
+}
 async function handleTool(name, args) {
     // Guard: if no JWT, return actionable onboarding message instead of HTTP 401
     if (!JWT) {
@@ -1034,9 +1105,32 @@ async function handleTool(name, args) {
         kostprobeHinweisText = gate.kostprobe;
         sendFunnelEvent('premium_taste_used', { tool: name, instance_id: args.instance_id ?? '' });
     }
+    /*
+     * GROW-046: Erst messen, dann zusammenlegen.
+     *
+     * Die Glama-Bewertung sagt, cachly habe zu viele Werkzeuge. Der Einwand ist
+     * plausibel — nur konnte ihm niemand mit Zahlen begegnen, weil nirgends
+     * gezaehlt wurde, welches Werkzeug wie oft laeuft. Ohne diese Zahl streicht
+     * man das, was man SELBST selten benutzt, und das ist selten dasselbe wie
+     * das, was die Nutzer selten benutzen.
+     *
+     * Gezaehlt wird NACH dem Tarif-Gate: ein abgewiesener Aufruf ist kein
+     * Gebrauch, sondern ein verhinderter. Wer beides zusammenzaehlt, haelt
+     * gesperrte Werkzeuge faelschlich fuer beliebt.
+     *
+     * Fire-and-forget: eine Zaehlung darf einen Aufruf nie verzoegern und nie
+     * scheitern lassen.
+     */
+    if (typeof args.instance_id === 'string' && args.instance_id) {
+        void zaehleWerkzeug(args.instance_id, name);
+    }
     // Delegate brain tools (learn, recall, session, etc.)
     const brainResult = await handleBrainTool(name, args, getConnection, apiFetch);
     if (brainResult !== null) {
+        // Erst hier steht die Antwort fest — vorher gibt es nichts zu zaehlen.
+        if (typeof args.instance_id === 'string' && args.instance_id) {
+            void zaehleLieferung(args.instance_id, name, String(brainResult ?? ''));
+        }
         if (!_firstCallSuccessSent && JWT) {
             _firstCallSuccessSent = true;
             // Persistent guard: ambient hooks spawn a fresh process per prompt, so the
@@ -1351,8 +1445,90 @@ const CACHLY_MCP_INSTRUCTIONS = `This project has a Cachly AI Brain — persiste
 - BEFORE a risky op (deploy, migration, dependency bump): call brain_predict.
 
 The Brain instance id comes from the CACHLY_BRAIN_INSTANCE_ID environment variable.`;
-const server = new Server({ name: 'cachly-mcp', version: CURRENT_VERSION }, { capabilities: { tools: {} }, instructions: CACHLY_MCP_INSTRUCTIONS });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+/**
+ * Baut einen frischen MCP-Server mit allen Handlern.
+ *
+ * ─── WARUM DAS EINE FABRIK IST UND KEINE KONSTANTE ──────────────────────────
+ *
+ * Im HTTP-Betrieb braucht JEDE Anfrage ihren eigenen Server samt Transport.
+ * Bis zum 17.08.2026 gab es genau einen, beim Start erzeugt und fuer alles
+ * wiederverwendet — und ein MCP-Server laesst sich nur EINMAL initialisieren.
+ *
+ * Die Folge war unauffaellig und teuer: Der erste initialize nach dem Start
+ * antwortete mit 200, jeder weitere mit 500 und LEEREM Rumpf. Nachgestellt:
+ *
+ *     Aufruf 1: HTTP 200
+ *     Aufruf 2: HTTP 500
+ *     Aufruf 3: HTTP 500
+ *
+ * Nach jedem Ausrollen war der Endpunkt also fuer genau eine Anfrage gesund.
+ * Glama und Smithery haben ihren einen Treffer gelandet und die Antwort
+ * eingefroren — beide zeigen bis heute 80 Werkzeuge, obwohl es 122 sind. Kein
+ * Log, keine Fehlermeldung, kein roter Alarm. Der Endpunkt galt als "up",
+ * weil /health antwortete.
+ *
+ * Der Aufbau ist billig: ein "new Server" und zwei Handler. TOOLS ist eine
+ * Konstante des Moduls, es wird nichts kopiert.
+ */
+/**
+ * Was dieser Server kann. Werkzeuge sind der Kern; Ressourcen und Prompts
+ * fuehren wir mit LEEREN Listen.
+ *
+ * ─── WARUM LEER UND NICHT WEGGELASSEN (18.08.2026) ──────────────────────────
+ *
+ * Genau genommen war das Weglassen richtig: Wer eine Faehigkeit nicht
+ * ankuendigt, darf auf `resources/list` mit -32601 "Method not found"
+ * antworten, und das ist die vorgesehene Antwort.
+ *
+ * Nur liest sie niemand so. Im Scan-Protokoll von Smithery stand:
+ *
+ *   [scan] Capabilities found: 122 tools. Warning: Failed to list resources:
+ *   MCP error -32601: Method not found; Failed to list prompts: ...
+ *
+ * Ein Pruefer, der "Failed" protokolliert, faellt nicht auf die Feinheit
+ * herein, dass unser Nein das korrekte Nein war. Aus einer sauberen Antwort
+ * wird eine Warnzeile im Bericht — und Warnzeilen kosten Noten in den
+ * Verzeichnissen, ohne dass irgendwo etwas kaputt ist.
+ *
+ * Eine leere Liste sagt dasselbe wie der Fehler ("hier gibt es nichts"), aber
+ * in einer Form, die jeder Aufrufer richtig versteht. Das ist keine
+ * Beschoenigung: Wir behaupten nicht, Ressourcen zu haben, wir liefern
+ * nachpruefbar null Stueck.
+ */
+const CAPABILITIES = { tools: {}, resources: {}, prompts: {} };
+const listToolsHandler = async () => ({ tools: TOOLS });
+// Bewusst Funktionsdeklarationen statt const: makeServer() steht weiter oben
+// als callToolHandler, und Deklarationen werden hochgezogen. So gibt es EINE
+// Stelle je Handler, nicht eine pro Server-Aufbau.
+async function listResourcesHandler() {
+    return { resources: [] };
+}
+async function listResourceTemplatesHandler() {
+    return { resourceTemplates: [] };
+}
+async function listPromptsHandler() {
+    return { prompts: [] };
+}
+/** Haengt alle Handler an einen Server. Beide Betriebsarten teilen sich diese
+ *  eine Liste — sonst kennt der HTTP-Server bald etwas, das der stdio-Server
+ *  nicht kennt, und niemand merkt es. */
+function registriereHandler(s) {
+    s.setRequestHandler(ListToolsRequestSchema, listToolsHandler);
+    s.setRequestHandler(CallToolRequestSchema, callToolHandler);
+    s.setRequestHandler(ListResourcesRequestSchema, listResourcesHandler);
+    s.setRequestHandler(ListResourceTemplatesRequestSchema, listResourceTemplatesHandler);
+    s.setRequestHandler(ListPromptsRequestSchema, listPromptsHandler);
+}
+function makeServer() {
+    const s = new Server({ name: 'cachly-mcp', version: CURRENT_VERSION }, { capabilities: CAPABILITIES, instructions: CACHLY_MCP_INSTRUCTIONS });
+    registriereHandler(s);
+    return s;
+}
+const server = new Server({ name: 'cachly-mcp', version: CURRENT_VERSION }, { capabilities: CAPABILITIES, instructions: CACHLY_MCP_INSTRUCTIONS });
+server.setRequestHandler(ListToolsRequestSchema, listToolsHandler);
+server.setRequestHandler(ListResourcesRequestSchema, listResourcesHandler);
+server.setRequestHandler(ListResourceTemplatesRequestSchema, listResourceTemplatesHandler);
+server.setRequestHandler(ListPromptsRequestSchema, listPromptsHandler);
 // ── Auto-session management ───────────────────────────────────────────────────
 // Transparently starts a Brain session on the first tool call of a process
 // and saves a session_end summary on SIGTERM/exit so users never have to call
@@ -1423,7 +1599,7 @@ async function autoEndSession() {
     }
     catch { /* non-fatal */ }
 }
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+const callToolHandler = async (request) => {
     const { name, arguments: args } = request.params;
     // Auto-start brain session on first tool call that has an instance_id.
     // Skip session management tools to avoid recursion.
@@ -1456,7 +1632,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         notify('cachly', 'tool_error', { tool: name, error: msg }).catch(() => undefined);
         throw new McpError(ErrorCode.InternalError, msg);
     }
-});
+};
+server.setRequestHandler(CallToolRequestSchema, callToolHandler);
 // Graceful shutdown – close all Redis connections + auto-end brain session
 process.on('SIGTERM', async () => {
     await autoEndSession().catch(() => undefined);
@@ -1865,23 +2042,60 @@ if (process.argv[2] === 'export') {
     }
     process.stdout.write('\n📤 Exporting your Brain...\n\n');
     try {
-        const memRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/memory`, {
+        // ── Warum /export und nicht /memory ──────────────────────────────────────
+        //
+        // Bis zum 19.08.2026 stand hier /memory. Der Endpunkt ist die
+        // Dashboard-Zusammenfassung: oberste 50 Lektionen, what_worked auf 120
+        // Zeichen gekuerzt. Gemessen am 19.08.2026 an einem Brain mit 493
+        // Lektionen: der Export lieferte 50 Stueck mit mitten im Wort
+        // abgeschnittenen Saetzen — 10 Prozent, unlesbar.
+        //
+        // Bei einem Produkt, das "your memory, not the vendor's" verspricht, ist
+        // das kein Schoenheitsfehler. /export liefert alles, ungekuerzt.
+        let lessons = [];
+        let unvollstaendig = '';
+        const expRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/export`, {
             headers: { Authorization: `Bearer ${apiKey}` },
-            signal: AbortSignal.timeout(8000),
+            signal: AbortSignal.timeout(120000), // alles lesen dauert laenger als eine Zusammenfassung
         });
-        if (!memRes.ok)
-            throw new Error(`memory HTTP ${memRes.status}`);
-        const mem = await memRes.json();
-        const lessons = (mem.top_lessons ?? []).map((l) => ({
-            topic: l.topic,
-            outcome: l.outcome,
-            severity: l.severity,
-            tags: l.tags,
-            whatWorked: l.what_worked,
-            ts: l.ts,
-            author: l.author,
-            recallCount: l.recall_count,
-        }));
+        if (expRes.ok) {
+            const dump = await expRes.json();
+            lessons = (dump.lessons ?? [])
+                .map(vonRohLektion)
+                .filter((l) => l !== null);
+            // Der Server sagt selbst, ob er alles hatte. Diese Antwort wird
+            // weitergereicht statt geschluckt — ein abgeschnittener Export, der wie
+            // ein vollstaendiger aussieht, ist schlimmer als ein Fehler.
+            if (dump.complete === false)
+                unvollstaendig = dump.note ?? 'the server reported an incomplete read';
+        }
+        else if (expRes.status === 404) {
+            // Aeltere Server kennen /export noch nicht. Dann gibt es die
+            // Zusammenfassung — aber der Nutzer erfaehrt, dass er sie bekommt.
+            const memRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/memory`, {
+                headers: { Authorization: `Bearer ${apiKey}` },
+                signal: AbortSignal.timeout(8000),
+            });
+            if (!memRes.ok)
+                throw new Error(`memory HTTP ${memRes.status}`);
+            const mem = await memRes.json();
+            lessons = (mem.top_lessons ?? []).map((l) => ({
+                topic: l.topic,
+                outcome: l.outcome,
+                severity: l.severity,
+                tags: l.tags,
+                whatWorked: l.what_worked,
+                ts: l.ts,
+                author: l.author,
+                recallCount: l.recall_count,
+            }));
+            unvollstaendig =
+                'this server has no /export endpoint yet, so this is the DASHBOARD SUMMARY: ' +
+                    'at most 50 lessons, each shortened to 120 characters. Update the server for a full export.';
+        }
+        else {
+            throw new Error(`export HTTP ${expRes.status}`);
+        }
         if (lessons.length === 0) {
             console.log('   No lessons in this Brain yet — nothing to export.\n');
             process.exit(0);
@@ -1898,7 +2112,14 @@ if (process.argv[2] === 'export') {
             await writeFile(jsonlPath, buildLessonsJsonl(lessons), 'utf-8');
             written.push(`${lessons.length} lesson${lessons.length === 1 ? '' : 's'} → ${jsonlPath}`);
         }
-        console.log('✅ Export complete:');
+        if (unvollstaendig) {
+            console.log('⚠️  Export INCOMPLETE — this is not your whole Brain:');
+            console.log(`   ${unvollstaendig}`);
+            console.log('');
+        }
+        else {
+            console.log('✅ Export complete:');
+        }
         for (const line of written)
             console.log(`   ${line}`);
         console.log('');
@@ -4045,8 +4266,6 @@ if (httpPort) {
     // ── HTTP mode (Streamable HTTP transport) ───────────────────────────────
     // Used for Smithery URL deployment: PORT=3000 node dist/src/index.js
     const { createServer } = await import('node:http');
-    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-    await server.connect(transport);
     const httpServer = createServer((req, res) => {
         const url = new URL(req.url ?? '/', `http://localhost:${httpPort}`);
         if (url.pathname === '/health') {
@@ -4062,7 +4281,34 @@ if (httpPort) {
             return;
         }
         if (url.pathname === '/mcp' || url.pathname === '/') {
-            transport.handleRequest(req, res);
+            // JEDE Anfrage bekommt einen eigenen Server samt Transport.
+            //
+            // Vorher gab es genau einen, beim Start erzeugt. Ein MCP-Server laesst
+            // sich aber nur EINMAL initialisieren — der erste Aufruf nach dem Start
+            // ging durch, jeder weitere endete mit 500 und leerem Rumpf. Siehe die
+            // Begruendung bei makeServer().
+            void (async () => {
+                const s = makeServer();
+                const t = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+                // Aufraeumen, sobald die Antwort durch ist — sonst haelt jede Anfrage
+                // ihren Server fest und der Speicher waechst mit jedem Aufruf.
+                res.on('close', () => {
+                    t.close().catch(() => undefined);
+                    s.close().catch(() => undefined);
+                });
+                try {
+                    await s.connect(t);
+                    await t.handleRequest(req, res);
+                }
+                catch (err) {
+                    // Ein Fehler ohne Text war genau das Problem, das hier behoben wird.
+                    process.stderr.write(`cachly-mcp HTTP: ${err.message}\n`);
+                    if (!res.headersSent) {
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: err.message }));
+                    }
+                }
+            })();
             return;
         }
         res.writeHead(404);