@cachly-dev/mcp-server 0.10.47 → 0.10.49

package/packages/telegram-notify/client.ts

@@ -0,0 +1,88 @@
+/**
+ * telegram-notify — shared Telegram notification client.
+ *
+ * Used by cachly-mcp (TypeScript) and TCO backend (Python via client.py).
+ * Single source of truth for: emoji map, message format, env var convention.
+ *
+ * Interface: notify(app, event, payload)
+ *
+ * Env vars:
+ *   TELEGRAM_BOT_TOKEN          — bot token from @BotFather
+ *   {APP_UPPER}_TELEGRAM_CHAT_ID — app-specific channel (e.g. CACHLY_TELEGRAM_CHAT_ID)
+ *   TELEGRAM_CHAT_ID             — fallback for all apps
+ *
+ * No-op when unconfigured. Never throws.
+ *
+ * Note: emoji map is kept in sync with emojis.json (Python reads the JSON file at runtime).
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+declare const process: { env: Record<string, string | undefined> };
+
+const EMOJI: Record<string, string> = {
+  tool_call:          '🔧',
+  tool_error:         '🔴',
+  cache_hit:          '⚡',
+  cache_miss:         '💭',
+  auth_ok:            '🔑',
+  auth_fail:          '🚫',
+  startup:            '🚀',
+  waitlist_signup:    '📬',
+  parse_file:         '📄',
+  parse_text:         '📝',
+  parse_url:          '🔗',
+  trip_created:       '🗺️',
+  trip_deleted:       '🗑️',
+  error:              '🔴',
+  stripe_payment:     '💳',
+  stripe_checkout:    '🛒',
+  new_user:           '🆕',
+  pdf_export:         '📑',
+  trip_search:        '🔍',
+  default:            '🔔',
+};
+
+function getToken(): string {
+  return process.env.TELEGRAM_BOT_TOKEN ?? '';
+}
+
+function getChatId(app: string): string {
+  const key = `${app.toUpperCase()}_TELEGRAM_CHAT_ID`;
+  return process.env[key] ?? process.env.TELEGRAM_CHAT_ID ?? '';
+}
+
+export function formatMessage(
+  app: string,
+  event: string,
+  payload: Record<string, unknown>,
+): string {
+  const icon = EMOJI[event] ?? EMOJI['default'];
+  const lines = [`${icon} *${app.toUpperCase()}* · \`${event}\``];
+  for (const [k, v] of Object.entries(payload)) {
+    if (v !== null && v !== undefined && v !== '') {
+      lines.push(`  ${k}: \`${String(v)}\``);
+    }
+  }
+  return lines.join('\n');
+}
+
+export async function notify(
+  app: string,
+  event: string,
+  payload: Record<string, unknown> = {},
+): Promise<void> {
+  const token = getToken();
+  const chatId = getChatId(app);
+  if (!token || !chatId) return;
+  try {
+    const text = formatMessage(app, event, payload);
+    await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ chat_id: chatId, text, parse_mode: 'Markdown' }),
+      signal: AbortSignal.timeout(5000),
+    });
+  } catch {
+    // never throws
+  }
+}

package/packages/telegram-notify/emojis.json

@@ -0,0 +1,22 @@
+{
+  "tool_call":             "🔧",
+  "tool_error":            "🔴",
+  "cache_hit":             "⚡",
+  "cache_miss":            "💭",
+  "auth_ok":               "🔑",
+  "auth_fail":             "🚫",
+  "startup":               "🚀",
+  "waitlist_signup":       "📬",
+  "parse_file":            "📄",
+  "parse_text":            "📝",
+  "parse_url":             "🔗",
+  "trip_created":          "🗺️",
+  "trip_deleted":          "🗑️",
+  "error":                 "🔴",
+  "stripe_payment":        "💳",
+  "stripe_checkout":       "🛒",
+  "new_user":              "🆕",
+  "pdf_export":            "📑",
+  "trip_search":           "🔍",
+  "default":               "🔔"
+}

package/packages/telegram-notify/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "telegram-notify"
+version = "0.1.0"
+description = "Shared Telegram notification client for cachly-mcp monorepo"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["telegram_notify*"]
+
+[tool.setuptools.package-data]
+telegram_notify = ["emojis.json"]

package/packages/telegram-notify/telegram_notify/__init__.py

@@ -0,0 +1,3 @@
+from .client import notify, notify_user, format_message
+
+__all__ = ["notify", "notify_user", "format_message"]

package/packages/telegram-notify/telegram_notify/client.py

@@ -0,0 +1,87 @@
+"""
+telegram-notify — shared Telegram notification client.
+
+Used by TCO backend (Python) and importable as a pip local package.
+Single source of truth for: emoji map, message format, env var convention.
+
+Interface: notify(app, event, payload)
+          notify_user(db, user_id, message)   — direct DM via stored chat_id
+
+Env vars:
+  TELEGRAM_BOT_TOKEN            — bot token from @BotFather
+  {APP_UPPER}_TELEGRAM_CHAT_ID  — app-specific channel (e.g. TCO_TELEGRAM_CHAT_ID)
+  TELEGRAM_CHAT_ID              — fallback for all apps
+
+No-op when unconfigured. Never throws.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+_EMOJI: dict[str, str] = json.loads(
+    (Path(__file__).parent / "emojis.json").read_text()
+)
+
+
+def _token() -> str:
+    return os.getenv("TELEGRAM_BOT_TOKEN", "")
+
+
+def _chat_id(app: str) -> str:
+    key = f"{app.upper()}_TELEGRAM_CHAT_ID"
+    return os.getenv(key) or os.getenv("TELEGRAM_CHAT_ID", "")
+
+
+def format_message(app: str, event: str, payload: dict[str, Any]) -> str:
+    icon = _EMOJI.get(event, _EMOJI["default"])
+    lines = [f"{icon} *{app.upper()}* · `{event}`"]
+    for k, v in payload.items():
+        if v is not None and v != "":
+            lines.append(f"  {k}: `{v}`")
+    return "\n".join(lines)
+
+
+async def notify(app: str, event: str, payload: dict[str, Any] | None = None) -> None:
+    """Send event notification to the app's configured Telegram channel."""
+    token = _token()
+    chat_id = _chat_id(app)
+    if not token or not chat_id:
+        return
+    try:
+        import httpx
+        text = format_message(app, event, payload or {})
+        async with httpx.AsyncClient(timeout=5) as client:
+            await client.post(
+                f"https://api.telegram.org/bot{token}/sendMessage",
+                json={"chat_id": chat_id, "text": text, "parse_mode": "Markdown"},
+            )
+    except Exception:
+        pass  # never raises
+
+
+async def notify_user(db: Any, user_id: str, message: str) -> None:
+    """Send a direct Telegram message to a user by their DB user_id.
+    Looks up telegram_chat_id from the users table. No-op if not linked."""
+    token = _token()
+    if not token:
+        return
+    try:
+        from sqlalchemy import text as sql_text
+        result = await db.execute(
+            sql_text("SELECT telegram_chat_id FROM users WHERE id = :uid"),
+            {"uid": user_id},
+        )
+        row = result.fetchone()
+        if not row or not row[0]:
+            return
+        import httpx
+        async with httpx.AsyncClient(timeout=5) as client:
+            await client.post(
+                f"https://api.telegram.org/bot{token}/sendMessage",
+                json={"chat_id": row[0], "text": message, "parse_mode": "Markdown"},
+            )
+    except Exception:
+        pass  # never raises

package/packages/telegram-notify/telegram_notify/emojis.json

@@ -0,0 +1,22 @@
+{
+  "tool_call":             "🔧",
+  "tool_error":            "🔴",
+  "cache_hit":             "⚡",
+  "cache_miss":            "💭",
+  "auth_ok":               "🔑",
+  "auth_fail":             "🚫",
+  "startup":               "🚀",
+  "waitlist_signup":       "📬",
+  "parse_file":            "📄",
+  "parse_text":            "📝",
+  "parse_url":             "🔗",
+  "trip_created":          "🗺️",
+  "trip_deleted":          "🗑️",
+  "error":                 "🔴",
+  "stripe_payment":        "💳",
+  "stripe_checkout":       "🛒",
+  "new_user":              "🆕",
+  "pdf_export":            "📑",
+  "trip_search":           "🔍",
+  "default":               "🔔"
+}

package/scripts/generate-icons.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Converts SVG icon assets to PNG for Expo.
+ * Run: node scripts/generate-icons.js
+ * Requires: npm install -g sharp-cli  OR  npx sharp-cli
+ */
+const { execSync } = require('child_process');
+const path = require('path');
+
+const frontend = path.join(__dirname, '..', 'apps', 'travel-chaos-organizer', 'frontend');
+
+const conversions = [
+  { input: 'assets/icon.svg', output: 'assets/icon.png', width: 1024, height: 1024 },
+  { input: 'assets/adaptive-icon.svg', output: 'assets/adaptive-icon.png', width: 1024, height: 1024 },
+  { input: 'assets/icon.svg', output: 'assets/splash.png', width: 1284, height: 2778 },
+  { input: 'assets/icon.svg', output: 'assets/favicon.png', width: 32, height: 32 },
+];
+
+for (const { input, output, width, height } of conversions) {
+  const src = path.join(frontend, input);
+  const dst = path.join(frontend, output);
+  try {
+    execSync(`npx sharp-cli --input "${src}" --output "${dst}" resize ${width} ${height}`, { stdio: 'inherit' });
+    console.log(`✓ ${output}`);
+  } catch {
+    console.error(`✗ ${output} — install sharp-cli: npm i -g sharp-cli`);
+  }
+}

