getclaros 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timur Monasypov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# getclaros guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local stdio MCP proxy. It wraps an app's MCP server and checks every write tool call against the company's
+expert-approved Work Maps (`POST /v1/check`) before the call reaches the app. A call that breaks a rule is never
+forwarded; the agent gets a tool error with the rule, the expert's words and who to ask.
+
+The package name (`getclaros`) is a placeholder and lives only in `package.json`.
+
+## Install
+
+```
+npx getclaros init
+```
+
+Not published yet (`"private": true`); until then run `node dist/cli.js init` with
+`GETCLAROS_LAUNCHER="node /abs/path/to/dist/cli.js"` so the configs launch your build instead of `npx -y getclaros`.
+
+`init` signs you in through the browser (RFC 8628 device flow): it prints a URL and a code (XXXX-XXXX), opens the
+URL (`--no-browser` to skip), and once you approve on Claros's `/device` page and pick a workspace it receives an
+`agent` key for that workspace. A key from `--key` / `$CLAROS_KEY` / the saved config wins; `--paste` (or a Claros
+without device sign-in) asks for a hidden paste instead. It checks the key, finds your agent clients' MCP configs, lists their servers and
+asks which to guard. Servers whose name matches an app with a Work Map are preselected. `--yes` takes that default,
+`--servers a,b` picks by name, `--project <dir>` sets where project configs are read (default: the current
+directory), `--no-mcp` skips the Claros MCP entry. Restart the agent client afterwards.
+
+| Client | Files read |
+|---|---|
+| Claude Code | `<project>/.mcp.json`; `~/.claude.json` (`mcpServers` and each `projects[path].mcpServers`) |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json`, `%APPDATA%\Claude\…`, `~/.config/Claude/…` |
+| Cursor | `~/.cursor/mcp.json`, `<project>/.cursor/mcp.json` |
+| VS Code | the profile's `mcp.json` (`~/Library/Application Support/Code/User/mcp.json`, …), `<project>/.vscode/mcp.json` |
+| Codex | `~/.codex/config.toml` (`$CODEX_HOME`), `<project>/.codex/config.toml`: `[mcp_servers.<name>]` tables |
+
+What it changes, in files that already exist (it never creates a client config):
+
+- Each picked stdio server: `command` becomes `npx`, and `-y getclaros guard --server <name> --` plus the original
+  command go in front of the original `args`. `env`, `cwd`, comments and everything else stay. Already-guarded
+  servers are left alone, so running `init` again changes nothing.
+- Each picked remote (`url`) server with static headers: the entry becomes a stdio one running
+  `npx -y getclaros guard --server <name> --remote <url> --header "K: V"…`, which reaches the server over Streamable
+  HTTP. The headers stay in that file and are never sent to Claros. Servers that need OAuth (no static header), take
+  their token from an env var or helper, or speak legacy SSE are listed as not guarded yet.
+- A `claros` server (`npx -y getclaros mcp`, a stdio bridge to Claros's `/mcp`) so agents can read the Work Map
+  up front with `get_workflow`; in each client's user config (or its project config when it has no user config).
+- Every file is backed up before it changes (`~/.config/getclaros/backups/<time>/`) and written atomically.
+
+```
+npx getclaros test     # a made-up record that breaks one of your rules → prints the stop (rule, expert's words, who to ask)
+npx getclaros status   # which servers are guarded, Claros reachable, key valid
+npx getclaros undo     # undo the last init; --all: every init, plus any guard wrapping it finds
+npx getclaros export <workflow_id> [--format agents|design|skill] > AGENTS.md   # a map's rules as markdown
+```
+
+`export` prints a Work Map's rules (`GET /v1/maps/<id>/export`) as an AGENTS.md section, a DESIGN.md-style file or a
+SKILL.md: an advisory copy for tools that read rules files; Claros still enforces the rules when the agent acts.
+Exit codes: 0 printed, 1 no such map, 2 not signed in / bad usage, 3 Claros unreachable or key rejected.
+
+`override <check_id> --rule <id> --reason "…"` tells the rule's expert a check got it wrong
+(`POST /v1/checks/<id>/override`; `--verdict wrong_stop` by default, or `wrong_nudge | missed | right`). Every stop
+message ends with this command filled in. Nothing changes until the expert confirms a suggested change on the map's
+rules page. Exit codes: 0 sent, 1 no such check / not valid, 2 bad usage, 3 unreachable or key rejected.
+
+`test` asks Claros for a record that breaks a precise rule of a Work Map for one of your guarded servers
+(`GET /v1/check/example?app=…`), checks it with `POST /v1/check` and prints the stop. Nothing is sent to the app.
+With no guarded server matching a map it uses the newest map and says `DEMO`. Exit codes: 0 stopped, 1 not stopped
+or no map to test, 2 not signed in / bad usage, 3 Claros unreachable or key rejected (`status` uses 0 / 2 / 3 too).
+
+`undo` restores a file from its backup when it is byte-for-byte what `init` wrote; if anything changed it since, it
+unwraps the guarded servers and removes the `claros` entry in place instead, keeping the other edits, and says which
+it did. What `undo` overwrites is backed up as well.
+
+Security model:
+
+- The key is stored once, in `~/.config/getclaros/config.json` (`$XDG_CONFIG_HOME`), mode 0600 in a 0700 directory,
+  never in a client config (project files such as `.mcp.json` are often committed). The guard and the bridge read it
+  from there (`--key` / `$CLAROS_KEY` still win). The key is never printed; output shows only its id
+  (`clr_<prefix>_…`).
+- Backups hold the full previous config files (which can contain other servers' tokens): 0600 files in a 0700
+  directory. Delete `~/.config/getclaros/backups` once you're happy.
+- The guard adds no credentials to the wrapped server: its `env` is passed through as before.
+
+## Usage
+
+```
+export CLAROS_KEY=clr_...            # a key with the `agent` scope
+getclaros guard --server erpnext -- npx -y some-erpnext-mcp --site https://erp.example.com
+```
+
+In an MCP client config, replace the server's `command`/`args` with the guard in front of them:
+
+```json
+{ "erpnext": { "command": "getclaros",
+               "args": ["guard", "--server", "erpnext", "--", "npx", "-y", "some-erpnext-mcp"],
+               "env": { "CLAROS_KEY": "clr_..." } } }
+```
+
+| Flag | Default | |
+|---|---|---|
+| `--server <name>` | required | Sent as `app`; helps route the call to the right Work Map |
+| `--url <base>` | `$CLAROS_URL`, else the URL `init` saved, else the one the web app names | Claros server base URL |
+| `--web <origin>` | `$CLAROS_WEB`, else the web origin `init` saved, else `https://claros-eta.vercel.app` | Where to ask for the server address (`/.well-known/claros.json`) |
+| `--key <key>` | `$CLAROS_KEY`, else the key `init` saved | Prefer the env var: flags show up in process lists |
+| `--timeout <ms>` | `5000` | How long to wait for a check |
+| `--fail-open` | off | Forward writes when Claros can't be reached (default: block them) |
+
+Server address: `--url` / `$CLAROS_URL` win and are never changed. Otherwise the CLI uses the URL `init` saved, or asks
+the web app (`GET <web>/.well-known/claros.json` → `{"api": "<server>"}`) and saves the answer with the web origin.
+When the saved server doesn't answer at all (a connection error, not an HTTP error), it asks the web app once more and
+follows a moved server, updating the saved config: no reinstall. A config made with `init --url` alone stays pinned to
+that URL. `--help` / `-h` on any command prints the usage.
+
+## What it does
+
+- Relays newline-delimited JSON-RPC both ways byte for byte; only `tools/call` is inspected.
+- Every `tools/list` response is passed on unchanged, then its tools are registered with Claros
+  (`POST /v1/tools {app, tools:[{name, description, inputSchema, annotations}]}`) so Claros can map their arguments
+  to a Work Map's fields once per tool. Only new tools or tools whose definition changed are sent. Registration is
+  fire and forget: a failure is logged, retried on the next `tools/list`, and never delays or blocks a call.
+- Read tools pass without a check. Claros's classification (`GET /v1/tools/kinds`: LLM-proposed, expert-overridable)
+  wins once known; until then `annotations.readOnlyHint === true`, or a name starting with get / list / search / read /
+  find / describe / fetch / check_ / run_ / export_, or exactly version / ping. Everything else is a write.
+  Kinds are refreshed after registration, on every `tools/list` and at most every 30 s on writes.
+- Writes: `POST /v1/check` with `{app, tool, action: tool, state, arguments}`. `state` is the arguments flattened
+  (`{"items.0.amount": 7200, "supplier": "..."}`); the server checks each array row as its own record. When the
+  tool has a mapping (proposed by Claros, confirmed by the expert), the server reads `arguments` through it instead,
+  so argument names don't have to match the map (`debit_to`, `items[].amount`).
+- Record resolution: when the tool's mapping references a record (a submit by name, a partial doc) or needs values the
+  app fills on save (an item's group), Claros answers `need: [{key, tool, arguments}]`. The guard calls those read
+  tools on the wrapped server itself, with ids under a per-process prefix that are never relayed to the agent, waits
+  at most `--timeout`, takes the record from `structuredContent` or the JSON in the text, and checks again with
+  `fetched`. A failed or missing read blocks the write (or forwards it with `--fail-open`). A `need` naming a tool the
+  guard doesn't consider a read is refused. Lookups (`cache: true`) are cached for 60 s; the record itself is read
+  every time.
+- Cross-server lookups: a `need` with `app` (another guarded server's read tool) goes to that server's guard over a
+  Unix socket, `<config dir>/run/<hash of the server name>.sock` (0600, dir 0700). Each guard serves its own server's
+  read tools there to guards that present the same key (sha256), and only read tools. No guard for that app → the
+  read fails → the write is blocked. Not on Windows yet.
+- Allowed → forwarded unchanged. Stopped (`stop` or `ask`) → an `isError` result under the same id; the app never sees the call.
+  Nudged (a rule broken whose response is `nudge`, e.g. a taste rule) → forwarded; the app's result comes back with
+  one more text item, "Claros nudge: …" (rule, the expert's words, the suggested fix), so the agent can correct itself.
+  A call several Work Maps govern is checked against each (milestone 7); the stop names every map whose rule it
+  breaks, and a rule taken from a written policy is quoted as "In the written policy (file § section)".
+- Claros unreachable, timed out or rejecting the key → writes are blocked with "ask a person"; reads still pass.
+- A JSON-RPC batch containing a write `tools/call` is rejected.
+- One log line per decision on stderr (stdout carries the protocol).
+
+## How a stop looks
+
+What the agent receives as the tool result (`isError: true`):
+
+```
+Claros stopped this action: it breaks a rule from the expert-approved Work Map "wf_ap_invoice". Do not retry it as is.
+
+Rule: Equipment over 5,000 is capex: book to the capital equipment account, never to expense.
+In the expert's words (AP lead): "Equipment above five thousand is an asset, it goes to capex."
+Who to ask: AP lead
+Next: change the record so the rule holds, or ask AP lead to approve an exception. Tell the user why.
+```
+
+An ask-first rule is held the same way (never run), but opens with "Claros held this action: a rule from the expert-approved Work Map … says to ask first." and its Next line says who to ask.
+
+A nudge, appended to the app's own result (not an error):
+
+```
+Claros nudge: the call went through, but it doesn't follow a rule your team holds. Fix it if you still can, and follow it from now on.
+
+Rule: <the rule>
+In the expert's words (<expert>): "<their words>"
+Suggested fix: <the judge's fix, or the rule's fix template filled from the record>
+```
+
+And on stderr:
+
+```
+[getclaros guard] erpnext submit_purchase_invoice → stop wf_ap_invoice g1 31ms chk_0b14cb5eef
+[getclaros guard] erpnext call_method → stop wf_ap_invoice g1 12ms (1 read) chk_8187eaa79f
+[getclaros guard] erpnext create_purchase_invoice → nudge wf_ap_invoice g1 2ms chk_25cd79b34a
+[getclaros guard]   nudge: <the rule> (fix: <the fix>)
+```
+
+## Develop
+
+```
+npm install
+npm test          # tsc + node:test (fake MCP server + fake Claros; init/test/undo against a temp HOME)
+npm run smoke     # starts its own Claros on a free port with a temp DB, seeds wf_ap_invoice; create_purchase_invoice
+                  # (supplier_name, debit_to, items[].amount) passes unmapped, is stopped once the expert maps it;
+                  # update_record {doctype, name, values: {docstatus: 1}} is stopped after the guard reads the record
+                  # and the item (fetch recipe + derived amount + lookup)
+                  # then smoke-init: empty temp HOME with a Claude Code config → init --yes → test (timed) → status,
+                  # the Claros MCP bridge against the real /mcp, undo
+cd e2e && npm run e2e  # against a real ERPNext through frappe-mcp-server (docs/GATEWAY_E2E_ERPNEXT.md)
+cd e2e && npm run horizontal  # four maps made from written policies, guards around mcp-sqlite (helpdesk, crm),
+                              # mcp-server-git, the filesystem server and (when it answers) the local Zammad; the real
+                              # LLM mapper, router and judge; prints mapper / routing / per-case tables (docs/HORIZONTAL.md)
+```
+
+The smoke runs the server with `CLAROS_TOOL_MAPPER=off` (no LLM proposals, offline) and maps the tool the way an
+expert would, through `POST /v1/tools/{id}/mapping`.
+
+Limits: until a tool is mapped, only argument names that match the map's field names or aliases are understood, and
+an unmapped write nothing matches is allowed (logged `mapping_status: unmapped`). The record is read just before the
+write, not locked: it can change in between. No Windows `.cmd` shims (spawn
+without a shell). Fuzzy rules (`judge_yourself`) are not enforced yet (milestone 5).

package/dist/bridge.js

@@ -0,0 +1,72 @@
+// getclaros mcp: the Claros MCP server (get_workflow, check_action, …) for any client, as a stdio server.
+// Relays each newline-delimited JSON-RPC message to <url>/mcp (streamable HTTP) with the saved key, and the answer
+// (JSON, or the `data:` events of an SSE answer) back on stdout. Every client speaks stdio, and the key stays in
+// ~/.config/getclaros instead of each client's config.
+import { relocate, resolve } from "./config.js";
+export async function bridge() {
+    const log = (s) => process.stderr.write(`[getclaros mcp] ${s}\n`);
+    let at;
+    try {
+        at = await resolve();
+    }
+    catch (e) {
+        log(e.message);
+        return process.exit(2);
+    }
+    const key = at.key;
+    if (!key)
+        log("no key: run `npx getclaros init` (or set CLAROS_KEY)");
+    let session, version, chain = Promise.resolve();
+    const out = (m) => process.stdout.write(m.trim() + "\n");
+    async function send(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const post = () => fetch(`${at.url}/mcp`, {
+            method: "POST", body: line, signal: AbortSignal.timeout(30_000),
+            headers: { "content-type": "application/json", accept: "application/json, text/event-stream",
+                ...(key ? { authorization: `Bearer ${key}` } : {}), ...(session ? { "mcp-session-id": session } : {}),
+                ...(version ? { "mcp-protocol-version": version } : {}) },
+        });
+        try {
+            // a server that doesn't answer may have moved: ask the web app once, then retry there
+            const r = await post().catch(async (e) => {
+                if (e.name === "TimeoutError" || !(await relocate(at)))
+                    throw e;
+                log(`Claros moved: now ${at.url}`);
+                return post();
+            });
+            session = r.headers.get("mcp-session-id") ?? session;
+            const text = await r.text();
+            if (!r.ok)
+                throw new Error(`HTTP ${r.status}`);
+            const msgs = (r.headers.get("content-type") ?? "").includes("event-stream")
+                ? text.split(/\r?\n\r?\n/).map((ev) => ev.split(/\r?\n/).filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim()).join("\n"))
+                : [text];
+            for (const m of msgs.filter((x) => x.trim())) {
+                version ??= JSON.parse(m)?.result?.protocolVersion;
+                out(m);
+            }
+        }
+        catch (e) {
+            if (msg?.id !== undefined) {
+                out(JSON.stringify({ jsonrpc: "2.0", id: msg.id, error: { code: -32000, message: `Claros MCP at ${at.url}: ${e.message}` } }));
+            }
+        }
+    }
+    let buf = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => {
+        buf += c;
+        for (let i; (i = buf.indexOf("\n")) >= 0; buf = buf.slice(i + 1)) {
+            const line = buf.slice(0, i);
+            if (line.trim())
+                chain = chain.then(() => send(line)); // in order; the server is stateless, so this is just simple
+        }
+    });
+    process.stdin.on("end", () => chain.then(() => process.exit(0)));
+}