@cachly-dev/mcp-server 0.10.26 → 0.10.40

package/scripts/postinstall.js

@@ -2,28 +2,28 @@
 // Shown once after: npm install @cachly-dev/mcp-server
 
 const c = {
-  reset: "\x1b[0m",
-  bold: "\x1b[1m",
+  reset:  "\x1b[0m",
+  bold:   "\x1b[1m",
   violet: "\x1b[35m",
-  green: "\x1b[32m",
-  cyan: "\x1b[36m",
+  green:  "\x1b[32m",
+  cyan:   "\x1b[36m",
+  dim:    "\x1b[2m",
   yellow: "\x1b[33m",
-  dim: "\x1b[2m",
 };
 
 const line = `${c.dim}─────────────────────────────────────────────────────${c.reset}`;
 
 console.log(`
 ${line}
-  ${c.bold}${c.violet}🧠 Cachly Brain MCP Server${c.reset} ${c.dim}v${process.env.npm_package_version ?? ""}${c.reset}
+  ${c.bold}${c.violet}🧠 cachly AI Brain${c.reset} ${c.dim}v${process.env.npm_package_version ?? ""}${c.reset}
 
-  ${c.bold}Your AI forgets everything after each session. This fixes that.${c.reset}
+  ${c.bold}One command sets everything up:${c.reset}
 
-  ${c.green}Setup in 30 seconds (auto-detects all your editors):${c.reset}
-  ${c.cyan}npx @cachly-dev/init${c.reset}
+  ${c.cyan}npx @cachly-dev/mcp-server@latest setup${c.reset}
 
-  ${c.dim}Claude Code · Cursor · GitHub Copilot · Windsurf · Continue${c.reset}
-  ${c.dim}Free tier · GDPR · EU servers · No credit card${c.reset}
+  Signs you in → detects your editors → writes all MCP configs
+  automatically → adds Brain rules to CLAUDE.md.
 
+  ${c.green}No credentials. No credit card. Free forever.${c.reset}
+  ${c.dim}Other editors: https://cachly.dev/docs/mcp${c.reset}
 ${line}`);
-

package/server.json

@@ -1,27 +1,21 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.cachly-dev/cachly-mcp",
-  "description": "Give Claude a persistent memory that never forgets. cachly learns automatically from every session, bug fix, and git commit — no manual calls needed. Arrives pre-briefed. Predicts failures before they happen. One-click sign-in (OAuth Device Flow) · 63 tools · Free tier · EU servers · works with Claude Code, Cursor, Copilot, Windsurf.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 89 MCP tools · Free tier · EU servers · GDPR.",
   "repository": {
     "url": "https://github.com/cachly-dev/cachly-mcp",
     "source": "github"
   },
-  "version": "0.10.1",
+  "version": "0.10.23",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.10.1",
+      "version": "0.10.23",
       "transport": {
         "type": "stdio"
       }
     }
-  ],
-  "remotes": [
-    {
-      "transportType": "streamable-http",
-      "url": "https://mcp.cachly.dev/mcp"
-    }
   ]
 }

package/smithery.yaml

@@ -1,3 +1,12 @@
+name: cachly AI Brain
+description: >
+  Persistent AI memory for Claude Code, Cursor, Copilot, Windsurf, Cline & Zed.
+  Your AI remembers every lesson, fix, and architecture decision — forever.
+  Features: causal root-cause analysis (causal_trace), failure prediction (brain_predict),
+  git-ambient learning (brain_from_git), team knowledge sharing, Memory Crystals,
+  BM25+ search in 11 languages. 89 MCP tools. Free tier. GDPR. German servers.
+  Zero-config: sign in once via browser, auto-provisions your Brain instance.
+
 startCommand:
   type: stdio
   configSchema:
@@ -5,23 +14,21 @@ startCommand:
     properties:
       CACHLY_JWT:
         type: string
-        title: "API Key"
-        description: "Optional. Leave blank — on your first tool call the server starts a one-click browser sign-in (OAuth Device Flow) and auto-provisions your free Brain instance. No copy-paste, no dashboard visit required. Or pre-fill with your API key from cachly.dev/setup-ai."
-        default: ""
+        title: "API Key (optional — sign in via browser on first use)"
+        description: "Leave blank for zero-config: on your first tool call the server opens a browser sign-in (OAuth Device Flow) and auto-provisions your Brain instance. Or pre-fill with your API key from cachly.dev/setup-ai."
         examples:
           - "cky_live_abc123..."
       CACHLY_BRAIN_INSTANCE_ID:
         type: string
