kojee-mcp 0.2.1 → 0.4.0

package/README.md

@@ -1,14 +1,36 @@
 # kojee-mcp
 
-kojee-mcp is a local MCP proxy that lets any MCP-capable agent use Kojee-managed tools seamlessly. It handles DPoP authentication, key enrollment, nonce rotation, step-up re-auth, and governance flows internally -- the agent just sees tools and calls them.
+There are two ways to connect Kojee to an MCP-capable agent:
 
-## Quick Start
+1. **Mobile, web & desktop (recommended)** — paste the Kojee MCP URL into the app's "Add custom connector" dialog. The app handles OAuth login and consent. No local install. Works on Claude (web/desktop/iOS/Android) and ChatGPT (web/desktop/iOS/Android with Developer Mode enabled).
+2. **Power user / local proxy with DPoP** — run this stdio proxy locally with a gateway token. Strongest wire-level security (DPoP proof-of-possession, RFC 9449), but requires Node and a token you generate manually in the Kojee dashboard.
 
-1. **Get a gateway token** from the [Kojee dashboard](https://kojee.ai).
-2. **Add to your MCP config** (see examples below).
-3. **Tools appear automatically** -- all Kojee tools your token has access to are exposed directly (e.g. `gmail_send_email`, `github_list_repos`, `calendar_create_event`). Agents call them like any native MCP tool — no discovery step, no wrapper, no indirection.
+## Mobile, Web & Desktop (Recommended)
 
-## MCP Config Examples
+Paste this URL into the app's connector dialog:
+
+```
+https://api.kojee.ai/mcp
+```
+
+- **Claude (any surface):** Settings → Connectors → Add custom connector → paste URL → Connect → log in to Kojee → approve scopes.
+- **ChatGPT (any surface, Developer Mode on):** Settings → Connectors → New connector → paste URL → choose OAuth → Connect.
+
+The OAuth login + consent flow takes care of everything — no token paste, no config file, no Node required. Tokens are short-lived (1 h) and audience-bound to the MCP URL (RFC 8707). Refresh tokens rotate on every use.
+
+### Remote MCP URL details
+
+| Field | Value |
+|---|---|
+| MCP URL | `https://api.kojee.ai/mcp` |
+| Transport | Streamable HTTP (POST + GET-SSE) |
+| Auth | OAuth 2.1 + Dynamic Client Registration (RFC 7591) |
+| Discovery | `https://api.kojee.ai/.well-known/oauth-protected-resource` |
+| Scopes | `mcp:tools`, `mcp:read` |
+
+## Power User: Local Proxy with DPoP
+
+The `kojee-mcp` stdio proxy holds a `gw_` gateway token + ES256 keypair locally and signs every request with DPoP (RFC 9449). This survives token-in-transit theft (TLS-terminating proxy logs, etc.) — strictly stronger wire-level posture than bearer-only OAuth, but requires a long-lived token.
 
 ### Claude Code / Claude Desktop
 
@@ -25,7 +47,7 @@ kojee-mcp is a local MCP proxy that lets any MCP-capable agent use Kojee-managed
 
 ### Generic MCP Client
 
-Any MCP client that supports stdio transports can use kojee-mcp. Point it at the CLI binary:
+Any MCP client that supports stdio transports can use kojee-mcp:
 
 ```bash
 npx kojee-mcp --token gw_abc123... --url https://kojee.ai
@@ -46,6 +68,117 @@ kojee-mcp --token gw_abc123... --url https://kojee.ai
 | `--url` | yes | -- | Kojee broker URL (e.g. `https://kojee.ai`) |
 | `--keystore-path` | no | `~/.kojee/keypair.json` | Path for DPoP keypair storage |
 
+## Pair Mode (Tandem)
+
+If your token comes from the Kojee Tandem web wizard (a "pair code"), you can persist it for future runs:
+
+```bash
+# One-time setup:
+npx kojee-mcp pair ABCD-1234 --url https://rosie-server.kojee.net
+npx kojee-mcp init                              # adds the MCP entry to EVERY detected Claude installation
+```
+
+`init` writes to both `~/.claude.json` (terminal `claude` CLI) and `~/Library/Application Support/Claude/claude_desktop_config.json` (Claude.app on macOS — Windows / Linux paths in the spec) if either exists. The canonical MCP entry includes `env.KOJEE_RUNTIME=claude-code` so the proxy correctly identifies as Claude Code even when the desktop app strips environment variables from MCP subprocesses.
+
+**Important for Claude.app users:** existing agent-mode sessions snapshot the MCP config at creation time and won't pick up changes from `init`. Start a NEW session (not a resumed one) to use the updated kojee config.
+
+Subsequent runs of `claude` will find kojee automatically. The proxy writes credentials to `~/.kojee/config.json` (mode 0600). Existing `--token` users are unaffected.
+
+To remove kojee from Claude:
+```bash
+npx kojee-mcp init --uninstall
+```
+
+## Claude Code Channels Support
+
+When this proxy detects it's running under Claude Code, it declares the `claude/channel` capability and pushes Tandem messages directly into the Claude session via `notifications/claude/channel`. Other MCP clients (Cursor, Codex, Openclaw, etc.) see no behavior change.
+
+**Runtime detection (3 tiers, first match wins):**
+1. `KOJEE_RUNTIME=claude-code` env var (set by `kojee-mcp init` in the MCP entry's `env` block — survives Claude.app's env strip)
+2. `CLAUDE_CODE_SESSION_ID` env var (set by the terminal `claude` CLI; **not** forwarded by Claude.app to MCP stdio servers)
+3. Process-ancestry walk for a parent process whose command line matches `\bclaude\b` (handles fresh installs where neither env var is present)
+
+CC Channels are in research preview — you must launch CC with `claude --dangerously-load-development-channels server:kojee` until kojee is on the official allowlist.
+
+## Hooks Support (always-on, no allowlist required)
+
+While Channels is in research preview and gated behind Anthropic's allowlist, kojee also supports the standard Claude Code hooks system as a complementary wake path. Hooks require no special launch flag.
+
+If you used `kojee-mcp init` above, hooks are already installed. The standalone command is:
+
+```bash
+npx kojee-mcp install-hooks
+```
+
+This writes to **`~/.claude/settings.json`** (the file CC reads for hooks — NOT `~/.claude.json`, which is the MCP-servers file). Foreign hooks already in `settings.json` (e.g. babysitter wrappers) are preserved as siblings.
+
+Restart Claude Code. Tandem events arriving between turns (Stop hook) or while you're typing a new prompt (UserPromptSubmit hook) will be injected into the agent's context the next time it acts.
+
+To remove:
+
+```bash
+npx kojee-mcp install-hooks --uninstall
+```
+
+Override the default `~/.claude/settings.json` path with `--hooks-path <path>` if needed.
+
+If both Channels (dangerous-flag launched) and hooks are active, the proxy deduplicates so events arrive exactly once. Hook-delivered events are also suppressed when Monitor (below) has already delivered them push-style.
+
+## Waiting on Tandem Peers
+
+When kojee-mcp is running under Claude Code, the proxy writes one line per Tandem message to a per-session log file. The agent watches this log via Claude Code's built-in `Monitor` tool.
+
+**You don't need to figure out the path yourself.** The proxy bakes the resolved path into the MCP server's `instructions` string at startup, so the agent gets the exact command to spawn:
+
+```ts
+Monitor({
+  command: "tail -n +1 -F /tmp/kojee-events-<discoveryKey>.log",
+  persistent: true,
+  description: "kojee Tandem events",
+});
+```
+
+The `<discoveryKey>` is computed from `sha256(CLAUDE_PROJECT_DIR).slice(0,12) + '-' + <ccPid>` where `ccPid` is the parent Claude Code process. (This replaces the pre-v0.4 scheme that used `CLAUDE_CODE_SESSION_ID`, which Claude.app doesn't forward to MCP servers.) The matching `~/.kojee/sessions/cc-<discoveryKey>.json` discovery file lets the Stop / UserPromptSubmit hooks find this proxy via the same independent derivation.
+
+Each appended event line arrives as a separate spontaneous wake notification. The agent stays free to chat with the user between events; CC delivers each event from idle as it arrives.
+
+**Stop hook is Monitor-aware** (v0.4+): when a Monitor is watching the log file, the Stop hook does an instant queue snapshot (~50ms) instead of a 30s long-poll, since events have already been delivered push-style. When no Monitor is running, the Stop hook long-polls for up to 30s AND emits a "spawn a Monitor" recommendation to the agent — self-healing if the session-start spawn was skipped.
+
+Channel notifications (when available — see "Claude Code Channels Support" above) supplement this with mid-turn `<channel>` tag delivery, but Monitor is the default no-allowlist wake path that works for every user.
+
+For one-shot blocking waits (return as soon as a single reply arrives), call `tandem_listen(tandem_id, since=cursor, timeout_ms=N)` instead.
+
+## Backend SSE Wire Compatibility
+
+The proxy normalizes incoming SSE events from `/api/v2/tandems/stream` so that the on-the-wire payload shape (which currently differs from the spec'd `TandemEvent`) is mapped transparently:
+
+| Wire field | Internal field |
+|---|---|
+| `message_id` | `id` |
+| `sender.principal_id` | `from.principal` |
+| `sender.agent_id` | `from.agent_id` |
+| top-level `body` | `content.body` |
+| top-level `format` | `content.format` |
+| (missing) `displayname` | synthesized as `principal:<first-8-chars-of-principal_id>` |
+
+The normalizer also accepts canonical (spec-aligned) payloads unchanged, so the proxy works against either shape during any future backend migration.
+
+## Development
+
+Run tests:
+```bash
+npm install
+npm test
+```
+
+The test suite uses an in-process stub broker (`dev-tools/stub-broker.ts`) — no external dependencies, no Docker, no MongoDB. CI runs the same way.
+
+Run the stub manually for hands-on CC verification:
+```bash
+npm run dev:stub
+# Stub listens on http://localhost:8765
+```
+
 ## How Approvals Work
 
 Some tools are governed by approval policies configured in the Kojee dashboard. When an agent calls a governed tool:

package/dist/chunk-36DMIXH7.js

@@ -0,0 +1,51 @@
+// src/runtime/ancestry.ts
+import childProcess from "child_process";
+import { createHash } from "crypto";
+function findClaudeAncestorPid(startPid = process.ppid) {
+  if (process.platform === "win32") return null;
+  let pid = startPid;
+  for (let depth = 0; depth < 20 && pid !== void 0 && pid > 1; depth++) {
+    let row;
+    try {
+      row = readProcInfo(pid);
+    } catch {
+      return null;
+    }
+    if (!row) return null;
+    if (/\bclaude\b/.test(row.command)) return pid;
+    if (row.ppid === void 0 || row.ppid === pid) return null;
+    pid = row.ppid;
+  }
+  return null;
+}
+function readProcInfo(pid) {
+  const out = childProcess.execFileSync("ps", ["-ww", "-p", String(pid), "-o", "ppid=,command="], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  }).trim();
+  if (!out) return null;
+  const firstSpace = out.indexOf(" ");
+  if (firstSpace < 0) return null;
+  const ppid = Number.parseInt(out.slice(0, firstSpace).trim(), 10);
+  if (!Number.isFinite(ppid)) return null;
+  const command = out.slice(firstSpace + 1).trim();
+  return { command, ppid };
+}
+function deriveDiscoveryKey(projectDir, ccPid) {
+  const hasProjectDir = typeof projectDir === "string" && projectDir.length > 0;
+  if (!hasProjectDir && ccPid === null) {
+    return `orphan-${process.pid}`;
+  }
+  if (!hasProjectDir) {
+    const hash2 = createHash("sha256").update("<no-project>").digest("hex").slice(0, 12);
+    return `${hash2}-${ccPid}`;
+  }
+  const hash = createHash("sha256").update(projectDir).digest("hex").slice(0, 12);
+  if (ccPid === null) return `${hash}-orphan`;
+  return `${hash}-${ccPid}`;
+}
+
+export {
+  findClaudeAncestorPid,
+  deriveDiscoveryKey
+};

package/dist/chunk-E7TE4QZD.js

@@ -0,0 +1,33 @@
+// src/auth/paired-config.ts
+import fs from "fs";
+import path from "path";
+function pairedConfigPath() {
+  return path.join(process.env["HOME"] ?? "~", ".kojee", "config.json");
+}
+function loadPairedConfig(filePath = pairedConfigPath()) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function savePairedConfig(filePath, config) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  try {
+    fs.chmodSync(dir, 448);
+  } catch {
+  }
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2), { mode: 384 });
+  try {
+    fs.chmodSync(filePath, 384);
+  } catch {
+  }
+}
+
+export {
+  pairedConfigPath,
+  loadPairedConfig,
+  savePairedConfig
+};

