feat(m2m): OAuth2 client_credentials + agent-framework tool-spec export (v0.10.84)

Brings cachly to every caller — human, CI, agent, or AI-to-AI — not just MCP clients.

M2M / headless auth:
- auth.ts: readClientCredentialsFromEnv / buildClientCredentialsBody /
  clientCredentialsTokenUrl — standard OAuth2 client_credentials grant
- index.ts: at startup, if no JWT but CACHLY_CLIENT_ID + CACHLY_CLIENT_SECRET are
  set, mint an access token against Keycloak — fully non-interactive (no device flow)
- m2m_auth_completed / m2m_auth_failed telemetry events

Agent-ecosystem tool-spec exporter (zero new deps, derived from TOOLS):
- toolspecs.ts: toOpenAITools / toAnthropicTools / toLangChainTools / toOpenAPI
- CLI: `tool-specs --format=openai|anthropic|langchain` and `openapi` (OpenAPI 3.1)
- exit-after-flush fix so large (>64KB) payloads aren't truncated on a pipe

14 new tests (auth + toolspecs); 591/591 passing; lint clean.

https://claude.ai/code/session_01LhzzcUPCuRAfqizEtyGoJr

Author: HeinrichNebula

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.10.83",
+  "version": "0.10.84",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
   "description": "Your AI forgets everything between sessions. cachly fixes that permanently. Persistent memory + causal root-cause analysis for Claude Code, Cursor, Copilot & Windsurf. Learns from every bug fix, git commit, and CI run automatically. Arrives pre-briefed. Predicts failures before they happen. 107 MCP tools · Free tier forever · GDPR · EU servers.",
   "type": "module",

server.json

@@ -6,13 +6,13 @@
     "url": "https://github.com/cachly-dev/cachly-mcp",
     "source": "github"
   },
-  "version": "0.10.83",
+  "version": "0.10.84",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.10.83",
+      "version": "0.10.84",
       "transport": {
         "type": "stdio"
       }

src/__tests__/auth.test.ts

@@ -1,7 +1,9 @@
 import { describe, it, expect } from 'vitest';
 import { ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { jwtExpiryMs, checkJwt, handleApiError,
-         diagnoseAuth, planAuthHeal, isLongLivedApiKey, NEAR_EXPIRY_MS } from '../auth.js';
+         diagnoseAuth, planAuthHeal, isLongLivedApiKey, NEAR_EXPIRY_MS,
+         readClientCredentialsFromEnv, buildClientCredentialsBody,
+         clientCredentialsTokenUrl, DEFAULT_AUTH_BASE } from '../auth.js';
 
 function makeJwt(payload: Record<string, unknown>): string {
   const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
@@ -226,3 +228,44 @@ describe('planAuthHeal', () => {
     expect(planAuthHeal(diagnoseAuth('cky_live_abc'))).toBe('none');
   });
 });
+
+describe('M2M client_credentials auth', () => {
+  it('returns null when either credential is missing', () => {
+    expect(readClientCredentialsFromEnv({})).toBeNull();
+    expect(readClientCredentialsFromEnv({ CACHLY_CLIENT_ID: 'x' } as NodeJS.ProcessEnv)).toBeNull();
+    expect(readClientCredentialsFromEnv({ CACHLY_CLIENT_SECRET: 'y' } as NodeJS.ProcessEnv)).toBeNull();
+  });
+
+  it('reads both credentials with sensible defaults', () => {
+    const c = readClientCredentialsFromEnv({ CACHLY_CLIENT_ID: 'svc', CACHLY_CLIENT_SECRET: 'shh' } as NodeJS.ProcessEnv);
+    expect(c).toEqual({ clientId: 'svc', clientSecret: 'shh', scope: 'openid', authBase: DEFAULT_AUTH_BASE });
+  });
+
+  it('honors scope and self-host auth base overrides', () => {
+    const c = readClientCredentialsFromEnv({
+      CACHLY_CLIENT_ID: 'svc', CACHLY_CLIENT_SECRET: 'shh',
+      CACHLY_CLIENT_SCOPE: 'openid profile', CACHLY_AUTH_URL: 'https://kc.local/realms/r/protocol/openid-connect',
+    } as NodeJS.ProcessEnv);
+    expect(c?.scope).toBe('openid profile');
+    expect(c?.authBase).toBe('https://kc.local/realms/r/protocol/openid-connect');
+  });
+
+  it('builds a valid client_credentials form body', () => {
+    const body = buildClientCredentialsBody({ clientId: 'svc', clientSecret: 's/h h', scope: 'openid' });
+    const p = new URLSearchParams(body);
+    expect(p.get('grant_type')).toBe('client_credentials');
+    expect(p.get('client_id')).toBe('svc');
+    expect(p.get('client_secret')).toBe('s/h h'); // properly url-encoded round-trip
+    expect(p.get('scope')).toBe('openid');
+  });
+
+  it('omits scope from the body when not provided', () => {
+    const body = buildClientCredentialsBody({ clientId: 'svc', clientSecret: 'shh' });
+    expect(new URLSearchParams(body).has('scope')).toBe(false);
+  });
+
+  it('derives the token endpoint from the realm base', () => {
+    expect(clientCredentialsTokenUrl({ clientId: 'a', clientSecret: 'b' })).toBe(`${DEFAULT_AUTH_BASE}/token`);
+    expect(clientCredentialsTokenUrl({ clientId: 'a', clientSecret: 'b', authBase: 'https://kc.local/x' })).toBe('https://kc.local/x/token');
+  });
+});

