@cachly-dev/mcp-server 0.10.108 → 0.10.113

package/README.md

@@ -22,7 +22,7 @@
     <img src="https://img.shields.io/badge/GDPR-EU%20servers-green" alt="GDPR: EU servers" />
   </a>
   &nbsp;
-  <img src="https://img.shields.io/badge/121%20MCP%20tools-violet" alt="121 MCP tools" />
+  <img src="https://img.shields.io/badge/136%20MCP%20tools-violet" alt="136 MCP tools" />
   &nbsp;
   <img src="https://img.shields.io/badge/License-Apache--2.0-yellow" alt="License: Apache-2.0" />
 </p>
@@ -246,7 +246,27 @@ npx @cachly-dev/mcp-server@latest learn-git # Auto-learn lessons from recent git
 
 ---
 
-## MCP Tools (120 total)
+## CI integration — your pipeline teaches the Brain
+
+Every CI run is a lesson: a red→green transition is a proven fix, a green→red one is a
+known cause. Ready-to-paste templates live in
+[`src/ci-integration/`](./src/ci-integration/):
+
+- **GitHub Actions** — copy [`brain-from-ci-action.yml`](./src/ci-integration/brain-from-ci-action.yml)
+  into `.github/workflows/`. It triggers on `workflow_run` (completed) and pushes the
+  outcome to your Brain. Requires `CACHLY_JWT` + `CACHLY_BRAIN_INSTANCE_ID` secrets.
+- **GitLab CI** — copy [`brain-from-ci-gitlab.yml`](./src/ci-integration/brain-from-ci-gitlab.yml)
+  into your pipeline: two `.post` jobs (`on_success` / `on_failure`) with `allow_failure: true`.
+- **Anything else** — [`push-ci-outcome.mjs`](./src/ci-integration/push-ci-outcome.mjs) is a
+  standalone Node.js helper with zero dependencies. It always exits 0 — your CI never
+  fails because of a Brain push.
+
+Already have months of CI history? Backfill it in one call with the **`brain_from_ci`**
+MCP tool — bulk-ingests past outcomes the same way `brain_from_git` ingests commits.
+
+---
+
+## MCP Tools (136 total)
 
 ### 🧠 Session & Memory (most used)
 
@@ -286,6 +306,7 @@ npx @cachly-dev/mcp-server@latest learn-git # Auto-learn lessons from recent git
 | **`causal_trace`** | Root-cause analysis through the Causal Knowledge Graph |
 | **`brain_predict`** / `brain_predict_failures` | Predict likely failures before they happen |
 | **`brain_from_git`** | Bootstrap people + files + lessons from git history — incremental |
+| **`brain_from_ci`** | Bulk-ingest CI outcomes: red→green becomes a fix lesson + causal `fixes` edge, green→red a `causes` edge — `brain_from_git` for CI logs |
 | `memory_consolidate` | Detect contradictions, merge duplicates, expire stale lessons |
 | `ckg_inspect` | Inspect the causal graph around any concept |
 
@@ -305,7 +326,8 @@ npx @cachly-dev/mcp-server@latest learn-git # Auto-learn lessons from recent git
 |------|-------------|
 | `syndicate` / `fedbrain_search` | Contribute to / search the global Knowledge Commons |
 | `brain_marketplace` / `brain_install` | Browse + install curated Domain Brains (Kubernetes, Auth, DB…) into your Brain |
-| `cache_get` / `cache_set` / `semantic_search` / `index_project` | Cache + semantic ops |
+| `cache_get` / `cache_set` / `semantic_search` / `index_project` | Cache + semantic ops — pass `org_id` on `cache_get`/`cache_set` to share the cache org-wide (writes mirror to `org:{org_id}:sem`, reads fall back to it on miss) |
+| `cache_stats` / `cache_org_stats` | Tokenmaxxing ROI: hits, estimated USD saved + monthly projection — per instance or aggregated across your whole org. Zero hits yet? You get a day-1 ROI projection instead. |
 | `list_instances` / `create_instance` / `delete_instance` | Manage Brain instances |
 | `roadmap_add` / `roadmap_next` | Persistent project roadmap stored in the Brain |
 

package/dist/src/brain-watch-hook.d.ts

@@ -0,0 +1,21 @@
+/** Bumped whenever the hook script changes so installers can upgrade old hooks. */
+export declare const BRAIN_WATCH_HOOK_VERSION = "v1";
+export type BrainWatchHookResult = 'written' | 'upgraded' | 'appended' | 'unchanged' | 'skipped-no-git';
+/**
+ * Idempotently install/upgrade the brain_watch post-commit hook in `projectDir`.
+ * Never throws — returns a status string the caller can report. Safe to run
+ * repeatedly; a second call with the same version returns 'unchanged'.
+ */
+export declare function installBrainWatchHook(projectDir: string, instanceId: string, apiKey?: string): Promise<{
+    result: BrainWatchHookResult;
+    hookPath: string;
+}>;
+/**
+ * Build the `.git/hooks/post-commit` shell script for brain_watch.
+ * Uses curl (not Node) so it works without npx. Runs in the background and
+ * always exits 0 — never blocks a commit.
+ *
+ * @param instanceId  Cachly Brain instance to learn into.
+ * @param apiKey      Optional cky_… key; if absent, the script reads $CACHLY_JWT from env.
+ */
+export declare function buildBrainWatchHook(instanceId: string, apiKey?: string): string;

