@cachly-dev/mcp-server 0.5.6 → 0.5.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "MCP server – manage cachly.dev instances from any AI assistant (Copilot, Claude, Cursor, Windsurf)",
   "type": "module",
   "bin": {

package/src/index.ts

@@ -1343,6 +1343,11 @@ const TOOLS = [
           items: { type: 'string' },
           description: 'Topic tags for filtering (e.g. ["bash", "deploy", "env"])',
         },
+        depends_on: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Prerequisites this lesson depends on (e.g. ["node:>=20", "docker:running", "wireguard:active"]). When a dependency is marked stale, all dependent lessons get needs_review.',
+        },
       },
       required: ['instance_id', 'topic', 'outcome', 'what_worked'],
     },
@@ -1653,6 +1658,100 @@ const TOOLS = [
       required: ['instance_id', 'framework'],
     },
   },
+  // ── Brain Archaeology + Causal Chain ────────────────────────────────────
+  {
+    name: 'recall_at',
+    description:
+      'Brain Archaeology — see what a lesson looked like at a specific point in time. ' +
+      '"What did we know about deployments 3 months ago?" ' +
+      'Returns the history of a topic filtered to entries before the given date. ' +
+      'Shows how the lesson evolved: failure → partial → success. ' +
+      'Also useful to understand WHY old code decisions were made.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        topic:       { type: 'string', description: 'Topic slug to look up, e.g. "deploy:api"' },
+        date:        { type: 'string', description: 'ISO date string (e.g. "2026-01-15") — returns entries stored BEFORE this date' },
+      },
+      required: ['instance_id', 'topic', 'date'],
+    },
+  },
+  {
+    name: 'trace_dependency',
+    description:
+      'Causal Chain — find all lessons that depend on a given prerequisite. ' +
+      '"What lessons are affected if node version changes?" ' +
+      'When a dependency changes (new version, different provider, new OS), call this to see which lessons need review. ' +
+      'Lessons store dependencies via the depends_on field in learn_from_attempts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        dependency:  { type: 'string', description: 'Dependency to trace (e.g. "node:>=20", "docker:running", "wireguard:active")' },
+        mark_review: { type: 'boolean', description: 'If true, marks all dependent lessons as needs_review (default: false)' },
+      },
+      required: ['instance_id', 'dependency'],
+    },
+  },
+  // ── Team / Org Management ────────────────────────────────────────────────
+  {
+    name: 'list_orgs',
+    description:
+      'List your Cachly organizations (team/org plans). ' +
+      'Returns each org with plan, seat count, and member info. ' +
+      'Org plans (Team €99, Business €299, Enterprise custom) are billed separately from cache tiers.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: 'create_org',
+    description:
+      'Create a new Cachly organization for team collaboration. ' +
+      'After creation, invite team members with invite_member and upgrade the plan via the billing portal. ' +
+      'Org plans: Team (€99/mo, 10 seats), Business (€299/mo, 50 seats), Enterprise (custom).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Organization display name (e.g. "Acme Engineering")' },
+        slug: { type: 'string', description: 'URL-safe slug (e.g. "acme-eng"). Auto-generated from name if omitted.' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'invite_member',
+    description:
+      'Invite a team member to a Cachly organization by email. ' +
+      'They will receive an invite email and can join via the dashboard. ' +
+      'Roles: owner (full access), admin (manage members + instances), member (read + cache ops).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        org_id: { type: 'string', description: 'UUID of the organization' },
+        email:  { type: 'string', description: 'Email address to invite' },
+        role:   { type: 'string', enum: ['admin', 'member'], description: 'Role for the invited member (default: member)' },
+      },
+      required: ['org_id', 'email'],
+    },
+  },
+  {
+    name: 'get_org_plan',
+    description:
+      'Get the current org plan, seat usage, and billing info for an organization. ' +
+      'Shows: plan name, price, seats used/max, next billing date. ' +
+      'To upgrade: use the billing portal URL returned by this tool.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        org_id: { type: 'string', description: 'UUID of the organization' },
+      },
+      required: ['org_id'],
+    },
+  },
   // ── Legacy / Setup ────────────────────────────────────────────────────────
   {
     name: 'setup_ai_memory',
@@ -1829,6 +1928,69 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       return `✅ Instance \`${instance_id}\` has been deleted and all data removed.`;
     }
 