src/__tests__/toolspecs.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Unit tests for the agent-framework tool-spec exporter.
+ *
+ * Verifies that every dialect (OpenAPI 3.1, OpenAI, Anthropic, LangChain) is
+ * derived faithfully from the real TOOLS source of truth — so the wider agent
+ * ecosystem can wrap cachly without hand-written glue.
+ *
+ * Run: npx vitest run src/__tests__/toolspecs.test.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import { TOOLS } from '../tools.js';
+import {
+  toOpenAITools, toAnthropicTools, toLangChainTools, toOpenAPI, renderToolSpecs,
+  type ToolDef,
+} from '../toolspecs.js';
+
+const tools = TOOLS as unknown as ReadonlyArray<ToolDef>;
+
+describe('tool-spec exporter', () => {
+  it('covers every MCP tool in each dialect', () => {
+    expect(toOpenAITools(tools)).toHaveLength(tools.length);
+    expect(toAnthropicTools(tools)).toHaveLength(tools.length);
+    expect(toLangChainTools(tools)).toHaveLength(tools.length);
+    expect(tools.length).toBeGreaterThanOrEqual(114);
+  });
+
+  it('OpenAI format uses {type:function, function:{name,description,parameters}}', () => {
+    const t = toOpenAITools(tools)[0] as { type: string; function: { name: string; description: string; parameters: unknown } };
+    expect(t.type).toBe('function');
+    expect(t.function.name).toBe(tools[0].name);
+    expect(t.function.description).toBe(tools[0].description);
+    expect(t.function.parameters).toEqual(tools[0].inputSchema);
+  });
+
+  it('Anthropic format uses input_schema (not parameters)', () => {
+    const t = toAnthropicTools(tools)[0] as Record<string, unknown>;
+    expect(t.name).toBe(tools[0].name);
+    expect(t).toHaveProperty('input_schema');
+    expect(t).not.toHaveProperty('parameters');
+  });
+
+  it('LangChain format exposes name/description/schema', () => {
+    const t = toLangChainTools(tools)[0] as Record<string, unknown>;
+    expect(t.name).toBe(tools[0].name);
+    expect(t).toHaveProperty('schema');
+  });
+
+  it('OpenAPI is a valid 3.1 doc with one POST path per tool', () => {
+    const doc = toOpenAPI(tools, '9.9.9') as { openapi: string; paths: Record<string, { post: unknown }>; security: unknown[] };
+    expect(doc.openapi).toBe('3.1.0');
+    expect(Object.keys(doc.paths)).toHaveLength(tools.length);
+    for (const t of tools) {
+      const path = doc.paths[`/mcp/tools/${t.name}`] as { post: { operationId: string } };
+      expect(path).toBeTruthy();
+      expect(path.post.operationId).toBe(t.name);
+    }
+    expect(doc.security).toEqual([{ bearerAuth: [] }]);
+  });
+
+  it('OpenAPI requestBody.required reflects whether the tool has required params', () => {
+    const withReq = tools.find(t => (t.inputSchema?.required?.length ?? 0) > 0)!;
+    const noReq = tools.find(t => (t.inputSchema?.required?.length ?? 0) === 0)!;
+    const doc = toOpenAPI(tools, '1.0.0') as { paths: Record<string, { post: { requestBody: { required: boolean } } }> };
+    expect(doc.paths[`/mcp/tools/${withReq.name}`].post.requestBody.required).toBe(true);
+    expect(doc.paths[`/mcp/tools/${noReq.name}`].post.requestBody.required).toBe(false);
+  });
+
+  it('renderToolSpecs emits parseable JSON for every format', () => {
+    for (const fmt of ['openapi', 'openai', 'anthropic', 'langchain'] as const) {
+      const out = renderToolSpecs(tools, fmt, '0.0.1');
+      expect(() => JSON.parse(out)).not.toThrow();
+    }
+  });
+
+  it('embeds the version into the OpenAPI info block', () => {
+    const doc = JSON.parse(renderToolSpecs(tools, 'openapi', '7.7.7')) as { info: { version: string } };
+    expect(doc.info.version).toBe('7.7.7');
+  });
+});