-        title: "Brain Instance ID"
-        description: "Optional. Leave blank — the server auto-detects your active instance. Only set this if you have multiple Brain instances."
-        default: ""
+        title: "Brain Instance ID (optional)"
+        description: "Only needed if you have multiple Brain instances. Leave blank — the server auto-detects your active instance from the API key."
         pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
         examples:
           - "9d4077aa-bfa2-468b-89cd-0a8d8f3ec483"
       CACHLY_API_URL:
         type: string
-        title: "API URL"
-        description: "Optional. Leave blank unless you self-host cachly."
+        title: "API URL (optional)"
+        description: "Leave blank unless you self-host Cachly."
         default: "https://api.cachly.dev"
     required: []
   commandFunction: |-

package/src/__tests__/auth.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from 'vitest';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { jwtExpiryMs, checkJwt, handleApiError } from '../auth.js';
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+  const body   = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return `${header}.${body}.fakesig`;
+}
+
+const nowSec = () => Math.floor(Date.now() / 1000);
+
+describe('jwtExpiryMs', () => {
+  it('returns null for an empty string', () => {
+    expect(jwtExpiryMs('')).toBeNull();
+  });
+
+  it('returns null for a plain (non-JWT) string', () => {
+    expect(jwtExpiryMs('not-a-token')).toBeNull();
+  });
+
+  it('returns null when the JWT has only two parts', () => {
+    expect(jwtExpiryMs('header.payload')).toBeNull();
+  });
+
+  it('returns null when the JWT has four parts', () => {
+    expect(jwtExpiryMs('a.b.c.d')).toBeNull();
+  });
+
+  it('returns null when the payload base64 is invalid', () => {
+    expect(jwtExpiryMs('header.!!!.sig')).toBeNull();
+  });
+
+  it('returns null when the payload has no exp field', () => {
+    expect(jwtExpiryMs(makeJwt({ sub: 'user-123', iat: nowSec() }))).toBeNull();
+  });
+
+  it('returns null when exp is 0', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: 0 }))).toBeNull();
+  });
+
+  it('converts exp (seconds) to milliseconds', () => {
+    const expSec = nowSec() + 3600;
+    expect(jwtExpiryMs(makeJwt({ exp: expSec }))).toBe(expSec * 1000);
+  });
+
+  it('returns a past timestamp for an expired token', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: nowSec() - 300 }))).toBeLessThan(Date.now());
+  });
+
+  it('returns a future timestamp for a valid token', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: nowSec() + 86400 }))).toBeGreaterThan(Date.now());
+  });
+
+  it('handles a token expiring in less than 60 minutes', () => {
+    const expSec = nowSec() + 30 * 60;
+    const result = jwtExpiryMs(makeJwt({ exp: expSec }))!;
+    const minsLeft = Math.floor((result - Date.now()) / 60_000);
+    expect(minsLeft).toBeGreaterThanOrEqual(29);
+    expect(minsLeft).toBeLessThanOrEqual(30);
+  });
+
+  it('ignores extra claims', () => {
+    const expSec = nowSec() + 3600;
+    expect(jwtExpiryMs(makeJwt({ sub: 'u', iat: nowSec(), exp: expSec, plan: 'free' }))).toBe(expSec * 1000);
+  });
+
+  it('handles padding-free base64url payloads', () => {
+    // base64url (no =) — Buffer.from handles this natively
+    const expSec = nowSec() + 7200;
+    expect(jwtExpiryMs(makeJwt({ exp: expSec, x: 'a' }))).toBe(expSec * 1000);
+  });
+});
+
+describe('checkJwt', () => {
+  it('throws InvalidRequest when jwt is empty', () => {
+    expect(() => checkJwt('')).toThrowError(
+      expect.objectContaining({ code: ErrorCode.InvalidRequest, message: expect.stringContaining('CACHLY_JWT env var not set') }),
+    );
+  });
+
+  it('throws with setup URL when jwt is missing', () => {
+    expect(() => checkJwt('')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }),
+    );
+  });
+
+  it('throws InvalidRequest with expiry timestamp for an expired token', () => {
+    const expSec = nowSec() - 60;
+    const token  = makeJwt({ exp: expSec });
+    expect(() => checkJwt(token)).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('expired at'),
+      }),
+    );
+  });
+
+  it('does not throw for a valid non-expired token', () => {
+    expect(() => checkJwt(makeJwt({ exp: nowSec() + 3600 }))).not.toThrow();
+  });
+
+  it('does not throw for a token with no exp claim', () => {
+    expect(() => checkJwt(makeJwt({ sub: 'user' }))).not.toThrow();
+  });
+});
+
+describe('handleApiError', () => {
+  it('throws InvalidRequest for 401 with the detail message', () => {
+    expect(() => handleApiError(401, 'token expired')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('Authentication failed (401): token expired'),
+      }),
+    );
+  });
+
+  it('throws InvalidRequest for 403 with the detail message', () => {
+    expect(() => handleApiError(403, 'plan limit reached')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('Access denied (403): plan limit reached'),
+      }),
+    );
+  });
+
+  it('throws InternalError for other status codes', () => {
+    expect(() => handleApiError(500, 'server crash')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InternalError,
+        message: expect.stringContaining('cachly API error 500: server crash'),
+      }),
+    );
+  });
+
+  it('includes the cachly.dev/setup-ai link for 401 errors', () => {
+    expect(() => handleApiError(401, 'Unauthorized')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }),
+    );
+  });
+
+  it('includes account access hint for 403 errors', () => {
+    expect(() => handleApiError(403, 'Forbidden')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('access to this resource') }),
+    );
+  });
+});