+    // ── Org / Team management ────────────────────────────────────────────
+    case 'list_orgs': {
+      const res = await apiFetch<{ orgs: Array<{ id: string; name: string; slug: string; plan: string; max_members: number; member_count?: number }> }>('/api/v1/orgs');
+      const orgs = res.orgs ?? [];
+      if (orgs.length === 0) return `📭 No organizations yet.\n\nCreate one with \`create_org(name="My Team")\`.\nOrg plans: Team €99/mo (10 seats), Business €299/mo (50 seats), Enterprise custom.`;
+      return [
+        `🏢 **Your organizations (${orgs.length})**\n`,
+        ...orgs.map(o => `• **${o.name}** (\`${o.slug}\`) — plan: ${o.plan} · seats: ${o.member_count ?? '?'}/${o.max_members}\n  ID: \`${o.id}\``),
+        `\n_Manage: \`get_org_plan\`, \`invite_member\`, dashboard → /team_`,
+      ].join('\n');
+    }
+
+    case 'create_org': {
+      const { name: orgName, slug } = args as { name: string; slug?: string };
+      const body: Record<string, string> = { name: orgName };
+      if (slug) body.slug = slug;
+      const res = await apiFetch<{ id: string; name: string; slug: string; plan: string }>('/api/v1/orgs', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+      return [
+        `✅ **Organization created:** ${res.name}`,
+        `   ID: \`${res.id}\` · Slug: \`${res.slug}\` · Plan: ${res.plan}`,
+        ``,
+        `**Next steps:**`,
+        `1. Invite team members: \`invite_member(org_id="${res.id}", email="dev@example.com")\``,
+        `2. Upgrade plan: open billing portal via dashboard → /team`,
+        `   Team: €99/mo (10 seats) · Business: €299/mo (50 seats)`,
+      ].join('\n');
+    }
+
+    case 'invite_member': {
+      const { org_id, email, role = 'member' } = args as { org_id: string; email: string; role?: string };
+      await apiFetch(`/api/v1/orgs/${org_id}/members`, {
+        method: 'POST',
+        body: JSON.stringify({ email, role }),
+      });
+      return `✅ Invite sent to **${email}** as \`${role}\` in org \`${org_id}\`.\n\nThey will receive an email to join the organization.`;
+    }
+
+    case 'get_org_plan': {
+      const { org_id } = args as { org_id: string };
+      const org = await apiFetch<{
+        id: string; name: string; plan: string; max_members: number;
+        members: Array<{ role: string; invite_email: string; accepted_at?: string }>;
+        stripe_customer_id?: string;
+      }>(`/api/v1/orgs/${org_id}`);
+      const accepted = (org.members ?? []).filter(m => m.accepted_at).length;
+      const pending = (org.members ?? []).filter(m => !m.accepted_at).length;
+      const planPrice: Record<string, string> = { free: '€0', team: '€99/mo', business: '€299/mo', enterprise: 'custom' };
+      return [
+        `🏢 **${org.name}** — Plan: **${org.plan}** (${planPrice[org.plan] ?? org.plan})`,
+        `   Seats: ${accepted} active + ${pending} pending / ${org.max_members} max`,
+        ``,
+        `**Members:**`,
+        ...(org.members ?? []).map(m => `  • ${m.invite_email} (${m.role})${m.accepted_at ? '' : ' — pending'}`),
+        ``,
+        org.stripe_customer_id
+          ? `💳 Billing: managed via Stripe. Upgrade/cancel: dashboard → /billing`
+          : `💳 No payment method yet. Upgrade: dashboard → /billing → Team Plans`,
+      ].join('\n');
+    }
+
     // ── Live cache operations ────────────────────────────────────────────
     case 'cache_get': {
       const { instance_id, key } = args as { instance_id: string; key: string };
@@ -2556,6 +2718,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         file_paths = [],
         commands = [],
         tags = [],
+        depends_on = [],
       } = args as {
         instance_id: string;
         topic: string;
@@ -2567,6 +2730,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         file_paths?: string[];
         commands?: string[];
         tags?: string[];
+        depends_on?: string[];
       };
 
       const redis = await getConnection(instance_id);
@@ -2624,6 +2788,47 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         auditTrail = [{ ts, action: 'created' }];
       }
 
