@cachly-dev/mcp-server 0.9.24 → 0.10.0

package/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to npm
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm install --ignore-scripts
+
+      - name: Build
+        run: npm run build
+
+      - name: Check if version is already published
+        id: version_check
+        run: |
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          echo "version=$PKG_VERSION" >> $GITHUB_OUTPUT
+          if npm view "@cachly-dev/mcp-server@$PKG_VERSION" version &>/dev/null; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "Version $PKG_VERSION already published — skipping."
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+            echo "Version $PKG_VERSION is new — will publish."
+          fi
+
+      - name: Publish
+        if: steps.version_check.outputs.skip == 'false'
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/handlers/brain.js

@@ -1,8 +1,21 @@
 import { execSync } from 'node:child_process';
 import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES, CONFIDENCE_WARN_VALUE, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_DAYS } from '../confidence.js';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
+import { safeJsonParse } from '../utils.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
+// ── Changelog (shown once per version in session_start) ──────────────────────
+const MCP_VERSION = '0.10.0';
+const WHATS_NEW = {
+    '0.10.0': [
+        `🆕 **What's new in v${MCP_VERSION}:**`,
+        `  ✅ Zero-friction setup — auto-provisions your Brain, no manual config needed`,
+        `  ✅ 10× faster briefings — batch Redis fetches replace per-key loops`,
+        `  ✅ Crash-proof data reads — corrupted cache entries no longer break tools`,
+        `  ✅ \`session_end\` warns when called without an active session`,
+        `  ✅ \`get_api_status\` now shows live Redis ping + all instance statuses`,
+    ],
+};
 export const BRAIN_TOOL_NAMES = new Set([
     'learn_from_attempts', 'recall_best_solution', 'smart_recall',
     'session_start', 'session_end', 'session_ping', 'session_handoff', 'auto_learn_session',
@@ -98,7 +111,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             for (const dep of depends_on) {
                 const depKey = `cachly:dep:${dep}`;
                 const existing = await redis.get(depKey);
-                const depTopics = existing ? JSON.parse(existing) : [];
+                const depTopics = safeJsonParse(existing, []);
                 if (!depTopics.includes(topic))
                     depTopics.push(topic);
                 await redis.set(depKey, JSON.stringify(depTopics));
@@ -190,7 +203,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const er = await redis.get(ek);
                         if (!er)
                             continue;
-                        const existEdge = JSON.parse(er);
+                        const existEdge = safeJsonParse(er, null);
+                        if (!existEdge)
+                            continue;
                         if (existEdge.edgeType === 'fixes' && existEdge.confidence > 0.7 && existEdge.trials >= 3) {
                             beliefConflict = `⚠️ **belief_conflict** on \`${topic}\`: previously confirmed fix (confidence ${existEdge.confidence.toFixed(2)}, n=${existEdge.trials}) now reports failure. Both beliefs retained as \`contested\`. Use \`ckg_inspect(concept="${conceptId}")\` to review.`;
                             // Store conflict marker
@@ -210,7 +225,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const er = await redis.get(ek);
                         if (!er)
                             continue;
-                        const e2 = JSON.parse(er);
+                        const e2 = safeJsonParse(er, null);
+                        if (!e2)
+                            continue;
                         if (e2.edgeType !== 'fixes')
                             continue;
                         // Boost second-degree: edges from e2.to get a small fractional success
@@ -219,7 +236,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             const sr = await redis.get(sk);
                             if (!sr)
                                 continue;
-                            const se = JSON.parse(sr);
+                            const se = safeJsonParse(sr, null);
+                            if (!se)
+                                continue;
                             if (se.edgeType !== 'co-occurs')
                                 continue;
                             // Add 0.1 fractional success (second-degree signal)
@@ -241,7 +260,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const er = await redis.get(ek);
                         if (!er)
                             continue;
-                        const de = JSON.parse(er);
+                        const de = safeJsonParse(er, null);
+                        if (!de)
+                            continue;
                         if (de.trials < 3 && de.last_updated && new Date(de.last_updated).getTime() < decayCutoff) {
                             de.confidence = de.confidence * 0.9;
                             de.last_updated = new Date().toISOString();
@@ -281,7 +302,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // Try exact best-solution key first
             const best = await redis.get(`cachly:lesson:best:${topic}`);
             if (best) {
-                const lesson = JSON.parse(best);
+                const lesson = safeJsonParse(best, null);
+                if (!lesson)
+                    return `⚠️ Lesson data for \`${topic}\` is corrupted. Re-store it with \`learn_from_attempts\`.`;
                 // ── Confidence decay check ───────────────────────────────────────────
                 const confidence = calculateConfidence(lesson);
                 const ref = lesson.verified_at ?? lesson.ts;
@@ -336,7 +359,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const histKey = `cachly:lessons:${topic}`;
                 const all = await redis.lrange(histKey, -3, -1);
                 if (all.length > 0) {
-                    const parsed = all.map(e => JSON.parse(e));
+                    const parsed = all.map(e => safeJsonParse(e, null)).filter(Boolean);
                     const lines = parsed.map(p => `- ${p.outcome === 'success' ? '✅' : '❌'} ${p.what_worked.slice(0, 120)} (${new Date(p.ts).toLocaleDateString('de-DE')})`);
                     return `⚠️ No successful solution for \`${topic}\` yet. Last attempts:\n\n${lines.join('\n')}`;
                 }
@@ -348,7 +371,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const raw = await redis.get(k);
                 if (!raw)
                     continue;
-                const lesson = JSON.parse(raw);
+                const lesson = safeJsonParse(raw, null);
+                if (!lesson)
+                    continue;
                 results.push(`**\`${lesson.topic}\`** — ${lesson.what_worked.slice(0, 200)}`);
             }
             return `🔍 **Partial matches for \`${topic}\`:**\n\n${results.join('\n\n')}`;
@@ -485,14 +510,13 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 lStream.on('error', reject);
             });
             const lessons = [];
-            for (const k of lessonKeys) {
-                const raw = await redis.get(k);
-                if (!raw)
-                    continue;
-                try {
-                    lessons.push(JSON.parse(raw));
+            if (lessonKeys.length > 0) {
+                const raws = await redis.mget(...lessonKeys);
+                for (const raw of raws) {
+                    const l = safeJsonParse(raw ?? null, null);
+                    if (l)
+                        lessons.push(l);
                 }
-                catch { /* skip corrupt */ }
             }
             lessons.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
             // 3. Count context entries (filter :meta keys)
@@ -507,13 +531,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             });
             // 4. Last session
             const lastSessionRaw = await redis.get('cachly:session:last');
-            let lastSession = null;
-            if (lastSessionRaw) {
-                try {
-                    lastSession = JSON.parse(lastSessionRaw);
-                }
-                catch { /* ignore */ }
-            }
+            const lastSession = safeJsonParse(lastSessionRaw, null);
             // 5. Focus filtering
             const focusTerms = focus.toLowerCase().split(/\s+/).filter(Boolean);
             const focusLessons = focusTerms.length > 0
@@ -526,7 +544,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             let streakMessage = '';
             try {
                 const streakRaw = await redis.get('cachly:streak:current');
-                const streak = streakRaw ? JSON.parse(streakRaw) : null;
+                const streak = safeJsonParse(streakRaw, null);
                 const today = new Date().toISOString().slice(0, 10);
                 if (streak) {
                     const lastDate = streak.last_date;
@@ -572,6 +590,35 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             const lines = [`🧠 **Session Briefing**${providerLabel}`, ''];
             if (streakMessage)
                 lines.push(streakMessage, '');
+            // ── What's New (shown once per version update) ──────────────────────────
+            try {
+                const seenVersion = await redis.get('cachly:mcp:version:last_seen');
+                if (seenVersion !== MCP_VERSION) {
+                    await redis.set('cachly:mcp:version:last_seen', MCP_VERSION, 'EX', 365 * 86400);
+                    const changelog = WHATS_NEW[MCP_VERSION];
+                    if (changelog) {
+                        lines.push(...changelog, '');
+                    }
+                }
+            }
+            catch { /* non-critical */ }
+            // ── First-time welcome (empty brain) ───────────────────────────────────
+            const isFirstSession = !lastSession && lessons.length === 0 && ctxCount === 0;
+            if (isFirstSession) {
+                lines.push('🎉 **Welcome! Your AI Brain is live.**', '');
+                lines.push('It learns from your work automatically. After your first session it will look like this:', '');
+                lines.push('  ✅ `api:auth` — Bearer token in header, not cookie; 401 on missing scope');
+                lines.push('  ✅ `database:migrations` — always run migrations before deploy');
+                lines.push('  ⚠️ `docker:build` — ARG changes bust all subsequent cache layers');
+                lines.push('');
+                lines.push('**3 steps to grow your brain:**');
+                lines.push('  1. Fix something → `learn_from_attempts(topic="bug:name", outcome="success", what_worked="...")`');
+                lines.push('  2. Save context → `remember_context(key="arch", value="...")`');
+                lines.push('  3. End session → `session_end(summary="What I did")`');
+                lines.push('');
+                lines.push('💡 Run `brain_doctor` for a setup health-check and personalised tips.');
+                lines.push('');
+            }
             // Handoff from previous window (if any)
             const handoffRaw = await redis.get('cachly:session:handoff');
             if (handoffRaw) {
@@ -1011,8 +1058,6 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             }
             catch { /* non-critical */ }
             // ── 🌍 Knowledge Commons — community stats banner ───────────────────────
-            // Fetch syndication stats and show a 1-liner: total lessons + confirms + weekly growth.
-            // Non-fatal: never blocks session start if the API call fails.
             try {
                 const commonsStats = await apiFetch('/api/v1/syndication/stats');
                 if (commonsStats.total_lessons > 0) {
@@ -1023,6 +1068,19 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 }
             }
             catch { /* non-critical — never block session start */ }
+            // ── Brain Doctor hint (Punkt 6) — surface when brain needs attention ───
+            const hasOpenFailures = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial').length > 0;
+            const hasStaleLessons = lessons.some(l => l.outcome === 'success' && calculateConfidence(l) < CONFIDENCE_WARN_VALUE);
+            if (lessons.length === 0 || hasOpenFailures || hasStaleLessons) {
+                const reasons = [];
+                if (lessons.length === 0)
+                    reasons.push('brain is empty');
+                if (hasOpenFailures)
+                    reasons.push('open failures');
+                if (hasStaleLessons)
+                    reasons.push('stale lessons');
+                lines.push(`🩺 _Run \`brain_doctor\` to fix: ${reasons.join(', ')}._`);
+            }
             return lines.join('\n');
         }
         // ── session_end ───────────────────────────────────────────────────────────
@@ -1033,18 +1091,20 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // Calculate duration from session_start marker
             let durationMin;
             const currentRaw = await redis.get('cachly:session:current');
-            if (currentRaw) {
-                try {
-                    const current = JSON.parse(currentRaw);
-                    durationMin = Math.round((now.getTime() - new Date(current.started).getTime()) / 60000);
-                }
-                catch { /* ignore */ }
+            if (!currentRaw) {
+                return `⚠️ No active session found.\n\nRun \`session_start\` first to begin tracking a session, then call \`session_end\` when you're done.`;
+            }
+            const current = safeJsonParse(currentRaw, null);
+            if (current?.started) {
+                durationMin = Math.round((now.getTime() - new Date(current.started).getTime()) / 60000);
             }
-            // ── Session Replay: capture decision log ─────────────────────────────
             let decisionLog = [];
             try {
                 const dlEntries = await redis.lrange('cachly:session:decision-log', 0, -1);
-                decisionLog = dlEntries.map(e => JSON.parse(e));
+                decisionLog = dlEntries.flatMap(e => {
+                    const entry = safeJsonParse(e, null);
+                    return entry ? [entry] : [];
+                });
                 await redis.del('cachly:session:decision-log');
             }
             catch { /* non-critical */ }