remote-access-mcp 3.0.0 → 3.0.1

package/AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md — Guide for AI Coding Agents
+
+This file is the entry point for any AI agent (Claude Code, Cursor, opencode,
+Windsurf, etc.) working in this repository. Read it fully before touching code.
+
+**Deep documentation lives in [`docs/ai/`](docs/ai/)** — go there next:
+
+| File | What it covers |
+|---|---|
+| [`docs/ai/architecture.md`](docs/ai/architecture.md) | Module map, request lifecycle, data flow |
+| [`docs/ai/tools-and-cli.md`](docs/ai/tools-and-cli.md) | Every tool (44) and CLI command, with schemas and policy gates |
+| [`docs/ai/security-model.md`](docs/ai/security-model.md) | Auth, policy engine, guards, audit chain — read before security-adjacent changes |
+| [`docs/ai/transport-compatibility.md`](docs/ai/transport-compatibility.md) | The three MCP dialects we serve and why (hard-won lessons) |
+| [`docs/ai/decisions.md`](docs/ai/decisions.md) | Architecture Decision Records, including the fleet removal |
+
+## What this project is
+
+`remote-access-mcp` turns **one machine** (a server, a laptop, a desktop) into
+an endpoint an AI chatbot can operate over the [Model Context Protocol](https://modelcontextprotocol.io).
+ChatGPT, Grok and Claude connectors drive the machine's filesystem, shell,
+services, logs and packages through a per-token security policy.
+
+**One gateway = one machine. By design.** Multi-server orchestration ("fleet
+mode") was implemented and then removed (v3.0.0) — see
+[decisions.md ADR-007](docs/ai/decisions.md). If a task asks you to add it
+back, stop and confirm with the owner first.
+
+## The 30-second mental model
+
+```
+Chatbot (ChatGPT/Grok/Claude)
+   │  HTTPS via Cloudflare (TLS) / or quick tunnel on laptops
+   ▼
+nginx (port 80, SSE-tuned)         ── only on servers with a domain
+   ▼
+express gateway (127.0.0.1:8765)   ── node dist/server/run.js
+   ├─ authenticate token (URL-path or Bearer header)
+   ├─ per-token policy: scopes + paths + shell flag + read-only + rpm + expiry
+   ├─ per-request McpServer build → tools re-registered fresh (hot-reload)
+   ├─ audit wrapper → JSONL hash chain + webhook notifications
+   ▼
+the machine: fs, shell, systemd, journalctl, apt/npm, git, sqlite …
+```
+
+- Server speaks **both** Streamable HTTP (stateless + stateful) **and** the
+  legacy 2024-11-05 SSE transport, on **both** `/mcp` and `/sse` paths.
+- Config: `~/.config/remote-access-mcp/` (Linux), `AppData/Roaming` (Win),
+  `Library/Application Support` (mac). Live tunnel URL goes to `runtime.json`,
+  never config.
+
+## Ground rules for changes
+
+1. **TypeScript strict, ESM-only, zero `require()`** in `src/` — a `require()`
+   slipped past vitest once and crash-looped production for a day (ADR-004).
+2. **No native dependencies** in the runtime path. better-sqlite3 caused
+   SIGABRT in the stateless loop; the audit log is plain JSONL now (ADR-005).
+3. **Tests must be hermetic** — build gateway state explicitly; never read the
+   host's real config. A test suite that leaks production config will fail
+   whenever the service is running (ADR-006).
+4. **Run `npm test` (107 tests) before any publish.** CI runs Node 18/20/22.
+5. **Schema parameters must never be conditionally omitted** — the SDK
+   silently drops client args that aren't in the schema, which once turned a
+   "remote" command into a local execution (ADR-008).
+6. Commits: conventional, small, one concern each. This repo's history is
+   read as documentation (see `docs/ai/decisions.md`).
+
+## Commands
+
+```bash
+npm run build      # tsc → dist/
+npm test           # vitest, 107 tests
+npm run dev        # tsx watch (local only)
+ramcp doctor       # after deploying: full-chain health check
+```
+
+Deploy flow: build → test → `npm publish` → `npm i -g remote-access-mcp@latest`
+on the server → `systemctl restart remote-access-mcp` → verify via
+`ramcp doctor` + a ChatGPT-dialect initialize POST.

package/docs/ai/architecture.md

@@ -0,0 +1,106 @@
+# Architecture
+
+How the gateway is put together, for AI agents (and humans) who need to
+reason about it before changing it.
+
+## Module map
+
+```
+src/
+├── core/                    # framework-free building blocks
+│   ├── config.ts            # RamcpConfig + tokens; loads/migrates config.json
+│   ├── policy.ts            # path sandbox, scope groups, tool permission gate
+│   ├── audit.ts             # JSONL hash-chain audit log + redaction
+│   ├── crypto.ts            # timing-safe token compare
+│   ├── rate-limit.ts        # token-bucket per token
+│   ├── platform.ts          # OS detection, shells, dataDir, runtime state
+│   ├── tunnel.ts            # cloudflared quick-tunnel lifecycle
+│   ├── webhooks.ts          # fire-and-forget event notifications
+│   └── context.ts           # ConfigWatcher (hot-reload) + ToolContext
+├── server/
+│   ├── app.ts               # express app: auth, routes, sessions, MCP wiring
+│   ├── run.ts                # boot: listen, tunnel, runtime state, shutdown
+│   ├── sessions.ts           # stateful MCP session store (Claude dialect)
+│   └── legacy-sse.ts         # 2024-11-05 SSE transport + keepalive
+├── tools/                   # one file per suite, registered per request
+│   ├── filesystem.ts shell.ts system.ts http.ts git.ts sqlite.ts
+│   ├── logs.ts services.ts packages.ts schedule.ts security.ts
+│   ├── project.ts web.ts planning.ts ops.ts policy.ts index.ts
+└── cli/main.ts              # ramcp — all commands
+```
+
+## Request lifecycle (the part that matters most)
+
+One MCP POST travels this path:
+
+```
+nginx ─→ express
+        │  app.all('/<token>/sse') or ('/sse' + Bearer header)
+        ├─ authenticate(presented)                     [core/crypto + config]
+        │    reloads config if mtime changed  (hot-reload)
+        │    timing-safe compare against all tokens
+        ├─ rateLimited(token)?  → 429
+        ├─ normalizeAccept(req)                       [compat: never 406]
+        ├─ session routing:
+        │    Mcp-Session-Id present?
+        │      ├─ known session → its StreamableHTTP transport
+        │      └─ unknown → 404 (client restarts cleanly)
+        │    no session id:
+        │      ├─ initialize → new stateful session (id in response header)
+        │      └─ anything else → stateless throwaway transport
+        ├─ buildServerFor(token)                      [per request!]
+        │    McpServer + registerAllTools(server, ctx)
+        │    every tool handler wrapped: try/catch → audit → webhooks
+        └─ transport.handleRequest → tool executes → response
+```
+
+**Tools are re-registered for every request.** That is what makes policy
+edits (CLI or in-chat `allow_path`) apply on the next request with zero
+restarts. Do not "optimize" this by caching servers across requests — it
+would break hot-reload and per-token isolation.
+
+`ctx: ToolContext` carries `{ cfg, token, readOnly, persist, audit }`.
+The token record is looked up fresh per request, so a revoked token dies
+mid-conversation.
+
+## The three dialects (why server code looks redundant)
+
+| Client | Dialect | First request | Follow-ups |
+|---|---|---|---|
+| ChatGPT, Grok | Streamable, stateless | POST initialize (200 JSON/SSE) | fresh POST per call, ignores session id |
+| Claude (new SDK) | Streamable, stateful | POST initialize → **Mcp-Session-Id header back** | same id on every request; GET opens notification stream |
+| Claude (auto for `/sse` URLs) | Legacy SSE 2024-11-05 | **GET** stream → `event: endpoint` frame | POST to `/<token>/sse/messages?sessionId=…`, replies ride the stream |
+
+GET disambiguation: a GET **with** `Mcp-Session-Id` is a stateful client
+opening its notification stream; **without** it, it's a legacy client
+starting the handshake. Mixing these up sends `event: endpoint` to a
+stateful client, which aborts with `Unknown SSE event: endpoint` — that
+exact bug killed Claude connectors for a full day. Tests pin it
+(`tests/get-dispatch.test.ts`).
+
+## Data & state
+
+| File | Lives in | Written by | Lifetime |
+|---|---|---|---|
+| `config.json` | dataDir per OS | CLI, policy tools | persistent; 0600 |
+| `audit.jsonl` | dataDir | audit wrapper | append-only, hash-chained |
+| `runtime.json` | dataDir | gateway boot | ephemeral — pid-checked, cleared on exit |
+| `schedule.json`, `plans.json`, `snapshots.json`, `snapshots/` | dataDir | tools | persistent |
+
+The tunnel URL **only** ever goes to `runtime.json`. Writing it to config
+would clobber a server's real `public_host` the moment someone ran
+`ramcp tunnel` on it (that happened; ADR-003).
+
+## Cross-platform layer
+
+`core/platform.ts` normalizes: which shell (`bash -lc` / `pwsh` / `cmd.exe`),
+where data lives, how paths compare (case-insensitive on Win/mac),
+`which()`, `hasSystemd()`. Tools call `shellCommand()` instead of hardcoding
+bash — Windows compat lives or dies here.
+
+## Service installers
+
+`ramcp service install` writes a systemd unit (Linux), a launchd plist
+(macOS, per-user, no sudo), or a schtasks entry (Windows, logon trigger).
+The unit points at `dist/server/run.js` under the *global npm* install path —
+`ramcp upgrade` rewrites nothing but must restart the right manager per OS.

package/docs/ai/decisions.md

@@ -0,0 +1,141 @@
+# Decision Records (ADR)
+
+Short, dated records of *why* the code is the way it is. Each one encodes a
+lesson that cost real debugging time. When one of these decisions blocks
+something you're trying to do, don't quietly route around it — write a new
+record superseding the old one.
+
+---
+
+## ADR-001 — Express + per-request McpServer builds
+**Status:** accepted · **Date:** 2026-08-30
+
+The gateway builds a **fresh `McpServer` with all tools re-registered for
+every request** (stateless dialect) or per session (stateful).
+
+Why: (a) policy mutations — CLI, config hot-reload, or in-chat
+`allow_path` — must apply on the *next* request, not after a restart;
+(b) per-request builds bind the calling token's record into the handlers,
+so revocation/rotation takes effect mid-conversation; (c) the MCP SDK
+guidance for our compat matrix is one transport per request anyway.
+
+Cost: registration overhead per request (~1ms measured). Accepted.
+
+---
+
+## ADR-002 — Dual auth: Bearer header *and* token-in-URL
+**Status:** accepted · **Date:** 2026-08-30
+
+ChatGPT custom connectors cannot set custom headers, so the token rides in
+the URL path (`/<token>/mcp`). Everything else uses `Authorization: Bearer`.
+Both resolve through the same timing-safe comparison.
+
+---
+
+## ADR-003 — Tunnel URL lives in runtime.json, never config
+**Status:** accepted · **Date:** 2026-08-31
+
+Quick-tunnel URLs are valid only while the gateway process runs. The first
+implementation persisted the URL into `config.json`'s `public_host` — and
+one test run on the production server **clobbered the real domain**, after
+which `ramcp url` printed a dead trycloudflare URL to the user.
+
+Fix: `runtime.json` = {pid, tunnel_url, host, port, started}, written on
+boot, pid-checked on read (stale → ignored), cleared on exit including
+`process.on('exit')` for Windows service stops. `ramcp url` prefers the
+live tunnel. Pinned by `tests/runtime-state.test.ts`.
+
+---
+
+## ADR-004 — Pure ESM, no require() in src/
+**Status:** accepted · **Date:** 2026-08-31
+
+A `require()` in `src/cli/main.ts` passed the entire test suite (vitest's
+CJS interop tolerates it) and **crash-looped production** within a second
+of every systemd start. Diagnosis needed a boot test that runs the built
+output under plain node — which now exists (`tests/boot.test.ts`) and
+should be the pattern for anything touching startup paths.
+
+---
+
+## ADR-005 — Audit log is JSONL, not better-sqlite3
+**Status:** accepted · **Date:** 2026-08-31
+
+The original audit used better-sqlite3. In the stateless request loop its
+native `Statement` destructor aborted Node with SIGABRT (~8 requests in,
+native stack trace pointing at `Statement::~Statement`). Root cause:
+better-sqlite3's teardown hooks racing the SDK's per-request transports.
+
+The rewrite is a plain append + fsync JSONL file with the same hash chain,
+zero native code in the dependency tree, and a regression test that runs
+30 full stateless cycles with audit writes (`tests/crash-regression.test.ts`).
+sqlite_query/sqlite_schema keep better-sqlite3 for *user* databases (open
+per call, closed in-finally) — that usage never crashed.
+
+---
+
+## ADR-006 — Hermetic tests: build gateway state explicitly
+**Status:** accepted · **Date:** 2026-08-31
+
+Tests that called `buildApp()` without seeding state read the **host's real
+config**. It worked until the production server deployed with
+`mcp_path: /sse` — then 10 tests failed only-when-the-service-was-running.
+All suites now construct explicit `GatewayState` objects (see any
+`tests/*.test.ts` `beforeAll`).
+
+---
+
+## ADR-007 — Fleet mode removed (single machine by design)
+**Status:** accepted · **Date:** 2026-09-01 · **Supersedes:** the v2.4.0 fleet feature
+
+Fleet (SSH to N machines, per-host tool allowlists, 14 remote-capable
+tools, `ramcp fleet` CLI) was fully implemented, tested (including live-SSH
+and fake-ssh suites), published as 2.4.x — and then **removed entirely** in
+3.0.0 by owner decision: the product is one gateway per machine; multi-
+server orchestration is not the problem this project solves.
+
+What the removal kept: webhooks and `config export/import` (independent
+value). What it took with it: `src/core/fleet.ts`, `src/tools/fleet.ts`,
+the `host` parameter on 14 tools, fleet CLI/scopes/config, three test
+files. `ramcp fleet` is now an unknown command (pinned by a test).
+
+---
+
+## ADR-008 — Never omit schema parameters conditionally
+**Status:** accepted · **Date:** 2026-09-01 · **Learned from:** the fleet era
+
+When a tool's schema includes a parameter only under some conditions
+(e.g., `host` only when fleet hosts exist), the MCP SDK **silently strips**
+client arguments that aren't in the current schema. Consequence observed on
+production: a client sending `run_command {command, host: "ghost"}$` to a
+fleet-less gateway had `host` dropped and the **"remote" command executed
+locally on the gateway** — a silent security downgrade, not an error.
+
+Rule: parameters that gate security-relevant behavior stay in the schema
+always; the *handler* refuses with a clear error when the capability is
+absent. (Superseded by ADR-007 removing the host param outright, but the
+rule stands for anything like it.)
+
+---
+
+## ADR-009 — SSE-framed responses by default
+**Status:** accepted · **Date:** 2026-08-31
+
+`enableJsonResponse: true` (plain-JSON replies) works for ChatGPT/Grok but
+Claude's connector read a valid 200 initialize reply and silently
+abandoned the connection. SSE framing (`event: message\ndata: …`,
+`content-type: text/event-stream`) is the reference behavior and the only
+framing observed to satisfy every dialect we've tested. The wire-log proxy
+session that proved this is described in transport-compatibility.md.
+
+---
+
+## ADR-010 — execFile does not support the `input` option
+**Status:** accepted · **Date:** 2026-09-01
+
+`promisify(execFile)({... input})` never closes the child's stdin — the
+call hangs until timeout (fleet's remote file writes hung 5s→timeout every
+time before this was understood; a minimal `bash -c cat` repro confirmed
+it's the API, not our code). Pattern: when stdin must be piped, use
+`spawn()` and end the stream manually. The helper shape lives in git
+history (core/fleet.ts) if ever needed again.

package/docs/ai/security-model.md

@@ -0,0 +1,114 @@
+# Security Model
+
+The gateway hands an AI the keys to a machine. Every design choice below
+exists to make that survivable. Read this before touching anything in the
+auth, policy, or audit paths.
+
+## Threat model, plainly
+
+The token holder is **trusted** (that's you). The threats are:
+1. **Token leakage** → mitigate: no secrets in logs/audit (fingerprints only),
+   tight file perms, rotate in one command.
+2. **The AI itself** going somewhere you didn't intend → mitigate: path
+   sandbox, scope groups, read-only mode, shell opt-in, protected
+   services/packages/processes, SSRF walls.
+3. **A hostile chat platform or MITM** → mitigate: TLS at the edge
+   (Cloudflare/Let's Encrypt), loopback-only bind, timing-safe compares.
+4. **Tampering with history** after an incident → the hash chain.
+
+## Layer 1 — Network
+
+- Binds `127.0.0.1` only. Nothing listens publicly but nginx/Cloudflare.
+- `ramcp tunnel` (laptops) publishes a temporary https URL via cloudflared;
+  the URL dies with the process, is tracked in pid-checked `runtime.json`,
+  and self-verifies reachability before promising anything.
+
+## Layer 2 — Authentication
+
+- Two equivalent forms: `Authorization: Bearer <token>` or the token in the
+  URL path (`/<token>/mcp`) — the latter because ChatGPT connectors cannot
+  set custom headers.
+- Compare is **timing-safe** with a length pre-filter (`core/crypto.ts`).
+- Token records: expiry (ISO date), per-token rate limit (token bucket,
+  burst = rpm/4), revocation is config write + hot reload — a rotated token
+  dies mid-conversation.
+- Sessions (stateful dialect) are **bound to the token fingerprint** that
+  opened them: presenting another token with a stolen session id → 403.
+
+## Layer 3 — Authorization (per token)
+
+`assertToolPermitted()` enforces, in order:
+
+1. **scopes** — empty = every group; else the tool must belong to a listed
+   group. Group map is static in `core/policy.ts` (TOOL_SCOPES).
+2. **read-only** — per-token or global `ramcp policy readonly on` refuses
+   every entry of `MUTATING_TOOLS`.
+3. **path sandbox** — only if the tool passes a `target`:
+
+```
+resolveReal(path)               # realpathSync; for missing paths, the deepest
+                                # existing ancestor is resolved and the
+                                # remainder re-attached → symlink escapes collapse
+  → in denied_paths?  → refuse  # deny always wins, even inside an allowed root
+  → in allowed_paths? → allow
+  → else              → refuse  # empty allow-list denies everything
+```
+
+Path comparison is case-insensitive on Windows/macOS, separators normalized
+(`core/platform.ts`).
+
+**In-chat policy tools can only widen their own token's sandbox** — they
+mutate the calling token's record, never another token's.
+
+## Layer 4 — Tool-level guards
+
+| Guard | Tool(s) | Behavior |
+|---|---|---|
+| Shell opt-in | run_command, kill_process, schedule | refuse unless token `shell_enabled` |
+| Protected pids | kill_process | gateway pid, ppid, PID 1 |
+| SSRF wall | http_request, web_fetch, port_check | 127/8, 10/8, 172.16/12, 192.168/16, 169.254/16 (cloud metadata), 0/8, ::1, fc00::/7, fe80::/10, IPv4-mapped v6, metadata hostnames |
+| Git arg whitelist | git | ~45 known verbs; `--upload-pack`/`--exec=` refused; no `;&|`${}`<>` in args |
+| SQL single-statement | sqlite_query | one statement; ATTACH/DETACH refused (escape the sandbox via another db file) |
+| Unit-name regex | service_*, journal | `[A-Za-z0-9@._-]+` only |
+| Protected units | service_action | ssh/sshd/systemd/networkd/dbus/gateway itself/major Windows services |
+| Protected packages | package_remove | nodejs/npm/nginx/openssh/systemd/remote-access-mcp |
+| Secret masking | secret_scan | matches reported as file:line + type only — never the secret |
+| Secret redaction | environment_inspect | pass/secret/token/key/auth/credential vars → `[MASKED]` |
+| Schedule floor | schedule_command | ≥60s recurrence; one-shot allowed |
+
+## Layer 5 — Accounting
+
+- **Audit log** (`audit.jsonl`): one line per tool invocation — ts, token
+  **fingerprint** (sha256-16, never the secret), tool, redacted args,
+  ok/is_error, duration. Each line's `hash = sha256(prev_hash + fields)` →
+  deleting or editing any line breaks every hash after it.
+  `ramcp audit chain` walks it; exit code 2 on tamper. Args are redacted
+  (`pass|secret|token|key|auth` keys → `[REDACTED]`, values capped at 300ch).
+- **Webhooks** mirror tool.error/tool.success out to URLs you own —
+  fire-and-forget, 5s timeout, identical events deduped within 10s.
+
+## Layer 6 — The audit wrapper itself
+
+`buildServerFor()` monkey-patches `server.registerTool` so **every** handler
+is wrapped: errors are caught and converted to `isError` results (a tool
+crash must never 500 the transport), then audit + webhooks fire. This is
+also the single choke point where a future change would accidentally bypass
+accounting — keep it that way.
+
+## Things we refuse to add (non-negotiable)
+
+- No `require()` in `src/` (pure ESM; one slip crash-looped production).
+- No native modules in the request path (better-sqlite3 SIGABRT'd the
+  stateless loop — audit is plain JSONL now).
+- No dynamic schema omission (the SDK silently drops unknown client args;
+  that once executed a "remote" command locally — ADR-008).
+- No second machine (fleet removed by owner decision — ADR-007).
+
+## If you're adding a tool
+
+Checklist: (1) pick/extend a scope group; (2) decide mutating or read-only
+and add to MUTATING_TOOLS if mutating; (3) accept `path`-style targets →
+pass them as `target:` to the gate; (4) think about injection (quotes,
+metacharacters, second-order effects) and add a guard, not a regex hope;
+(5) never log secrets; the audit wrapper redacts args but your *output* is
+on you.

package/docs/ai/tools-and-cli.md

@@ -0,0 +1,152 @@
+# Tools & CLI Reference
+
+Complete inventory of what the gateway exposes, as of v3.0.0.
+Counts: **44 tools / 17 suites**, **17 CLI commands**.
+
+Every tool handler runs inside the audit wrapper (app.ts): execution is
+timed, arguments redacted, outcome appended to the hash chain, webhooks
+notified. A thrown `PolicyError`/`ScopeError` becomes a normal `isError`
+result — never a 500.
+
+## Permission gate (read this first)
+
+`assertToolPermitted({ tool, scopes, readOnly, policy?, target? })` in
+`core/policy.ts` — three checks, in order:
+
+1. **scopes** — token's `scopes[]` empty = all groups; otherwise tool must
+   be in a listed group (group map in `TOOL_SCOPES`).
+2. **readOnly** — token or global read-only refuses `MUTATING_TOOLS`.
+3. **policy paths** — if `target` given: resolveReal() (symlinks collapsed,
+   deepest existing ancestor for not-yet-existing files) → deny-list wins →
+   must be inside an allow-list entry.
+
+Scope groups: `filesystem shell system http git sqlite policy logs services
+packages schedule security project planning formatting documents ops web`.
+(`ramcp scopes` prints them with member tools.)
+
+## Suites
+
+### filesystem (7) — policy-gated on every path
+| Tool | Notable |
+|---|---|
+| `list_directory` | 2000-entry cap |
+| `read_file` | `offset`/`limit` line windows |
+| `write_file` | mkdir option |
+| `edit_file` | exact-text replace, `all` flag |
+| `delete_path` | rm -rf — destructive, policy-gated |
+| `search_code` | recursive regex, skips .git/node_modules |
+| `file_info` | stat essentials |
+
+### shell (3) — behind token `shell_enabled`
+| Tool | Notable |
+|---|---|
+| `run_command` | platform shell via `shellCommand()`; ≤600s; 60KB output cap; cwd policy-gated |
+| `process_list` | ps (POSIX) / Get-Process (Win) |
+| `kill_process` | refuses gateway pid, ppid, PID 1 |
+
+### system (3)
+`system_info` · `disk_usage` (df / Get-Volume) · `network_interfaces` — all
+cross-platform, no gates (read-only host facts).
+
+### http (3) — SSRF-guarded
+`http_request` · `port_check` · `web_fetch` — loopback/private/link-local
+(169.254.0.0/16 incl. cloud metadata) refused; IPv4-mapped IPv6 too.
+
+### git (1)
+`git` — args validated: verb must match a whitelist (~45 verbs, no
+`upload-pack`/`exec=`), no shell metacharacters in any arg; `repo_path`
+policy-gated.
+
+### sqlite (2) — policy-gated on db_path
+`sqlite_query` — single statement only, ATTACH/DETACH refused, SELECT/WITH/
+PRAGMA/EXPLAIN return rows, others report changes. `sqlite_schema`.
+
+### logs (3) — policy-gated paths
+`tail_logs` (1MB tail read) · `search_logs` (regex + context) · `journal`
+(unit-name regex validated; journalctl / mac `log show` / Get-WinEvent).
+
+### services (2)
+`service_status` · `service_action` — `PROTECTED_UNITS` regex refuses ssh,
+the gateway itself, dbus/networkd/WinDefend etc. Unit names regex-validated.
+
+### packages (3)
+`package_list` / `package_install` / `package_remove` — manager auto-detected
+(apt / brew / winget / choco / npm); `package_remove` refuses
+nodejs/npm/nginx/openssh/systemd/remote-access-mcp.
+
+### schedule (3)
+`schedule_command` (one-shot ISO time or recurring ≥60s; requires shell
+token) · `list_scheduled_tasks` · `cancel_scheduled_task`. File-backed
+(`schedule.json`), a 30s in-process ticker executes them.
+
+### security (2)
+`secret_scan` — 10 credential patterns (keys, AWS, GitHub, Slack, npm,
+bearer, connection-string passwords); **output is masked**, only
+file:line + type. `port_scan_local` — ss / lsof / Get-NetTCPConnection.
+
+### project (2)
+`analyze_project` (files/LOC/manifests/entry points, depth-capped walk) ·
+`project_health_check` (git dirty, README presence, TODO density).
+
+### planning (4)
+`create_task_plan` · `task_status` (mark steps done) · `workspace_snapshot`
+(content-addressed file copies) · `rollback_changes` (atomic restore).
+Snapshot/rollback are in `MUTATING_TOOLS`.
+
+### web (1)
+`web_fetch` — SSRF-guarded public fetch, UA-tagged, size-capped.
+
+### ops (2)
+`environment_inspect` — env vars, secrets masked, long values truncated.
+`nginx_inspect` — read-only; site names regex-validated (no traversal);
+`nginx -T` summary or per-site config.
+
+### policy (4) — token manages only its own sandbox
+`list_allowed_paths` · `allow_path` · `deny_path` · `shell_enabled`. Mutations
+persist via `saveConfig` and hot-reload; they cannot touch other tokens.
+
+## CLI (`ramcp`)
+
+| Command | Subcommands / flags | Notes |
+|---|---|---|
+| `init` | `--paths a,b` | creates config + default token; re-run safe |
+| `start` | `--tunnel --read-only --host --port` | foreground |
+| `tunnel` | — | gateway + public URL; runtime state; self-checks reachability |
+| `url` | `[name]` | live tunnel URL wins, else public_host/local |
+| `token` | `add --name --paths --deny --scopes --shell --read-only --rpm --expires` · `list [--json]` · `show [--full]` · `rotate` · `revoke` | last token can't be revoked |
+| `policy` | `allow <p…>` · `deny <p…>` · `shell on/off` · `scopes <groups|all>` (all `--token`) · `readonly on/off` (global) | multi-path, space-separated |
+| `scopes` | — | group → tools map |
+| `audit` | `--tool --since --limit --json` · `chain` | chain verifies hash chain, exit 2 on tamper |
+| `doctor` | — | platform, config, tokens, gateway, service, tunnel, public, audit |
+| `service` | `install [--domain] [--tunnel] [--dry-run]` · `uninstall` · `logs [-f]` · `status` | systemd / launchd / schtasks by OS |
+| `schedule` | `list [--json]` | |
+| `upgrade` | `--dry-run` | npm self-update + right restart per OS |
+| `status` | — | incl. live runtime state |
+| `version` | — | |
+| `config` | `show` · `export [--out]` · `import FILE [--merge]` | export 0600, contains live tokens; merge preserves local identity |
+| `webhook` | `add --url --events` · `list` · `on/off URL` · `remove URL` | events: `tool.error`, `tool.success`, `*` |
+| ~~`fleet`~~ | — | **removed in v3.0.0** — unknown command now |
+
+### Config file shape (v3)
+
+```jsonc
+{
+  "host": "127.0.0.1", "port": 8765, "public_host": "mcp.example.com",
+  "mcp_path": "/mcp", "mcp_path_aliases": ["/sse"],
+  "log_level": "info",
+  "audit": { "enabled": true, "db_path": "…/audit.jsonl" },
+  "read_only": false,
+  "tunnel": { "provider": "cloudflare", "auto_start": false },
+  "webhooks": [{ "url": "…", "events": ["tool.error"], "enabled": true }],
+  "tokens": [{
+    "id": "…", "name": "default", "token": "…", "created": "ISO",
+    "expires": "ISO?", "scopes": [], "read_only": false,
+    "max_requests_per_minute": 60?, "shell_enabled": true,
+    "allowed_paths": ["…"], "denied_paths": []
+  }]
+}
+```
+
+Env overrides (tests, minimal deploys): `RAMCP_TOKEN RAMCP_HOST RAMCP_PORT
+RAMCP_PUBLIC_HOST RAMCP_SHELL RAMCP_ALLOWED_PATHS RAMCP_DENIED_PATHS`
+(legacy `DANA_*` still honored). `SSH_BIN` existed for fleet tests — gone.

package/docs/ai/transport-compatibility.md

@@ -0,0 +1,85 @@
+# Transport Compatibility
+
+Why the server speaks three MCP dialects, and the exact bugs that forced
+each one. This file exists so nobody "simplifies" it away.
+
+## The three dialects
+
+| # | Dialect | Who speaks it | Handshake | Replies |
+|---|---|---|---|---|
+| 1 | Streamable HTTP, **stateless** | ChatGPT, Grok | POST initialize | inside the POST response; session id ignored |
+| 2 | Streamable HTTP, **stateful** | Claude (new SDK), most reference clients | POST initialize → `Mcp-Session-Id` response header | every request carries the id; GET opens a server→client notification stream |
+| 3 | **Legacy SSE** (2024-11-05) | Claude's connector UI auto-selects it when the URL ends in `/sse` | **GET** → `event: endpoint` frame announces the POST URL + sessionId | replies ride the long-lived GET stream; POSTs are 202 |
+
+All three are served on **both** endpoint paths (`/mcp` and `/sse`, plus any
+configured aliases) — the URL does not determine the dialect; the request
+shape does.
+
+## Dispatch rules (server/app.ts)
+
+```
+POST with Mcp-Session-Id:
+    known session    → that session's StreamableHTTP transport
+    unknown session  → 404 "Session not found"   (client re-initializes)
+POST initialize (no id) → new stateful session, id in response header
+POST anything else (no id) → stateless throwaway transport  (ChatGPT/Grok)
+GET  with Mcp-Session-Id   → streamable notification stream for that session
+GET  without id            → legacy SSE handshake (event: endpoint …)
+POST /<token>/<path>/messages?sessionId=… → legacy SSE post-back leg
+DELETE with id             → session teardown (204)
+```
+
+`normalizeAccept()` widens every Accept header to
+`application/json, text/event-stream` (GET → `text/event-stream`) before
+the SDK sees it. The SDK enforces the spec strictly and answers 406 to
+`*/*` or single-type Accepts; real clients send all of those.
+
+Responses are **SSE-framed** (`enableJsonResponse: false`) — the spec's
+reference behavior, and the framing every dialect we've seen accepts.
+Plain-JSON mode was tried; Claude's connector silently dropped it.
+
+## The incident log (each of these shipped and hurt)
+
+1. **No session id** → Claude retried initialize every ~60s and reported
+   "Couldn't reach <server>". Fix: stateful sessions (v2.2.0),
+   `sessions.ts` store with 30-min idle TTL, 200 cap, per-token binding.
+2. **406 on honest Accepts** → clients sending `*/*` or
+   `text/event-stream` alone got rejected by the SDK's strict check.
+   Fix: normalizeAccept (v2.2.1).
+3. **`Unknown SSE event: endpoint`** → the legacy transport was bolted on
+   by hijacking **every** GET; a stateful client opening its notification
+   stream received the legacy `event: endpoint` frame and aborted its whole
+   TaskGroup. Fix: dispatch GETs by the Mcp-Session-Id header (v2.2.2/3).
+4. **Plain-JSON responses dropped** → initialize answered 200 +
+   `application/json`, Claude read it and silently gave up. Fix: SSE
+   framing everywhere (v2.2.4). Diagnosed with a byte-logging wire proxy:
+   the client's exact headers/body made it obvious Claude got a *valid*
+   reply and still walked away — only the framing differed.
+
+## Verification (do not trust, run)
+
+The byte-exact Claude simulation lives in git history
+(`python-httpx/0.28.1` + `clientInfo.name: "Anthropic"`); the pinned suite
+covers the matrix:
+
+- `tests/sessions.test.ts` — stateful handshake, routing, hijack-refusal,
+  DELETE teardown, stateless fallback
+- `tests/get-dispatch.test.ts` — GET with id never emits `endpoint`; GET
+  without id always does
+- `tests/legacy-sse.test.ts` — full 2024-11-05 handshake over `/sse` and
+  `/mcp`, sessionId-less POST-back → 400, unknown → 404, cross-token → 403
+- `tests/accept-compat.test.ts` — six Accept variants all initialize
+
+## Edge / proxy notes (production config)
+
+- nginx: `proxy_buffering off`, `proxy_request_buffering off`,
+  `proxy_set_header Connection ""`, `chunked_transfer_encoding on`,
+  `gzip off`, `add_header X-Accel-Buffering no`, read/send timeouts 3600s —
+  a legacy SSE stream idles between tool calls; the default 60s proxy
+  timeouts kill it. The gateway sends `: keepalive` comments every 15s so
+  intermediate hops don't reap the stream.
+- Cloudflare proxies all three dialects fine (verified from the edge).
+- Quick tunnels on filtered networks can register but not carry traffic —
+  `ramcp tunnel` self-verifies and warns instead of handing out a dead URL
+  (that's environment, not protocol; http2-over-TCP is forced for the same
+  reason — QUIC is blocked on some ISPs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-access-mcp",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Turn any Linux server into an AI-agent-accessible machine via MCP. ChatGPT, Claude, and Grok connect over HTTPS and control files, shell, git, and more — securely and with zero Python dependencies.",
   "type": "module",
   "bin": {
@@ -12,7 +12,9 @@
     "README.md",
     "README.fa.md",
     "LICENSE",
-    "install.sh"
+    "install.sh",
+    "AGENTS.md",
+    "docs/ai"
   ],
   "engines": {
     "node": ">=20.18.1"