kojee-mcp 0.2.2 → 0.5.0

package/README.md

@@ -1,14 +1,38 @@
 # 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.
+> **First time using Kojee Tandem in Claude Code?** See [docs/getting-started-tandem.md](docs/getting-started-tandem.md) for the 3-command setup + verification walkthrough.
 
-## Quick Start
+There are two ways to connect Kojee to an MCP-capable agent:
 
-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.
+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.
 
-## MCP Config Examples
+## Mobile, Web & Desktop (Recommended)
+
+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 +49,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 +70,126 @@ 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 under the OS's temp directory
+(`os.tmpdir()` — `/tmp` on Linux, `/var/folders/…` on macOS, `%TEMP%` on
+Windows). The agent watches this log via Claude Code's built-in `Monitor`
+tool — spawned once at the start of each session:
+
+```ts
+Monitor({
+  command: `npx kojee-mcp tail "${eventLogPath}"`,
+  persistent: true,
+  description: "kojee Tandem events",
+});
+```
+
+`kojee-mcp tail` is a portable line-streamer shipped with this proxy —
+works the same on macOS, Linux, and Windows. The proxy interpolates the
+resolved `eventLogPath` into the Channel-`instructions` string so the
+agent receives a ready-to-run command.
+
+The `<discoveryKey>` embedded in the log filename 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 always long-polls** (up to 30s): the queue's `markMonitorDelivered` dedup ensures every event is delivered exactly once across the Channel / Monitor / Stop-hook paths, so the hook doesn't need to probe whether a Monitor is running. If the agent skipped the session-start Monitor spawn, the long-poll backstop still catches events; if Monitor is running, the dedup filters out anything already delivered push-style.
+
+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.
+
+**Cross-platform support:** the proxy core, the `kojee-mcp tail` Monitor command, and the Channel wake path are portable across macOS, Linux, and Windows — path resolution uses `os.homedir()` / `os.tmpdir()` and process-ancestry detection uses the pure-JS `ps-list` package. Claude Code hook invocation on Windows is pending end-to-end verification; on macOS and Linux it is exercised by CI.
+
+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-BJMASMKX.js

@@ -0,0 +1,41 @@
+// src/runtime/ancestry.ts
+import psList from "ps-list";
+import { createHash } from "crypto";
+async function findClaudeAncestorPid(startPid = process.ppid) {
+  let processes;
+  try {
+    processes = await psList();
+  } catch {
+    return null;
+  }
+  const byPid = /* @__PURE__ */ new Map();
+  for (const p of processes) byPid.set(p.pid, p);
+  let pid = startPid;
+  for (let depth = 0; depth < 20 && pid !== void 0 && pid > 1; depth++) {
+    const row = byPid.get(pid);
+    if (!row) return null;
+    const haystack = `${row.name} ${row.cmd ?? ""}`;
+    if (/\bclaude\b/i.test(haystack)) return pid;
+    if (row.ppid === void 0 || row.ppid === pid) return null;
+    pid = row.ppid;
+  }
+  return null;
+}
+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-E26AHU6J.js

@@ -0,0 +1,27 @@
+// src/tandem/recipe.ts
+var SEND_BODY_PARAM = "body";
+function buildMonitorCommand(logPath) {
+  return `npx kojee-mcp tail "${logPath}"`;
+}
+function buildMonitorSpawn(logPath) {
+  return `Monitor(command=\`${buildMonitorCommand(logPath)}\`, persistent=true, description="kojee Tandem events")`;
+}
+function buildReplyRecipe(event) {
+  if (event) {
+    return `reply directly with tandem_send(tandem_id="${event.tandem_id}", ${SEND_BODY_PARAM}="...", reply_to="${event.message_id}"); fetch context only if needed via tandem_messages(tandem_id, since=cursor-1)`;
+  }
+  return `reply directly with tandem_send(tandem_id, ${SEND_BODY_PARAM}, reply_to=<msg>); fetch context only if needed via tandem_messages(tandem_id, since=cursor-1)`;
+}
+function buildCatchUpNote() {
+  return "If the event line `cursor=<n>` ever jumps (a gap) or the log resets (the proxy caps and truncates the messages log in place on overflow \u2014 a `status=rotated` line is recorded in the status sibling), you may have missed messages: catch up with tandem_messages(tandem_id, since=<last cursor you saw>).";
+}
+function buildMonitorNudge(logPath) {
+  return `[kojee] Tandem events are being logged but no Monitor is reading them \u2014 you may be missing wake notifications. Spawn the watcher once: ${buildMonitorSpawn(logPath)}. Then ${buildReplyRecipe()}.`;
+}
+
+export {
+  buildMonitorSpawn,
+  buildReplyRecipe,
+  buildCatchUpNote,
+  buildMonitorNudge
+};

package/dist/chunk-GBOTBYEP.js

@@ -0,0 +1,34 @@
+// src/auth/paired-config.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+function pairedConfigPath() {
+  return path.join(os.homedir(), ".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
+};