@chatpanel/gateway 0.6.34 → 0.6.36

package/README.md

@@ -172,6 +172,62 @@ Streaming (SSE) is supported on all three: placeholders are restored on the fly,
 holding back a tail so a token split across chunks (`[[PER` … `SON_1]]`) still
 restores cleanly.
 
+## Use it as an MCP server (Codex, Claude Code, any MCP client)
+
+Point one MCP server at the gateway and any CLI agent can reach your **local history**
+(past chats, meeting transcripts, notes — redacted on the way out) **and every skill
+installed on your machine** — across Claude Code, Codex, Copilot, Gemini, Hermes,
+`~/.agents/skills` and any folder you configure. History is served by the gateway; skills
+are proxied from the [bridge](https://github.com/chatpanel/chatpanel-bridge) (optional — if
+it is not running, the history tools still work and the skill tools say so).
+
+It is a stdio MCP server: `chatpanel-gateway mcp`.
+
+**Codex** — add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.chatpanel]
+command = "chatpanel-gateway"
+args = ["mcp"]
+```
+
+**Claude Code** — one command (`--scope user` makes it available in every project):
+
+```bash
+claude mcp add --scope user chatpanel chatpanel-gateway mcp
+```
+
+**Any other MCP client** — run the stdio server `chatpanel-gateway mcp`, or point at it the
+way your client configures a `command` + `args` stdio server.
+
+> If your client launches with a stripped `PATH` and cannot find `chatpanel-gateway`, use
+> the absolute path (find it with `which chatpanel-gateway`).
+
+### Tools it exposes
+
+| Tool | What it does |
+|------|--------------|
+| `search_history` | Full-text search your chats, meetings and notes by relevance |
+| `get_record` | Fetch one record's full text by id (`chat:…`, `meeting:…`, `note:…`) |
+| `list_history` | Browse/page the corpus (newest first, no bodies) |
+| `list_skills` | List every installed skill (name + one-line description, and where it came from) |
+| `open_skill` | Load one skill's full instructions by name |
+| `read_skill_file` | Read a reference file a skill's instructions point at |
+
+Everything a history tool returns is **redacted** with the same engine
+([`@chatpanel/pii`](https://github.com/chatpanel/chatpanel-pii)) the gateway uses for model
+traffic — the real values never leave your device. Skill scripts are never served as text.
+
+### One local view
+
+```bash
+chatpanel-gateway local
+```
+
+prints what is running — the gateway (this) and the bridge (your agents + skills) — so you
+can see the whole local runtime at a glance. The bridge is an optional companion; a missing
+one is reported plainly, never as an error.
+
 ## How it fits with ChatPanel
 
 The [extension](https://github.com/chatpanel/chatpanel-extension) redacts inside
@@ -192,6 +248,22 @@ agent's own multi-turn loop is blinded, not just the first prompt.
   edits. The default tier touches only structured secrets and (in `full`) detected
   entities — keep your dictionary prose-focused.
 
+**Using it as an MCP server:**
+
+- The **gateway must be running** for any of its tools to work — it is a background
+  service (`chatpanel-gateway --install` registers it to start at login). If a tool
+  returns *"the ChatPanel gateway is not running"*, start it and retry; the message tells
+  you the command.
+- **Skills need the bridge** (an optional companion). Without it, the history tools still
+  work and the skill tools return a one-line *"the bridge is not running — install it
+  with …"* — no silent empty result.
+- History tools search the gateway's **warm store**, which is seeded from your ChatPanel
+  backups. If `list_history` says it is empty, the gateway has not been seeded yet — open
+  ChatPanel so a backup lands, or check the [ingest docs](#endpoints).
+- Everything returned is **redacted** at the configured tier. A tool result may contain a
+  placeholder like `[[EMAIL_1]]` where a value was blinded — that is the privacy guarantee
+  working, not a bug.
+
 ## License
 
 Source-available under the same license as the ChatPanel extension and bridge —

package/bin/chatpanel-gateway.js

@@ -3,6 +3,7 @@
 //
 //   chatpanel-gateway              start the gateway (foreground)
 //   chatpanel-gateway mcp          stdio MCP server exposing warm history as tools
+//   chatpanel-gateway local        show the local runtime — bridge + gateway, one view
 //   chatpanel-gateway --install    register login auto-start + start now
 //   chatpanel-gateway --uninstall  remove login auto-start
 //   chatpanel-gateway --status     is auto-start registered?
@@ -19,6 +20,10 @@ try {
     // server.js (which would open a second handle on the warm SQLite store).
     const { runMcpServer } = await import('../src/mcp.js');
     await runMcpServer();
+  } else if (arg === 'local') {
+    // Read-only unified view of both services. No server.js import — just HTTP probes.
+    const { localStatus, formatLocalStatus } = await import('../src/local-status.js');
+    process.stdout.write(formatLocalStatus(await localStatus()));
   } else {
     const { start, VERSION } = await import('../src/server.js');
     const { installService, uninstallService, serviceStatus } = await import('../src/service.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.34",
+  "version": "0.6.36",
   "description": "Local privacy gateway \u2014 redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
   },
   "scripts": {
     "start": "node bin/chatpanel-gateway.js",
-    "test": "node --test",
+    "test": "node scripts/run-tests.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "build:bin": "bash scripts/build-binaries.sh"
   },

package/src/local-status.js

@@ -0,0 +1,105 @@
+// local-status.js — one view of ChatPanel's local runtime: the bridge and the gateway.
+//
+// U3 of docs/bridge-gateway-unification.md: a person should be able to ask "what's running
+// locally?" once and get a straight answer, without knowing there are two services on two
+// ports. This is the read side of that — it probes both over HTTP and reports. It does NOT
+// control either service (start/stop stays with each module's own installer, which owns its
+// launchd/systemd unit); managing another module's service from here would duplicate the
+// knowledge of how to do it and drift.
+//
+// The bridge is OPTIONAL from the gateway's side and the gateway is OPTIONAL from the
+// bridge's — so a missing one is reported plainly, never as an error.
+
+import { loadConfig } from './config.js';
+
+function gatewayUrl() {
+  try {
+    return `http://127.0.0.1:${loadConfig().port || 4320}`;
+  } catch {
+    return 'http://127.0.0.1:4320';
+  }
+}
+
+function bridgeUrl() {
+  try {
+    return String(loadConfig().bridge?.url || 'http://127.0.0.1:4319').replace(/\/+$/, '');
+  } catch {
+    return 'http://127.0.0.1:4319';
+  }
+}
+
+async function probe(url, path = '/health') {
+  try {
+    const res = await fetch(url + path, { signal: AbortSignal.timeout(2500) });
+    if (!res.ok) return { ok: false, reason: `HTTP ${res.status}` };
+    return { ok: true, data: await res.json().catch(() => ({})) };
+  } catch (e) {
+    return { ok: false, reason: e?.name === 'TimeoutError' ? 'no response' : (e?.message || 'unreachable') };
+  }
+}
+
+/**
+ * A structured picture of the local runtime — for the `local` command and for the gateway
+ * to log at startup. Pure except the two probes; the caller decides how to render it.
+ */
+export async function localStatus({ gatewayUrl: gwOverride, bridgeUrl: brOverride } = {}) {
+  const gwUrl = gwOverride || gatewayUrl();
+  const brUrl = brOverride || bridgeUrl();
+  const [gw, br] = await Promise.all([probe(gwUrl), probe(brUrl)]);
+  const skills = br.ok ? await probe(brUrl, '/skills').then((r) => (r.ok ? (r.data.skills || []).length : null)).catch(() => null) : null;
+  return {
+    gateway: {
+      url: gwUrl,
+      running: gw.ok,
+      version: gw.ok ? gw.data.version : null,
+      tier: gw.ok ? gw.data.tier : null,
+      reason: gw.ok ? null : gw.reason,
+    },
+    bridge: {
+      url: brUrl,
+      running: br.ok,
+      version: br.ok ? br.data.version : null,
+      agents: br.ok ? (br.data.agents || []).filter((a) => a.available).length : null,
+      skills: skills ?? (br.ok ? br.data.skills?.count ?? null : null),
+      reason: br.ok ? null : br.reason,
+    },
+  };
+}
+
+/** Human-readable block for the CLI. */
+export function formatLocalStatus(s) {
+  const line = (name, m, extra) => {
+    const dot = m.running ? '●' : '○';
+    const head = m.running ? `${name}  running · v${m.version}` : `${name}  not running${m.reason ? ` (${m.reason})` : ''}`;
+    return `  ${dot} ${head}\n      ${extra}`;
+  };
+  const gw = line('Gateway', s.gateway, s.gateway.running
+    ? `Privacy layer: redaction, routing, voice. ${s.gateway.url}`
+    : `Optional upgrade (redaction, routing, voice). Start with: chatpanel-gateway --install`);
+  const brExtra = s.bridge.running
+    ? `Local agents & skills${s.bridge.agents != null ? ` · ${s.bridge.agents} agent(s)` : ''}${s.bridge.skills != null ? ` · ${s.bridge.skills} skill(s)` : ''}. ${s.bridge.url}`
+    : `Runs your local coding agents and skills. Start with: curl -fsSL https://dl.chatpanel.net/bridge/install.sh | bash`;
+  const br = line('Bridge', s.bridge, brExtra);
+  const summary = s.bridge.running && s.gateway.running
+    ? 'Both running — local traffic can route through the gateway\'s privacy layer.'
+    : s.bridge.running
+      ? 'Bridge up. The gateway is an optional upgrade.'
+      : s.gateway.running
+        ? 'Gateway up. Start the bridge to use local agents and skills.'
+        : 'Neither running.';
+  return `ChatPanel local\n\n${gw}\n\n${br}\n\n  ${summary}\n`;
+}
+
+/**
+ * One-line note for the gateway to log at startup, so the operator sees the unified picture
+ * without running anything. Never throws; a probe failure just says "not detected".
+ */
+export async function bridgePresenceNote(brOverride) {
+  const url = brOverride || bridgeUrl();
+  const br = await probe(url);
+  if (br.ok) {
+    const n = (br.data.skills?.count ?? null);
+    return `bridge detected at ${url} (v${br.data.version}${n != null ? `, ${n} skills` : ''}) — its agents and skills are available through this gateway.`;
+  }
+  return `bridge not detected at ${url} — local agents/skills are unavailable until it runs (curl -fsSL https://dl.chatpanel.net/bridge/install.sh | bash). The gateway runs fine without it.`;
+}

