@cachly-dev/mcp-server 0.10.82 → 0.10.84

package/dist/src/handlers/viz.d.ts

@@ -0,0 +1,6 @@
+import type { Redis } from 'ioredis';
+type GetConnection = (instanceId: string) => Promise<Redis>;
+type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
+export declare const VIZ_TOOL_NAMES: Set<string>;
+export declare function handleVizTool(name: string, args: Record<string, unknown>, getConnection: GetConnection, _apiFetch: ApiFetch): Promise<string | null>;
+export {};

package/dist/src/handlers/viz.js

@@ -0,0 +1,148 @@
+import { safeJsonParse } from '../utils.js';
+export const VIZ_TOOL_NAMES = new Set(['brain_graph']);
+// Stable color groups so the 3D frontend can theme node kinds consistently.
+const NODE_GROUP = {
+    concept: 1, person: 2, file: 3, service: 4,
+};
+function nodeKind(id) {
+    if (id.startsWith('person:'))
+        return 'person';
+    if (id.startsWith('file:'))
+        return 'file';
+    if (id.startsWith('service:'))
+        return 'service';
+    return 'concept';
+}
+function nodeLabel(n, kind) {
+    if (kind === 'person')
+        return n.handle ?? n.id.replace(/^person:/, '');
+    if (kind === 'file')
+        return (n.path ?? n.id.replace(/^file:/, '')).split('/').slice(-1)[0] ?? n.id;
+    if (kind === 'service')
+        return n.name ?? n.id.replace(/^service:/, '');
+    return n.id;
+}
+async function scanAll(redis, match, limit) {
+    const keys = [];
+    const stream = redis.scanStream({ match, count: 200 });
+    await new Promise((resolve, reject) => {
+        stream.on('data', (batch) => {
+            for (const k of batch) {
+                if (keys.length < limit)
+                    keys.push(k);
+            }
+            if (keys.length >= limit)
+                stream.destroy();
+        });
+        stream.on('end', resolve);
+        stream.on('close', resolve);
+        stream.on('error', reject);
+    });
+    return keys;
+}
+export async function handleVizTool(name, args, getConnection, _apiFetch) {
+    if (name !== 'brain_graph')
+        return null;
+    const { instance_id, max_nodes = 400, domain = '', min_confidence = 0, format = 'json', } = args;
+    const redis = await getConnection(instance_id);
+    const nodeCap = Math.max(1, Math.min(2000, Number(max_nodes) || 400));
+    const minConf = Math.max(0, Math.min(1, Number(min_confidence) || 0));
+    const domainFilter = String(domain || '').toLowerCase().trim();
+    // ── Nodes ────────────────────────────────────────────────────────────────
+    const nodeKeys = await scanAll(redis, 'cachly:ckg:node:*', nodeCap);
+    const nodes = [];
+    const present = new Set();
+    for (const key of nodeKeys) {
+        const raw = await redis.get(key);
+        const stored = safeJsonParse(raw, null);
+        if (!stored || !stored.id)
+            continue;
+        const kind = nodeKind(stored.id);
+        const ndomain = String(stored.domain ?? '').toLowerCase();
+        if (domainFilter && !ndomain.includes(domainFilter) && !stored.id.toLowerCase().includes(domainFilter))
+            continue;
+        const count = Number(stored.count ?? 1) || 1;
+        nodes.push({
+            id: stored.id,
+            name: nodeLabel(stored, kind),
+            type: kind,
+            group: NODE_GROUP[kind] ?? 0,
+            domain: stored.domain ?? '',
+            val: Math.max(1, Math.round(Math.sqrt(count) * 3)),
+            count,
+        });
+        present.add(stored.id);
+    }
+    // ── Edges ──────────────────────────────────────────────────────────────────
+    // Edge keys: cachly:ckg:edge:{from}:{edgeType}:{to}. We read the stored CKGEdge
+    // (not the key) so from/to/confidence come straight from the value — robust to
+    // ids that themselves contain ':' (e.g. "docker:layer-cache").
+    const edgeKeys = await scanAll(redis, 'cachly:ckg:edge:*', nodeCap * 8);
+    const links = [];
+    let edgesSkippedConf = 0;
+    let edgesSkippedDangling = 0;
+    for (const key of edgeKeys) {
+        const raw = await redis.get(key);
+        const edge = safeJsonParse(raw, null);
+        if (!edge || !edge.from || !edge.to)
+            continue;
+        if ((edge.confidence ?? 0) < minConf) {
+            edgesSkippedConf++;
+            continue;
+        }
+        // Drop dangling edges (endpoint filtered out) so the 3D graph stays consistent.
+        if (!present.has(edge.from) || !present.has(edge.to)) {
+            edgesSkippedDangling++;
+            continue;
+        }
+        links.push({
+            source: edge.from,
+            target: edge.to,
+            type: edge.edgeType ?? 'related',
+            value: Number((edge.confidence ?? 0).toFixed(3)),
+            trials: edge.trials ?? 0,
+        });
+    }
+    const byType = {};
+    for (const n of nodes)
+        byType[n.type] = (byType[n.type] ?? 0) + 1;
+    const graph = {
+        schema: 'cachly.brain_graph/v1',
+        nodes,
+        links,
+        meta: {
+            instance_id,
+            generated_at: new Date().toISOString(),
+            node_count: nodes.length,
+            link_count: links.length,
+            node_types: byType,
+            truncated: nodeKeys.length >= nodeCap,
+            filters: { domain: domainFilter || null, min_confidence: minConf, max_nodes: nodeCap },
+        },
+    };
+    if (format === 'summary') {
+        const lines = [
+            `## 🧠 Brain Graph — 3D Viz Export`,
+            '',
+            `**${nodes.length}** nodes · **${links.length}** links`,
+            ...Object.entries(byType).map(([t, c]) => `  • ${t}: ${c}`),
+            edgesSkippedConf ? `  • ${edgesSkippedConf} edges below confidence ${minConf}` : '',
+            edgesSkippedDangling ? `  • ${edgesSkippedDangling} dangling edges dropped` : '',
+            '',
+            graph.meta.truncated ? `⚠️ Truncated at ${nodeCap} nodes — raise \`max_nodes\` for the full graph.` : '',
+            '',
+            `Call \`brain_graph(instance_id="${instance_id}", format="json")\` for the full payload the 3D frontend renders.`,
+        ].filter(Boolean);
+        return lines.join('\n');
+    }
+    // Default: emit the renderable payload in a fenced block so the frontend /
+    // API can lift it verbatim into react-force-graph-3d.
+    return [
+        `🧠 **Brain Graph** — ${nodes.length} nodes, ${links.length} links (schema \`cachly.brain_graph/v1\`)`,
+        '',
+        '```json',
+        JSON.stringify(graph, null, 2),
+        '```',
+    ].join('\n');
+}
+//# sourceMappingURL=viz.js.map