src/auth.ts

@@ -122,6 +122,54 @@ export function checkJwt(jwt: string): void {
   }
 }
 
+// ── M2M / headless auth (OAuth2 client_credentials) ──────────────────────────
+// For machine-to-machine callers — CI runners, agent orchestrators, AI-to-AI
+// pipelines — there is no human to complete a device flow. When CACHLY_CLIENT_ID
+// and CACHLY_CLIENT_SECRET are present we run the standard OAuth2
+// client_credentials grant against Keycloak and use the resulting access token
+// exactly like a CACHLY_JWT. Fully non-interactive.
+
+export const DEFAULT_AUTH_BASE = 'https://auth.cachly.dev/realms/cachly/protocol/openid-connect';
+
+export interface ClientCredentials {
+  clientId: string;
+  clientSecret: string;
+  scope?: string;
+  /** Override the Keycloak realm token base (self-host). */
+  authBase?: string;
+}
+
+/** Read M2M client credentials from the environment, if both are present. */
+export function readClientCredentialsFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): ClientCredentials | null {
+  const clientId = env.CACHLY_CLIENT_ID;
+  const clientSecret = env.CACHLY_CLIENT_SECRET;
+  if (!clientId || !clientSecret) return null;
+  return {
+    clientId,
+    clientSecret,
+    scope: env.CACHLY_CLIENT_SCOPE || 'openid',
+    authBase: env.CACHLY_AUTH_URL || DEFAULT_AUTH_BASE,
+  };
+}
+
+/** Build the application/x-www-form-urlencoded body for a client_credentials grant. */
+export function buildClientCredentialsBody(c: ClientCredentials): string {
+  const params = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: c.clientId,
+    client_secret: c.clientSecret,
+  });
+  if (c.scope) params.set('scope', c.scope);
+  return params.toString();
+}
+
+/** Token endpoint URL for a given credentials/realm config. */
+export function clientCredentialsTokenUrl(c: ClientCredentials): string {
+  return `${c.authBase ?? DEFAULT_AUTH_BASE}/token`;
+}
+
 export function handleApiError(status: number, detail: string): never {
   if (status === 401) {
     throw new McpError(

src/handlers/brain.ts

@@ -14,8 +14,15 @@ import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.83';
+const MCP_VERSION = '0.10.84';
 const WHATS_NEW: Record<string, string[]> = {
+  '0.10.84': [
+    `🤖 **M2M & agent-ecosystem reach — cachly for every caller, human or machine**`,
+    `  🔑 OAuth2 \`client_credentials\` grant — set CACHLY_CLIENT_ID + CACHLY_CLIENT_SECRET for fully headless auth (CI, agents, AI-to-AI)`,
+    `  🗂️ \`npx ... tool-specs --format=openai|anthropic|langchain\` — export all 114 tools in any framework's dialect`,
+    `  🌐 \`npx ... openapi\` — OpenAPI 3.1 doc (1 POST path per tool) for Assistants / codegen / Postman`,
+    `  🧪 14 new tests: client_credentials helpers, all four spec dialects, OpenAPI required-body inference`,
+  ],
   '0.10.83': [
     `🧠 **Brain Viz — 3D graph export**`,
     `  🌐 \`brain_graph(instance_id)\` — exports the Causal Knowledge Graph as a render-ready {nodes, links} payload`,

src/index.ts

@@ -1,5 +1,6 @@
 #!/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 type { FunnelEventName, DashboardMetrics } from './telemetry-types.js';
 import { handleTcoTool } from './handlers/tco.js';
 import { notify } from './notifier.js';
@@ -75,7 +76,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.83';
+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
@@ -2051,6 +2052,38 @@ 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 as unknown as Parameters<typeof renderToolSpecs>[0], format as 'openapi' | 'openai' | 'anthropic' | 'langchain', 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).
@@ -3176,14 +3209,47 @@ if (process.argv[2] === 'learn-git') {
 
 // ── 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() as { access_token?: string };
+        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 as Error).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.
 //   • Human in a real terminal (TTY), no args  → show the setup banner, exit 0.
 //   • 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) {

src/telemetry-types.ts

@@ -18,6 +18,8 @@ export type FunnelEventName =
   | 'device_flow_completed'
   | 'device_flow_failed'
   | 'auth_self_healed'
+  | 'm2m_auth_completed'
+  | 'm2m_auth_failed'
   | 'setup_started'
   | 'setup_auth_started'
   | 'setup_auth_completed'