+      // ── "I Was Wrong" Protocol — failure attribution ───────────────────────
+      const iWasWrongWarning: string[] = [];
+      if (outcome === 'failure') {
+        // Search for related success lessons that might have prevented this failure
+        const scanKeys: string[] = [];
+        const scanStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 100 });
+        await new Promise<void>((res, rej) => {
+          scanStream.on('data', (b: string[]) => scanKeys.push(...b));
+          scanStream.on('end', res);
+          scanStream.on('error', rej);
+        });
+        const topicWords = topic.split(/[:\-_]/).filter(w => w.length > 2);
+        for (const k of scanKeys.slice(0, 50)) {
+          const raw = await redis.get(k);
+          if (!raw) continue;
+          try {
+            const l = JSON.parse(raw) as { outcome?: string; topic?: string; severity?: string };
+            if (l.outcome !== 'success') continue;
+            const lWords = (l.topic ?? '').split(/[:\-_]/).filter(w => w.length > 2);
+            const overlap = topicWords.filter(w => lWords.includes(w)).length;
+            if (overlap >= 1 && l.topic !== topic) {
+              iWasWrongWarning.push(
+                `⚠️ **"I Was Wrong"**: lesson \`${l.topic}\` (success, ${l.severity ?? 'major'}) might have prevented this failure.`,
+                `   → Use \`recall_best_solution(topic="${l.topic}")\` before next attempt.`,
+                `   → To mark it critical: \`learn_from_attempts(topic="${l.topic}", ..., severity="critical")\``,
+              );
+              break; // only show the most relevant match
+            }
+          } catch { /* skip */ }
+        }
+      }
+
+      // ── Register dependency index for causal chain ─────────────────────────
+      for (const dep of depends_on) {
+        const depKey = `cachly:dep:${dep}`;
+        const existing = await redis.get(depKey);
+        const depTopics: string[] = existing ? JSON.parse(existing) : [];
+        if (!depTopics.includes(topic)) depTopics.push(topic);
+        await redis.set(depKey, JSON.stringify(depTopics));
+      }
+
       const lessonObj = {
         topic,
         outcome,
@@ -2634,6 +2839,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         file_paths,
         commands,
         tags,
+        depends_on,
         recall_count: recallCount,
         ts,
         verified_at: outcome === 'success' || outcome === 'partial' ? ts : undefined,
@@ -2678,7 +2884,11 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         isUpdate
           ? `♻️ Updated (recall count: ${recallCount} · audit entries: ${auditTrail.length})`
           : `💡 Recall later with \`recall_best_solution(topic="${topic}")\``,
+        depends_on.length > 0
+          ? `🔗 Depends on: ${depends_on.map(d => `\`${d}\``).join(', ')} → trace with \`trace_dependency\``
+          : '',
         ...templateWarnings,
+        ...iWasWrongWarning,
       ].filter(l => l !== '').join('\n');
     }
 
@@ -2713,9 +2923,22 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
 
         const sevEmoji = lesson.severity === 'critical' ? '🔴' : lesson.severity === 'major' ? '🟡' : lesson.severity ? '🟢' : '';
         const auditSummary = (lesson.audit_trail ?? []).length > 1