package/smithery.yaml

@@ -7,19 +7,15 @@ description: >
   BM25+ search in 11 languages. 80 MCP tools. Free tier. GDPR. German servers.
   Zero-config: sign in once via browser, auto-provisions your Brain instance.
 
-# Streamable HTTP — hosted on our infrastructure (mcp.cachly.dev).
-# Multi-tenant: per-request CACHLY_JWT + instance ID resolved from
-# Authorization header + X-Cachly-Instance-Id, or Smithery ?config= param.
 startCommand:
-  type: http
-  url: https://mcp.cachly.dev/mcp
+  type: stdio
   configSchema:
     type: object
     properties:
       CACHLY_JWT:
         type: string
-        title: "API Key"
-        description: "Get your free API key at https://cachly.dev/setup-ai (no credit card)."
+        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:
@@ -29,6 +25,21 @@ startCommand:
         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"
-    required:
-      - CACHLY_JWT
-
+      CACHLY_API_URL:
+        type: string
+        title: "API URL (optional)"
+        description: "Leave blank unless you self-host Cachly."
+        default: "https://api.cachly.dev"
+    required: []
+  commandFunction: |-
+    (config) => ({
+      command: "npx",
+      args: ["-y", "@cachly-dev/mcp-server@latest"],
+      env: Object.fromEntries(
+        Object.entries({
+          CACHLY_JWT: config.CACHLY_JWT,
+          CACHLY_BRAIN_INSTANCE_ID: config.CACHLY_BRAIN_INSTANCE_ID,
+          CACHLY_API_URL: config.CACHLY_API_URL ?? "https://api.cachly.dev",
+        }).filter(([, v]) => v != null && v !== "")
+      )
+    })