package/src/mcp.js

@@ -120,9 +120,16 @@ const TOOLS = [
 ];
 
 async function gatewayJson(path, init) {
-  const res = await fetch(baseUrl() + path, init);
+  let res;
+  try {
+    res = await fetch(baseUrl() + path, init);
+  } catch (e) {
+    // The most common cause by far: the gateway service is not running. Say so, and how to
+    // fix it, so the agent can relay something actionable instead of a bare fetch error.
+    throw new Error(`the ChatPanel gateway is not running at ${baseUrl()} — start it with "chatpanel-gateway --install" (or run "chatpanel-gateway"), then retry. [${e.message}]`);
+  }
   const data = await res.json().catch(() => ({}));
-  if (!res.ok) throw new Error(data?.error?.message || `gateway ${res.status}`);
+  if (!res.ok) throw new Error(data?.error?.message || `the gateway returned HTTP ${res.status} for ${path}`);
   return data;
 }
 
@@ -153,7 +160,7 @@ async function callTool(name, args = {}) {
   if (name === 'list_skills') {
     let data;
     try { data = await bridgeJson('/skills'); }
-    catch (e) { return `The ChatPanel bridge is not reachable (${e.message}), so installed skills are unavailable. Start it to use skills.`; }
+    catch (e) { return `Installed skills are unavailable because the ChatPanel bridge is not running at ${bridgeBase()}. Install/start it with:\n    curl -fsSL https://dl.chatpanel.net/bridge/install.sh | bash\nThen retry. History tools work without the bridge. [${e.message}]`; }
     const rows = data.skills || [];
     if (!rows.length) return 'No skills installed on this machine yet.';
     return [`${rows.length} skill(s) installed:`, ...rows.map((r) => `- ${r.command || r.id}: ${r.description || r.name}${r.origin?.source ? ` (from ${r.origin.source})` : ''}`)].join('\n') + '\n\nUse open_skill with a name to load its instructions.';
@@ -161,7 +168,7 @@ async function callTool(name, args = {}) {
   if (name === 'open_skill') {
     let data;
     try { data = await bridgeJson(`/skills/${encodeURIComponent(String(args.name || '').trim())}`); }
-    catch (e) { return `Could not open "${args.name}": ${e.message}`; }
+    catch (e) { return `Could not open "${args.name}": ${e.message}. If the bridge isn't running, start it: curl -fsSL https://dl.chatpanel.net/bridge/install.sh | bash`; }
     return data.skill?.prompt || '(this skill has no extra instructions — just apply it.)';
   }
   if (name === 'read_skill_file') {
@@ -169,7 +176,7 @@ async function callTool(name, args = {}) {
     const path = String(args.path || '').trim().split('/').map(encodeURIComponent).join('/');
     let data;
     try { data = await bridgeJson(`/skills/${skill}/file/${path}`); }
-    catch (e) { return `Could not read ${args.path}: ${e.message}`; }
+    catch (e) { return `Could not read ${args.path}: ${e.message}. If the bridge isn't running, start it: curl -fsSL https://dl.chatpanel.net/bridge/install.sh | bash`; }
     return data.text || '(empty)';
   }
   throw new Error(`unknown tool: ${name}`);

package/src/server.js

@@ -45,7 +45,7 @@ import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.34';
+export const VERSION = '0.6.36';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
@@ -1013,6 +1013,13 @@ export function start(cfg = loadConfig()) {
   server.listen(cfg.port, cfg.host, () => {
     console.log(`ChatPanel Privacy Gateway v${VERSION} on http://${cfg.host}:${cfg.port}`);
     console.log(`  backend  : ${cfg.backend}` + (cfg.backend === 'bridge' ? ` (agent: ${cfg.bridge.agent}, via ${cfg.bridge.url})` : ''));
+    // U3: report the bridge at startup so the operator sees the unified picture without
+    // running anything. Detect only — never force-spawn a managed service. Best-effort and
+    // non-fatal: a probe failure just logs "not detected".
+    import('./local-status.js')
+      .then((m) => m.bridgePresenceNote())
+      .then((note) => console.log(`  bridge   : ${note}`))
+      .catch(() => {});
     console.log(`  redaction: ${cfg.redaction.tier}` + (cfg.redaction.detection?.backend && cfg.redaction.detection.backend !== 'off'
       ? ` + ${cfg.redaction.detection.backend} detector` : (cfg.ner?.autostart ? ' (+ NER starting…)' : '')));
     // M7: a non-loopback bind exposes the gateway on the LAN, where the per-request