package/dist/chunk-VZVGTHGF.js

@@ -0,0 +1,142 @@
+// src/tandem/session-discovery.ts
+import fs from "fs";
+import path from "path";
+function sessionDiscoveryDir() {
+  return path.join(process.env["HOME"] ?? "~", ".kojee", "sessions");
+}
+function sessionDiscoveryPath(sessionId) {
+  return path.join(sessionDiscoveryDir(), `${sessionId}.json`);
+}
+function discoveryFileName(key) {
+  return `cc-${key}.json`;
+}
+function writeSessionDiscovery(sessionId, entry) {
+  const dir = sessionDiscoveryDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  try {
+    fs.chmodSync(dir, 448);
+  } catch {
+  }
+  const filePath = sessionDiscoveryPath(sessionId);
+  fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), { mode: 384 });
+  try {
+    fs.chmodSync(filePath, 384);
+  } catch {
+  }
+}
+function readSessionDiscovery(sessionId) {
+  try {
+    const raw = fs.readFileSync(sessionDiscoveryPath(sessionId), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function cleanupSessionDiscovery(sessionId) {
+  try {
+    fs.unlinkSync(sessionDiscoveryPath(sessionId));
+  } catch {
+  }
+}
+function discoveryPathForKey(key) {
+  return path.join(sessionDiscoveryDir(), discoveryFileName(key));
+}
+function writeDiscoveryByKey(key, entry) {
+  const dir = sessionDiscoveryDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  try {
+    fs.chmodSync(dir, 448);
+  } catch {
+  }
+  const filePath = discoveryPathForKey(key);
+  fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), { mode: 384 });
+  try {
+    fs.chmodSync(filePath, 384);
+  } catch {
+  }
+}
+function cleanupDiscoveryByKey(key) {
+  try {
+    fs.unlinkSync(discoveryPathForKey(key));
+  } catch {
+  }
+}
+function readSessionDiscoveryByKey(key) {
+  try {
+    const raw = fs.readFileSync(discoveryPathForKey(key), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_SWEEP_MIN_AGE_MS = 6e4;
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === "EPERM") return true;
+    return false;
+  }
+}
+function sweepStaleDiscovery(opts = {}) {
+  const minAgeMs = opts.minAgeMs ?? DEFAULT_SWEEP_MIN_AGE_MS;
+  const dir = sessionDiscoveryDir();
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  for (const name of entries) {
+    if (!name.endsWith(".json")) continue;
+    const filePath = path.join(dir, name);
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      continue;
+    }
+    const ageMs = Math.max(0, now - stat.mtimeMs);
+    if (ageMs < minAgeMs) continue;
+    let parsed = null;
+    try {
+      parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    } catch {
+      try {
+        fs.unlinkSync(filePath);
+      } catch {
+      }
+      continue;
+    }
+    if (parsed?.schema !== 2) {
+      try {
+        fs.unlinkSync(filePath);
+      } catch {
+      }
+      continue;
+    }
+    if (typeof parsed.proxyPid !== "number" || !isProcessAlive(parsed.proxyPid)) {
+      try {
+        fs.unlinkSync(filePath);
+      } catch {
+      }
+      continue;
+    }
+  }
+}
+
+export {
+  sessionDiscoveryDir,
+  sessionDiscoveryPath,
+  discoveryFileName,
+  writeSessionDiscovery,
+  readSessionDiscovery,
+  cleanupSessionDiscovery,
+  discoveryPathForKey,
+  writeDiscoveryByKey,
+  cleanupDiscoveryByKey,
+  readSessionDiscoveryByKey,
+  sweepStaleDiscovery
+};