package/src/__tests__/brain-flow.test.ts

@@ -17,6 +17,7 @@ import { EventEmitter } from 'node:events';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
 import { EMBED_PROVIDER, hasEmbedProvider, embedProviderHint, embedConfig, setEmbedJwt } from '../embeddings.js';
 import { keywordSearch } from '../search.js';
+import { handleBrainTool } from '../handlers/brain.js';
 import type { Redis } from 'ioredis';
 
 // ── In-memory Redis mock ──────────────────────────────────────────────────────
@@ -67,6 +68,21 @@ class MockRedis {
     return [...(this.sets.get(key) ?? [])];
   }
 
+  async mget(...keys: string[]): Promise<(string | null)[]> {
+    return keys.map(k => this.store.get(k) ?? null);
+  }
+
+  async exists(key: string): Promise<number> {
+    return this.store.has(key) ? 1 : 0;
+  }
+
+  async incrbyfloat(key: string, increment: number): Promise<string> {
+    const cur = parseFloat(this.store.get(key) ?? '0');
+    const next = cur + increment;
+    this.store.set(key, String(next));
+    return String(next);
+  }
+
   /** Simplified scanStream: returns all matching keys in a single 'data' event. */
   scanStream(opts: { match: string; count?: number }): EventEmitter {
     const emitter = new EventEmitter();
@@ -83,13 +99,13 @@ class MockRedis {
   /** Minimal pipeline: batches GET calls, returns [err, value][] */
   pipeline() {
     const commands: Array<{ cmd: string; key: string }> = [];
-    const self = this;
+    const store = this.store;
     return {
       get(key: string) { commands.push({ cmd: 'get', key }); return this; },
       async exec(): Promise<Array<[null, string | null]>> {
         const out: Array<[null, string | null]> = [];
         for (const c of commands) {
-          out.push([null, self.store.get(c.key) ?? null]);
+          out.push([null, store.get(c.key) ?? null]);
         }
         return out;
       },
@@ -872,3 +888,161 @@ describe('Brain Flow: advanced scenarios', () => {
     });
   });
 });
