arcus-agent-gateway 0.1.0__tar.gz

arcus_agent_gateway-0.1.0/.agents/skills/arcus-gateway/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: arcus-gateway
+description: Market data for Robinhood Chain (Arcus) tokenized US equities via the arcus-agent-gateway MCP server. Use for quotes, corporate actions, splits, market status, and sector data on the 194 tokenized stocks. Includes the watchlist/price-tracking cron recipe.
+---
+
+# Arcus Gateway (Robinhood Chain tokenized equities)
+
+## What this is
+
+`arcus-agent-gateway` is a read-only, keyless MCP server exposing market data
+for the 194 tokenized US equities on Robinhood Chain (Arcus DEX). Prices come
+raw from the REST API; multiplier-adjusted values are computed by the server
+and always returned alongside the raw ones.
+
+## When to use
+
+- "What's X trading at?" / current bid-ask for a tokenized stock
+- Halts, trading capabilities, market-wide status
+- Upcoming splits / corporate actions (pending multiplier warnings)
+- Sector comparisons (13-sector map) and symbol discovery
+- Recurring price tracking of a symbol set → **watchlist recipe below**
+
+Symbols are ticker-style (`AAPL`, `NVDA`). Discover them with `token_list()`
+or `search()`; an unknown symbol raises an error that mentions `token_list()`.
+
+## Tools
+
+| Tool | Call | Notes |
+|------|------|-------|
+| `token_list` | `token_list(status="ACTIVE", limit=100)` | Valid symbols; alphabetical; `limit` ≤ 500. |
+| `quote` | `quote(symbol="AAPL")` | Raw + adjusted prices, `is_halted`, multiplier block. |
+| `quotes` | `quotes(symbols=["AAPL","NVDA"])` | **Max 20 symbols per call.** Unknowns → `errors`, batch continues. |
+| `token_detail` | `token_detail(symbol="AAPL")` | Dossier: contract, ISIN, actions, `warnings` (pending split). |
+| `market_status` | `market_status()` | Cheap market health; `halted` lists only cached quotes. |
+| `corporate_actions` | `corporate_actions(symbol=None, limit=10)` | Splits/dividends, all or one symbol. |
+| `search` | `search(query="apple")` | `apple` → `AAPL`; top 10 with sector + score. |
+| `sector_view` | `sector_view()` | 13 sectors; averages populate only after `quotes()` calls. |
+| `onchain_info` | `onchain_info(symbol="AAPL")` | Contract/chain 4663/ISIN — v0.2 stub. |
+
+Reading prices: report `bid_raw`/`ask_raw` as the REST price;
+`bid_adjusted`/`ask_adjusted` = raw × `multiplier.current`. Always read
+adjusted values next to the multiplier (a pending split changes the ratio).
+
+## Watchlist / price tracking
+
+There is deliberately **no watchlist tool**. Tracking = a scheduled
+`quotes()` call. Use the agent's cron (e.g. Hermes cron), not a tight loop.
+
+**Rules:**
+
+1. Interval **≥ 5 minutes**. The server's price cache is 15 s and the client
+   caps itself at ≤ 50 req/s — polling faster than 5 min adds nothing and
+   wastes the upstream budget (60 req/s keyless limit is shared).
+2. **≤ 20 symbols per `quotes()` call** — more raises a `ValueError`. Split
+   larger watchlists into multiple calls (or multiple cron entries).
+3. One cron entry can cover the whole watchlist: `quotes()` accepts the list.
+
+**Example** — track NVDA and TSLA every 5 minutes (Hermes cron):
+
+```json
+{
+  "name": "watchlist-nvda-tsla",
+  "schedule": "*/5 * * * *",
+  "prompt": "Call quotes(symbols=[\"NVDA\",\"TSLA\"]) on the arcus MCP server. "
+            "Alert me if any quote has is_halted=true or a non-null "
+            "multiplier.pending; otherwise stay silent."
+}
+```
+
+Equivalent plain-cron line if your scheduler prefers shell:
+
+```
+*/5 * * * *  your-agent run --tool quotes --args '{"symbols":["NVDA","TSLA"]}'
+```
+
+**Watch for in each poll:** `is_halted: true` (halt), a new
+`multiplier.pending` (upcoming split — verify with
+`token_detail(symbol=...)`), `errors[]` (a symbol was delisted/renamed —
+re-check with `token_list()`).
+
+## Caveats
+
+- Read-only market data, **not trading advice**; verify against the official
+  source before acting.
+- `market_status().halted` and `sector_view()` averages are cache-driven —
+  prime with `quotes()` for a real scan.
+- `onchain_info` is a stub until v0.2 (no balances/history yet).