package/dist/chunk-WHTH6WBP.js

@@ -0,0 +1,72 @@
+// src/hooks/hook-input.ts
+var MAX_STDIN_BYTES = 1024 * 1024;
+var IDLE_TIMEOUT_MS = 50;
+var NULL_RESULT = {
+  sessionId: null,
+  transcriptPath: null,
+  hookEventName: null,
+  raw: ""
+};
+async function readHookStdin() {
+  const raw = await drainStdinBuffered();
+  if (raw === null) {
+    return { ...NULL_RESULT };
+  }
+  if (raw === "") {
+    return { ...NULL_RESULT };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      sessionId: stringOrNull(parsed["session_id"]),
+      transcriptPath: stringOrNull(parsed["transcript_path"]),
+      hookEventName: stringOrNull(parsed["hook_event_name"]),
+      raw
+    };
+  } catch {
+    return {
+      sessionId: null,
+      transcriptPath: null,
+      hookEventName: null,
+      raw
+    };
+  }
+}
+function stringOrNull(value) {
+  return typeof value === "string" ? value : null;
+}
+function drainStdinBuffered() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let total = 0;
+    let overflowed = false;
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const onData = (chunk) => {
+      if (overflowed) return;
+      total += chunk.length;
+      if (total > MAX_STDIN_BYTES) {
+        overflowed = true;
+        chunks.length = 0;
+        finish(null);
+        return;
+      }
+      chunks.push(chunk);
+    };
+    process.stdin.on("data", onData);
+    process.stdin.on("end", () => finish(Buffer.concat(chunks).toString("utf8")));
+    process.stdin.on("error", () => finish(Buffer.concat(chunks).toString("utf8")));
+    setTimeout(
+      () => finish(Buffer.concat(chunks).toString("utf8")),
+      IDLE_TIMEOUT_MS
+    );
+  });
+}
+
+export {
+  readHookStdin
+};