procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/xlsx/reader.py

@@ -0,0 +1,91 @@
+"""Pure reader for .xlsx / .xlsm workbooks (openpyxl), kept import-light and
+unit-testable. The handlers in main.py wrap these into JSON actions.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _load(path: str, data_only: bool = True):
+    from openpyxl import load_workbook
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"file not found: {path}")
+    if p.suffix.lower() not in (".xlsx", ".xlsm"):
+        raise ValueError(f"not an .xlsx/.xlsm file: {path}")
+    return load_workbook(str(p), data_only=data_only)
+
+
+def list_sheets(path: str) -> list[dict]:
+    """Return [{title, rows, columns}] for every worksheet."""
+    wb = _load(path)
+    out = []
+    for ws in wb.worksheets:
+        out.append({
+            "title": ws.title,
+            "rows": ws.max_row,
+            "columns": ws.max_column,
+        })
+    return out
+
+
+def _trim_row(row: tuple) -> list:
+    """Drop trailing empty cells; stringify everything (None -> '')."""
+    vals = list(row)
+    while vals and (vals[-1] is None or str(vals[-1]).strip() == ""):
+        vals.pop()
+    return ["" if v is None else v for v in vals]
+
+
+def _is_empty(vals: list) -> bool:
+    return all(v is None or str(v).strip() == "" for v in vals)
+
+
+def read_sheet(path: str, sheet: str | None = None, *,
+               max_rows: int | None = None, skip_empty: bool = True) -> dict:
+    """Return {sheet, rows: [[...]], truncated} for one worksheet.
+
+    sheet=None reads the first/active worksheet. Cell values are JSON-safe
+    (numbers/strings/bools; dates become their string form via openpyxl)."""
+    wb = _load(path)
+    ws = wb[sheet] if sheet else wb.worksheets[0]
+    rows: list[list] = []
+    truncated = False
+    for r in ws.iter_rows(values_only=True):
+        vals = _trim_row(r)
+        if skip_empty and _is_empty(vals):
+            continue
+        rows.append([_json_safe(v) for v in vals])
+        if max_rows is not None and len(rows) >= max_rows:
+            truncated = True
+            break
+    return {"sheet": ws.title, "rows": rows, "truncated": truncated}
+
+
+def _json_safe(v):
+    import datetime
+    if isinstance(v, (datetime.datetime, datetime.date, datetime.time)):
+        return v.isoformat()
+    return v
+
+
+def dump_text(path: str, *, max_rows: int | None = None) -> str:
+    """Whole workbook as readable pipe-delimited text (one row per line,
+    empty rows skipped), with sheet headers. Mirrors the original ad-hoc dump."""
+    wb = _load(path)
+    lines = [f"### FILE: {path}", f"### SHEETS: {wb.sheetnames}", ""]
+    for ws in wb.worksheets:
+        lines.append(f"\n===== SHEET: {ws.title}  (dims {ws.dimensions}) =====")
+        shown = 0
+        for i, r in enumerate(ws.iter_rows(values_only=True), start=1):
+            vals = _trim_row(r)
+            if _is_empty(vals):
+                continue
+            lines.append(f"r{i}: " + " | ".join(str(_json_safe(v)) for v in vals))
+            shown += 1
+            if max_rows is not None and shown >= max_rows:
+                lines.append(f"... [truncated at {max_rows} non-empty rows]")
+                break
+        if shown == 0:
+            lines.append("(empty)")
+    return "\n".join(lines)

procesio_cli/tools/xlsx/tests/conftest.py

@@ -0,0 +1,39 @@
+"""Fixtures for the xlsx tool: sys.path + a generated sample workbook."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+# openpyxl is an OPTIONAL dependency (reading .xlsx workbooks), so a plain install does not
+# have it. These tests then FAIL, which reads as a broken repository rather
+# than as an extra nobody asked for. Skip instead, with the reason visible.
+#
+# exc_type matters: pytest 9 skips only on ModuleNotFoundError by default,
+# and a package can be installed yet unimportable - openpyxl on a runner
+# without its native library raises a plain ImportError, which would
+# otherwise re-raise and take collection down instead of skipping.
+pytest.importorskip('openpyxl', reason="install the extra that provides openpyxl",
+                    exc_type=ImportError)
+
+FRAMEWORK_ROOT = Path(__file__).resolve().parents[3]
+if str(FRAMEWORK_ROOT) not in sys.path:
+    sys.path.insert(0, str(FRAMEWORK_ROOT))
+
+
+@pytest.fixture
+def sample_xlsx(tmp_path):
+    """A 2-sheet workbook with a header row, data, a blank row, and diacritics."""
+    from openpyxl import Workbook
+    wb = Workbook()
+    ws1 = wb.active
+    ws1.title = "Data"
+    ws1.append(["Item", "Cost", "Notă"])
+    ws1.append(["Hosting", 1200, "lunară"])
+    ws1.append([None, None, None])          # blank row -> skipped
+    ws1.append(["Support", 800, "ăîâșț"])
+    ws2 = wb.create_sheet("Empty")
+    p = tmp_path / "sample.xlsx"
+    wb.save(str(p))
+    return str(p)