package/dist/src/brain-watch-hook.js

@@ -0,0 +1,86 @@
+// Ambient git post-commit hook builder for Brain auto-learning.
+//
+// Installs a .git/hooks/post-commit script that POSTs the commit data
+// directly to the cachly API via curl — no Node required at hook runtime,
+// so it works even without npx or the MCP server installed locally.
+//
+// Safety contract:
+//   • exit 0 is ALWAYS the last line — the hook never blocks a commit.
+//   • All network calls run in the background (&) with 2>/dev/null.
+//   • Commit message / sha / files are never interpolated into JS source;
+//     they're passed as shell variables in the JSON body (curl --data-raw).
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, chmod, mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/** Bumped whenever the hook script changes so installers can upgrade old hooks. */
+export const BRAIN_WATCH_HOOK_VERSION = 'v1';
+/**
+ * Matches any previously-installed cachly brain_watch block (from its marker
+ * comment down to the trailing `exit 0`), optionally including a shebang.
+ * Used to upgrade old hooks in place rather than duplicating them.
+ */
+const BRAIN_WATCH_BLOCK_RE = /(?:#!\/bin\/sh\n)?# cachly brain_watch[\s\S]*?\nexit 0\n?/;
+/**
+ * Idempotently install/upgrade the brain_watch post-commit hook in `projectDir`.
+ * Never throws — returns a status string the caller can report. Safe to run
+ * repeatedly; a second call with the same version returns 'unchanged'.
+ */
+export async function installBrainWatchHook(projectDir, instanceId, apiKey) {
+    if (!existsSync(resolve(projectDir, '.git'))) {
+        return { result: 'skipped-no-git', hookPath: '' };
+    }
+    const hookDir = resolve(projectDir, '.git', 'hooks');
+    const hookPath = resolve(hookDir, 'post-commit');
+    await mkdir(hookDir, { recursive: true });
+    const script = buildBrainWatchHook(instanceId, apiKey);
+    let existing = '';
+    try {
+        existing = await readFile(hookPath, 'utf-8');
+    }
+    catch { /* no existing hook */ }
+    if (!existing) {
+        await writeFile(hookPath, script + '\n', 'utf-8');
+        await chmod(hookPath, 0o755).catch(() => { });
+        return { result: 'written', hookPath };
+    }
+    if (existing.includes(`cachly brain_watch — Auto-Learn ${BRAIN_WATCH_HOOK_VERSION}`)) {
+        return { result: 'unchanged', hookPath };
+    }
+    if (BRAIN_WATCH_BLOCK_RE.test(existing)) {
+        const replaced = existing.replace(BRAIN_WATCH_BLOCK_RE, script);
+        await writeFile(hookPath, replaced.endsWith('\n') ? replaced : replaced + '\n', 'utf-8');
+        await chmod(hookPath, 0o755).catch(() => { });
+        return { result: 'upgraded', hookPath };
+    }
+    // Foreign hook with no brain_watch block → append ours.
+    await writeFile(hookPath, existing.trimEnd() + '\n\n' + script + '\n', 'utf-8');
+    await chmod(hookPath, 0o755).catch(() => { });
+    return { result: 'appended', hookPath };
+}
+/**
+ * Build the `.git/hooks/post-commit` shell script for brain_watch.
+ * Uses curl (not Node) so it works without npx. Runs in the background and
+ * always exits 0 — never blocks a commit.
+ *
+ * @param instanceId  Cachly Brain instance to learn into.
+ * @param apiKey      Optional cky_… key; if absent, the script reads $CACHLY_JWT from env.
+ */
+export function buildBrainWatchHook(instanceId, apiKey) {
+    return [
+        `#!/bin/sh`,
+        `# cachly brain_watch — Auto-Learn ${BRAIN_WATCH_HOOK_VERSION}`,
+        `# Silently teaches your Brain after every commit — no manual brain_from_git needed.`,
+        ...(apiKey ? [`CACHLY_JWT="${apiKey}"`] : []),
+        `_BW_SHA=$(git rev-parse HEAD 2>/dev/null || echo "")`,
+        `_BW_MSG=$(git log -1 --pretty=%B 2>/dev/null | head -1 | cut -c1-200)`,
+        `_BW_FILES=$(git diff-tree --no-commit-id -r --name-only HEAD 2>/dev/null | tr '\\n' '\\t' | sed 's/\\t$//')`,
+        `(curl -s -o /dev/null -m 8 \\`,
+        `  -X POST "https://api.cachly.dev/api/v1/instances/${instanceId}/learn" \\`,
+        `  -H "Authorization: Bearer \${CACHLY_JWT}" \\`,
+        `  -H "Content-Type: application/json" \\`,
+        `  --data-raw "{\\"message\\":\\"$(echo "$_BW_MSG" | sed 's/"/\\\\"/g')\\",\\"sha\\":\\"$_BW_SHA\\",\\"files\\":[$(echo "$_BW_FILES" | tr '\\t' '\\n' | grep -v '^$' | sed 's/.*/\\"&\\"/' | tr '\\n' ',' | sed 's/,$//')],\\"source\\":\\"brain_watch\\"}" \\`,
+        `) 2>/dev/null &`,
+        `exit 0`,
+    ].join('\n');
+}
+//# sourceMappingURL=brain-watch-hook.js.map

package/dist/src/brain-watch-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-watch-hook.js","sourceRoot":"","sources":["../../src/brain-watch-hook.ts"],"names":[],"mappings":"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"}

package/dist/src/handlers/brain.js

@@ -7,8 +7,43 @@ import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _i
 import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.108';
+const MCP_VERSION = '0.10.113';
 const WHATS_NEW = {
+    '0.10.113': [
+        `📈 **Week-over-week savings trend in \`cache_stats\`**`,
+        `  📅 \`cache_stats\` now shows **7-day hits** + **WoW trend %** (e.g. \`+23.0% vs prev week\`) so ROI momentum is visible, not just the cumulative total.`,
+        `  ⬇️ Goes red (📉) on drops, green (📈) on growth — first week always shows +100% (new).`,
+        `  🔧 Backed by new \`CountHitsInWindow\` repo method + \`hits_last_7d\`, \`hits_prev_7d\`, \`week_over_week_pct\` fields in \`SavingsEstimate\`.`,
+        `  📊 137 MCP tools`,
+    ],
+    '0.10.112': [
+        `⚙️ **Configurable cost_per_call_usd — accurate ROI for any LLM**`,
+        `  💡 New \`set_cost_per_call\` tool: set your real per-call cost (claude-opus-4.8 → $0.02, gpt-5.5 → $0.015, claude-sonnet-4.6 → $0.009, claude-haiku-4.5 → $0.001) so savings estimates in \`cache_stats\` reflect your actual bill.`,
+        `  🔧 New API: \`PUT /api/v1/instances/:id/cost-per-call\` — persisted per instance, used by \`cache_stats\`, org savings, and SSE analytics stream.`,
+        `  📊 137 MCP tools`,
+    ],
+    '0.10.111': [
+        `🏢 **Org-wide ROI + GitLab CI — the CFO number, aggregated**`,
+        `  💰 \`cache_org_stats\` now shows **org-wide Tokenmaxxing ROI**: total savings summed across every instance in your org, monthly projection, top-5 instances by savings. One number for the whole team.`,
+        `  🔌 Backed by new API endpoint \`GET /api/v1/orgs/:id/savings\` (org members only)`,
+        `  🦊 GitLab CI integration: \`brain-from-ci-gitlab.yml\` — two \`.post\` jobs (on_success/on_failure), same helper script, pipeline never fails because of Brain push`,
+        `  🛠️ GitHub Action template fixed: \`secrets.*\` in job-level \`if\` is invalid — guard removed (helper script skips cleanly on missing secrets)`,
+        `  📊 136 MCP tools`,
+    ],
+    '0.10.110': [
+        `🏢 **Zero friction: ROI-Projektor, Org-Shared-Cache, CI ready-to-paste**`,
+        `  📈 \`cache_stats\` — zero-hit projection calculator: shows expected monthly savings for 5/10/20-dev teams before a single cache hit lands. ROI visible from day 1.`,
+        `  🏢 New \`cache_org_stats\` — shared org-level cache stats across multiple instances. Convention-based (\`org:{id}:sem\`), zero API changes needed.`,
+        `  🔗 \`cache_set\`/\`cache_get\` now accept optional \`org_id\` — write to personal + org namespace, fall back to org on miss. Fully backwards-compatible.`,
+        `  📋 Copy-paste CI integration: \`brain-from-ci-action.yml\` → Brain self-calibrates confidence on every GitHub Actions run. No config beyond two repo secrets.`,
+        `  📊 136 MCP tools`,
+    ],
+    '0.10.109': [
+        `💰 **Tokenmaxxing ROI + Closed-loop CI learning**`,
+        `  📊 \`cache_stats\` now shows a **Tokenmaxxing ROI** section — total tokens saved, monthly cost projection, and top 3 most-cached prompts. Finally a number you can show the CFO.`,
+        `  🔄 New \`brain_from_ci\` — bulk-ingest CI history into the Brain (red→green = learned fix, green→red = CKG causal edge). The brain_from_git equivalent for CI. Bootstrap the Brain from your CI logs in one call.`,
+        `  📊 134 MCP tools`,
+    ],
     '0.10.108': [
         `🧠 **Focused briefing + trustworthy autopilot**`,
         `  🎯 New \`session_start_summary\` — top-N focused briefing by topic. Scores lessons by relevance × confidence + recall_count + severity + recency. Use it for a quick pre-brief without loading the full Brain.`,