@buildaureon/mcp 0.1.8 → 0.1.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +81 -0
- package/README.md +487 -401
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/docs/agent-guide.md +652 -652
- package/docs/architecture.md +384 -377
- package/docs/auth.md +361 -351
- package/docs/security.md +335 -335
- package/docs/setup.md +406 -347
- package/docs/tools.md +767 -765
- package/examples/claude-desktop.json +11 -11
- package/examples/cursor.hosted.mcp.json +7 -0
- package/examples/cursor.hosted.user.mcp.json +10 -0
- package/examples/cursor.mcp.json +11 -11
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,401 +1,487 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# Aureon MCP
|
|
4
|
-
|
|
5
|
-
**The Financial Intelligence Layer for Onchain AI Agents**
|
|
6
|
-
|
|
7
|
-
Official [Model Context Protocol](https://modelcontextprotocol.io) server for the AUREON Financial Compass.
|
|
8
|
-
Exposes the full `@buildaureon/sdk` surface as tools for Cursor, Claude Desktop, and any MCP host on the Robinhood Chain.
|
|
9
|
-
|
|
10
|
-
<br />
|
|
11
|
-
|
|
12
|
-
[](https://www.typescriptlang.org/)
|
|
13
|
-
[![MCP](https://img.shields.io/badge/Protocol-
|
|
14
|
-
[ server for the AUREON Financial Compass.
|
|
8
|
+
Exposes the full `@buildaureon/sdk` surface as tools for Cursor, Claude Desktop, and any MCP host on the Robinhood Chain.
|
|
9
|
+
|
|
10
|
+
<br />
|
|
11
|
+
|
|
12
|
+
[](https://www.typescriptlang.org/)
|
|
13
|
+
[](https://modelcontextprotocol.io)
|
|
14
|
+
[](https://mcp.aureonlabs.network/mcp)
|
|
15
|
+
[](https://github.com/buildaureon)
|
|
16
|
+
[](LICENSE)
|
|
17
|
+
[](#requirements--installation)
|
|
18
|
+
|
|
19
|
+
<br />
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
# Hosted (no local process)
|
|
23
|
+
https://mcp.aureonlabs.network/mcp
|
|
24
|
+
|
|
25
|
+
# Or local stdio
|
|
26
|
+
npx -y @buildaureon/mcp
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
[How to connect](#how-to-connect) · [Quickstart](#quickstart) · [Architecture](#architecture) · [Authentication](#authentication) · [Tool Surface](#tool-surface) · [Agent Workflows](#agent-workflows) · [Docs](#documentation-registry)
|
|
30
|
+
|
|
31
|
+
</div>
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Table of Contents
|
|
36
|
+
|
|
37
|
+
1. [What is AUREON MCP?](#what-is-aureon-mcp)
|
|
38
|
+
2. [How to connect](#how-to-connect)
|
|
39
|
+
3. [Why AUREON MCP?](#why-aureon-mcp)
|
|
40
|
+
4. [Requirements & Installation](#requirements--installation)
|
|
41
|
+
5. [Architecture](#architecture)
|
|
42
|
+
6. [Quickstart](#quickstart)
|
|
43
|
+
7. [Authentication](#authentication)
|
|
44
|
+
8. [Tool Surface](#tool-surface)
|
|
45
|
+
9. [Agent Workflows](#agent-workflows)
|
|
46
|
+
10. [Sample Agent Prompts](#sample-agent-prompts)
|
|
47
|
+
11. [Security Model](#security-model)
|
|
48
|
+
12. [Development](#development)
|
|
49
|
+
13. [Documentation Registry](#documentation-registry)
|
|
50
|
+
14. [FAQ](#faq)
|
|
51
|
+
15. [Community & License](#community)
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## What is AUREON MCP?
|
|
56
|
+
|
|
57
|
+
**AUREON** is a policy and execution layer for capital on **Robinhood Chain**. Agents register continuous financial rules (Financial Compass Objectives), monitor health, and restore allocations with honest settlement receipts rather than one-off swaps that forget intent.
|
|
58
|
+
|
|
59
|
+
**`@buildaureon/mcp`** is the agent adapter. It maps every public `@buildaureon/sdk` client method to a named tool (`aureon_ping`, `aureon_create_objective`, `aureon_restore_objective`, …). You can reach that same 54-tool surface in two ways:
|
|
60
|
+
|
|
61
|
+
| Transport | When to use it | How |
|
|
62
|
+
| --- | --- | --- |
|
|
63
|
+
| **Hosted HTTP** | Fastest path. No Node process on your machine. | Point the host at `https://mcp.aureonlabs.network/mcp` |
|
|
64
|
+
| **Local stdio** | You want your own issued API key in the host env. | `npx -y @buildaureon/mcp` |
|
|
65
|
+
|
|
66
|
+
The npm package is the stdio server. The official hosted process is Streamable HTTP at `/mcp` (see `hostedMCP/` in this monorepo). Both call `https://api.aureonlabs.network`. Neither holds a wallet private key. Neither signs or broadcasts.
|
|
67
|
+
|
|
68
|
+
| You can | Through |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| Authenticate with an issued developer API key | `AUREON_API_KEY` env (recommended) |
|
|
71
|
+
| Optionally complete a wallet Bearer handshake | `aureon_get_auth_nonce` → sign → `aureon_verify_wallet` |
|
|
72
|
+
| Sync and manage the Capital Book | `aureon_sync_portfolio`, `aureon_set_portfolio`, `aureon_clear_portfolio` |
|
|
73
|
+
| Create and query Financial Compass objectives | `aureon_create_objective`, `aureon_list_objectives`, … |
|
|
74
|
+
| Read health, timeline, vault, executions | `aureon_get_health`, `aureon_list_timeline`, `aureon_get_vault`, … |
|
|
75
|
+
| Prepare non-custodial vault deposit / withdraw steps | `aureon_prepare_vault_deposit`, `aureon_prepare_vault_withdraw` |
|
|
76
|
+
| Fetch and execute restore plans | `aureon_get_restore_plan`, `aureon_restore_objective` |
|
|
77
|
+
| Rehearse market shocks | `aureon_apply_market_event`, `aureon_refresh_watchdog` |
|
|
78
|
+
| Manage developer API keys | `aureon_list_api_keys`, `aureon_create_api_key`, … |
|
|
79
|
+
|
|
80
|
+
**54 tools**: one per public `AureonClient` method. Full schemas: [docs/tools.md](docs/tools.md).
|
|
81
|
+
|
|
82
|
+
For scripts without MCP, use [`@buildaureon/sdk`](https://github.com/buildaureon/aureon-sdk). The operator app at [app.aureonlabs.network](https://app.aureonlabs.network) stays wallet-Bearer only. Public Living Capital is still the testnet console. SDK and MCP default to mainnet.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## How to connect
|
|
87
|
+
|
|
88
|
+
### Hosted (recommended first use)
|
|
89
|
+
|
|
90
|
+
Paste this into Cursor `.cursor/mcp.json`. A user key is not required to connect.
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"aureon": {
|
|
96
|
+
"url": "https://mcp.aureonlabs.network/mcp"
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Open without a key: `aureon_ping`, `aureon_list_market_presets`, `aureon_validate_receipt`.
|
|
103
|
+
|
|
104
|
+
Wallet tools need **your** issued Developers key on the same URL:
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"mcpServers": {
|
|
109
|
+
"aureon": {
|
|
110
|
+
"url": "https://mcp.aureonlabs.network/mcp",
|
|
111
|
+
"headers": {
|
|
112
|
+
"X-Aureon-Api-Key": "<issued-developer-api-key>"
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Templates: [`examples/cursor.hosted.mcp.json`](examples/cursor.hosted.mcp.json), [`examples/cursor.hosted.user.mcp.json`](examples/cursor.hosted.user.mcp.json).
|
|
120
|
+
|
|
121
|
+
Confirm the host is up: [https://mcp.aureonlabs.network/healthz](https://mcp.aureonlabs.network/healthz).
|
|
122
|
+
|
|
123
|
+
Restart Cursor. Ask: *“Ping AUREON with aureon_ping.”* For `aureon_me` and the rest of your book, add the header or use stdio.
|
|
124
|
+
|
|
125
|
+
### Local stdio (your key)
|
|
126
|
+
|
|
127
|
+
```json
|
|
128
|
+
{
|
|
129
|
+
"mcpServers": {
|
|
130
|
+
"aureon": {
|
|
131
|
+
"command": "npx",
|
|
132
|
+
"args": ["-y", "@buildaureon/mcp"],
|
|
133
|
+
"env": {
|
|
134
|
+
"AUREON_API_KEY": "<issued-developer-api-key>"
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Issue the key at [app.aureonlabs.network](https://app.aureonlabs.network) → **Developers**. Template: [`examples/cursor.mcp.json`](examples/cursor.mcp.json).
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Why AUREON MCP?
|
|
146
|
+
|
|
147
|
+
Traditional AI trading scripts execute isolated market orders without context, forgetting target allocations as soon as a prompt ends. **AUREON MCP** provides a persistent financial compass for your AI agents:
|
|
148
|
+
|
|
149
|
+
* **Continuous Rules vs. One-off Swaps**: Instead of telling an agent to "buy 0.5 WETH," you register a Financial Compass Objective like *"Maintain 20% WETH weight with 3% tolerance."* The watchdog automatically monitors drift and plans restores when needed.
|
|
150
|
+
* **Non-Custodial Architecture**: Your private keys stay safely in your local wallet host. The MCP server generates unsigned transaction payloads that you review and sign.
|
|
151
|
+
* **Two transports, one tool surface**: Hosted HTTP at `https://mcp.aureonlabs.network/mcp`, or local stdio via `npx -y @buildaureon/mcp`. Same 54 tools. No local database to run.
|
|
152
|
+
* **Honest Settlement Receipts**: Clearly distinguishes between on-chain smart vault settlements (`vault`) and ledger-local staged receipts (`staged`).
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Requirements & Installation
|
|
157
|
+
|
|
158
|
+
### Requirements
|
|
159
|
+
|
|
160
|
+
- **Node.js**: 20 or higher (ESM compatible)
|
|
161
|
+
- **Developer API Key**: Issued at [app.aureonlabs.network](https://app.aureonlabs.network) → **Developers**. Public Living Capital is still the testnet console. SDK and MCP default to mainnet.
|
|
162
|
+
- **Network Access**: Default official API `https://api.aureonlabs.network` on mainnet. Optional `AUREON_NETWORK=testnet` stays on testnet on the same host.
|
|
163
|
+
|
|
164
|
+
### Installation
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
# Using pnpm
|
|
168
|
+
pnpm add @buildaureon/mcp
|
|
169
|
+
|
|
170
|
+
# Using npm
|
|
171
|
+
npm install @buildaureon/mcp
|
|
172
|
+
|
|
173
|
+
# Or run instantly via npx without installing
|
|
174
|
+
npx -y @buildaureon/mcp
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
You do not need to clone the AUREON monorepo: only the package and an issued key for the network you will call.
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## Architecture
|
|
182
|
+
|
|
183
|
+
```mermaid
|
|
184
|
+
flowchart LR
|
|
185
|
+
Host[Cursor / Claude / other MCP host]
|
|
186
|
+
Host -->|Streamable HTTP| Hosted["https://mcp.aureonlabs.network/mcp"]
|
|
187
|
+
Host -->|stdio| Local["npx @buildaureon/mcp"]
|
|
188
|
+
Hosted --> SDK["@buildaureon/sdk"]
|
|
189
|
+
Local --> SDK
|
|
190
|
+
SDK -->|default| Official[api.aureonlabs.network / mainnet]
|
|
191
|
+
SDK -->|AUREON_NETWORK=testnet| Test[api.aureonlabs.network / testnet]
|
|
192
|
+
Official --> VaultMN[Smart Vault mainnet]
|
|
193
|
+
Test --> VaultTN[Smart Vault testnet]
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Surface & Ownership Breakdown
|
|
197
|
+
|
|
198
|
+
| Surface | Auth | Role |
|
|
199
|
+
| --- | --- | --- |
|
|
200
|
+
| Operator utility | Wallet sign-in (Bearer) | Human operators managing vaults and approving manual restores |
|
|
201
|
+
| `@buildaureon/sdk` | Issued API key (+ optional Bearer) | Automated scripts, bots, serverless routines, and products |
|
|
202
|
+
| `@buildaureon/mcp` (stdio) | Same as SDK via host `env` | Local agent adapter you spawn with your issued key |
|
|
203
|
+
| Hosted MCP | URL-only for open tools. Optional `X-Aureon-Api-Key` for your wallet. | Same 54 tools over `https://mcp.aureonlabs.network/mcp` |
|
|
204
|
+
|
|
205
|
+
### Layer Responsibilities
|
|
206
|
+
|
|
207
|
+
| Concern | Owner | Description |
|
|
208
|
+
| --- | --- | --- |
|
|
209
|
+
| HTTP, retries, types, validation, errors | `@buildaureon/sdk` | Core underlying SDK client managing network communications |
|
|
210
|
+
| Tool names, zod schemas, agent formatting | `@buildaureon/mcp` | MCP server mapping SDK methods to AI-friendly tools |
|
|
211
|
+
| stdio / Streamable HTTP / JSON-RPC | `@modelcontextprotocol/sdk` | Official MCP protocol. Stdio is the npm package. Streamable HTTP is the official hosted process. |
|
|
212
|
+
|
|
213
|
+
**Trust boundary**: The API monitors objectives and generates restore plans; private keys stay strictly on the host machine. MCP never signs chain transactions.
|
|
214
|
+
|
|
215
|
+
Deep dive: [docs/architecture.md](docs/architecture.md).
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Quickstart
|
|
220
|
+
|
|
221
|
+
**Fastest path:** skip the key for now and use the hosted URL in [How to connect](#how-to-connect). The steps below are for **local stdio** with your own issued key.
|
|
222
|
+
|
|
223
|
+
### 1. Create an issued API key
|
|
224
|
+
|
|
225
|
+
Issue the key on the **same** API this MCP process will call:
|
|
226
|
+
|
|
227
|
+
1. Open https://app.aureonlabs.network → **Developers**.
|
|
228
|
+
2. Create API Key → copy your key once.
|
|
229
|
+
|
|
230
|
+
That key identifies your wallet for control-plane tools. **No Bearer token required.** Issue the key on the official API this process will call.
|
|
231
|
+
|
|
232
|
+
### 2. Configure Cursor IDE (local stdio)
|
|
233
|
+
|
|
234
|
+
If you already added the hosted URL, you do not need this block. For your own key, copy [`examples/cursor.mcp.json`](examples/cursor.mcp.json) into `.cursor/mcp.json`:
|
|
235
|
+
|
|
236
|
+
```json
|
|
237
|
+
{
|
|
238
|
+
"mcpServers": {
|
|
239
|
+
"aureon": {
|
|
240
|
+
"command": "npx",
|
|
241
|
+
"args": ["-y", "@buildaureon/mcp"],
|
|
242
|
+
"env": {
|
|
243
|
+
"AUREON_API_KEY": "<issued-developer-api-key>"
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Restart Cursor. Open the AI chat panel and ask: *“Ping AUREON and show my wallet with aureon_me.”*
|
|
251
|
+
|
|
252
|
+
### 3. Configure Claude Desktop
|
|
253
|
+
|
|
254
|
+
Merge [`examples/claude-desktop.json`](examples/claude-desktop.json) into Claude Desktop's configuration file:
|
|
255
|
+
|
|
256
|
+
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
257
|
+
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
258
|
+
|
|
259
|
+
```json
|
|
260
|
+
{
|
|
261
|
+
"mcpServers": {
|
|
262
|
+
"aureon": {
|
|
263
|
+
"command": "npx",
|
|
264
|
+
"args": ["-y", "@buildaureon/mcp"],
|
|
265
|
+
"env": {
|
|
266
|
+
"AUREON_API_KEY": "<issued-developer-api-key>"
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
Restart Claude Desktop and test the connection.
|
|
274
|
+
|
|
275
|
+
### 4. From a local clone (maintainers)
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
pnpm install
|
|
279
|
+
pnpm --filter @buildaureon/mcp build
|
|
280
|
+
pnpm --filter @buildaureon/mcp start
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
Point the host `command` / `args` at the built `dist/index.js`. See [docs/setup.md](docs/setup.md).
|
|
284
|
+
|
|
285
|
+
---
|
|
286
|
+
|
|
287
|
+
## Authentication
|
|
288
|
+
|
|
289
|
+
### Recommended: Issued API key
|
|
290
|
+
|
|
291
|
+
| Variable | Required | Role |
|
|
292
|
+
| --- | --- | --- |
|
|
293
|
+
| `AUREON_API_KEY` | Yes (recommended) | Issued developer key for product access **and** wallet identity |
|
|
294
|
+
| `AUREON_NETWORK` | No | Omit for official API / mainnet. Set `testnet` to stay on testnet. |
|
|
295
|
+
| `AUREON_API_URL` | No | Optional override of `https://api.aureonlabs.network`. |
|
|
296
|
+
| `AUREON_AUTH_TOKEN` | No | Optional wallet Bearer (**wins** if both key and Bearer are sent) |
|
|
297
|
+
|
|
298
|
+
**Private Key Boundary**: Private keys are only needed outside MCP when signing and broadcasting deposit or withdrawal transactions. Prepare tools return unsigned transaction steps; the MCP server never signs.
|
|
299
|
+
|
|
300
|
+
### Optional: Wallet Bearer session
|
|
301
|
+
|
|
302
|
+
Use `aureon_get_auth_nonce` → host wallet signs challenge → `aureon_verify_wallet`. Prefer issued keys for always-on agents.
|
|
303
|
+
|
|
304
|
+
### Preview / Dev Mode only
|
|
305
|
+
|
|
306
|
+
`aureon_dev_login` works only when the API backend has `AUREON_ALLOW_DEV_LOGIN=1` (it does not function on production).
|
|
307
|
+
|
|
308
|
+
Deep dive: [docs/auth.md](docs/auth.md).
|
|
309
|
+
|
|
310
|
+
---
|
|
311
|
+
|
|
312
|
+
## Tool Surface
|
|
313
|
+
|
|
314
|
+
AUREON MCP exposes **54 tools** covering 100% of the `AureonClient` SDK surface:
|
|
315
|
+
|
|
316
|
+
| Category | Count | Tools Included | Primary Purpose |
|
|
317
|
+
| --- | --- | --- | --- |
|
|
318
|
+
| **Health** | 1 | `aureon_ping` | Check API connectivity & backend watchdog state |
|
|
319
|
+
| **Auth** | 5 | `aureon_get_auth_nonce`, `aureon_verify_wallet`, `aureon_dev_login`, `aureon_logout`, `aureon_me` | Manage wallet sessions, challenges, and identity |
|
|
320
|
+
| **Read** | 12 | `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`, `aureon_get_audit_trail` | Inspect portfolio allocations, health scores, timelines, vault state, and the joined audit trail |
|
|
321
|
+
| **Objectives** | 4 | `aureon_create_objective`, `aureon_update_objective`, `aureon_pause_objective`, `aureon_resume_objective` | Create, modify, pause, and resume Financial Compass Objectives |
|
|
322
|
+
| **Portfolio** | 3 | `aureon_set_portfolio`, `aureon_clear_portfolio`, `aureon_sync_portfolio` | Synchronize and manage live Capital Book asset marks |
|
|
323
|
+
| **Execution** | 2 | `aureon_run_execution`, `aureon_restore_objective` | Trigger policy rebalancing and execute objective restore plans |
|
|
324
|
+
| **Market** | 2 | `aureon_apply_market_event`, `aureon_refresh_watchdog` | Rehearse market shocks (e.g. price shifts) against active policy |
|
|
325
|
+
| **Vault** | 2 | `aureon_prepare_vault_deposit`, `aureon_prepare_vault_withdraw` | Generate unsigned steps for non-custodial smart vault deposits/withdrawals |
|
|
326
|
+
| **Developer** | 4 | `aureon_list_api_keys`, `aureon_create_api_key`, `aureon_revoke_api_key`, `aureon_toggle_api_key` | Create, pause, and revoke developer API access keys |
|
|
327
|
+
|
|
328
|
+
Full argument schemas: [docs/tools.md](docs/tools.md) · Playbooks: [docs/agent-guide.md](docs/agent-guide.md).
|
|
329
|
+
|
|
330
|
+
### Locked fields
|
|
331
|
+
|
|
332
|
+
- `targetSymbol` and `automationMode` are set at **create** time and cannot be modified via `aureon_update_objective`: recreate the objective instead.
|
|
333
|
+
- Default `automationMode` is `"auto"`. Use `"manual"` only when a human must Approve changes inside the utility web app.
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
## Agent Workflows
|
|
338
|
+
|
|
339
|
+
Agents perform best when following the **Read → Decide → Act** execution pattern:
|
|
340
|
+
|
|
341
|
+
```mermaid
|
|
342
|
+
flowchart TD
|
|
343
|
+
subgraph Read Phase
|
|
344
|
+
R1[1. aureon_ping] --> R2[2. aureon_me]
|
|
345
|
+
R2 --> R3[3. aureon_sync_portfolio]
|
|
346
|
+
R3 --> R4[4. aureon_get_health]
|
|
347
|
+
end
|
|
348
|
+
|
|
349
|
+
subgraph Decide Phase
|
|
350
|
+
R4 --> D1{Policy Breached?}
|
|
351
|
+
end
|
|
352
|
+
|
|
353
|
+
subgraph Act Phase
|
|
354
|
+
D1 -- Yes --> A1[aureon_get_restore_plan]
|
|
355
|
+
A1 --> A2[aureon_restore_objective]
|
|
356
|
+
A2 --> A3[aureon_list_timeline]
|
|
357
|
+
D1 -- No --> A4[Maintain current positions]
|
|
358
|
+
end
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
### 1. Control-Plane Routine (API Key Only)
|
|
362
|
+
|
|
363
|
+
1. `aureon_ping` → `aureon_me` (Verify connection and wallet identity)
|
|
364
|
+
2. `aureon_sync_portfolio` → `aureon_get_vault_status` (Fetch marks and check vault readiness)
|
|
365
|
+
3. If the vault is empty: `aureon_restore_objective` returns **409**. Call `aureon_prepare_vault_deposit`, return unsigned steps, and wait for the user or host wallet to broadcast. Agents do not fund the vault.
|
|
366
|
+
4. `aureon_create_objective` (`auto`) (Register continuous financial objective)
|
|
367
|
+
5. `aureon_refresh_watchdog` / `aureon_get_health` (Check health score and drift)
|
|
368
|
+
6. On violation after the vault is funded → `aureon_get_restore_plan` → `aureon_restore_objective`
|
|
369
|
+
7. Confirm with `aureon_list_timeline` (Verify settlement receipts)
|
|
370
|
+
|
|
371
|
+
### 2. Vault Deposit Path (API Key + External Signer)
|
|
372
|
+
|
|
373
|
+
1. `aureon_prepare_vault_deposit` → returns unsigned steps
|
|
374
|
+
2. Host wallet signs and broadcasts transaction on Robinhood Chain
|
|
375
|
+
3. `aureon_sync_portfolio` / `aureon_get_vault` (Re-sync marks to reflect new deposit)
|
|
376
|
+
|
|
377
|
+
More playbooks: [docs/agent-guide.md](docs/agent-guide.md).
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
381
|
+
## Sample Agent Prompts
|
|
382
|
+
|
|
383
|
+
Copy and paste these example prompts into Cursor or Claude Desktop:
|
|
384
|
+
|
|
385
|
+
### Portfolio Audit
|
|
386
|
+
> *"Ping AUREON, verify my wallet address with aureon_me, sync my portfolio, and give me a summary of total AUM and active objective health."*
|
|
387
|
+
|
|
388
|
+
### Setting a Compass Objective
|
|
389
|
+
> *"Create an automatic Financial Compass Objective named 'Maintain 20% WETH' targeting symbol WETH with weight 0.20 and tolerance 0.03."*
|
|
390
|
+
|
|
391
|
+
### Monitoring & Drift Restoration
|
|
392
|
+
> *"Refresh the watchdog and inspect my AUREON health. If any objective is in breach, show me the restore plan and run aureon_restore_objective."*
|
|
393
|
+
|
|
394
|
+
### Deposit Preparation
|
|
395
|
+
> *"Prepare an unsigned vault deposit for 0.1 ETH. Return the exact step payload so I can review and sign it in my wallet."*
|
|
396
|
+
|
|
397
|
+
---
|
|
398
|
+
|
|
399
|
+
## Security Model
|
|
400
|
+
|
|
401
|
+
* **Official hosted vs your own process**: Use `https://mcp.aureonlabs.network/mcp` for the official Streamable HTTP host. Local stdio is a child process of Cursor or Claude — do not publish **your** stdio server as an open internet socket. Do not put a wallet private key in either transport.
|
|
402
|
+
* **API Key Protection**: Treat `AUREON_API_KEY` like a password. Pause, revoke, or rotate keys in the Developer dashboard if compromised.
|
|
403
|
+
* **Environment Hygiene**: Never commit keys to version control. Never put wallet private keys into MCP environment variables.
|
|
404
|
+
* **Prompt Safety**: Review agent prompts before enabling write tools in untrusted or multi-user chat channels.
|
|
405
|
+
|
|
406
|
+
Deep dive details: [docs/security.md](docs/security.md).
|
|
407
|
+
|
|
408
|
+
---
|
|
409
|
+
|
|
410
|
+
## Development
|
|
411
|
+
|
|
412
|
+
To build and test `@buildaureon/mcp` locally:
|
|
413
|
+
|
|
414
|
+
```bash
|
|
415
|
+
pnpm install
|
|
416
|
+
pnpm --filter @buildaureon/mcp build
|
|
417
|
+
pnpm --filter @buildaureon/mcp test
|
|
418
|
+
pnpm --filter @buildaureon/mcp typecheck
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
### Script Reference
|
|
422
|
+
|
|
423
|
+
| Script | Purpose | Description |
|
|
424
|
+
| --- | --- | --- |
|
|
425
|
+
| `build` | `tsup` → `dist/` | Bundles TypeScript source into distribution ESM output |
|
|
426
|
+
| `dev` | `tsx src/index.ts` | Runs server directly from source for local development |
|
|
427
|
+
| `start` | `node dist/index.js` | Runs compiled distribution binary |
|
|
428
|
+
| `test` | `tsx --test ...` | Runs unit, smoke, and integration test suites |
|
|
429
|
+
| `typecheck` | `tsc --noEmit` | Validates TypeScript types across source files |
|
|
430
|
+
|
|
431
|
+
---
|
|
432
|
+
|
|
433
|
+
## Documentation Registry
|
|
434
|
+
|
|
435
|
+
| Document | Description & Contents |
|
|
436
|
+
| --- | --- |
|
|
437
|
+
| **[Setup Guide](docs/setup.md)** | Hosted URL first, then Cursor / Claude stdio, npx, source build, troubleshooting |
|
|
438
|
+
| **[Authentication Guide](docs/auth.md)** | Issued API key vs. Wallet Bearer vs. private key boundaries |
|
|
439
|
+
| **[Tools Reference](docs/tools.md)** | Full 54-tool reference with arguments, schemas, and caveats |
|
|
440
|
+
| **[Agent Playbooks](docs/agent-guide.md)** | End-to-end agent decision playbooks, turn templates, and anti-patterns |
|
|
441
|
+
| **[Architecture Deep Dive](docs/architecture.md)** | Module boundaries, file maps, and end-to-end request data flows |
|
|
442
|
+
| **[Security Model](docs/security.md)** | Credential management, threat modeling, and operational safety |
|
|
443
|
+
| **[Changelog](CHANGELOG.md)** | Published versions, including 0.1.10 mainnet default and hosted URL docs |
|
|
444
|
+
| **[`examples/cursor.hosted.mcp.json`](examples/cursor.hosted.mcp.json)** | Cursor config for URL-only hosted MCP |
|
|
445
|
+
| **[`examples/cursor.hosted.user.mcp.json`](examples/cursor.hosted.user.mcp.json)** | Same URL plus `X-Aureon-Api-Key` for your wallet tools |
|
|
446
|
+
| **[`@buildaureon/sdk`](https://github.com/buildaureon/aureon-sdk)** | Core TypeScript SDK documentation, types, and error definitions |
|
|
447
|
+
|
|
448
|
+
---
|
|
449
|
+
|
|
450
|
+
## FAQ
|
|
451
|
+
|
|
452
|
+
**Do I need a private key in Cursor or Claude env?**
|
|
453
|
+
No. You only need an issued `AUREON_API_KEY`. Private keys stay in your host wallet when signing prepare steps.
|
|
454
|
+
|
|
455
|
+
**Is there only stdio?**
|
|
456
|
+
No. Official hosted MCP is `https://mcp.aureonlabs.network/mcp` (Streamable HTTP, 54 tools). Connect with the URL alone for ping. Add `X-Aureon-Api-Key` for your wallet tools. Local stdio is `npx -y @buildaureon/mcp` with your issued `AUREON_API_KEY`.
|
|
457
|
+
|
|
458
|
+
**Does MCP talk to a local backend server?**
|
|
459
|
+
No. Both transports call the official API `https://api.aureonlabs.network` on mainnet by default. Set `AUREON_NETWORK=testnet` on a **stdio** process to stay on testnet on that same host.
|
|
460
|
+
|
|
461
|
+
**Why did my restore receipt say `staged`?**
|
|
462
|
+
`staged` is a ledger-local receipt, not an on-chain vault settlement. Always describe settlement receipts accurately in agent responses.
|
|
463
|
+
|
|
464
|
+
**Can agents use Manual automation mode?**
|
|
465
|
+
Prefer Automatic (`auto`). Manual mode requires human Approval inside the operator utility app.
|
|
466
|
+
|
|
467
|
+
**What happens if an objective breaches its drift tolerance?**
|
|
468
|
+
The watchdog marks health as breached. Agents call `aureon_get_restore_plan` to inspect the rebalancing steps, then `aureon_restore_objective` to execute the restore.
|
|
469
|
+
|
|
470
|
+
**How does MCP handle network errors or disconnects?**
|
|
471
|
+
The underlying `@buildaureon/sdk` handles HTTP retries and reports structured error objects with stable error codes back to the MCP host.
|
|
472
|
+
|
|
473
|
+
---
|
|
474
|
+
|
|
475
|
+
## Community
|
|
476
|
+
|
|
477
|
+
- **Website**: https://www.aureonlabs.network
|
|
478
|
+
- **Hosted MCP**: https://mcp.aureonlabs.network/mcp
|
|
479
|
+
- **Hosted health**: https://mcp.aureonlabs.network/healthz
|
|
480
|
+
- **X (Twitter)**: https://x.com/buildaureon
|
|
481
|
+
- **App Utility**: https://app.aureonlabs.network
|
|
482
|
+
- **MCP repo**: https://github.com/buildaureon/aureon-mcp
|
|
483
|
+
- **SDK repo**: https://github.com/buildaureon/aureon-sdk
|
|
484
|
+
|
|
485
|
+
## License
|
|
486
|
+
|
|
487
|
+
MIT (see [LICENSE](LICENSE)).
|