shiyuyun/wyndham-ARR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
12881be17e8c88be3f1cae08d67b69b7074b61eb
wyndham-ARR/arr_mcp/README.md
Wyndham ARR a701de9f0e feat: prepare ARR for controlled public deployment
2026-07-29 16:38:05 +08:00

2.6 KiB
Raw Blame History

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:

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 and low-level server guidance.

Local launch with Keychain-backed secrets:

.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:

--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.