package/dist/src/handlers/viz.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viz.js","sourceRoot":"","sources":["../../../src/handlers/viz.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAoB5C,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,UAAU,GAA2B;IACzC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3C,CAAC;AA0BF,SAAS,QAAQ,CAAC,EAAU;IAC1B,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC9C,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,SAAS,CAAC,CAAa,EAAE,IAAqB;IACrD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACvE,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;IACnG,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACvE,OAAO,CAAC,CAAC,EAAE,CAAC;AACd,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,KAAY,EAAE,KAAa,EAAE,KAAa;IAC/D,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACvD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAe,EAAE,EAAE;YACpC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK;oBAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACxC,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,IAAI,KAAK;gBAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC1B,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC5B,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAY,EACZ,IAA6B,EAC7B,aAA4B,EAC5B,SAAmB;IAEnB,IAAI,IAAI,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IAExC,MAAM,EACJ,WAAW,EACX,SAAS,GAAG,GAAG,EACf,MAAM,GAAG,EAAE,EACX,cAAc,GAAG,CAAC,EAClB,MAAM,GAAG,MAAM,GAChB,GAAG,IAMH,CAAC;IAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtE,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IAE/D,4EAA4E;IAC5E,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,CAAC,CAAC;IACpE,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,MAAM,GAAG,aAAa,CAAoB,GAAG,EAAE,IAAI,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,SAAS;QACpC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACjC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC1D,IAAI,YAAY,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,SAAS;QACjH,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC;YACT,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC;YAC7B,IAAI,EAAE,IAAI;YACV,KAAK,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;YAC3B,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YAClD,KAAK;SACN,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,8EAA8E;IAC9E,gFAAgF;IAChF,+EAA+E;IAC/E,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IACxE,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,IAAI,gBAAgB,GAAG,CAAC,CAAC;IACzB,IAAI,oBAAoB,GAAG,CAAC,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,aAAa,CAAiB,GAAG,EAAE,IAAI,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,SAAS;QAC9C,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC;YAAC,gBAAgB,EAAE,CAAC;YAAC,SAAS;QAAC,CAAC;QACvE,gFAAgF;QAChF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAAC,oBAAoB,EAAE,CAAC;YAAC,SAAS;QAAC,CAAC;QAC3F,KAAK,CAAC,IAAI,CAAC;YACT,MAAM,EAAE,IAAI,CAAC,IAAI;YACjB,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,IAAI,EAAE,IAAI,CAAC,QAAQ,IAAI,SAAS;YAChC,KAAK,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAChD,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC;SACzB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAElE,MAAM,KAAK,GAAG;QACZ,MAAM,EAAE,uBAAuB;QAC/B,KAAK;QACL,KAAK;QACL,IAAI,EAAE;YACJ,WAAW;YACX,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACtC,UAAU,EAAE,KAAK,CAAC,MAAM;YACxB,UAAU,EAAE,KAAK,CAAC,MAAM;YACxB,UAAU,EAAE,MAAM;YAClB,SAAS,EAAE,QAAQ,CAAC,MAAM,IAAI,OAAO;YACrC,OAAO,EAAE,EAAE,MAAM,EAAE,YAAY,IAAI,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE;SACvF;KACF,CAAC;IAEF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG;YACZ,mCAAmC;YACnC,EAAE;YACF,KAAK,KAAK,CAAC,MAAM,gBAAgB,KAAK,CAAC,MAAM,UAAU;YACvD,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3D,gBAAgB,CAAC,CAAC,CAAC,OAAO,gBAAgB,2BAA2B,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE;YACnF,oBAAoB,CAAC,CAAC,CAAC,OAAO,oBAAoB,yBAAyB,CAAC,CAAC,CAAC,EAAE;YAChF,EAAE;YACF,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,OAAO,kDAAkD,CAAC,CAAC,CAAC,EAAE;YACxG,EAAE;YACF,mCAAmC,WAAW,mEAAmE;SAClH,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAClB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,2EAA2E;IAC3E,sDAAsD;IACtD,OAAO;QACL,wBAAwB,KAAK,CAAC,MAAM,WAAW,KAAK,CAAC,MAAM,2CAA2C;QACtG,EAAE;QACF,SAAS;QACT,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9B,KAAK;KACN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/src/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { jwtExpiryMs, checkJwt, handleApiError, diagnoseAuth, planAuthHeal } from './auth.js';
+import { jwtExpiryMs, checkJwt, handleApiError, diagnoseAuth, planAuthHeal, readClientCredentialsFromEnv, buildClientCredentialsBody, clientCredentialsTokenUrl } from './auth.js';
 import { handleTcoTool } from './handlers/tco.js';
 import { notify } from './notifier.js';
 import { fileURLToPath } from 'node:url';