+
+// ── New feature coverage (0.10.41 / 0.10.42) ─────────────────────────────────
+// Trust badges, Proven Laws crystallization, and focus-less predictive warning.
+// These exercise the REAL handleBrainTool code path with the MockRedis.
+
+const noopApiFetch = (async () => null) as unknown as Parameters<typeof handleBrainTool>[3];
+
+/** Seed a best-solution lesson with an explicit recall_count / authors / pinned. */
+async function seedLesson(
+  redis: MockRedis,
+  topic: string,
+  opts: {
+    outcome?: 'success' | 'failure' | 'partial';
+    what_worked?: string;
+    what_failed?: string;
+    recall_count?: number;
+    severity?: 'critical' | 'major' | 'minor';
+    pinned?: boolean;
+    author?: string;
+    tags?: string[];
+  } = {},
+): Promise<void> {
+  const ts = new Date().toISOString();
+  const obj = {
+    topic,
+    outcome: opts.outcome ?? 'success',
+    what_worked: opts.what_worked ?? `solution for ${topic}`,
+    what_failed: opts.what_failed,
+    severity: opts.severity ?? 'minor',
+    recall_count: opts.recall_count ?? 0,
+    ts,
+    verified_at: ts,
+    confidence: 1.0,
+    tags: opts.tags ?? [],
+    ...(opts.pinned ? { pinned: true } : {}),
+    ...(opts.author ? { author: opts.author } : {}),
+  };
+  await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(obj));
+}
+
+describe('Trust badges (recall_best_solution)', () => {
+  let redis: MockRedis;
+  const getConn = async () => redis as unknown as Redis;
+  beforeEach(() => { redis = new MockRedis(); });
+
+  it('shows "Battle-tested" when recall_count crosses 10', async () => {
+    await seedLesson(redis, 'redis:pool', { recall_count: 9, what_worked: 'set max_retries=3' });
+    const out = (await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'redis:pool' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Battle-tested');
+    expect(out).toContain('recalled 10×');
+  });
+
+  it('shows "Proven" when recall_count is between 5 and 9', async () => {
+    await seedLesson(redis, 'api:auth', { recall_count: 4 });
+    const out = (await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'api:auth' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Proven');
+    expect(out).toContain('recalled 5×');
+    expect(out).not.toContain('Battle-tested');
+  });
+
+  it('shows no trust badge for a fresh low-recall lesson', async () => {
+    await seedLesson(redis, 'misc:thing', { recall_count: 0 });
+    const out = (await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'misc:thing' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('Battle-tested');
+    expect(out).not.toContain('Proven —');
+    expect(out).not.toContain('Team-verified');
+  });
+
+  it('increments recall_count and persists it', async () => {
+    await seedLesson(redis, 'deploy:x', { recall_count: 2 });
+    await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'deploy:x' }, getConn, noopApiFetch);
+    const stored = JSON.parse((await redis.get('cachly:lesson:best:deploy:x'))!);
+    expect(stored.recall_count).toBe(3);
+  });
+});
+
+describe('Proven Laws crystallization (session_start)', () => {
+  let redis: MockRedis;
+  const getConn = async () => redis as unknown as Redis;
+  beforeEach(async () => {
+    redis = new MockRedis();
+    // Provide a last session so session_start does not attempt git reconstruction.
+    await redis.set('cachly:session:last', JSON.stringify({ summary: 'prior work', ts: new Date().toISOString(), files_changed: [] }));
+  });
+
+  it('surfaces lessons recalled >= 5 in the Proven Laws section', async () => {
+    await seedLesson(redis, 'infra:k3s', { recall_count: 7, what_worked: 'add WireGuard IP to TLS-SAN' });
+    await seedLesson(redis, 'random:note', { recall_count: 1 });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Proven Laws');
+    expect(out).toContain('infra:k3s');
+    expect(out).toContain('recalled 7×');
+  });
+
+  it('surfaces an explicitly pinned lesson even with low recall', async () => {
+    await seedLesson(redis, 'team:convention', { recall_count: 0, pinned: true, what_worked: 'always snake_case handlers' });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Proven Laws');
+    expect(out).toContain('team:convention');
+    expect(out).toContain('pinned');
+  });
+
+  it('omits the Proven Laws section when nothing qualifies', async () => {
+    await seedLesson(redis, 'small:thing', { recall_count: 1 });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('Proven Laws');
+  });
+
+  it('does not crystallize failure lessons', async () => {
+    await seedLesson(redis, 'broken:flow', { recall_count: 9, outcome: 'failure', what_failed: 'never works' });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('Proven Laws');
+  });
+});
+
+describe('Predictive pre-warning without explicit focus (session_start)', () => {
+  let redis: MockRedis;
+  const getConn = async () => redis as unknown as Redis;
+  beforeEach(() => { redis = new MockRedis(); });
+
+  it('derives danger area from last session files and warns', async () => {
+    // Last session touched payment files → likely to continue there.
+    await redis.set('cachly:session:last', JSON.stringify({
+      summary: 'worked on payment integration',
+      ts: new Date().toISOString(),
+      files_changed: ['api/payment/stripe_webhook.go'],
+    }));
+    // A known failure in the payment area.
+    await seedLesson(redis, 'payment:webhook', { outcome: 'failure', what_failed: 'missed idempotency key → double charge', tags: ['payment'] });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).toContain('PRE-WARNING');
+    expect(out).toContain('payment:webhook');
+  });
+
+  it('does not warn when last-session area has no known failures', async () => {
+    await redis.set('cachly:session:last', JSON.stringify({
+      summary: 'wrote docs',
+      ts: new Date().toISOString(),
+      files_changed: ['docs/readme.md'],
+    }));
+    await seedLesson(redis, 'payment:webhook', { outcome: 'failure', what_failed: 'x', tags: ['payment'] });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('PRE-WARNING');
+  });
+
+  it('filters path noise so common segments do not trigger false matches', async () => {
+    // Last session only touched generic noise paths (src/lib/index).
+    await redis.set('cachly:session:last', JSON.stringify({
+      summary: 'refactor',
+      ts: new Date().toISOString(),
+      files_changed: ['src/lib/index.ts'],
+    }));
+    // A failure tagged 'src' — should NOT match because 'src' is noise.
+    await seedLesson(redis, 'src:thing', { outcome: 'failure', what_failed: 'noise', tags: ['src'] });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('PRE-WARNING');
+  });
+});

package/src/__tests__/handlers-unit.test.ts

@@ -334,7 +334,7 @@ describe('handleRoadmapTool', () => {
       // Add and complete one item
       const addResult = await handleRoadmapTool('roadmap_add', { instance_id: INSTANCE, title: 'Finished task', priority: 'low' }, getConnection, apiFetch);
       const idMatch = addResult!.match(/`(rm_[a-z0-9_]+)`/);
-      const id = idMatch?.[1]!;
+      const id = idMatch![1];
       await handleRoadmapTool('roadmap_update', { instance_id: INSTANCE, id, status: 'done' }, getConnection, apiFetch);
 
       const result = await handleRoadmapTool('roadmap_list', { instance_id: INSTANCE, status: 'done' }, getConnection, apiFetch);