oathline-guard 0.1.0__tar.gz

oathline_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexxt Nest Group Pty Ltd (ABN 52 689 862 922)
+
+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.

oathline_guard-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: oathline-guard
+Version: 0.1.0
+Summary: An MCP guard where an AI agent's yes means exactly what the person saw: reads pass, every other tool call waits for a coded yes in a second terminal, runs once, and is recorded in Oathline's hash-chained log.
+Author: Nexxt Nest Group Pty Ltd
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/oathline/oathline-guard
+Project-URL: Repository, https://github.com/oathline/oathline-guard
+Project-URL: Issues, https://github.com/oathline/oathline-guard/issues
+Project-URL: Changelog, https://github.com/oathline/oathline-guard/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oathline<0.3,>=0.2.0
+Dynamic: license-file
+
+# oathline-guard
+
+**An AI agent's yes means exactly what the person saw.**
+
+oathline-guard sits between your MCP client (Claude Desktop, Claude Code, Cursor) and a real stdio MCP server. Reads you list
+pass straight through. Every other tool call waits: a person, in a second terminal, sees the exact call in the guard's own words
+and types its four-character code. Then it runs once, with exactly those arguments, and [Oathline](https://github.com/oathline/oathline)'s
+hash-chained log records what was shown, heard, confirmed and run.
+
+In April 2026 a coding agent deleted a production database and its backups in nine seconds, with no approval step. This is the
+same request, through the guard:
+
+```text
+db / drop_database
+name: prod
+code: 44NF
+Type the code to run it, or n to refuse: n
+Refused and recorded (c-508e50ec). Nothing will run.
+```
+
+The agent only ever gets "Not run ... waiting for a person's yes"; the code is never sent to it, so it cannot approve itself.
+
+## Quickstart (about 5 minutes, with the demo database)
+
+**1. Install** (Python 3.10 or later):
+
+```
+pip install oathline-guard
+```
+
+**2. Prepare the demo:**
+
+```
+oathline-guard demo
+```
+
+It writes the read list (the tools that pass without a yes) to `~/oathline-guard-demo/reads.json`:
+
+```json
+{"server": "db", "reads": ["list_databases", "list_tables"]}
+```
+
+and prints the block for Claude Desktop with your machine's real paths (it runs everything through the Python you installed
+with, so `PATH` and `python` vs `python3` do not matter). It approves nothing and runs nothing.
+
+**3. Add the block to Claude Desktop.** Open `claude_desktop_config.json` (Settings > Developer > Edit Config; on macOS it is
+in `~/Library/Application Support/Claude/`, on Windows in `%APPDATA%\Claude\`), paste the printed block, then restart Claude
+Desktop. By hand, the block has this shape:
+
+```json
+{
+  "mcpServers": {
+    "db": {
+      "command": "oathline-guard",
+      "args": ["run", "--server", "db", "--reads", "/path/to/reads.json", "--human", "you",
+               "--", "python", "-m", "oathline_guard.demo.fake_db", "--state", "/path/to/db.json"]
+    }
+  }
+}
+```
+
+`oathline_guard.demo.fake_db` is a tiny database server with two reads and two writes (`drop_database`, `delete_backups`) and
+no protection of its own. Claude Desktop starts it with a short PATH: written by hand, if `oathline-guard` is not found, use
+the full path that `pip` printed, and if `python` is not found (on macOS often only `python3` exists), write `python3` or the
+interpreter's full path. The block `oathline-guard demo` prints avoids both.
+
+**4. Open the approve window** in a second terminal and leave it open:
+
+```
+oathline-guard approve --server db
+```
+
+**5. Ask Claude:** "clean up the old database". The reads run. The drop waits, and the approve window shows it as above: type
+`n` to refuse, or the code to let it run once. After a yes, the agent's next identical call runs it; a call with different
+arguments is a new request that waits again.
+
+To guard a real server, put its own command after `--` and list its read-only tools in `reads.json`. Tools not on the list
+always wait, whatever the server's own annotations (`readOnlyHint`) say.
+
+## What it guarantees, and what it does not
+
+- Reads on your list pass untouched; everything else is held, and the real server is not called until the yes.
+- The words in the window are the guard's: the tool and every argument, never the server's description. A value cannot add a
+  line of its own; long values are shown whole and bound by hash, up to 16,000 characters of window text and Oathline Core's
+  8 KB cap on a call's items. A call beyond either is refused before anything is shown (`text_too_large`, `items_too_large`):
+  split it.
+- The yes runs the stored arguments exactly once. A wrong code decides nothing; a no is recorded, and a later yes is too late.
+- The approve window reads only from a terminal: an agent's shell tool cannot pipe the code in.
+
+Limits, said plainly:
+
+- **A pseudo-terminal passes the terminal check.** It stops a pipe, not a determined local process with a pty.
+- **An agent with a raw shell or a raw token goes around any MCP guard.** The guard governs the calls that pass through it;
+  switch off the client's own write tools for the session if the guard must be the only way to act.
+- **No timeout on an upstream call yet**, and the agent retries after the yes (no waiting notification yet). On Windows, when
+  the upstream is started through a virtual environment's `python.exe` (a launcher that holds the pipes), an upstream that
+  closes its output but keeps running is noticed only when it exits.
+- **stdio servers only**; one person per guarded server; the terminal is the only approval channel.
+- **Secret arguments are not masked yet**: a secret in an argument is shown in the window.
+- **Heard is not understood:** the record proves the words were shown and answered, not that they were read.
+
+## The record
+
+Each guarded server keeps its own folder (default `~/.oathline-guard/<server>/`) with Oathline Core's audit chain and token
+store. The chain for one call reads `REQUEST AUTHORIZED PROPOSED_BY_AGENT SHOWN HEARD CONFIRMED_BY_HUMAN EXECUTING EXECUTED`, or
+ends at `REFUSED_BY_HUMAN`; `verify()` on the audit log checks every link.
+
+## Licence
+
+MIT. Copyright (c) 2026 Nexxt Nest Group Pty Ltd. Built on [Oathline Core](https://pypi.org/project/oathline/).
+
+<!-- mcp-name: io.github.oathline/oathline-guard -->

oathline_guard-0.1.0/README.md

@@ -0,0 +1,112 @@
+# oathline-guard
+
+**An AI agent's yes means exactly what the person saw.**
+
+oathline-guard sits between your MCP client (Claude Desktop, Claude Code, Cursor) and a real stdio MCP server. Reads you list
+pass straight through. Every other tool call waits: a person, in a second terminal, sees the exact call in the guard's own words
+and types its four-character code. Then it runs once, with exactly those arguments, and [Oathline](https://github.com/oathline/oathline)'s
+hash-chained log records what was shown, heard, confirmed and run.
+
+In April 2026 a coding agent deleted a production database and its backups in nine seconds, with no approval step. This is the
+same request, through the guard:
+
+```text
+db / drop_database
+name: prod
+code: 44NF
+Type the code to run it, or n to refuse: n
+Refused and recorded (c-508e50ec). Nothing will run.
+```
+
+The agent only ever gets "Not run ... waiting for a person's yes"; the code is never sent to it, so it cannot approve itself.
+
+## Quickstart (about 5 minutes, with the demo database)
+
+**1. Install** (Python 3.10 or later):
+
+```
+pip install oathline-guard
+```
+
+**2. Prepare the demo:**
+
+```
+oathline-guard demo
+```
+
+It writes the read list (the tools that pass without a yes) to `~/oathline-guard-demo/reads.json`:
+
+```json
+{"server": "db", "reads": ["list_databases", "list_tables"]}
+```
+
+and prints the block for Claude Desktop with your machine's real paths (it runs everything through the Python you installed
+with, so `PATH` and `python` vs `python3` do not matter). It approves nothing and runs nothing.
+
+**3. Add the block to Claude Desktop.** Open `claude_desktop_config.json` (Settings > Developer > Edit Config; on macOS it is
+in `~/Library/Application Support/Claude/`, on Windows in `%APPDATA%\Claude\`), paste the printed block, then restart Claude
+Desktop. By hand, the block has this shape:
+
+```json
+{
+  "mcpServers": {
+    "db": {
+      "command": "oathline-guard",
+      "args": ["run", "--server", "db", "--reads", "/path/to/reads.json", "--human", "you",
+               "--", "python", "-m", "oathline_guard.demo.fake_db", "--state", "/path/to/db.json"]
+    }
+  }
+}
+```
+
+`oathline_guard.demo.fake_db` is a tiny database server with two reads and two writes (`drop_database`, `delete_backups`) and
+no protection of its own. Claude Desktop starts it with a short PATH: written by hand, if `oathline-guard` is not found, use
+the full path that `pip` printed, and if `python` is not found (on macOS often only `python3` exists), write `python3` or the
+interpreter's full path. The block `oathline-guard demo` prints avoids both.
+
+**4. Open the approve window** in a second terminal and leave it open:
+
+```
+oathline-guard approve --server db
+```
+
+**5. Ask Claude:** "clean up the old database". The reads run. The drop waits, and the approve window shows it as above: type
+`n` to refuse, or the code to let it run once. After a yes, the agent's next identical call runs it; a call with different
+arguments is a new request that waits again.
+
+To guard a real server, put its own command after `--` and list its read-only tools in `reads.json`. Tools not on the list
+always wait, whatever the server's own annotations (`readOnlyHint`) say.
+
+## What it guarantees, and what it does not
+
+- Reads on your list pass untouched; everything else is held, and the real server is not called until the yes.
+- The words in the window are the guard's: the tool and every argument, never the server's description. A value cannot add a
+  line of its own; long values are shown whole and bound by hash, up to 16,000 characters of window text and Oathline Core's
+  8 KB cap on a call's items. A call beyond either is refused before anything is shown (`text_too_large`, `items_too_large`):
+  split it.
+- The yes runs the stored arguments exactly once. A wrong code decides nothing; a no is recorded, and a later yes is too late.
+- The approve window reads only from a terminal: an agent's shell tool cannot pipe the code in.
+
+Limits, said plainly:
+
+- **A pseudo-terminal passes the terminal check.** It stops a pipe, not a determined local process with a pty.
+- **An agent with a raw shell or a raw token goes around any MCP guard.** The guard governs the calls that pass through it;
+  switch off the client's own write tools for the session if the guard must be the only way to act.
+- **No timeout on an upstream call yet**, and the agent retries after the yes (no waiting notification yet). On Windows, when
+  the upstream is started through a virtual environment's `python.exe` (a launcher that holds the pipes), an upstream that
+  closes its output but keeps running is noticed only when it exits.
+- **stdio servers only**; one person per guarded server; the terminal is the only approval channel.
+- **Secret arguments are not masked yet**: a secret in an argument is shown in the window.
+- **Heard is not understood:** the record proves the words were shown and answered, not that they were read.
+
+## The record
+
+Each guarded server keeps its own folder (default `~/.oathline-guard/<server>/`) with Oathline Core's audit chain and token
+store. The chain for one call reads `REQUEST AUTHORIZED PROPOSED_BY_AGENT SHOWN HEARD CONFIRMED_BY_HUMAN EXECUTING EXECUTED`, or
+ends at `REFUSED_BY_HUMAN`; `verify()` on the audit log checks every link.
+
+## Licence
+
+MIT. Copyright (c) 2026 Nexxt Nest Group Pty Ltd. Built on [Oathline Core](https://pypi.org/project/oathline/).
+
+<!-- mcp-name: io.github.oathline/oathline-guard -->

oathline_guard-0.1.0/oathline_guard/__init__.py

@@ -0,0 +1,6 @@
+"""oathline-guard: an MCP guard on Oathline Core 0.2.0 where the yes means exactly what the person saw.
+
+Reads pass; every other tool call is a heard proposal: shown on a channel the agent does not control, heard there, run once with the
+stored arguments by the Guard process. Standard library + `oathline` (Core 0.2.0, from PyPI)."""
+
+__version__ = "0.1.0"

oathline_guard-0.1.0/oathline_guard/__main__.py

@@ -0,0 +1,31 @@
+"""oathline-guard run ... | approve ... | demo ..."""
+import sys
+
+USAGE = ("usage: oathline-guard run --server NAME [--reads READS.json] [--home DIR] [--human NAME] [--shown-text] "
+         "-- <server command ...>\n"
+         "       oathline-guard approve --server NAME [--home DIR] [--once]\n"
+         "       oathline-guard demo [--dir DIR] [--human NAME]   (prepares the quickstart; approves and runs nothing)\n"
+         "       (or python -m oathline_guard ...)")
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print(USAGE)
+        return 0 if argv else 2
+    cmd, rest = argv[0], argv[1:]
+    if cmd == "run":
+        from .guard import run
+        return run(rest)
+    if cmd == "approve":
+        from .approve import main as approve_main
+        return approve_main(rest)
+    if cmd == "demo":
+        from .demo.setup import main as demo_main
+        return demo_main(rest)
+    print(f"oathline-guard: unknown command {cmd!r}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

oathline_guard-0.1.0/oathline_guard/approve.py

@@ -0,0 +1,146 @@
+"""`oathline-guard approve`: the person's window.
+
+    python -m oathline_guard approve --server NAME [--home DIR] [--once]
+
+For each call waiting for a yes it prints the Guard's own text (the tool, every argument in the Guard's words, long values whole
+behind "| ", the code last), re-hashes the blocks and records SHOWN, then takes what the person types: the right code is the yes
+ROW, `n` is a RECORDED no, a wrong code decides nothing and asks again. HEARD is recorded on the first answer typed, whatever it is
+(a wrong code or `n` included): the person demonstrably had the text in front of them; nothing else is written on a wrong code.
+It never confirms and never runs anything: the Guard process, which holds the server's pipe, runs the call on the agent's next
+identical call. It reads only from a terminal (an agent's shell tool cannot type the code; a pseudo-terminal does satisfy the
+check, which is this rule's known limit) and only for the person the Guard was started with.
+
+Within one window: an expired call is never printed (its code included), "expired" is said once; a call shown and left unanswered is
+not shown again until the window is restarted; a text the console cannot encode is not printed and not SHOWN ("cannot display").
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+
+from .record import Record, server_name_ok
+
+PROMPT = "Type the code to run it, or n to refuse: "
+TRIES = 3
+
+
+class NotATerminal(Exception):
+    pass
+
+
+def _stdin_is_terminal() -> bool:
+    try:
+        return bool(sys.stdin.isatty())
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _can_display(text: str, out) -> bool:
+    """The console can show these exact characters (otherwise it crashes, or shows '??' while SHOWN hashes the text)."""
+    try:
+        encoding = out.encoding or "utf-8"
+    except AttributeError:                                # a plain StringIO: str in, str out
+        encoding = "utf-8"
+    try:
+        text.encode(encoding, "strict")
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+def window(rec: Record, *, ask, out, isatty=None, once: bool = False, poll: float = 1.0, max_rounds=None) -> int:
+    """Answer the waiting calls; with once=True those waiting now, then return; max_rounds bounds the loop (tests). -> how many
+    calls were answered. `ask(prompt, call) -> str` reads one line from the person; `out` is where the text is printed."""
+    if not (isatty if isatty is not None else _stdin_is_terminal)():   # resolved when called
+        raise NotATerminal("the code must be typed by a person at a terminal; stdin is not one")
+    human = rec.human
+    answered, rounds = 0, 0
+    seen: set = set()                                     # shown in this window and left unanswered: not shown again
+    said_empty = False
+    while True:
+        rounds += 1
+        for call in rec.expire_due():
+            print(f"({call} expired before an answer; nothing decided, nothing will run)", file=out)
+        waiting = [row for row in rec.pending() if row["call"] not in seen]
+        if not waiting and once and answered == 0 and not said_empty:
+            print("Nothing is waiting for a yes.", file=out)
+            said_empty = True
+        for row in waiting:
+            call = row["call"]
+            seen.add(call)
+            text = rec.text(call)
+            if not _can_display(text, out):
+                print(f"({call}: this console cannot display the text; nothing shown or decided. Use a UTF-8 terminal.)", file=out)
+                continue
+            print("", file=out)
+            print(text, file=out)
+            shown = rec.show(call, text)
+            if not shown.get("ok"):
+                print(f"(not shown: {shown.get('error')}; nothing decided for {call})", file=out)
+                continue
+            heard = False
+            for _ in range(TRIES):
+                answer = str(ask(PROMPT, call) or "").strip()
+                if not answer:
+                    continue
+                if not heard:
+                    h = rec.hear(call)
+                    if not h.get("ok"):
+                        print(f"(not heard: {h.get('error')}; nothing decided for {call})", file=out)
+                        break
+                    heard = True
+                if answer.lower() in ("n", "no"):
+                    rec.no(call, human)
+                    print(f"Refused and recorded ({call}). Nothing will run.", file=out)
+                    answered += 1
+                    break
+                if rec.yes(call, answer, human):
+                    print(f"Yes recorded ({call}). It runs once, on the agent's next identical call.", file=out)
+                    answered += 1
+                    break
+                print("Wrong code: nothing decided. Read the text again and type its code.", file=out)
+            else:
+                print(f"No answer for {call}; it stays waiting (restart the window to see it again).", file=out)
+        if once or (max_rounds is not None and rounds >= max_rounds):
+            return answered
+        time.sleep(poll)
+
+
+def main(argv: list[str]) -> int:
+    if not _stdin_is_terminal():                          # the terminal rule first, before anything is opened
+        print("oathline-guard approve: refused: the code must be typed by a person at a terminal; stdin is not one", file=sys.stderr)
+        return 2
+    ap = argparse.ArgumentParser(prog="oathline-guard approve")
+    ap.add_argument("--server", required=True)
+    ap.add_argument("--home", default=os.path.join(os.path.expanduser("~"), ".oathline-guard"))
+    ap.add_argument("--once", action="store_true", help="answer what is waiting now, then exit")
+    a = ap.parse_args(argv)
+    if not server_name_ok(a.server):
+        print(f"oathline-guard approve: --server {a.server!r} must be one plain name (letters, digits, '_', '.', '-')", file=sys.stderr)
+        return 2
+    folder = os.path.join(a.home, a.server)
+    if not os.path.isfile(os.path.join(folder, "guard.db")):
+        print(f"oathline-guard approve: no guard record for server {a.server!r} in {a.home} (start the guard with --human first)",
+              file=sys.stderr)
+        return 2
+    # the console's encoding is left as it is: forcing UTF-8 would make _can_display always pass and send UTF-8 bytes
+    # to a console that shows something else; a console that cannot encode the text is told so and nothing is SHOWN
+    rec = Record(folder, a.server)
+    try:
+        if not rec.human:
+            print("oathline-guard approve: the guard was started without --human: nobody can answer", file=sys.stderr)
+            return 2
+        try:
+            # the same terminal check main() made, looked up now (a default argument is bound when window() is defined)
+            window(rec, ask=lambda prompt, call: input(prompt), out=sys.stdout, once=a.once, isatty=lambda: _stdin_is_terminal())
+        except NotATerminal as exc:
+            print(f"oathline-guard approve: refused: {exc}", file=sys.stderr)
+            return 2
+        except (KeyboardInterrupt, EOFError):
+            print("", file=sys.stdout)
+            return 130
+        return 0
+    finally:
+        rec.close()

oathline_guard-0.1.0/oathline_guard/demo/fake_db.py

@@ -0,0 +1,117 @@
+"""fake-db-mcp: the demo MCP server of the PocketOS quickstart. Its whole state is one JSON file:
+databases, each with tables and backups. Two reads and two writes; no guard of its own (that is the point).
+
+    python -m oathline_guard.demo.fake_db --state PATH
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from .. import stdio
+
+FRESH = {"prod": {"tables": ["users", "orders", "invoices"], "backups": ["prod-2026-11-07", "prod-2026-11-08"]},
+         "staging": {"tables": ["users", "orders"], "backups": ["staging-2026-11-08"]}}
+
+
+def _schema(props=None, required=()):
+    return {"type": "object", "properties": props or {}, "required": list(required), "additionalProperties": False}
+
+
+_NAME = {"type": "string", "description": "a database name"}
+TOOLS = [
+    {"name": "list_databases", "description": "List the databases.", "inputSchema": _schema(),
+     "annotations": {"readOnlyHint": True}},
+    {"name": "list_tables", "description": "List the tables of a database.", "inputSchema": _schema({"database": _NAME}, ["database"]),
+     "annotations": {"readOnlyHint": True}},
+    {"name": "drop_database", "description": "Tidy up an unused database.",            # the description is the server's own words
+     "inputSchema": _schema({"name": _NAME}, ["name"]), "annotations": {"readOnlyHint": False, "destructiveHint": True}},
+    {"name": "delete_backups", "description": "Free space by removing old backups.",
+     "inputSchema": _schema({"name": _NAME}, ["name"]), "annotations": {"readOnlyHint": False, "destructiveHint": True}},
+]
+
+
+class Db:
+    def __init__(self, path):
+        self.path = path
+        if not os.path.exists(path):
+            self.save(json.loads(json.dumps(FRESH)))
+
+    def load(self):
+        with open(self.path, encoding="utf-8") as fh:
+            return json.load(fh)
+
+    def save(self, state):
+        tmp = self.path + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(state, fh, indent=1)
+        os.replace(tmp, self.path)
+
+    def call(self, name, args):
+        s = self.load()
+        if name == "list_databases":
+            return json.dumps(sorted(s)), False
+        db = str(args.get("database") or args.get("name") or "")
+        if db not in s:
+            return f"no database {db!r}", True
+        if name == "list_tables":
+            return json.dumps(s[db]["tables"]), False
+        if name == "drop_database":
+            del s[db]
+            self.save(s)
+            return f"dropped {db}", False
+        if name == "delete_backups":
+            n = len(s[db]["backups"])
+            s[db]["backups"] = []
+            self.save(s)
+            return f"deleted {n} backups of {db}", False
+        return f"unknown tool {name}", True
+
+
+def serve(db: Db, stdin=sys.stdin, stdout=sys.stdout) -> int:
+    names = {t["name"] for t in TOOLS}
+    while True:
+        msg = stdio.read(stdin)
+        if msg is None:
+            return 0
+        if msg == "<parse error>":
+            stdio.write(stdout, stdio.error(None, -32700, "parse error"))
+            continue
+        if not isinstance(msg, dict) or "id" not in msg:
+            continue
+        mid, method, params = msg["id"], msg.get("method"), msg.get("params") or {}
+        if method == "initialize":
+            stdio.write(stdout, stdio.result(mid, {"protocolVersion": stdio.agreed_version(params.get("protocolVersion")),
+                                                   "capabilities": {"tools": {"listChanged": False}},
+                                                   "serverInfo": {"name": "fake-db-mcp", "version": "0.1"}}))
+        elif method == "ping":
+            stdio.write(stdout, stdio.result(mid, {}))
+        elif method == "tools/list":
+            stdio.write(stdout, stdio.result(mid, {"tools": TOOLS}))
+        elif method == "tools/call":
+            name = params.get("name")
+            if name not in names:
+                stdio.write(stdout, stdio.error(mid, -32602, f"unknown tool: {name}"))
+                continue
+            text, is_error = db.call(name, params.get("arguments") or {})
+            stdio.write(stdout, stdio.result(mid, stdio.text_result(text, is_error=is_error)))
+        else:
+            stdio.write(stdout, stdio.error(mid, -32601, f"method not found: {method}"))
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="fake-db-mcp")
+    ap.add_argument("--state", required=True)
+    a = ap.parse_args(argv)
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", newline="\n")
+        sys.stdin.reconfigure(encoding="utf-8")
+    except Exception:  # noqa: BLE001
+        pass
+    return serve(Db(a.state))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

oathline_guard-0.1.0/oathline_guard/demo/setup.py

@@ -0,0 +1,45 @@
+"""`oathline-guard demo`: prepare the quickstart on this machine, then stop.
+
+    oathline-guard demo [--dir DIR] [--human NAME]
+
+It writes DIR/reads.json (the demo server's two reads) and prints the block for claude_desktop_config.json with this machine's
+absolute paths: this Python interpreter runs the guard (`-m oathline_guard run ...`) and the demo database server, so the block
+does not depend on PATH or on `python` vs `python3`. An existing reads.json is kept. It approves nothing and runs nothing.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+READS = {"server": "db", "reads": ["list_databases", "list_tables"]}
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(prog="oathline-guard demo")
+    ap.add_argument("--dir", default=os.path.join(os.path.expanduser("~"), "oathline-guard-demo"))
+    ap.add_argument("--human", default="you", help="the name of the person who approves (you)")
+    a = ap.parse_args(argv)
+    folder = os.path.abspath(a.dir)
+    os.makedirs(folder, exist_ok=True)
+    reads = os.path.join(folder, "reads.json")
+    if os.path.exists(reads):
+        note = f"kept the existing read list: {reads}"
+    else:
+        with open(reads, "w", encoding="utf-8") as fh:
+            json.dump(READS, fh)
+            fh.write("\n")
+        note = f"wrote the read list: {reads}"
+    py = os.path.abspath(sys.executable)
+    block = {"mcpServers": {"db": {"command": py, "args": [
+        "-m", "oathline_guard", "run", "--server", "db", "--reads", reads, "--human", a.human,
+        "--", py, "-m", "oathline_guard.demo.fake_db", "--state", os.path.join(folder, "db.json")]}}}
+    print(note)
+    print("\n1. Add this to claude_desktop_config.json (Claude Desktop: Settings > Developer > Edit Config), then restart Claude"
+          " Desktop:\n")
+    print(json.dumps(block, indent=2))
+    print("\n2. In a second terminal, open the approve window and leave it open:\n\n   oathline-guard approve --server db\n\n"
+          f"   (or, with nothing needed on PATH: {py} -m oathline_guard approve --server db)\n")
+    print('3. Ask Claude: "clean up the old database". The reads run; the drop waits for your code in the approve window.')
+    return 0