@buildaureon/mcp 0.1.1

package/docs/tools.md

@@ -0,0 +1,553 @@
+# AUREON MCP Tool Reference
+
+Complete reference for every tool exposed by `@buildaureon/mcp`.
+
+Each tool maps to one public method on the `@buildaureon/sdk` client. Handlers validate arguments, call the live AUREON API, and return pretty-printed JSON (or an agent-readable error envelope).
+
+For request/response shapes, error codes, and HTTP contracts, see the **@buildaureon/sdk documentation**.
+
+**Tool count:** 34.
+
+**API:** `https://api.aureonlabs.network` (Robinhood Chain L2, early access).
+
+---
+
+## Conventions
+
+These conventions apply to every tool below.
+
+| Convention | Meaning |
+| --- | --- |
+| Issued API key | Set `AUREON_API_KEY` to an issued Developers key. That key is product access **and** wallet identity for control-plane calls. |
+| Optional Bearer | You may also supply a wallet Bearer (`AUREON_AUTH_TOKEN` or `aureon_verify_wallet`). If both key and Bearer are present, Bearer wins. |
+| Live API only | Tools talk to the live AUREON gateway. There is no local-backend mode for agents. |
+| Private key outside MCP | Deposit and withdraw **prepare** tools return unsigned steps. Signing and broadcast happen in the host wallet — never inside the MCP process. |
+| Default automation | `aureon_create_objective` defaults `automationMode` to `"auto"`. |
+| Locked at create | `targetSymbol` and `automationMode` are immutable after create. Recreate the objective to change them. |
+| Unsigned prepare | `aureon_prepare_vault_deposit` and `aureon_prepare_vault_withdraw` never broadcast. |
+| Settlement honesty | Restore / execution receipts may show `settlement: "vault"` (on-chain) or `"staged"` (ledger-local). Label them honestly. |
+
+The catalog includes `aureon_dev_login` for preview APIs only. On the live production API it fails by design — agents should use an issued key (or optional Bearer) instead.
+
+### Auth bootstrap (agents)
+
+1. Create an issued key in the operator utility **Developers** console.
+2. Configure the MCP host with `AUREON_API_URL=https://api.aureonlabs.network` and `AUREON_API_KEY`.
+3. Call tools. Day-to-day agent work does **not** require a wallet handshake.
+
+Optional wallet path: `aureon_get_auth_nonce` → host signs → `aureon_verify_wallet`. Prefer issued keys for always-on agents.
+
+### Response shape
+
+Successful calls return structured JSON (formatted for agents). Failures return an error object with a stable code and message — see the **@buildaureon/sdk documentation** error model.
+
+### Quick index
+
+| Group | Tools |
+| --- | --- |
+| Health | `aureon_ping` |
+| Auth & identity | `aureon_get_auth_nonce`, `aureon_verify_wallet`, `aureon_dev_login`, `aureon_logout`, `aureon_me` |
+| Dashboard & read | `aureon_get_overview`, `aureon_get_portfolio`, `aureon_list_objectives`, `aureon_get_objective`, `aureon_get_health`, `aureon_list_timeline`, `aureon_list_market_presets`, `aureon_get_restore_plan`, `aureon_list_executions`, `aureon_get_vault`, `aureon_get_vault_status` |
+| Objectives | `aureon_create_objective`, `aureon_update_objective`, `aureon_pause_objective`, `aureon_resume_objective` |
+| Portfolio write | `aureon_set_portfolio`, `aureon_clear_portfolio`, `aureon_sync_portfolio` |
+| Execution | `aureon_run_execution`, `aureon_restore_objective` |
+| Market | `aureon_apply_market_event`, `aureon_refresh_watchdog` |
+| Vault prepare | `aureon_prepare_vault_deposit`, `aureon_prepare_vault_withdraw` |
+| Developer keys | `aureon_list_api_keys`, `aureon_create_api_key`, `aureon_revoke_api_key`, `aureon_toggle_api_key` |
+
+---
+
+## Health
+
+### `aureon_ping`
+
+**Purpose:** Confirm the live API is reachable and return a lightweight service / version smoke payload.
+
+**Typical args:** none.
+
+**When to use:** First call in a session; connectivity checks; before diagnosing auth or policy failures.
+
+**Caveats:** A successful ping does not prove the issued key is valid for wallet-scoped tools — follow with `aureon_me` when identity matters.
+
+---
+
+## Auth & identity
+
+### `aureon_get_auth_nonce`
+
+**Purpose:** Fetch an EIP-191 challenge message for a wallet address so the host can sign a Bearer login.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `address` | yes | Wallet `0x…` |
+
+**When to use:** Optional wallet handshake only. Issued API keys usually skip this path.
+
+**Caveats:** The message must be signed by the matching wallet. Early-access wallets may still need an invite on verify.
+
+### `aureon_verify_wallet`
+
+**Purpose:** Exchange a signed nonce for a Bearer session and store it in-process for later tools in this MCP session.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `address` | yes | Same wallet as the nonce |
+| `message` | yes | From `aureon_get_auth_nonce` |
+| `signature` | yes | Wallet signature hex |
+| `inviteCode` | no | First-login invite when required |
+
+**When to use:** When you intentionally want a Bearer session instead of (or in addition to) an issued key.
+
+**Caveats:** Bearer wins over the API key when both are present. Do not ask the user for a private key — only a signature over the challenge.
+
+### `aureon_dev_login`
+
+**Purpose:** Preview-API shortcut that returns a Bearer session without a wallet signature.
+
+**Typical args:** none.
+
+**When to use:** Only on a preview / staging API that explicitly enables `AUREON_ALLOW_DEV_LOGIN=1`.
+
+**Caveats:** Fails on `https://api.aureonlabs.network`. Do not put this tool in production agent playbooks. Prefer issued keys.
+
+### `aureon_logout`
+
+**Purpose:** Revoke the current Bearer session and clear the in-process token.
+
+**Typical args:** none.
+
+**When to use:** End a wallet session; rotate away from a Bearer after debugging.
+
+**Caveats:** Does not revoke the issued `AUREON_API_KEY`. Key-only agents may not need this tool.
+
+### `aureon_me`
+
+**Purpose:** Return the wallet bound to the issued API key or the current Bearer session.
+
+**Typical args:** none.
+
+**When to use:** Identity confirmation after connect; every morning check; before mutating portfolio or objectives.
+
+**Caveats:** If you see an error about env keys that cannot identify a wallet, replace the key with an **issued** Developers key.
+
+---
+
+## Dashboard & portfolio (read)
+
+### `aureon_get_overview`
+
+**Purpose:** Dashboard rollup — AUM, objective counts, aggregate health posture.
+
+**Typical args:** none.
+
+**When to use:** Morning checks; high-level status before diving into a single objective.
+
+**Caveats:** Overview is a summary. Drill into `aureon_get_health` / `aureon_get_objective` for policy decisions.
+
+### `aureon_get_portfolio`
+
+**Purpose:** Current Capital Book snapshot — positions, marks, and weights.
+
+**Typical args:** none.
+
+**When to use:** After sync; before creating objectives; when explaining current exposure.
+
+**Caveats:** Stale books mislead restore logic. Prefer `aureon_sync_portfolio` when chain balances may have changed.
+
+### `aureon_list_objectives`
+
+**Purpose:** List all Financial Compass objectives for the authenticated wallet.
+
+**Typical args:** none.
+
+**When to use:** Discover IDs; inventory auto vs paused objectives; pick a target for restore.
+
+**Caveats:** Empty list is normal for new wallets. Create with `automationMode: "auto"` for agent-driven restores.
+
+### `aureon_get_objective`
+
+**Purpose:** Fetch one objective by ID (policy fields, status, locked create-time fields).
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | yes | From list or create |
+
+**When to use:** Inspect before update / pause / restore; confirm `targetSymbol` and `automationMode`.
+
+**Caveats:** Remember `targetSymbol` and `automationMode` cannot be patched later.
+
+### `aureon_get_health`
+
+**Purpose:** Health / drift / breach state for one objective or all objectives.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | no | Omit for all |
+
+**When to use:** After watchdog refresh; before restore; when the operator asks why something looks red.
+
+**Caveats:** Health can flap after marks update. Re-read after restore instead of spamming restores.
+
+### `aureon_list_timeline`
+
+**Purpose:** Event timeline — objective changes, executions, health transitions.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | no | Omit for all |
+
+**When to use:** Post-restore confirmation; audit trail for the operator; debugging unexpected state.
+
+**Caveats:** Timeline is historical context, not a substitute for the latest health snapshot.
+
+### `aureon_list_market_presets`
+
+**Purpose:** List available market-event simulation presets for rehearsal.
+
+**Typical args:** none.
+
+**When to use:** Before `aureon_apply_market_event` in integration / demo flows.
+
+**Caveats:** Presets are for rehearsal, not live oracle prices.
+
+### `aureon_get_restore_plan`
+
+**Purpose:** Inspect the proposed restore plan for an objective (steps to return to policy).
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | yes | Target objective |
+
+**When to use:** Always prefer reading the plan before `aureon_restore_objective` when explaining risk to a human.
+
+**Caveats:** Plans can change after marks or vault balances move. Refresh health / watchdog if the book is stale.
+
+### `aureon_list_executions`
+
+**Purpose:** Recent execution receipts for restorative actions.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | no | Omit for all |
+
+**When to use:** Confirm last restore; check `settlement` field (`vault` vs `staged`).
+
+**Caveats:** Never claim on-chain settlement unless the receipt says `settlement: "vault"`.
+
+### `aureon_get_vault`
+
+**Purpose:** Full vault overview — balances, tokens, deposit-related history.
+
+**Typical args:** none.
+
+**When to use:** Funding diagnosis; after a broadcasted deposit; capital readiness reviews.
+
+**Caveats:** Vault overview can lag until chain txs confirm and portfolio sync runs.
+
+### `aureon_get_vault_status`
+
+**Purpose:** Compact funding / readiness status before Automatic restores.
+
+**Typical args:** none.
+
+**When to use:** Morning checks; gate before creating auto objectives; after prepare+broadcast deposits.
+
+**Caveats:** Empty vault often blocks meaningful Automatic restores — prepare a deposit and have the host sign.
+
+---
+
+## Portfolio (write)
+
+### `aureon_set_portfolio`
+
+**Purpose:** Replace the Capital Book with an explicit position list.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `positions` | yes | Array of rows: `symbol`, `name`, `category`, `quantity`, `markPriceUsd` |
+| `positions[].category` | yes | `stable` \| `stock_token` \| `gas` \| `other` |
+
+**When to use:** Controlled demos or explicit book overrides when the operator supplies positions.
+
+**Caveats:** Overwrites the book. Prefer `aureon_sync_portfolio` for live chain marks in production agent loops.
+
+### `aureon_clear_portfolio`
+
+**Purpose:** Clear all Capital Book positions for the authenticated wallet.
+
+**Typical args:** none.
+
+**When to use:** Reset before a clean sync or demo restart.
+
+**Caveats:** Destructive. Confirm with the operator before clearing a live book.
+
+### `aureon_sync_portfolio`
+
+**Purpose:** Replace the Capital Book with on-chain balances for the session wallet.
+
+**Typical args:** none.
+
+**When to use:** Default read-path refresh; after deposits/withdraws broadcast; before create / restore.
+
+**Caveats:** Sync does not move vault funds by itself — it refreshes the book the policy engine reads.
+
+---
+
+## Objectives (write)
+
+### `aureon_create_objective`
+
+**Purpose:** Create a Financial Compass objective. Defaults `automationMode` to `"auto"`.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `name` | yes | Display name |
+| `kind` | yes | `stable_allocation` \| `balanced_portfolio` \| `risk_ceiling` \| `reward_reinvestment` |
+| `targetWeight` | yes | 0–1 |
+| `tolerance` | yes | Drift band 0–1 |
+| `priority` | no | `low` \| `medium` \| `high` \| `critical` |
+| `maxRiskScore` | no | For risk-ceiling kinds |
+| `reinvestRatio` | no | For reward kinds |
+| `targetSymbol` | no | Asset symbol (nullable); **locked after create** |
+| `automationMode` | no | `auto` \| `manual`; default **`auto`**; **locked after create** |
+
+**When to use:** New policy intent (e.g. maintain ~15% WETH automatically).
+
+**Caveats:** Agents should use **Automatic** (`auto`) unless the human explicitly wants Manual Approve. To change symbol or mode later, create a new objective (pause or leave the old one).
+
+### `aureon_update_objective`
+
+**Purpose:** Partial update of mutable fields (name, weight, tolerance, priority, optional risk/reinvest fields).
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | yes | Target |
+| `name` | no | Display name |
+| `priority` | no | Priority enum |
+| `targetWeight` | no | 0–1 |
+| `tolerance` | no | 0–1 |
+| `maxRiskScore` | no | Optional |
+| `reinvestRatio` | no | Optional |
+
+**When to use:** Tighten tolerance; rename; adjust weight without changing token or automation mode.
+
+**Caveats:** **Cannot** change `targetSymbol` or `automationMode`. If the API rejects those fields, recreate instead.
+
+### `aureon_pause_objective`
+
+**Purpose:** Pause continuous evaluation for an objective.
+
+**Typical args:** `objectiveId` (required).
+
+**When to use:** Temporary halt during funding, maintenance, or operator review.
+
+**Caveats:** Paused objectives will not drive Automatic restores until resumed.
+
+### `aureon_resume_objective`
+
+**Purpose:** Resume evaluation for a paused objective.
+
+**Typical args:** `objectiveId` (required).
+
+**When to use:** After funding the vault or finishing a maintenance window.
+
+**Caveats:** Re-check health after resume; a breach may already exist.
+
+---
+
+## Compass / execution
+
+### `aureon_run_execution`
+
+**Purpose:** Run restorative execution for an objective currently outside policy.
+
+**Typical args:** `objectiveId` (required).
+
+**When to use:** Explicit execution path when the product flow calls for `runExecution` rather than vault-backed restore.
+
+**Caveats:** Prefer reading health / plan first. Report settlement type honestly from the receipt.
+
+### `aureon_restore_objective`
+
+**Purpose:** Run vault-backed restorative execution for an objective outside policy (primary agent restore path).
+
+**Typical args:** `objectiveId` (required).
+
+**When to use:** After a clear breach and a reviewed restore plan; Automatic objectives with a funded vault.
+
+**Caveats:** Empty vault or Manual-only product constraints can block or stage settlement. Confirm with `aureon_list_timeline` / `aureon_list_executions`.
+
+---
+
+## Market
+
+### `aureon_apply_market_event`
+
+**Purpose:** Apply a controlled mark shock to a symbol for integration rehearsal; optionally trigger auto-restore.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `symbol` | yes | e.g. `TSLA` |
+| `priceChangeRatio` | yes | Fractional change (`-0.1` = −10%) |
+| `name` | no | Event label |
+| `description` | no | Human description |
+| `autoRestore` | no | If true, may run restorative execution on breach |
+
+**When to use:** Demo / rehearsal of drift → plan → restore. Not for production price discovery.
+
+**Caveats:** Do not treat rehearsal shocks as live oracle prices for real capital decisions.
+
+### `aureon_refresh_watchdog`
+
+**Purpose:** Refresh portfolio marks from live data and re-evaluate objectives.
+
+**Typical args:** none.
+
+**When to use:** Morning checks; after market events; before reading health for restore decisions.
+
+**Caveats:** Refresh alone does not restore. Follow with health / plan / restore as needed.
+
+---
+
+## Vault
+
+### `aureon_prepare_vault_deposit`
+
+**Purpose:** Prepare **unsigned** vault deposit steps for a symbol and amount.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `symbol` | yes | `ETH` or allowlisted ERC-20 |
+| `amount` | yes | Human-readable amount string |
+
+**When to use:** Fund the vault so Automatic restores can settle on-chain.
+
+**Caveats:** Returns calldata / steps only. The **host** must sign and broadcast with a private key **outside** MCP. API key alone cannot move funds. After broadcast, sync and re-check vault status.
+
+### `aureon_prepare_vault_withdraw`
+
+**Purpose:** Prepare **unsigned** vault withdraw steps.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `amount` | yes | Human-readable amount string |
+| `symbol` | no | Default WETH (not ETH) |
+
+**When to use:** Operator-directed withdrawals after confirming vault balances.
+
+**Caveats:** Same non-custodial boundary as deposit — prepare ≠ completed withdrawal until the host broadcasts.
+
+---
+
+## Developer API keys
+
+### `aureon_list_api_keys`
+
+**Purpose:** List API key metadata for the authenticated wallet (no secrets).
+
+**Typical args:** none.
+
+**When to use:** Inventory keys; find IDs for toggle / revoke.
+
+**Caveats:** Secrets are never re-listed after create. Metadata only.
+
+### `aureon_create_api_key`
+
+**Purpose:** Create a new issued SDK API key. The secret is returned **once**.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `name` | yes | Display name (min length enforced) |
+
+**When to use:** Rotate or provision a new agent key under an already-authenticated identity.
+
+**Caveats:** Treat the returned secret like a password. Do not echo it into public chat logs. Store it in the MCP host env as `AUREON_API_KEY`.
+
+### `aureon_revoke_api_key`
+
+**Purpose:** Permanently revoke (delete) an issued API key.
+
+**Typical args:** `keyId` (required).
+
+**When to use:** Key compromise; decommissioning an agent.
+
+**Caveats:** Irreversible for that key material. Confirm the ID from `aureon_list_api_keys`.
+
+### `aureon_toggle_api_key`
+
+**Purpose:** Pause or unpause an API key without revoking it.
+
+**Typical args:** `keyId` (required).
+
+**When to use:** Temporary freeze during investigation; soft disable without rotation.
+
+**Caveats:** Toggled-off keys fail subsequent control-plane calls until re-enabled.
+
+---
+
+## Prompt → tool mapping
+
+| Operator ask | Tool(s) |
+| --- | --- |
+| “Is the API up?” | `aureon_ping` |
+| “Which wallet am I?” | `aureon_me` |
+| “Refresh balances from chain” | `aureon_sync_portfolio` |
+| “Is the vault funded?” | `aureon_get_vault_status` |
+| “Maintain 20% WETH automatic” | `aureon_create_objective` (`automationMode: auto`, `targetSymbol: WETH`) |
+| “Why is health red?” | `aureon_get_health`, `aureon_list_timeline` |
+| “Show the restore plan” | `aureon_get_restore_plan` |
+| “Execute restore” | `aureon_restore_objective` |
+| “Simulate −10% TSLA” | `aureon_apply_market_event` |
+| “Prepare 0.1 ETH deposit” | `aureon_prepare_vault_deposit` then host signs |
+| “Rotate my agent key” | `aureon_create_api_key` (+ secure store), optional `aureon_revoke_api_key` |
+
+---
+
+## Related reading
+
+- [Agent guide](./agent-guide.md) — read → decide → act playbooks
+- [Auth](./auth.md) — issued key, optional Bearer, private-key boundary
+- [Setup](./setup.md) — host configuration for Cursor / Claude Desktop
+- [Security](./security.md) — stdio trust boundary and key hygiene
+- **@buildaureon/sdk documentation** — typed client methods, data contracts, error model
+
+---
+
+## Notes for implementers
+
+- Tool names are stable strings beginning with `aureon_`.
+- Argument validation is strict; omit unknown fields rather than inventing them.
+- Prefer read tools before write tools in every agent turn that mutates state.
+- Automatic mode is the agent default; Manual mode is a human Approve surface.
+- Prepare tools are safe to call with an API key; broadcasting is a separate host step.
+- When summarizing restores, always include settlement type when the receipt provides it.
+
+This reference is the canonical MCP tool surface for live agents: **34 tools**, live API, issued key (optional Bearer), and private key only outside MCP for broadcast.