arcus_agent_gateway-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - name: GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

arcus_agent_gateway-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,27 @@
+name: tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  offline:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - name: Run tests
+        run: |
+          pytest tests/ -q --cov=arcus_mcp --tb=short > pytest_output.txt 2>&1 || FAILED=1
+          grep -E "^(FAILED|ERROR)|Error|error" pytest_output.txt | head -25 | while IFS= read -r line; do
+            echo "::error::${line:0:250}"
+          done
+          tail -40 pytest_output.txt
+          exit ${FAILED:-0}

arcus_agent_gateway-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+*.log
+.coverage
+.pytest_cache/

arcus_agent_gateway-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-09-04)
+
+Initial release.
+
+- 9 read-only MCP tools for 194 tokenized US equities on Robinhood Chain
+  (Arcus DEX): `token_list`, `quote`, `quotes`, `token_detail`,
+  `market_status`, `corporate_actions`, `search`, `sector_view`,
+  `onchain_info` (v0.2 stub)
+- Multiplier handling: raw and adjusted price fields side by side,
+  pending-split warnings (effective time), per-token multiplier history note
+- Caching (300s / 15s / 3600s), client rate limit (50 req/s cap), 429 retry
+  with backoff
+- Honest degradation: unknown symbol errors point at `token_list()`;
+  `market_status()` labels its estimates; `onchain_info` is a marked stub
+- 75 offline tests including spec invariants (adjusted == raw x multiplier,
+  spread >= 0, halted propagation, batch limits)

arcus_agent_gateway-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arcus-agent-gateway contributors
+
+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.

