@chatpanel/gateway 0.6.35 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.35",
+  "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

@@ -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.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.