feat: prepare ARR for controlled public deployment

arr_mcp/README.md

@@ -0,0 +1,70 @@
+# ARR MCP ingestion gateway
+
+This is a standalone Streamable HTTP MCP server with exactly one tool:
+`arr_submit_processing_result`.
+
+The protocol process is intentionally thin. It authenticates the HTTP request,
+advertises the frozen four-field tool Schema, bounds concurrent processor
+replays, and calls `DirectSubmissionService`. It does not contain SQL or trust
+Agent-provided Finance facts.
+
+## Runtime
+
+The official MCP Python SDK 2.0 requires Python 3.10+. Keep it separate from the
+portal's historical Python 3.9 virtual environment:
+
+```bash
+python3.12 -m venv .venv-mcp
+.venv-mcp/bin/python -m pip install -r requirements-arr-mcp.txt
+```
+
+The server uses the recommended stateless Streamable HTTP transport with JSON
+responses, a 4 MiB HTTP-body limit, DNS-rebinding Host allowlisting, and a
+required bearer token. See the
+[official Python SDK](https://github.com/modelcontextprotocol/python-sdk) and
+[low-level server guidance](https://py.sdk.modelcontextprotocol.io/v2/advanced/low-level-server/).
+
+Local launch with Keychain-backed secrets:
+
+```bash
+.venv-mcp/bin/python -m arr_mcp.launch \
+  --db-config /path/to/private/booking-test-db.env \
+  --host 127.0.0.1 \
+  --port 8890
+```
+
+The launcher reads only OSS routing values from the owned `0600` route file.
+It loads OSS credentials and `ARR_MCP_BEARER_TOKEN` from macOS Keychain account
+`arr-web`; no secret belongs in this repository, command line, Main Prompt, or
+Agent output.
+
+When binding beyond loopback, pass every accepted reverse-proxy Host header:
+
+```bash
+--host 0.0.0.0 --allowed-host mcp.example.com
+```
+
+Do not expose plain HTTP publicly. Terminate HTTPS at a controlled reverse proxy
+or tunnel and forward only the MCP endpoint.
+
+## SuperAgent MCP entry
+
+- Service identifier: `arr_ingestion_gateway`
+- Display name: `ARR Ingestion Gateway`
+- Transport: `HTTP`
+- Service address: `https://<controlled-host>/mcp`
+- Status: activate only after the no-PII acceptance test passes
+- Headers: `Authorization: Bearer <ARR_MCP_BEARER_TOKEN>` supplied through the
+  platform's secret facility
+- OAuth JSON: `{}` unless the deployment later adopts a dedicated OAuth server
+
+The bearer protects the transport. The short-lived `submission_grant` inside
+the tool call separately binds the write to one registered job attempt. Both
+must be valid.
+
+## Success and error behavior
+
+Success returns only the strict receipt: `committed` or `already_committed`,
+job/attempt, business date, daily version identity and record count. A business
+or validation error is an MCP tool error containing only a stable code, safe
+message and `retryable` flag. Request payloads and grants are never logged.