procesio_cli/tools/xlsx/tests/test_xlsx.py

@@ -0,0 +1,103 @@
+"""Tests for the xlsx tool: pure reader + dispatch + manifest sync."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from tools._lib.manifest import load_tool
+from tools.xlsx import main, reader
+
+
+# --- pure reader ------------------------------------------------------------
+
+def test_list_sheets(sample_xlsx):
+    sheets = reader.list_sheets(sample_xlsx)
+    titles = [s["title"] for s in sheets]
+    assert titles == ["Data", "Empty"]
+    data = next(s for s in sheets if s["title"] == "Data")
+    assert data["columns"] == 3
+
+
+def test_read_sheet_skips_empty_and_trims(sample_xlsx):
+    out = reader.read_sheet(sample_xlsx, "Data")
+    assert out["sheet"] == "Data"
+    # Blank middle row dropped: header + 2 data rows.
+    assert out["rows"] == [
+        ["Item", "Cost", "Notă"],
+        ["Hosting", 1200, "lunară"],
+        ["Support", 800, "ăîâșț"],
+    ]
+    assert out["truncated"] is False
+
+
+def test_read_sheet_default_first(sample_xlsx):
+    out = reader.read_sheet(sample_xlsx)
+    assert out["sheet"] == "Data"
+
+
+def test_read_sheet_max_rows(sample_xlsx):
+    out = reader.read_sheet(sample_xlsx, "Data", max_rows=1)
+    assert len(out["rows"]) == 1
+    assert out["truncated"] is True
+
+
+def test_read_empty_sheet(sample_xlsx):
+    out = reader.read_sheet(sample_xlsx, "Empty")
+    assert out["rows"] == []
+
+
+def test_dump_text(sample_xlsx):
+    text = reader.dump_text(sample_xlsx)
+    assert "SHEET: Data" in text
+    assert "Hosting | 1200 | lunară" in text
+    assert "ăîâșț" in text
+
+
+def test_missing_file():
+    with pytest.raises(FileNotFoundError):
+        reader.list_sheets("nope.xlsx")
+
+
+def test_wrong_extension(tmp_path):
+    p = tmp_path / "x.csv"
+    p.write_text("a,b\n")
+    with pytest.raises(ValueError):
+        reader.list_sheets(str(p))
+
+
+# --- dispatch ---------------------------------------------------------------
+
+def test_dispatch_list_sheets(sample_xlsx):
+    result = main.dispatch("list-sheets", ["--path", sample_xlsx])
+    assert [s["title"] for s in result["sheets"]] == ["Data", "Empty"]
+
+
+def test_dispatch_read_sheet(sample_xlsx):
+    result = main.dispatch("read-sheet", ["--path", sample_xlsx, "--sheet", "Data"])
+    assert result["rows"][0] == ["Item", "Cost", "Notă"]
+
+
+def test_dispatch_dump_save(sample_xlsx, tmp_path):
+    out = tmp_path / "dump.txt"
+    result = main.dispatch("dump", ["--path", sample_xlsx, "--save", str(out)])
+    assert out.read_text(encoding="utf-8").count("SHEET:") == 2
+    assert result["savedTo"] == str(out.resolve())
+
+
+def test_dispatch_unknown_action():
+    with pytest.raises(main.UsageError):
+        main.dispatch("nope", [])
+
+
+def test_dispatch_missing_required_arg():
+    with pytest.raises(main.UsageError):
+        main.dispatch("list-sheets", [])
+
+
+# --- manifest sync ----------------------------------------------------------
+
+def test_manifest_sync():
+    tool_root = Path(main.__file__).resolve().parent
+    m = load_tool(tool_root / "tool.yaml")
+    assert set(m.action_names()) == set(main.ACTIONS)

procesio_cli/tools/xlsx/tool.yaml

@@ -0,0 +1,30 @@
+name: xlsx
+description: Read local Excel (.xlsx/.xlsm) workbooks - list sheets, read a sheet as JSON, or dump the whole file to text. No credentials.
+version: 0.1.0
+runtime: python
+entrypoint: main.py
+
+secrets: []
+
+actions:
+  - name: list-sheets
+    description: List a workbook's sheets with row/column counts.
+    args:
+      - {name: path, type: string, required: true, description: Local .xlsx/.xlsm file}
+    output_schema: '{ "path": "...", "sheets": [ {title, rows, columns} ] }'
+
+  - name: read-sheet
+    description: Read one sheet's rows as a JSON 2D array (trailing-empty cells trimmed, empty rows skipped).
+    args:
+      - {name: path, type: string, required: true}
+      - {name: sheet, type: string, description: Sheet name (default first/active)}
+      - {name: max-results, type: integer, description: Cap rows returned}
+    output_schema: '{ "sheet": "...", "rows": [[...]], "truncated": false }'
+
+  - name: dump
+    description: Dump the whole workbook to readable pipe-delimited text.
+    args:
+      - {name: path, type: string, required: true}
+      - {name: save, type: string, description: Write text dump here instead of inline}
+      - {name: max-results, type: integer, description: Cap rows per sheet}
+    output_schema: '{ "text"?: "...", "savedTo"?: "...", "characters": N }'

procesio_cli/webplatform/aat_mcp/AAT-MCP-NOTES.md

@@ -0,0 +1,244 @@
+# aat-mcp — connection & mechanics notes
+
+Durable notes on how the bridge connects and non-obvious mechanics (Hard rules 6, 7).
+
+## How opencode connects to it
+
+opencode is an MCP **client**; aat-mcp is a **local (stdio)** MCP server. Wiring lives
+in `webplatform/spike/opencode.json`:
+
+```json
+"mcp": {
+  "aat": {
+    "type": "local",
+    "command": ["<abs>/.venv/Scripts/python.exe", "<abs>/webplatform/aat_mcp/server.py"],
+    "enabled": true
+  }
+}
+```
+
+- **Absolute paths** in the command: robust to opencode's spawn cwd, and space-safe
+  because each element is a separate argv entry. Machine-local for the spike; the
+  container image (spec 05) will use image paths + HTTP transport.
+- opencode spawns the server as a child of its own process (started by
+  `run-spike.cmd`, which put `.venv\Scripts` on PATH), so the server runs on the
+  framework venv. `server.py` and `bridge.py` resolve paths from `__file__`
+  (absolute), so cwd does not matter.
+- The model is nudged to prefer these tools over bash via
+  `webplatform/spike/MCP-HINT.md` (added to opencode `instructions`).
+
+## Protocol
+
+- Transport: newline-delimited JSON-RPC 2.0 over stdio. One JSON object per line;
+  responses flushed immediately. stdout is reconfigured to `newline="\n"` so Windows
+  does not inject `\r\n` into the protocol stream. **stdout is the protocol channel —
+  all logs go to stderr** (`_log`).
+- Methods handled: `server/discover`, `initialize`, `notifications/*` (swallowed, no
+  response), `ping`, `tools/list`, `tools/call`. Unknown request methods → JSON-RPC
+  `-32601`. The mechanics live once, in `protocol.py`, shared by both servers; see
+  "Protocol eras" below.
+- `tools/call` never raises: tool failures (incl. unknown capability, KeyError) come
+  back as `{content:[{type:text,text:<json>}], isError:true}` so the model can read
+  the error.
+
+## Protocol eras and version negotiation
+
+MCP 2026-07-28 drops the `initialize` handshake. The spec calls that revision *modern*
+and everything up to 2025-11-25 *legacy*. In the modern era:
+
+- every request carries its version in `_meta["io.modelcontextprotocol/protocolVersion"]`;
+- servers MUST answer `server/discover` (supported versions, capabilities, identity);
+- every result carries `resultType: "complete"`, and list results add `ttlMs` and
+  `cacheScope`;
+- an unsupported version gets error `-32022` with `data: {supported, requested}`.
+
+Both servers are **dual-era over stdio**. A request that names its version in `_meta`
+gets the modern shape; anything else gets the legacy shape, unchanged. A modern-only
+server would fail every legacy client, and legacy clients cannot fall forward.
+
+**Never echo the requested version.** Both servers used to answer `initialize` with
+whatever version the client sent, including dates that do not exist. The client then
+believes the server speaks a revision it has never heard of and waits for fields that
+never arrive. The answer must come from a list the server implements. `initialize`
+always selects the legacy era, so a client asking there for 2026-07-28 gets 2025-11-25.
+That case is real: at least one client release proposed the modern version inside
+`initialize`.
+
+**How a dual-era client probes** (checked against Claude Code 2.1.284 through a logging
+shim). By default it still sends `initialize`. With `MCP_PROTOCOL_NEGOTIATION=auto` it
+sends `server/discover` first and falls back to `initialize` on any error that is not a
+recognised modern one. So `-32601` on discover means "legacy server", and `-32022` means
+"modern server, retry with a listed version". A server that cannot serve modern requests
+must never return the second: a public MCP server that did had its client stop seeing
+its tools.
+
+**The HTTP transport is legacy-only** (`server.handle(m, modern=False)`). Modern
+Streamable HTTP adds `Mcp-Method` / `Mcp-Name` header rules that `http_server.py` does
+not implement, so over HTTP discover stays a plain `-32601`. Lift that only together
+with the header rules.
+
+**Not used, and deprecated in 2026-07-28 anyway:** roots, sampling, logging and dynamic
+client registration. Nothing here should start depending on them.
+
+**The tool-list digest.** `server/discover` reports `_meta["com.procesio/toolsDigest"]`:
+sha256 over the canonical JSON of the `tools` array (keys sorted, no whitespace, UTF-8,
+non-ASCII unescaped). The procesio-oss exporter writes the same value for the chat
+surface into the public `server.json`, which the MCP Registry does not allow to change
+after publication. The value a server reports about itself is a label for spotting the
+release, not a control - the spec says self-reported server information must not drive
+security decisions. The control is a client or gateway hashing the list it actually
+received and comparing it with the registry copy. Changing the canonical form in one
+place breaks every comparison, so `tests/test_pyoss_pins.py` asserts the exporter and
+`protocol.py` agree.
+
+## Capability discovery — why it is narrow
+
+A big tool's full schema is not a large answer, it is NO answer. `procesio` alone is
+~369 KB / 379 actions; an MCP client truncates that to a single-line JSON file, and
+then `read` (offset/limit sees one line), `grep` (ripgrep refuses a record over 64 KB)
+and `bash` (permission-gated) all fail on it. The turn is spent and the model has
+nothing. Measured on real autonomous runs: **27% of all tool calls were the model
+guessing argument names**, e.g. the same action retried with four different spellings
+(`--name`, `--title`, `--datastore_name`, `--workspace_id`) when the manifest said
+`--payload`.
+
+So `capabilities` answers narrowest-first:
+
+| call | returns | size (procesio) |
+|---|---|---|
+| `{}` | compact tool/agent/skill list | small |
+| `{search}` | matching ACTIONS, name+description only | ~0.3 KB |
+| `{name, action}` | that action's args + the literal call shape | ~1–2 KB |
+| `{name}` | full schema, **or** the action-name index if oversized | 11 KB (was 369 KB) |
+
+Three rules that matter when touching this:
+
+- **The degrade is a mechanism, not advice.** The prompt used to carry "NEVER call
+  `aat_capabilities` with a name"; transcripts show the model ignoring it and burning
+  the turn exactly as described above. Over `AAT_CAPABILITIES_MAX_BYTES` (default
+  40 000) the payload becomes the action index plus a pointer to `action=`/`search=`.
+  It keys off SIZE, not a tool list, so it covers every tool that grows.
+- **Usage errors answer themselves** (`server._usage_help`). On `unknown action` /
+  `unrecognized arguments` / `arguments are required`, the failure carries a `schema`
+  field with the valid arg names, or `did_you_mean` for the action. The framework
+  already held the answer at that moment; it just never said it. One choke point,
+  every tool, no per-tool change. Remote errors (HTTP 4xx/5xx) are NOT enriched —
+  those are real feedback, not naming problems.
+- **Suggestions must survive word order and plurals.** A model writes
+  `credential-list` for `list-credentials`; edit distance alone ranks those far apart,
+  so `_suggest` compares singularized WORD SETS first and only then falls back to
+  `difflib`.
+
+Argument names are returned verbatim from the manifest (`workspace-id`, hyphenated).
+Returning the literal spelling is what stops the snake_case guessing — do not
+normalize or prettify them.
+
+## Mechanics / gotchas
+
+- **Naming:** the parent dir is `webplatform/`, NOT `platform/` — a top-level
+  `platform/` package shadows Python's stdlib `platform` module whenever repo root is
+  on `sys.path` (every framework subprocess), breaking keyring/pydantic. Do not rename
+  it back.
+- **Execution reuse:** `bridge.run_tool/run_agent` delegate to
+  `dashboard.server.runner` (`flags_from` + `run_tool`/`run_agent`) — ONE definition of
+  "shell a framework script and normalize its JSON". `flags_from` JSON-encodes
+  dict/list arg values into a single argv element; the subprocess is a **list** (no
+  shell), which is why structured args don't need escaping.
+- **Registry cost:** `aat_capabilities` (no name) calls `registry.list_tools/agents`,
+  which probes credential presence per secret — a few hundred ms. Fine for the low
+  call volume; cache if it ever matters.
+- **Creds backend:** `registry` uses `tools/_lib/creds` (Windows Credential Manager
+  today). Running the server on another OS needs the creds backend from spec 06.
+
+## Safety gate (spec 03)
+
+- **Code-authoritative, pre-execution** (`gate.py` → `agents/_lib/reversibility`). The
+  plain `run_tool`/`run_agent` refuse an irreversible action (verb in the tool/agent
+  name or the ACTION name — send-message, delete-messages, issue-invoice) and return
+  `approval_required`; the `*_confirmed` tools execute it. Classification is on
+  name+action only, NOT arg values (a subject line "please send..." must not trip it).
+- **opencode permission keys (namespaced `aat_*`):** `aat_run_tool`/`aat_run_agent` →
+  `allow` (the server code-gate refuses irreversible on them), `aat_run_tool_confirmed`
+  /`aat_run_agent_confirmed` → `ask` (the human approval), `aat_capabilities`/
+  `aat_get_skill` → `allow`. This is why the human gate is unforgeable: the model
+  can't self-approve the `ask`, and can't route an irreversible action through an
+  `allow` tool (it refuses).
+- **Headless fail-safe:** `AAT_MCP_DENY_IRREVERSIBLE=1` makes even the confirmed tools
+  refuse — matches `orchestrator drive`'s default when no human is in the seat.
+
+## Two surfaces over one substrate
+
+There are two MCP servers here, on purpose. `server.py` offers six freeform tools that
+dispatch whatever the registry holds - right for an operator driving the framework.
+`chat_server.py` offers one named tool per operation, built from `chat_surface.yaml` -
+what a general chat client and a directory review both need.
+
+**A published tool list is a different kind of artefact from a registry.** The registry
+is the source of truth for what a tool IS, and a surface that derives from it tracks it
+automatically, which is correct for the freeform one. A published list is a contract
+with people who did not write the manifests, and deriving it from them means a rename
+silently removes a published tool, a new argument silently reshapes a published schema,
+and a new tool silently appears in a surface someone reviewed. **MCP clients cache tool
+definitions at initialisation and do not refresh them**, so none of those three errors
+even produce an error - the client keeps calling the old shape and the model
+misunderstands the result. That is why the declaration is a separate file and why the
+disagreement is resolved at CI rather than at a user's call.
+
+**`read_only` and `reversible` answer different questions.** Reversible asks whether a
+change can be undone; read-only asks whether anything changes at all. A create action is
+reversible and is not read-only. Mapping one onto the other would mark every write
+safe to run unattended. The implication only runs one way, and that is what is asserted:
+read_only ⟹ reversible.
+
+**Annotations are not a control.** The spec tells clients to treat tool annotations as
+untrusted. They drive a client's auto-run behaviour, so a wrong one is a write that
+fires unprompted - worth getting right - but the enforcement is `gate.py`. The curated
+surface carries no `*_confirmed` twin and instead refuses irreversible actions outright,
+with a test asserting nothing declared is irreversible; adding a destructive operation
+fails the build rather than growing a second, softer approval path.
+
+**Shared protocol, separate surfaces.** The two servers differ in what they publish and
+to whom, so their tools, dispatchers and identities stay apart. The protocol is a
+different matter: it has one correct behaviour. It used to be duplicated, about 50 lines
+in each server, and the two copies made the same mistake - agreeing to any version a
+client named. It now lives once in `protocol.py`: negotiation, the modern and legacy
+result shapes, `server/discover` and the stdio loop. That module is standard library
+only and imports neither surface, so a change to one surface cannot reach the other
+through it. Both servers import `bridge`, `gate` and `protocol`; neither imports the
+other. `test_chat_surface.py` asserts all of this by parsing the AST.
+
+### Design rules taken from published guidance
+
+- **Namespace tool names by domain** (`procesio_list_processes`, not `list_processes`).
+  A directory client merges several servers into one list. Anthropic's tool-writing
+  guidance reports that naming scheme alone has non-trivial effects on tool-use
+  evaluations.
+- **Curate for workflows, not endpoints.** Prefer `search_*` over `list_*` because agent
+  context is limited. The generated REST passthroughs are exactly what does not belong
+  in a published surface.
+- **Cap tool results.** A result lands directly in a model's context, so an unbounded
+  one is a context leak rather than a large answer. Truncation carries a hint naming the
+  arguments that narrow *that* tool, because a generic "too large" is not actionable.
+  (Claude Code caps tool responses at 25,000 tokens by default; MCP metadata has been
+  measured at ~40% of token usage in some environments, which is the argument for a
+  small surface.)
+- **Version the surface separately from the package.** The MCP registry requires a
+  unique version string per publication and recommends semver; `server.json` aligns with
+  the release, while `surface_version` describes the published tool contract. A client
+  pins to a surface, and a release can ship with the surface unchanged.
+- **Known gap:** the declaration is a 1:1 mapping (one MCP tool = one action), which
+  keeps it free of behaviour and fully verifiable against the registry, but forecloses
+  the consolidation that guidance recommends (one `schedule_event` rather than find-slot
+  + book). Consolidation needs composition logic in the surface layer and its own tests.
+
+## Status
+
+Spec 02 (B1) transport + surface AND spec 03 (B2) reversibility gate: built +
+unit-tested (19 tests) + wire-tested (send refused on plain tool, executes on
+confirmed). Tool names dropped the `aat_` prefix (opencode re-adds it → clean
+`aat_run_tool`). Pending: live opencode action-count/gate check in the browser, and
+HTTP transport (spec 05).
+
+Dual-era negotiation for MCP 2026-07-28 (`protocol.py`): built, unit-tested
+(`tests/test_protocol.py`), and checked live with Claude Code in both negotiation modes
+(default `initialize`, and `MCP_PROTOCOL_NEGOTIATION=auto` via `server/discover`).

procesio_cli/webplatform/aat_mcp/README.md

@@ -0,0 +1,78 @@
+# aat-mcp — the AAT → MCP bridge
+
+A stdio MCP server that exposes the live AAT registry to any MCP client (opencode
+now, others later) as a **small generic surface**. It replaces bash passthrough:
+capabilities are called as typed tools with **structured JSON args** (no shell
+quote-escaping), and capability schemas replace `--help` spelunking.
+
+Part of the "local web platform" initiative — specs `todo/local web platform Claude replacer/02-aat-mcp-bridge.md` (transport) and `03-safety-approval-parity.md` (gate).
+
+## Tools exposed
+
+Server tool names below; opencode shows them prefixed with the server name (e.g.
+`run_tool` → `aat_run_tool`).
+
+| MCP tool | Args | Purpose |
+|---|---|---|
+| `capabilities` | `{kind?, name?, action?, search?}` | discovery, narrowest door first (the `--help` replacement). Nothing: compact list of every ready tool/agent/skill. `search`: matching actions across everything (or inside `name`). `name`+`action`: that one action's arg schema. `name` alone: the full schema, degraded to the action-name index when oversized — see AAT-MCP-NOTES.md |
+| `run_tool` | `{tool, action?, args?}` | run a **reversible** tool action; refuses irreversible ones with `approval_required` |
+| `run_agent` | `{agent, action?, args?}` | run a **reversible** agent action |
+| `run_tool_confirmed` | `{tool, action?, args?}` | run a tool **including irreversible** actions — opencode asks the operator to approve |
+| `run_agent_confirmed` | `{agent, action?, args?}` | run an agent including irreversible actions — operator-approved |
+| `get_skill` | `{name}` | the skill's full markdown (model-decided loading; spec 04) |
+
+`args` is a JSON object of flag name → value. dict/array values are JSON-encoded into
+a single argv element and passed via a subprocess **list** (no shell) — the fix for
+the B0 spike's quote-escaping thrash.
+
+## Safety gate (code-authoritative)
+
+The reversibility gate is **code, evaluated before execution** (`gate.py` →
+`agents/_lib/reversibility`, the same policy as `orchestrator drive` and `deputy`):
+
+- `run_tool`/`run_agent` **refuse** an irreversible action (send/delete/pay/post/
+  issue-invoice/...) and return `approval_required`, naming the `*_confirmed` path.
+- Only the `*_confirmed` tools are marked `ask` in opencode, so a **human** approves
+  each side effect. A model cannot forge the approval, and cannot bypass by picking
+  the plain tool (it refuses). Reversible/read actions run freely on the plain tools.
+- `AAT_MCP_DENY_IRREVERSIBLE=1` makes even the confirmed tools refuse — a fail-safe
+  for a headless run with no human in the seat.
+
+## Run
+
+```
+python webplatform/aat_mcp/server.py      # opencode spawns this over stdio
+```
+
+Quick manual check (newline-delimited JSON-RPC on stdin):
+```
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run_tool","arguments":{"tool":"hello-world","args":{"name":"MCP"}}}}' \
+| .venv/Scripts/python.exe webplatform/aat_mcp/server.py
+```
+
+## Design
+
+- **Placement:** a platform component (`webplatform/aat_mcp/`), not a registered tool
+  — a long-running server does not fit the JSON-in/out-and-exit tool contract, and
+  this avoids a tools→agents import inversion (execution reuses `dashboard.server.runner`).
+- **Generic, not exploded:** a handful of tools, not one-per-capability — avoids MCP
+  tool-count limits and manifest drift. The model discovers capabilities via
+  `capabilities` (the router map), exactly as a session does today.
+- **Source of truth:** capability + arg schemas are read live from the registry
+  (manifests); the reversibility policy is the shared `agents/_lib/reversibility`.
+- **No new dependency:** the MCP protocol is hand-rolled JSON-RPC over stdio (stdlib
+  only), robust to environment quirks.
+
+## Not yet (downstream specs)
+
+- **HTTP/SSE transport** (spec 05): for containers/k8s, where opencode connects as a
+  remote MCP client. stdio is the local transport.
+
+## Tests
+
+`python -m pytest webplatform/aat_mcp/tests/ -q` — protocol dispatch, the
+reversibility gate (refuse/confirm/headless-deny), and the anti-thrash argv
+guarantee, all with fakes (no real subprocess or credentials).