arcus_agent_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: arcus-agent-gateway
+Version: 0.1.0
+Summary: MCP gateway for AI agents to Robinhood Chain (Arcus DEX) tokenized US equities: quotes, multipliers, corporate actions, market status, sectors. Read-only, keyless.
+Project-URL: Homepage, https://github.com/alekskram/arcus-agent-gateway
+Project-URL: Repository, https://github.com/alekskram/arcus-agent-gateway
+Project-URL: Issues, https://github.com/alekskram/arcus-agent-gateway/issues
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,arcus,defi,mcp,robinhood-chain,rwa,tokenized-stocks
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=3.0
+Provides-Extra: dev
+Requires-Dist: pip-audit; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# arcus-agent-gateway
+
+[![CI](https://github.com/alekskram/arcus-agent-gateway/actions/workflows/tests.yml/badge.svg)](https://github.com/alekskram/arcus-agent-gateway/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/arcus-agent-gateway.svg)](https://pypi.org/project/arcus-agent-gateway/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](pyproject.toml)
+
+An MCP (Model Context Protocol) server that gives AI agents read-only, keyless
+access to market data for the **194 tokenized US equities** on **Robinhood Chain
+(Arcus)** — quotes, corporate actions, trading capabilities, multipliers and a
+13-sector map. No API keys, no auth, no writes: every tool is a GET against the
+public `api.robinhood.com/rhj` REST surface, cached and rate-limited so an
+enthusiastic agent can't hammer the upstream.
+
+## Quickstart
+
+Run over stdio (the default, for local agents):
+
+```bash
+uvx arcus-agent-gateway
+```
+
+Claude Desktop / Cursor config (`claude_desktop_config.json` or
+`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "arcus": {
+      "command": "uvx",
+      "args": ["arcus-agent-gateway"]
+    }
+  }
+}
+```
+
+Hosted form — streamable HTTP on port **8902**:
+
+```bash
+uvx arcus-agent-gateway --http               # 127.0.0.1:8902
+curl http://127.0.0.1:8902/health            # -> {"ok": true, "service": "arcus-agent-gateway"}
+```
+
+## Tools
+
+All 9 tools are read-only (annotated `readOnlyHint: true`). Names and
+parameters are exactly as registered by `arcus_mcp/server.py`.
+
+| # | Tool | Signature | What it does |
+|---|------|-----------|--------------|
+| 1 | `token_list` | `token_list(status="ACTIVE", limit=100)` | Tokenized equities, one row per token (symbol, name, status, multiplier, tradable); `status` filters the `ASSET_STATUS_*` prefix, `'ALL'` disables. Start here for valid symbols. |
+| 2 | `quote` | `quote(symbol)` | Live quote joined with asset metadata: raw + multiplier-adjusted bid/ask/spread, `is_halted`, trading capabilities, multiplier block. Unknown symbol raises with a pointer to `token_list()`. |
+| 3 | `quotes` | `quotes(symbols)` | Batch of `quote()` rows, **max 20 per call** (more raises). Unknown symbols land in `errors` without failing the batch. |
+| 4 | `token_detail` | `token_detail(symbol)` | Full dossier: contract/chain/ISIN metadata, embedded quote, last 5 corporate actions, multiplier block with history note, `warnings` (pending split). |
+| 5 | `market_status` | `market_status()` | Market-wide health from assets only (never fetches 194 prices): totals, untradable count, cached-halted list, extended-hours estimate. |
+| 6 | `corporate_actions` | `corporate_actions(symbol=None, limit=10)` | Splits/dividends across all tokens or for one symbol; tolerant to the API's field-name variants. |
+| 7 | `search` | `search(query)` | Local fuzzy search over the token list; `apple` → `AAPL`; top 10 with scores and sectors. |
+| 8 | `sector_view` | `sector_view()` | 13-sector static map with sizes and — once quotes are cached — multiplier-adjusted sector averages. Makes no requests. |
+| 9 | `onchain_info` | `onchain_info(symbol)` | Contract address, chain id (4663, Robinhood Chain), network, decimals, ISIN. v0.2 stub — full on-chain data (balances, Transfer/Split history) is planned for v0.2. |
+| 10 | *watchlist* | — | Not a tool. Price tracking is done by your agent's scheduler (cron) calling `quotes()` on an interval — see [`.agents/skills/arcus-gateway/SKILL.md`](.agents/skills/arcus-gateway/SKILL.md). |
+
+## Multiplier logic (read this before using prices)
+
+Robinhood Chain tokens carry a **multiplier** — the corporate-action
+adjustment factor for the token contract (`1.0` = untouched). Splits change it;
+for example NVDA's 2026-11 split queues `pendingMultiplier: "4.0"`.
+
+- **The REST API returns RAW prices.** `bid`/`ask` from `/prices/{symbol}` are
+  in token-contract units and are **not** multiplier-adjusted.
+- **Adjusted values are computed by this server**, never taken from upstream:
+  `price_adjusted = round(price_raw × currentMultiplier, 6)`.
+- **Raw and adjusted always travel together.** Every quote carries
+  `bid_raw`/`ask_raw`/`spread_raw` *and* `bid_adjusted`/`ask_adjusted`/
+  `mid_adjusted` next to the `multiplier` block — never one without the other.
+- On-chain quantities (token balances, mint/burn volumes) are natively in
+  adjusted (multiplied) units; REST prices are not. If you compare the two,
+  go through the `*_adjusted` fields.
+
+Worked example (live fixture, 2026-09-03):
+
+```
+AAPL   currentMultiplier = 1.000566080061092436
+       bid_raw   = 327.77   →  bid_adjusted = round(327.77 × 1.000566…, 6) = 327.955544
+       ask_raw   = 327.78   →  ask_adjusted = 327.965550
+       mid                      mid_adjusted = 327.960547
+```
+
+**Pending split warning.** When `pendingMultiplier` is queued (non-empty) and
+differs from the current one, `token_detail()` adds a warning like
+`pending split: 1→4.0 on 2026-11-06T00:00:00Z`, and `quote()`'s multiplier
+block exposes `pending` + `effective_time`. After the split lands, raw prices
+jump by the ratio while `*_adjusted` fields stay comparable — another reason to
+always read adjusted values next to the multiplier.
+
+## API limits & caching
+
+- Upstream allows **60 req/s without a key**; this client self-limits to
+  **≤ 50 req/s** (a 20 ms politeness interval between requests, thread-safe).
+- Transient failures (`429/502/503/504`, network errors) are retried up to 3
+  times with `2s × (attempt+1)` backoff.
+- Response caches (per process): `/assets` **5 min**, `/prices/{symbol}`
+  **15 s**, `/corporate-actions` **1 h**. `market_status()` and `sector_view()`
+  are computed from caches and assets only — they never fan out 194 price
+  requests.
+
+## Raw prices disclaimer
+
+Prices are served **exactly as they arrive from Robinhood (RAW)** — they are
+*not* multiplier-adjusted, and the `*_adjusted` fields are **our computation**,
+not upstream data. All data is for information only, **not for trading
+decisions**, and should be verified against the official source before you act
+on it. No warranty of completeness, accuracy or timeliness.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest -q                      # 75 tests, all offline (fixtures + mocks)
+.venv/bin/python scripts/smoke_api_offline.py     # REST client smoke, zero HTTP
+.venv/bin/python scripts/smoke_server_offline.py  # 9-tool server smoke, zero HTTP
+```
+
+Layout: `arcus_mcp/api.py` (stdlib REST client), `arcus_mcp/server.py` (9 MCP
+tools + FastMCP wiring), `arcus_mcp/sectors.py` (validated 13-sector map),
+`arcus_mcp/paths.py` (state dir; override with `ARCUS_GATEWAY_DATA`).
+Live-captured schema fixtures live in `tests/fixtures/` with notes in
+`arcus_mcp/API_NOTES.md`. Usage scenarios: [`examples/use-cases.md`](examples/use-cases.md).

arcus_agent_gateway-0.1.0/README.md

@@ -0,0 +1,127 @@
+# arcus-agent-gateway
+
+[![CI](https://github.com/alekskram/arcus-agent-gateway/actions/workflows/tests.yml/badge.svg)](https://github.com/alekskram/arcus-agent-gateway/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/arcus-agent-gateway.svg)](https://pypi.org/project/arcus-agent-gateway/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](pyproject.toml)
+
+An MCP (Model Context Protocol) server that gives AI agents read-only, keyless
+access to market data for the **194 tokenized US equities** on **Robinhood Chain
+(Arcus)** — quotes, corporate actions, trading capabilities, multipliers and a
+13-sector map. No API keys, no auth, no writes: every tool is a GET against the
+public `api.robinhood.com/rhj` REST surface, cached and rate-limited so an
+enthusiastic agent can't hammer the upstream.
+
+## Quickstart
+
+Run over stdio (the default, for local agents):
+
+```bash
+uvx arcus-agent-gateway
+```
+
+Claude Desktop / Cursor config (`claude_desktop_config.json` or
+`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "arcus": {
+      "command": "uvx",
+      "args": ["arcus-agent-gateway"]
+    }
+  }
+}
+```
+
+Hosted form — streamable HTTP on port **8902**:
+
+```bash
+uvx arcus-agent-gateway --http               # 127.0.0.1:8902
+curl http://127.0.0.1:8902/health            # -> {"ok": true, "service": "arcus-agent-gateway"}
+```
+
+## Tools
+
+All 9 tools are read-only (annotated `readOnlyHint: true`). Names and
+parameters are exactly as registered by `arcus_mcp/server.py`.
+
+| # | Tool | Signature | What it does |
+|---|------|-----------|--------------|
+| 1 | `token_list` | `token_list(status="ACTIVE", limit=100)` | Tokenized equities, one row per token (symbol, name, status, multiplier, tradable); `status` filters the `ASSET_STATUS_*` prefix, `'ALL'` disables. Start here for valid symbols. |
+| 2 | `quote` | `quote(symbol)` | Live quote joined with asset metadata: raw + multiplier-adjusted bid/ask/spread, `is_halted`, trading capabilities, multiplier block. Unknown symbol raises with a pointer to `token_list()`. |
+| 3 | `quotes` | `quotes(symbols)` | Batch of `quote()` rows, **max 20 per call** (more raises). Unknown symbols land in `errors` without failing the batch. |
+| 4 | `token_detail` | `token_detail(symbol)` | Full dossier: contract/chain/ISIN metadata, embedded quote, last 5 corporate actions, multiplier block with history note, `warnings` (pending split). |
+| 5 | `market_status` | `market_status()` | Market-wide health from assets only (never fetches 194 prices): totals, untradable count, cached-halted list, extended-hours estimate. |
+| 6 | `corporate_actions` | `corporate_actions(symbol=None, limit=10)` | Splits/dividends across all tokens or for one symbol; tolerant to the API's field-name variants. |
+| 7 | `search` | `search(query)` | Local fuzzy search over the token list; `apple` → `AAPL`; top 10 with scores and sectors. |
+| 8 | `sector_view` | `sector_view()` | 13-sector static map with sizes and — once quotes are cached — multiplier-adjusted sector averages. Makes no requests. |
+| 9 | `onchain_info` | `onchain_info(symbol)` | Contract address, chain id (4663, Robinhood Chain), network, decimals, ISIN. v0.2 stub — full on-chain data (balances, Transfer/Split history) is planned for v0.2. |
+| 10 | *watchlist* | — | Not a tool. Price tracking is done by your agent's scheduler (cron) calling `quotes()` on an interval — see [`.agents/skills/arcus-gateway/SKILL.md`](.agents/skills/arcus-gateway/SKILL.md). |
+
+## Multiplier logic (read this before using prices)
+
+Robinhood Chain tokens carry a **multiplier** — the corporate-action
+adjustment factor for the token contract (`1.0` = untouched). Splits change it;
+for example NVDA's 2026-11 split queues `pendingMultiplier: "4.0"`.
+
+- **The REST API returns RAW prices.** `bid`/`ask` from `/prices/{symbol}` are
+  in token-contract units and are **not** multiplier-adjusted.
+- **Adjusted values are computed by this server**, never taken from upstream:
+  `price_adjusted = round(price_raw × currentMultiplier, 6)`.
+- **Raw and adjusted always travel together.** Every quote carries
+  `bid_raw`/`ask_raw`/`spread_raw` *and* `bid_adjusted`/`ask_adjusted`/
+  `mid_adjusted` next to the `multiplier` block — never one without the other.
+- On-chain quantities (token balances, mint/burn volumes) are natively in
+  adjusted (multiplied) units; REST prices are not. If you compare the two,
+  go through the `*_adjusted` fields.
+
+Worked example (live fixture, 2026-09-03):
+
+```
+AAPL   currentMultiplier = 1.000566080061092436
+       bid_raw   = 327.77   →  bid_adjusted = round(327.77 × 1.000566…, 6) = 327.955544
+       ask_raw   = 327.78   →  ask_adjusted = 327.965550
+       mid                      mid_adjusted = 327.960547
+```
+
+**Pending split warning.** When `pendingMultiplier` is queued (non-empty) and
+differs from the current one, `token_detail()` adds a warning like
+`pending split: 1→4.0 on 2026-11-06T00:00:00Z`, and `quote()`'s multiplier
+block exposes `pending` + `effective_time`. After the split lands, raw prices
+jump by the ratio while `*_adjusted` fields stay comparable — another reason to
+always read adjusted values next to the multiplier.
+
+## API limits & caching
+
+- Upstream allows **60 req/s without a key**; this client self-limits to
+  **≤ 50 req/s** (a 20 ms politeness interval between requests, thread-safe).
+- Transient failures (`429/502/503/504`, network errors) are retried up to 3
+  times with `2s × (attempt+1)` backoff.
+- Response caches (per process): `/assets` **5 min**, `/prices/{symbol}`
+  **15 s**, `/corporate-actions` **1 h**. `market_status()` and `sector_view()`
+  are computed from caches and assets only — they never fan out 194 price
+  requests.
+
+## Raw prices disclaimer
+
+Prices are served **exactly as they arrive from Robinhood (RAW)** — they are
+*not* multiplier-adjusted, and the `*_adjusted` fields are **our computation**,
+not upstream data. All data is for information only, **not for trading
+decisions**, and should be verified against the official source before you act
+on it. No warranty of completeness, accuracy or timeliness.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest -q                      # 75 tests, all offline (fixtures + mocks)
+.venv/bin/python scripts/smoke_api_offline.py     # REST client smoke, zero HTTP
+.venv/bin/python scripts/smoke_server_offline.py  # 9-tool server smoke, zero HTTP
+```
+
+Layout: `arcus_mcp/api.py` (stdlib REST client), `arcus_mcp/server.py` (9 MCP
+tools + FastMCP wiring), `arcus_mcp/sectors.py` (validated 13-sector map),
+`arcus_mcp/paths.py` (state dir; override with `ARCUS_GATEWAY_DATA`).
+Live-captured schema fixtures live in `tests/fixtures/` with notes in
+`arcus_mcp/API_NOTES.md`. Usage scenarios: [`examples/use-cases.md`](examples/use-cases.md).

arcus_agent_gateway-0.1.0/arcus_mcp/API_NOTES.md

@@ -0,0 +1,29 @@
+# rhj API schema notes (live capture 2026-09-03)
+
+Non-obvious details for anyone building on `arcus_mcp/api.py`. Fixtures:
+`tests/fixtures/assets.json`, `tests/fixtures/prices_AAPL.json`.
+
+1. **Every numeric field is a STRING.** `bid: "327.77"`,
+   `dailyTradingVolume: "25806784"`, and
+   `currentMultiplier: "1.000000000000000000"` — fixed 18-decimal
+   strings (token-style scaling, though `tokenDecimals` is also 18).
+   `float(x)` before any arithmetic; never `int()` directly.
+2. **`pendingMultiplier` can be `""`** — empty string, not `null`/`0`,
+   when no multiplier change is queued. Truthiness (`if a["pendingMultiplier"]`)
+   is the right liveness check; never parse it unconditionally.
+3. **`/prices/{symbol}` wraps the quote in a list** — `{"quotes": [ {...} ]}`
+   with exactly one element per fixture. Take `quotes[0]`, but guard for an
+   empty list. There is **no name or multiplier in the quote**: a full
+   ticker view = join `assets()` ↔ `prices()` on `tokenSymbol`.
+4. **`generatedAt` carries nanosecond precision**
+   (`2026-09-03T19:43:54.478722091Z`). Python 3.11+ `datetime.fromisoformat`
+   handles it after replacing the `Z` suffix with `+00:00` (3.11+ also
+   accepts the bare `Z`).
+5. **`/corporate-actions` response shape was NOT captured live** — no
+   fixture exists. `corporate_actions()` therefore accepts both a bare
+   JSON list and a dict-wrapped list (first list value found). Confirm the
+   real wrapper key on the first live call and tighten if desired. Symbol
+   filtering is done locally (query params not contractual).
+6. **Unknown symbol on `/prices/{x}` returns 404** — `prices()` maps that
+   to `None` (distinguishing "no quote" from "API down" is left to `get()`'s
+   exceptions). `asset()` likewise returns `None` for unknown symbols.

arcus_agent_gateway-0.1.0/arcus_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""Arcus Agent Gateway - MCP server package."""
+__version__ = "0.1.0"