-          ? `\n_Audit: ${(lesson.audit_trail ?? []).length} changes · ${new Date(lesson.ts).toLocaleDateString('de-DE')}_`
+          ? `_Audit: ${(lesson.audit_trail ?? []).length} changes · stored ${new Date(lesson.ts).toLocaleDateString('de-DE')}_`
+          : '';
+
+        // "Remember when..." — emotional header for lessons > 60 days old
+        const ageFromStoreDays = (Date.now() - new Date(lesson.ts).getTime()) / 86400000;
+        const rememberWhen = ageFromStoreDays > 60
+          ? `💭 _Remember when you solved this ${Math.round(ageFromStoreDays / 30)} months ago? Still works._`
+          : '';
+
+        // "Never Google This Again" — suggest pinning after 3rd recall
+        const suggestPin = updatedLesson.recall_count === 3 && !(lesson as { pinned?: boolean }).pinned
+          ? `📌 **You've looked this up 3 times.** Consider pinning it for instant access: add \`pinned: true\` via \`learn_from_attempts\` to always surface it first.`
           : '';
+
         return [
+          rememberWhen,
           `${badge} **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}×`,
           ``,
           `**What worked:** ${lesson.what_worked}`,
@@ -2725,6 +2948,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
           (lesson.commands ?? []).length > 0 ? `**Commands:** ${(lesson.commands ?? []).map((c: string) => `\`${c}\``).join(', ')}` : '',
           (lesson.tags ?? []).length > 0 ? `**Tags:** ${(lesson.tags ?? []).map((t: string) => `#${t}`).join(' ')}` : '',
           auditSummary,
+          suggestPin,
         ].filter(l => l !== '').join('\n');
       }
 
@@ -2995,7 +3219,43 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
           )
         : [];
 
-      // 6. Save session start marker
+      // 6. Streak tracking
+      let streakDays = 0;
+      let streakRecord = 0;
+      let streakMessage = '';
+      try {
+        const streakRaw = await redis.get('cachly:streak:current');
+        const streak = streakRaw ? JSON.parse(streakRaw) as { days: number; last_date: string; record: number } : null;
+        const today = new Date().toISOString().slice(0, 10);
+        if (streak) {
+          const lastDate = streak.last_date;
+          const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
+          if (lastDate === today) {
+            // Already counted today
+            streakDays = streak.days;
+            streakRecord = streak.record;
+          } else if (lastDate === yesterday) {
+            // Continuing streak
+            streakDays = streak.days + 1;
+            streakRecord = Math.max(streakDays, streak.record);
+            await redis.set('cachly:streak:current', JSON.stringify({ days: streakDays, last_date: today, record: streakRecord }));
+          } else {
+            // Streak broken
+            streakDays = 1;
+            streakRecord = streak.record;
+            await redis.set('cachly:streak:current', JSON.stringify({ days: 1, last_date: today, record: streakRecord }));
+          }
+        } else {
+          // First session ever
+          streakDays = 1;
+          streakRecord = 1;
+          await redis.set('cachly:streak:current', JSON.stringify({ days: 1, last_date: today, record: 1 }));
+        }
+        if (streakDays >= 7) streakMessage = `🔥 **${streakDays}-day streak!** ${streakDays === streakRecord ? ' New record!' : `Best: ${streakRecord}d`}`;
+        else if (streakDays > 1) streakMessage = `🔥 ${streakDays}-day streak`;
+      } catch { /* non-critical */ }
+
+      // 7. Save session start marker
       await redis.set('cachly:session:current', JSON.stringify({
         started: new Date().toISOString(),
         focus,
@@ -3003,6 +3263,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
 
       // ── Build briefing ──────────────────────────────────────────────────────
       const lines: string[] = ['🧠 **Session Briefing**', ''];
+      if (streakMessage) lines.push(streakMessage, '');
 
       // Handoff from previous window (if any)
       const handoffRaw = await redis.get('cachly:session:handoff');
@@ -3666,6 +3927,77 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       return lines.join('\n');
     }
 
+    // ── recall_at — Brain Archaeology ────────────────────────────────────────
+    case 'recall_at': {
+      const { instance_id, topic, date } = args as { instance_id: string; topic: string; date: string };
+      const redis = await getConnection(instance_id);
+      const cutoff = new Date(date).getTime();
+      if (isNaN(cutoff)) return `❌ Invalid date "${date}". Use ISO format: "2026-01-15"`;
+
+      const listKey = `cachly:lessons:${topic}`;
+      const all = await redis.lrange(listKey, 0, -1);
+      if (all.length === 0) return `📭 No history found for \`${topic}\`. Lessons are stored via \`learn_from_attempts\`.`;
+
+      const before = all
+        .map(raw => { try { return JSON.parse(raw) as { ts: string; outcome?: string; what_worked?: string; what_failed?: string }; } catch { return null; } })
+        .filter((l): l is NonNullable<typeof l> => l !== null && new Date(l.ts).getTime() <= cutoff)
+        .sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
+
+      if (before.length === 0) return `📭 No entries for \`${topic}\` found before **${date}**. Earliest entry: ${new Date(JSON.parse(all[0]).ts).toLocaleDateString('de-DE')}.`;
+
+      const lines = [
+        `🏺 **Brain Archaeology: \`${topic}\` before ${date}**`,
+        `_${before.length} of ${all.length} total entries shown_`,
+        '',
+      ];
+      for (const l of before.slice(-10)) {
+        const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+        const d = new Date(l.ts).toLocaleDateString('de-DE');
+        lines.push(`**${d}** ${emoji} ${l.outcome}`);
+        if (l.what_worked) lines.push(`  → ${l.what_worked.slice(0, 100)}`);
+        lines.push('');
+      }
+      lines.push(`_Full evolution: ${all.map(r => { try { const l = JSON.parse(r) as { outcome?: string }; return l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌'; } catch { return '?'; } }).join(' → ')}_`);
+      return lines.join('\n');
+    }
+
+    // ── trace_dependency — Causal Chain ──────────────────────────────────────
+    case 'trace_dependency': {
+      const { instance_id, dependency, mark_review = false } = args as { instance_id: string; dependency: string; mark_review?: boolean };
+      const redis = await getConnection(instance_id);
+
+      const depKey = `cachly:dep:${dependency}`;
+      const raw = await redis.get(depKey);
+      if (!raw) return `📭 No lessons found that depend on \`${dependency}\`.\n\nAdd dependencies via: \`learn_from_attempts(..., depends_on=["${dependency}"])\``;
+
+      const topics: string[] = JSON.parse(raw);
+      const lines = [
+        `🔗 **Causal Chain: \`${dependency}\`** — ${topics.length} dependent lesson${topics.length === 1 ? '' : 's'}`,
+        '',
+      ];
+
+      for (const t of topics) {
+        const lessonRaw = await redis.get(`cachly:lesson:best:${t}`);
+        if (!lessonRaw) { lines.push(`  • \`${t}\` _(lesson deleted)_`); continue; }
+        const lesson = JSON.parse(lessonRaw) as { outcome?: string; severity?: string; needs_review?: boolean };
+        const emoji = lesson.outcome === 'success' ? '✅' : lesson.outcome === 'partial' ? '⚠️' : '❌';
+        const reviewBadge = lesson.needs_review ? ' 🔍 **needs_review**' : '';
+        lines.push(`  ${emoji} \`${t}\` (${lesson.severity ?? 'major'})${reviewBadge}`);
+
+        if (mark_review) {
+          const updated = { ...lesson, needs_review: true };
+          await redis.set(`cachly:lesson:best:${t}`, JSON.stringify(updated));
+        }
+      }
+
+      if (mark_review) {
+        lines.push('', `🔍 All ${topics.length} lessons marked as **needs_review** — verify they still work with the changed dependency.`);
+      } else {
+        lines.push('', `_Run with \`mark_review: true\` to flag all dependent lessons for re-verification._`);
+      }
+      return lines.join('\n');
+    }
+
     // ── global_learn ──────────────────────────────────────────────────────────
     case 'global_learn': {
       const { instance_id, topic, lesson, severity = 'minor', tags = [] } = args as {