@chatpanel/gateway 0.6.35 → 0.6.37

package/README.md

@@ -172,6 +172,85 @@ 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"]
+```
+
+> **Corporate Codex with an approval guardian?** If a tool call is rejected with
+> *"Automatic approval review failed"* (an `approvals_reviewer = "auto_review"` policy
+> can't assess a tool it doesn't know), pre-approve ChatPanel's read-only tools the same
+> way you would any other server — one block per tool:
+>
+> ```toml
+> [mcp_servers.chatpanel.tools.search_history]
+> approval_mode = "approve"
+> [mcp_servers.chatpanel.tools.get_record]
+> approval_mode = "approve"
+> [mcp_servers.chatpanel.tools.list_history]
+> approval_mode = "approve"
+> [mcp_servers.chatpanel.tools.list_skills]
+> approval_mode = "approve"
+> [mcp_servers.chatpanel.tools.open_skill]
+> approval_mode = "approve"
+> [mcp_servers.chatpanel.tools.read_skill_file]
+> approval_mode = "approve"
+> ```
+>
+> All six only read local data (your redacted history and your installed skills), so
+> approving them carries no write or network risk.
+
+**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 +271,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

@@ -4,6 +4,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 connect      point your CLI agents (Codex, Claude Code, …) at this server
 //   chatpanel-gateway --install    register login auto-start + start now
 //   chatpanel-gateway --uninstall  remove login auto-start
 //   chatpanel-gateway --status     is auto-start registered?
@@ -24,6 +25,10 @@ try {
     // 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 if (arg === 'connect') {
+    const { connectAgents, formatConnect } = await import('../src/connect-agents.js');
+    const dryRun = process.argv.includes('--dry-run') || process.argv.includes('-n');
+    process.stdout.write(formatConnect(connectAgents({ dryRun }), { dryRun }));
   } 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.35",
+  "version": "0.6.37",
   "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/connect-agents.js

@@ -0,0 +1,173 @@
+// connect-agents.js — wire the local CLI agents to the ChatPanel MCP server in one step.
+//
+// `chatpanel-gateway connect` detects the agent CLIs installed on this machine and points
+// each at `chatpanel-gateway mcp`, so a person gets their history + skills in every agent
+// without hand-editing four different config files in four different formats.
+//
+// Two rules keep this safe to run unattended:
+//   • BACK UP then EDIT, and be IDEMPOTENT — running it twice changes nothing the second
+//     time. A user's existing MCP servers are never touched.
+//   • Only auto-write a format we can write CORRECTLY. Codex (TOML append), Claude Code
+//     (its own CLI) and Gemini (plain JSON) are safe. For agents whose config is JSONC with
+//     comments, or whose format we cannot verify, we PRINT the exact snippet instead of
+//     risking a corrupted config. Guessing a format and clobbering a config is worse than
+//     asking the user to paste four lines.
+
+import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import os from 'node:os';
+
+// The six read-only tools the ChatPanel MCP server exposes (history + skills). Named here so
+// the Codex approval blocks stay in step with what the server actually advertises.
+const TOOLS = ['search_history', 'get_record', 'list_history', 'list_skills', 'open_skill', 'read_skill_file'];
+
+// Resolve the command a config should launch. A bare name works when the client inherits a
+// normal PATH; an absolute path is the safe fallback when it does not.
+export function resolveServerCommand(which = whichSync) {
+  const abs = which('chatpanel-gateway');
+  return abs || 'chatpanel-gateway';
+}
+
+function whichSync(bin) {
+  try {
+    return execFileSync('which', [bin], { encoding: 'utf8' }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function backup(path) {
+  const b = `${path}.bak.chatpanel`;
+  try { copyFileSync(path, b); return b; } catch { return null; }
+}
+
+// ── Codex ──────────────────────────────────────────────────────────────────────────────
+// ~/.codex/config.toml. TOML, and Node has no TOML writer — but the change is a pure
+// APPEND of a server block plus per-tool approval blocks, so a text append (guarded by a
+// presence check) is correct and non-destructive. The approval blocks matter: a corporate
+// Codex with `approvals_reviewer = "auto_review"` rejects a tool it cannot assess, and this
+// is how every other server on such a setup is pre-approved.
+function connectCodex({ cmd, dryRun, home }) {
+  const dir = join(home, '.codex');
+  const path = join(dir, 'config.toml');
+  if (!existsSync(dir)) return { id: 'codex', status: 'absent' };
+  const cur = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  if (/\[mcp_servers\.chatpanel\]/.test(cur)) return { id: 'codex', status: 'already', path };
+
+  let block = '\n# ChatPanel — local history (redacted) + your installed skills, via one MCP server.\n';
+  block += `[mcp_servers.chatpanel]\ncommand = ${JSON.stringify(cmd)}\nargs = ["mcp"]\n\n`;
+  block += '# Read-only tools — pre-approved so a corporate auto_review guardian does not reject them.\n';
+  for (const t of TOOLS) block += `[mcp_servers.chatpanel.tools.${t}]\napproval_mode = "approve"\n\n`;
+
+  if (dryRun) return { id: 'codex', status: 'would', path, preview: block.trim() };
+  const bak = backup(path);
+  writeFileSync(path, `${cur.replace(/\s*$/, '')}\n${block}`);
+  return { id: 'codex', status: 'configured', path, backup: bak };
+}
+
+// ── Claude Code ────────────────────────────────────────────────────────────────────────
+// Its own CLI owns ~/.claude.json, so use `claude mcp add` rather than editing it. --scope
+// user makes it available in every project.
+function connectClaude({ cmd, dryRun, which }) {
+  const claude = which('claude');
+  if (!claude) return { id: 'claude-code', status: 'absent' };
+  // Already added? `claude mcp get` exits non-zero when it is not there.
+  try { execFileSync(claude, ['mcp', 'get', 'chatpanel'], { stdio: 'ignore' }); return { id: 'claude-code', status: 'already' }; } catch { /* not present */ }
+  if (dryRun) return { id: 'claude-code', status: 'would', preview: `claude mcp add --scope user chatpanel ${cmd} mcp` };
+  try {
+    execFileSync(claude, ['mcp', 'add', '--scope', 'user', 'chatpanel', cmd, 'mcp'], { stdio: 'ignore' });
+    return { id: 'claude-code', status: 'configured' };
+  } catch (e) {
+    return { id: 'claude-code', status: 'error', message: e.message };
+  }
+}
+
+// ── Gemini CLI / Antigravity ─────────────────────────────────────────────────────────────
+// ~/.gemini/settings.json — plain JSON, safe to parse and merge.
+function connectGemini({ cmd, dryRun, home }) {
+  const dir = join(home, '.gemini');
+  const path = join(dir, 'settings.json');
+  if (!existsSync(dir)) return { id: 'gemini', status: 'absent' };
+  let cfg = {};
+  if (existsSync(path)) {
+    try { cfg = JSON.parse(readFileSync(path, 'utf8')); } catch { return { id: 'gemini', status: 'error', message: 'settings.json is not valid JSON — left untouched', path }; }
+  }
+  cfg.mcpServers = cfg.mcpServers || {};
+  if (cfg.mcpServers.chatpanel) return { id: 'gemini', status: 'already', path };
+  const entry = { command: cmd, args: ['mcp'] };
+  if (dryRun) return { id: 'gemini', status: 'would', path, preview: JSON.stringify({ mcpServers: { chatpanel: entry } }, null, 2) };
+  const bak = existsSync(path) ? backup(path) : null;
+  cfg.mcpServers.chatpanel = entry;
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`);
+  return { id: 'gemini', status: 'configured', path, backup: bak };
+}
+
+// ── Agents we do NOT auto-write (JSONC with comments, or a format we can't verify) ───────
+// Detected and given the exact snippet, rather than risking a clobbered config.
+function manualAgent(id, present, snippet) {
+  return present ? { id, status: 'manual', snippet } : { id, status: 'absent' };
+}
+
+function otherAgents({ cmd, home, which }) {
+  const out = [];
+  // OpenCode — opencode.json / .jsonc. JSONC keeps comments; we won't rewrite and drop them.
+  out.push(manualAgent('opencode', existsSync(join(home, '.opencode')) || existsSync(join(home, '.config', 'opencode')),
+    `Add to your opencode config (opencode.json):\n  "mcp": { "chatpanel": { "type": "local", "command": [${JSON.stringify(cmd)}, "mcp"], "enabled": true } }`));
+  // GitHub Copilot CLI.
+  out.push(manualAgent('copilot', existsSync(join(home, '.copilot')),
+    `Copilot CLI: add an MCP server named "chatpanel" running:  ${cmd} mcp`));
+  // Hermes.
+  out.push(manualAgent('hermes', existsSync(join(home, '.hermes')) || !!which('hermes'),
+    `Hermes: register an MCP server "chatpanel" with command  ${cmd} mcp  (see Hermes' MCP docs).`));
+  // Pi.
+  out.push(manualAgent('pi', existsSync(join(home, '.pi')) || !!which('pi'),
+    `Pi: add an MCP server "chatpanel" running:  ${cmd} mcp`));
+  return out;
+}
+
+/**
+ * Detect and (unless dryRun) configure every agent found. Returns one result per agent so a
+ * caller can render a summary. Pure-ish: the only side effects are the config writes, and
+ * dryRun suppresses them.
+ */
+export function connectAgents({ dryRun = false, cmd, home = os.homedir(), which = whichSync } = {}) {
+  const serverCmd = cmd || resolveServerCommand(which);
+  const results = [
+    connectCodex({ cmd: serverCmd, dryRun, home }),
+    connectClaude({ cmd: serverCmd, dryRun, which }),
+    connectGemini({ cmd: serverCmd, dryRun, home }),
+    ...otherAgents({ cmd: serverCmd, home, which }),
+  ];
+  return { cmd: serverCmd, results };
+}
+
+const LABEL = {
+  codex: 'Codex', 'claude-code': 'Claude Code', gemini: 'Gemini / Antigravity',
+  opencode: 'OpenCode', copilot: 'GitHub Copilot', hermes: 'Hermes', pi: 'Pi',
+};
+
+/** Human summary for the CLI. */
+export function formatConnect({ cmd, results }, { dryRun = false } = {}) {
+  const lines = [`ChatPanel MCP — connecting your agents to:  ${cmd} mcp`, ''];
+  const icon = { configured: '✓', already: '•', would: '→', manual: '✎', absent: '·', error: '✕' };
+  for (const r of results) {
+    const name = LABEL[r.id] || r.id;
+    if (r.status === 'absent') continue; // don't list agents that aren't installed
+    const head = `  ${icon[r.status] || '?'} ${name}`;
+    if (r.status === 'configured') lines.push(`${head} — configured${r.backup ? ` (backup: ${r.backup})` : ''}`);
+    else if (r.status === 'already') lines.push(`${head} — already connected`);
+    else if (r.status === 'would') lines.push(`${head} — would configure:\n      ${(r.preview || '').split('\n').join('\n      ')}`);
+    else if (r.status === 'manual') lines.push(`${head} — add it yourself:\n      ${r.snippet.split('\n').join('\n      ')}`);
+    else if (r.status === 'error') lines.push(`${head} — ${r.message}`);
+  }
+  const configured = results.filter((r) => r.status === 'configured').length;
+  lines.push('');
+  if (dryRun) lines.push('  (dry run — nothing was written. Re-run without --dry-run to apply.)');
+  else if (configured) lines.push(`  Done. Restart the configured agent(s) to pick up the new server.`);
+  else lines.push('  Nothing to change.');
+  const anyManual = results.some((r) => r.status === 'manual');
+  if (anyManual) lines.push('  Agents marked ✎ use a config format best edited by hand — the snippet above is exact.');
+  return `${lines.join('\n')}\n`;
+}

package/src/local-status.js

@@ -42,9 +42,9 @@ async function probe(url, path = '/health') {
  * 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() {
-  const gwUrl = gatewayUrl();
-  const brUrl = bridgeUrl();
+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 {
@@ -94,11 +94,12 @@ export function formatLocalStatus(s) {
  * 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() {
-  const br = await probe(bridgeUrl());
+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 ${bridgeUrl()} (v${br.data.version}${n != null ? `, ${n} skills` : ''}) — its agents and skills are available through this gateway.`;
+    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 ${bridgeUrl()} — local agents/skills are unavailable until it runs (curl -fsSL https://dl.chatpanel.net/bridge/install.sh | bash). The gateway runs fine without it.`;
+  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.35';
+export const VERSION = '0.6.37';
 
 // 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.