@@ -65,7 +65,7 @@ import { Redis } from 'ioredis';
 let API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 let JWT = process.env.CACHLY_JWT ?? '';
 const _EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.10.82';
+const CURRENT_VERSION = '0.10.84';
 // Max time to wait for a freshly-provisioned instance to become "running" before
 // giving up. Free-tier provisioning in high-latency regions can take 45–90s, so the
 // old hard-coded 25s caused spurious "instance_not_reachable" on first run.
@@ -610,6 +610,7 @@ import { handleAdvancedTool } from './handlers/advanced.js';
 import { handleSyndicateTool } from './handlers/syndicate.js';
 import { handleFedbrainTool, _lastBrainFromGitCounts } from './handlers/fedbrain.js';
 import { handleShareTool } from './handlers/share.js';
+import { handleVizTool } from './handlers/viz.js';
 // ── Tools (imported from tools.ts) ─────────────────────────────────────────
 import { TOOLS } from './tools.js';
 // ── Handlers ──────────────────────────────────────────────────────────────────
@@ -882,6 +883,9 @@ async function handleTool(name, args) {
     const shareResult = await handleShareTool(name, args, getConnection, apiFetch);
     if (shareResult !== null)
         return shareResult;
+    const vizResult = await handleVizTool(name, args, getConnection, apiFetch);
+    if (vizResult !== null)
+        return vizResult;
     const fedbrainResult = await handleFedbrainTool(name, args, getConnection, apiFetch);
     if (fedbrainResult !== null) {
         // brain_from_git and brain_predict_failures are in fedbrain handler.
@@ -1973,6 +1977,36 @@ if (process.argv[2] === 'publish') {
     }
     process.exit(0);
 }
+// ── CLI: cachly tool-specs / openapi ───────────────────────────────────────────
+// Emit the 114-tool surface in any agent framework's dialect, derived from the
+// single TOOLS source of truth. Lets OpenAI Assistants, the Anthropic Messages
+// API, LangChain, CrewAI and AutoGen wrap cachly without hand-written glue.
+//   npx @cachly-dev/mcp-server tool-specs --format=openai   > cachly.openai.json
+//   npx @cachly-dev/mcp-server openapi                      > cachly.openapi.json
+if (process.argv[2] === 'tool-specs' || process.argv[2] === 'openapi') {
+    const { renderToolSpecs } = await import('./toolspecs.js');
+    // Accept both "--format openai" and "--format=openai".
+    let format = 'openapi';
+    if (process.argv[2] !== 'openapi') {
+        const eqArg = process.argv.find(a => a.startsWith('--format='));
+        if (eqArg) {
+            format = eqArg.slice('--format='.length);
+        }
+        else {
+            const fmtFlag = process.argv.indexOf('--format');
+            if (fmtFlag !== -1)
+                format = process.argv[fmtFlag + 1] ?? 'openapi';
+        }
+    }
+    const valid = ['openapi', 'openai', 'anthropic', 'langchain'];
+    if (!valid.includes(format)) {
+        process.stderr.write(`\n❌ Unknown format "${format}". Use one of: ${valid.join(', ')}\n\n`);
+        process.exit(1);
+    }
+    // Exit only after stdout has fully flushed — on a pipe, write() is async and an
+    // immediate process.exit() truncates large payloads (~64KB) mid-flush.
+    process.stdout.write(renderToolSpecs(TOOLS, format, CURRENT_VERSION) + '\n', () => process.exit(0));
+}
 // ── CLI: cachly badge ─────────────────────────────────────────────────────────
 // Outputs the Markdown + HTML snippet for embedding a live Brain lesson-count
 // badge in any README or website. Badge SVG served by cachly API (public, no auth).
@@ -3099,6 +3133,40 @@ if (process.argv[2] === 'learn-git') {
     process.exit(0);
 }
 // ── Start ─────────────────────────────────────────────────────────────────────
+// M2M / headless auth: if no JWT but client credentials are present, run the
+// OAuth2 client_credentials grant before any credential-missing handling. This
+// makes cachly fully non-interactive for CI runners, agent orchestrators and
+// AI-to-AI pipelines — no device flow, no human, no browser.
+if (!JWT) {
+    const creds = readClientCredentialsFromEnv();
+    if (creds) {
+        try {
+            const res = await fetch(clientCredentialsTokenUrl(creds), {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: buildClientCredentialsBody(creds),
+                signal: AbortSignal.timeout(8000),
+            });
+            if (res.ok) {
+                const tok = await res.json();
+                if (tok.access_token) {
+                    JWT = tok.access_token;
+                    setEmbedJwt(tok.access_token);
+                    sendFunnelEvent('m2m_auth_completed', { grant: 'client_credentials', client_id: creds.clientId });
+                    process.stderr.write('🤖 cachly: authenticated via client_credentials (M2M, headless).\n');
+                }
+            }
+            else {
+                process.stderr.write(`⚠️  cachly: client_credentials auth failed (${res.status}). Check CACHLY_CLIENT_ID / CACHLY_CLIENT_SECRET.\n`);
+                sendFunnelEvent('m2m_auth_failed', { status: res.status });
+            }
+        }
+        catch (err) {
+            process.stderr.write(`⚠️  cachly: client_credentials auth error: ${err.message}\n`);
+            sendFunnelEvent('m2m_auth_failed', { reason: 'network' });
+        }
+    }
+}
 // Credential-missing handling at startup. The critical distinction is HOW we were
 // launched, because writing anything to stdout in stdio-MCP mode corrupts the
 // JSON-RPC stream and exiting kills the zero-credential device-flow onboarding.
@@ -3106,7 +3174,7 @@ if (process.argv[2] === 'learn-git') {
 //   • Editor as an MCP stdio server (non-TTY)  → ONE stderr hint, then KEEP RUNNING
 //     so tools/list works and the first tool call starts the browser sign-in.
 // Skip entirely for CLI subcommands that intentionally run without credentials.
-const _cliNoAuthCommands = ['demo', 'share', 'publish', 'health', 'setup', 'init', 'digest', 'invite', 'badge', 'join', 'upgrade'];
+const _cliNoAuthCommands = ['demo', 'share', 'publish', 'health', 'setup', 'init', 'digest', 'invite', 'badge', 'join', 'upgrade', 'tool-specs', 'openapi'];
 if (!JWT && !_cliNoAuthCommands.includes(process.argv[2] ?? '')) {
     const runningInTerminal = !process.argv[2] && process.stdout.isTTY === true && _isMain;
     if (runningInTerminal) {