package/src/__tests__/e2e/api-auth.test.ts

@@ -0,0 +1,182 @@
+/**
+ * E2E: Authenticated API endpoints
+ *
+ * Requires: E2E_JWT, E2E_INSTANCE_ID
+ * Run: npx vitest run src/__tests__/e2e/api-auth.test.ts
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { cfg, requireAuth, apiGet, apiPost } from './config.js';
+
+beforeAll(() => requireAuth());
+
+describe('Auth guard', () => {
+  it('GET /api/v1/instances without token returns 401', async () => {
+    const { status } = await apiGet('/api/v1/instances', '');
+    expect(status).toBe(401);
+  });
+
+  it('GET /api/v1/instances with invalid token returns 401', async () => {
+    const { status } = await apiGet('/api/v1/instances', 'not-a-real-token');
+    expect(status).toBe(401);
+  });
+
+  it('GET /api/v1/instances with valid token returns 200', async () => {
+    const { status } = await apiGet('/api/v1/instances');
+    expect(status).toBe(200);
+  });
+});
+
+describe('Instances API', () => {
+  // API returns { data: Instance[], count: number }
+  it('returns object with data array', async () => {
+    const { body } = await apiGet('/api/v1/instances');
+    const b = body as { data?: unknown[]; count?: number };
+    expect(Array.isArray(b.data)).toBe(true);
+    expect(typeof b.count).toBe('number');
+  });
+
+  it('each instance has required fields', async () => {
+    const { body } = await apiGet('/api/v1/instances');
+    const instances = ((body as { data?: Record<string, unknown>[] }).data) ?? [];
+    if (instances.length === 0) return; // fresh account — skip
+    for (const inst of instances) {
+      expect(typeof inst.id).toBe('string');
+      expect(typeof inst.name).toBe('string');
+      expect(typeof inst.status).toBe('string');
+      expect(typeof inst.tier).toBe('string');
+    }
+  });
+
+  it('test instance is present and running', async () => {
+    const { body } = await apiGet('/api/v1/instances');
+    const instances = ((body as { data?: Record<string, unknown>[] }).data) ?? [];
+    const found = instances.find((i) => i.id === cfg.instanceId);
+    expect(found).toBeDefined();
+    expect(found!.status).toBe('running');
+  });
+});
+
+describe('Single instance GET', () => {
+  it('returns 200 for test instance', async () => {
+    const { status } = await apiGet(`/api/v1/instances/${cfg.instanceId}`);
+    expect(status).toBe(200);
+  });
+
+  it('returns 404 for non-existent instance', async () => {
+    const { status } = await apiGet('/api/v1/instances/00000000-0000-0000-0000-000000000000');
+    expect([403, 404]).toContain(status);
+  });
+
+  it('instance body has id, status running, tier, name', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}`);
+    const inst = body as Record<string, unknown>;
+    expect(inst.id).toBe(cfg.instanceId);
+    expect(inst.status).toBe('running');
+    expect(typeof inst.tier).toBe('string');
+    expect(typeof inst.name).toBe('string');
+  });
+});
+
+describe('Connection endpoint', () => {
+  it('returns 200 with connection details for running instance', async () => {
+    const { status, body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/connection`);
+    expect(status).toBe(200);
+    const conn = body as Record<string, unknown>;
+    expect(typeof conn.host).toBe('string');
+    expect(typeof conn.port).toBe('number');
+    expect(typeof conn.password).toBe('string');
+    expect((conn.host as string).length).toBeGreaterThan(3);
+  });
+
+  it('connection host is not localhost (prod/dev has real host)', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/connection`);
+    const conn = body as Record<string, unknown>;
+    expect(String(conn.host)).not.toBe('localhost');
+    expect(String(conn.host)).not.toBe('127.0.0.1');
+  });
+
+  it('port is within valid Redis range', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/connection`);
+    const conn = body as Record<string, unknown>;
+    expect(Number(conn.port)).toBeGreaterThan(1023);
+    expect(Number(conn.port)).toBeLessThan(65536);
+  });
+});
+
+describe('API keys', () => {
+  // API returns { keys: APIKey[], count: number }
+  it('GET /api/v1/api-keys returns 200 with keys array', async () => {
+    const { status, body } = await apiGet('/api/v1/api-keys');
+    expect(status).toBe(200);
+    const b = body as { keys?: unknown[]; count?: number };
+    expect(Array.isArray(b.keys)).toBe(true);
+  });
+
+  it('api-keys have id and instance_id fields', async () => {
+    const { body } = await apiGet('/api/v1/api-keys');
+    const keys = ((body as { keys?: Record<string, unknown>[] }).keys) ?? [];
+    if (keys.length === 0) return;
+    for (const k of keys) {
+      expect(typeof k.id).toBe('string');
+      expect(typeof k.instance_id).toBe('string');
+    }
+  });
+});
+
+describe('Brain Stats endpoint', () => {
+  it('GET /api/v1/instances/:id/brain-stats returns 200', async () => {
+    const { status } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+    expect(status).toBe(200);
+  });
+
+  it('brain-stats body has brain_level and brain_level_name', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+    const stats = body as Record<string, unknown>;
+    expect(typeof stats.brain_level).toBe('number');
+    expect(stats.brain_level).toBeGreaterThanOrEqual(1);
+    expect(typeof stats.brain_level_name).toBe('string');
+    expect(['Apprentice', 'Explorer', 'Expert', 'Architect', 'Oracle']).toContain(stats.brain_level_name);
+  });
+
+  it('brain-stats has hours_saved and brain_recall_count', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+    const stats = body as Record<string, unknown>;
+    expect(typeof stats.hours_saved).toBe('number');
+    expect(stats.hours_saved).toBeGreaterThanOrEqual(0);
+    expect(typeof stats.brain_recall_count).toBe('number');
+    expect(stats.brain_recall_count).toBeGreaterThanOrEqual(0);
+  });
+
+  it('brain-stats has standard search telemetry fields', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+    const stats = body as Record<string, unknown>;
+    expect(typeof stats.total_searches).toBe('number');
+    expect(typeof stats.avg_latency_ms).toBe('number');
+    expect(Array.isArray(stats.top_queries)).toBe(true);
+  });
+});
+
+describe('Provisioning status messages', () => {
+  it('non-existent instance connection returns 4xx, never 500', async () => {
+    const { status } = await apiGet('/api/v1/instances/00000000-0000-0000-0000-000000000001/connection');
+    expect([400, 403, 404, 422]).toContain(status);
+  });
+});
+
+describe('Auto-provision endpoint', () => {
+  it('POST /api/v1/instances/auto returns 200 or 201', async () => {
+    const { status } = await apiPost('/api/v1/instances/auto', {});
+    expect([200, 201]).toContain(status);
+  });
+
+  it('returns existing running instance without creating a new one', async () => {
+    const { body } = await apiPost('/api/v1/instances/auto', {});
+    const b = body as { instance?: { id: string; status: string }; created?: boolean };
+    if (b.instance) {
+      // Existing instance returned
+      expect(typeof b.instance.id).toBe('string');
+      expect(b.created).toBe(false);
+    }
+  });
+});

package/src/__tests__/e2e/api-health.test.ts

@@ -0,0 +1,103 @@
+/**
+ * E2E: API health & public endpoints
+ *
+ * These tests require NO credentials — they hit publicly accessible endpoints.
+ * Run: E2E_API_URL=https://api.dev.cachly.dev npx vitest run src/__tests__/e2e/api-health.test.ts
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { cfg } from './config.js';
+
+describe('API health (no auth required)', () => {
+  it('GET /health returns 200', async () => {
+    const res = await fetch(`${cfg.apiUrl}/health`);
+    expect(res.status).toBe(200);
+  });
+
+  it('GET /health body contains status ok', async () => {
+    const res = await fetch(`${cfg.apiUrl}/health`);
+    const body = await res.json() as Record<string, unknown>;
+    expect(body.status ?? body.ok ?? body.alive).toBeTruthy();
+  });
+
+  it('unknown route returns 404, not 500', async () => {
+    const res = await fetch(`${cfg.apiUrl}/api/v1/does-not-exist-xyz`);
+    expect(res.status).toBe(404);
+  });
+});
+
+describe('Device flow init (no auth required)', () => {
+  it('GET /api/v1/auth/device/code returns device_code and user_code', async () => {
+    const res = await fetch(`${cfg.apiUrl}/api/v1/auth/device/code`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    expect(typeof body.device_code).toBe('string');
+    expect(typeof body.user_code).toBe('string');
+    expect(typeof body.verification_uri).toBe('string');
+    expect(body.verification_uri).toContain('cachly.dev');
+  });
+
+  it('device_code is at least 20 chars (not truncated)', async () => {
+    const res = await fetch(`${cfg.apiUrl}/api/v1/auth/device/code`);
+    const body = await res.json() as Record<string, unknown>;
+    expect((body.device_code as string).length).toBeGreaterThanOrEqual(20);
+  });
+
+  it('expires_in is a positive number', async () => {
+    const res = await fetch(`${cfg.apiUrl}/api/v1/auth/device/code`);
+    const body = await res.json() as Record<string, unknown>;
+    expect(Number(body.expires_in)).toBeGreaterThan(0);
+  });
+});
+
+describe('Badge endpoint (public, no auth)', () => {
+  it('returns 400 or 404 for an invalid instance id', async () => {
+    const res = await fetch(`${cfg.apiUrl}/api/v1/badge/not-a-real-uuid`);
+    expect([400, 404]).toContain(res.status);
+  });
+
+  it('returns badge JSON for a valid instance id', async () => {
+    if (!cfg.instanceId) return; // skip if not configured
+    const res = await fetch(`${cfg.apiUrl}/api/v1/badge/${cfg.instanceId}`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    expect(typeof body.schemaVersion).toBe('number');
+    expect(typeof body.label).toBe('string');
+    expect(typeof body.message).toBe('string');
+  });
+
+  it('badge message contains lesson count (numeric string)', async () => {
+    if (!cfg.instanceId) return;
+    const res = await fetch(`${cfg.apiUrl}/api/v1/badge/${cfg.instanceId}`);
+    const body = await res.json() as Record<string, unknown>;
+    expect((body.message as string)).toMatch(/\d+/);
+  });
+});
+
+describe('Telemetry endpoint (public)', () => {
+  it('POST /api/v1/telemetry/mcp accepts anonymous event', async () => {
+    const res = await fetch(`${cfg.apiUrl}/api/v1/telemetry/mcp`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ event: 'e2e_test_ping', version: '0.0.0', editor: 'test', source: 'e2e' }),
+    });
+    expect([200, 202, 204]).toContain(res.status);
+  });
+
+  it('POST /api/v1/telemetry/mcp accepts jwt-attributed event', async () => {
+    if (!cfg.jwt) return;
+    const res = await fetch(`${cfg.apiUrl}/api/v1/telemetry/mcp`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        event: 'e2e_test_ping_authed',
+        version: '0.0.0',
+        editor: 'test',
+        source: 'e2e',
+        jwt: cfg.jwt,
+        instance_id: cfg.instanceId,
+      }),
+    });
+    expect([200, 202, 204]).toContain(res.status);
+  });
+});