@cachly-dev/mcp-server 0.5.7 → 0.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "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'],
     },
@@ -1572,6 +1577,22 @@ const TOOLS = [
       required: ['instance_id'],
     },
   },
+  {
+    name: 'team_synthesize',
+    description:
+      'Team Brain Synthesis — merge multiple contributors\' lessons on the same topic into one canonical version. ' +
+      'When 2+ developers store lessons for the same topic with different details, this proposes the best merged version. ' +
+      'Shows: all contributions by author, what worked (consensus), what failed (union), canonical lesson to store. ' +
+      'Use this when onboarding new team members or before documenting a process.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the shared team brain instance' },
+        topic:       { type: 'string', description: 'Topic slug to synthesize (e.g. "deploy:api")' },
+      },
+      required: ['instance_id', 'topic'],
+    },
+  },
   {
     name: 'brain_doctor',
     description:
@@ -1653,6 +1674,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 +1944,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 +2734,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 +2746,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 +2804,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 +2855,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 +2900,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');
     }
 
@@ -3594,6 +3820,71 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       return lines.join('\n');
     }
 
+    // ── team_synthesize — Team Brain Synthesis ────────────────────────────────
+    case 'team_synthesize': {
+      const { instance_id, topic } = args as { instance_id: string; topic: string };
+      const redis = await getConnection(instance_id);
+
+      // Load history list for this topic (all authors' contributions)
+      const listKey = `cachly:lessons:${topic}`;
+      const all = await redis.lrange(listKey, 0, -1);
+      if (all.length < 2) {
+        return `📭 Need at least 2 entries for topic \`${topic}\` to synthesize.\n\nCurrently: ${all.length} entr${all.length === 1 ? 'y' : 'ies'}.\n\nHave team members store lessons via \`learn_from_attempts(topic="${topic}", ...)\`.`;
+      }
+
+      type Entry = { outcome: string; what_worked: string; what_failed?: string; author?: string; ts: string; severity?: string };
+      const entries: Entry[] = all.map(r => { try { return JSON.parse(r) as Entry; } catch { return null; } }).filter((e): e is Entry => e !== null);
+
+      // Group by outcome
+      const successes = entries.filter(e => e.outcome === 'success');
+      const failures  = entries.filter(e => e.outcome === 'failure');
+      const partials  = entries.filter(e => e.outcome === 'partial');
+
+      const authors = [...new Set(entries.map(e => e.author).filter(Boolean))];
+      const hasMultiAuthor = authors.length > 1;
+
+      // Build canonical merged version
+      // what_worked: pick the most recent success, or longest for most detail
+      const bestSuccess = successes.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime())[0];
+      const whatWorkedCandidates = successes.map(e => e.what_worked).filter(w => w && w.length > 10);
+      const canonicalWorked = whatWorkedCandidates.sort((a, b) => b.length - a.length)[0] ?? bestSuccess?.what_worked ?? '';
+
+      // what_failed: union of all unique failure reasons
+      const allFailed = [...new Set(
+        [...failures, ...partials].map(e => e.what_failed).filter((w): w is string => !!w && w.length > 5)
+      )];
+
+      const severities = entries.map(e => e.severity).filter(Boolean);
+      const canonicalSeverity = severities.includes('critical') ? 'critical' : severities.includes('major') ? 'major' : 'minor';
+
+      const lines = [
+        `🧬 **Team Brain Synthesis: \`${topic}\`**`,
+        `_${entries.length} entries from ${authors.length} author${authors.length === 1 ? '' : 's'}${hasMultiAuthor ? ` (${authors.join(', ')})` : ''} · ${successes.length} success · ${failures.length} failure · ${partials.length} partial_`,
+        '',
+        `**Canonical "what worked":**`,
+        `> ${canonicalWorked}`,
+        '',
+        allFailed.length > 0 ? `**Avoid (combined failures):**` : '',
+        ...allFailed.map(f => `> ❌ ${f}`),
+        allFailed.length > 0 ? '' : '',
+        `**Suggested canonical lesson:**`,
+        '```',
+        `learn_from_attempts(`,
+        `  topic       = "${topic}",`,
+        `  outcome     = "success",`,
+        `  what_worked = "${canonicalWorked.replace(/"/g, "'")}",`,
+        allFailed.length > 0 ? `  what_failed = "${allFailed[0].replace(/"/g, "'")}",` : '',
+        `  severity    = "${canonicalSeverity}",`,
+        `)`,
+        '```',
+        '',
+        hasMultiAuthor
+          ? `💡 _${authors.length} team members contributed to this synthesis. Store the canonical version to replace individual entries._`
+          : `💡 _Single author — more value when multiple team members contribute to the same topic._`,
+      ].filter(l => l !== undefined).join('\n');
+      return lines;
+    }
+
     // ── brain_doctor ──────────────────────────────────────────────────────────
     case 'brain_doctor': {
       const { instance_id } = args as { instance_id: string };
@@ -3717,6 +4008,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 {