package/examples/claude-desktop.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "aureon": {
+      "command": "npx",
+      "args": ["-y", "@buildaureon/mcp"],
+      "env": {
+        "AUREON_API_URL": "https://api.aureonlabs.network",
+        "AUREON_API_KEY": "<issued-developer-api-key>"
+      }
+    }
+  }
+}

package/examples/cursor.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "aureon": {
+      "command": "npx",
+      "args": ["-y", "@buildaureon/mcp"],
+      "env": {
+        "AUREON_API_URL": "https://api.aureonlabs.network",
+        "AUREON_API_KEY": "<issued-developer-api-key>"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@buildaureon/mcp",
+  "version": "0.1.1",
+  "description": "MCP server for AUREON Financial Compass: Financial Compass capital context for AI agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "aureon-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test tests/**/*.test.ts",
+    "test:e2e": "tsx tests/e2e-full.mjs",
+    "test:live-agent": "tsx tests/live-agent-exercise.mjs",
+    "verify": "tsx tests/verify-agent.ts"
+  },
+  "keywords": [
+    "aureon",
+    "mcp",
+    "model-context-protocol",
+    "robinhood-chain",
+    "financial-compass",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/buildaureon/aureon-mcp"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@buildaureon/sdk": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "viem": "^2.55.0"
+  }
+}