@buildaureon/mcp 0.1.8 → 0.1.9
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 +62 -0
- package/README.md +402 -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 +377 -377
- package/docs/auth.md +351 -351
- package/docs/security.md +335 -335
- package/docs/setup.md +347 -347
- package/docs/tools.md +765 -765
- package/examples/claude-desktop.json +11 -11
- package/examples/cursor.mcp.json +11 -11
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,401 +1,402 @@
|
|
|
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
|
-
[](https://modelcontextprotocol.io)
|
|
14
|
-
[](LICENSE)
|
|
16
|
-
[](#requirements--installation)
|
|
17
|
-
|
|
18
|
-
<br />
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
npx -y @buildaureon/mcp
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
[Quickstart](#quickstart) · [Architecture](#architecture) · [Authentication](#authentication) · [Tool Surface](#tool-surface) · [Agent Workflows](#agent-workflows) · [Docs](#documentation-registry)
|
|
25
|
-
|
|
26
|
-
</div>
|
|
27
|
-
|
|
28
|
-
---
|
|
29
|
-
|
|
30
|
-
## Table of Contents
|
|
31
|
-
|
|
32
|
-
1. [What is AUREON MCP?](#what-is-aureon-mcp)
|
|
33
|
-
2. [Why AUREON MCP?](#why-aureon-mcp)
|
|
34
|
-
3. [Requirements & Installation](#requirements--installation)
|
|
35
|
-
4. [Architecture](#architecture)
|
|
36
|
-
5. [Quickstart](#quickstart)
|
|
37
|
-
6. [Authentication](#authentication)
|
|
38
|
-
7. [Tool Surface](#tool-surface)
|
|
39
|
-
8. [Agent Workflows](#agent-workflows)
|
|
40
|
-
9. [Sample Agent Prompts](#sample-agent-prompts)
|
|
41
|
-
10. [Security Model](#security-model)
|
|
42
|
-
11. [Development](#development)
|
|
43
|
-
12. [Documentation Registry](#documentation-registry)
|
|
44
|
-
13. [FAQ](#faq)
|
|
45
|
-
14. [Community & License](#community)
|
|
46
|
-
|
|
47
|
-
---
|
|
48
|
-
|
|
49
|
-
## What is AUREON MCP?
|
|
50
|
-
|
|
51
|
-
**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.
|
|
52
|
-
|
|
53
|
-
**`@buildaureon/mcp`** is the agent adapter. It runs as a local **stdio** MCP server and maps every public `@buildaureon/sdk` client method to a named tool (`aureon_ping`, `aureon_create_objective`, `aureon_restore_objective`, …).
|
|
54
|
-
|
|
55
|
-
| You can | Through |
|
|
56
|
-
| --- | --- |
|
|
57
|
-
| Authenticate with an issued developer API key | `AUREON_API_KEY` env (recommended) |
|
|
58
|
-
| Optionally complete a wallet Bearer handshake | `aureon_get_auth_nonce` → sign → `aureon_verify_wallet` |
|
|
59
|
-
| Sync and manage the Capital Book | `aureon_sync_portfolio`, `aureon_set_portfolio`, `aureon_clear_portfolio` |
|
|
60
|
-
| Create and query Financial Compass objectives | `aureon_create_objective`, `aureon_list_objectives`, … |
|
|
61
|
-
| Read health, timeline, vault, executions | `aureon_get_health`, `aureon_list_timeline`, `aureon_get_vault`, … |
|
|
62
|
-
| Prepare non-custodial vault deposit / withdraw steps | `aureon_prepare_vault_deposit`, `aureon_prepare_vault_withdraw` |
|
|
63
|
-
| Fetch and execute restore plans | `aureon_get_restore_plan`, `aureon_restore_objective` |
|
|
64
|
-
| Rehearse market shocks | `aureon_apply_market_event`, `aureon_refresh_watchdog` |
|
|
65
|
-
| Manage developer API keys | `aureon_list_api_keys`, `aureon_create_api_key`, … |
|
|
66
|
-
|
|
67
|
-
**54 tools**: one per public `AureonClient` method. Full schemas: [docs/tools.md](docs/tools.md).
|
|
68
|
-
|
|
69
|
-
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.
|
|
70
|
-
|
|
71
|
-
---
|
|
72
|
-
|
|
73
|
-
## Why AUREON MCP?
|
|
74
|
-
|
|
75
|
-
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:
|
|
76
|
-
|
|
77
|
-
* **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.
|
|
78
|
-
* **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.
|
|
79
|
-
* **Zero Infrastructure Overhead**: Standard I/O transport (`stdio`) means no local database, Docker containers, or background services to manage.
|
|
80
|
-
* **Honest Settlement Receipts**: Clearly distinguishes between on-chain smart vault settlements (`vault`) and ledger-staged
|
|
81
|
-
|
|
82
|
-
---
|
|
83
|
-
|
|
84
|
-
## Requirements & Installation
|
|
85
|
-
|
|
86
|
-
### Requirements
|
|
87
|
-
|
|
88
|
-
- **Node.js**: 20 or higher (ESM compatible)
|
|
89
|
-
- **Developer API Key**: Issued
|
|
90
|
-
- **Network Access**: Default
|
|
91
|
-
|
|
92
|
-
### Installation
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
# Using pnpm
|
|
96
|
-
pnpm add @buildaureon/mcp
|
|
97
|
-
|
|
98
|
-
# Using npm
|
|
99
|
-
npm install @buildaureon/mcp
|
|
100
|
-
|
|
101
|
-
# Or run instantly via npx without installing
|
|
102
|
-
npx -y @buildaureon/mcp
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
You do not need to clone the AUREON monorepo: only the package and an issued key for the network you will call.
|
|
106
|
-
|
|
107
|
-
---
|
|
108
|
-
|
|
109
|
-
## Architecture
|
|
110
|
-
|
|
111
|
-
```mermaid
|
|
112
|
-
flowchart LR
|
|
113
|
-
Agent[Cursor / Claude] -->|stdio MCP| MCP["@buildaureon/mcp"]
|
|
114
|
-
MCP --> SDK["@buildaureon/sdk"]
|
|
115
|
-
SDK -->|default|
|
|
116
|
-
SDK -->|AUREON_NETWORK=
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
### Surface & Ownership Breakdown
|
|
122
|
-
|
|
123
|
-
| Surface | Auth | Role |
|
|
124
|
-
| --- | --- | --- |
|
|
125
|
-
| Operator utility | Wallet sign-in (Bearer) | Human operators managing vaults and approving manual restores |
|
|
126
|
-
| `@buildaureon/sdk` | Issued API key (+ optional Bearer) | Automated scripts, bots, serverless routines, and products |
|
|
127
|
-
| `@buildaureon/mcp` | Same as SDK via host `env` | AI agents operating inside Cursor, Claude Desktop, or custom MCP hosts |
|
|
128
|
-
|
|
129
|
-
### Layer Responsibilities
|
|
130
|
-
|
|
131
|
-
| Concern | Owner | Description |
|
|
132
|
-
| --- | --- | --- |
|
|
133
|
-
| HTTP, retries, types, validation, errors | `@buildaureon/sdk` | Core underlying SDK client managing network communications |
|
|
134
|
-
| Tool names, zod schemas, agent formatting | `@buildaureon/mcp` | MCP server mapping SDK methods to AI-friendly tools |
|
|
135
|
-
| stdio / JSON-RPC protocol | `@modelcontextprotocol/sdk` | Official MCP protocol framework for inter-process communication |
|
|
136
|
-
|
|
137
|
-
**Trust boundary**: The API monitors objectives and generates restore plans; private keys stay strictly on the host machine. MCP never signs chain transactions.
|
|
138
|
-
|
|
139
|
-
Deep dive: [docs/architecture.md](docs/architecture.md).
|
|
140
|
-
|
|
141
|
-
---
|
|
142
|
-
|
|
143
|
-
## Quickstart
|
|
144
|
-
|
|
145
|
-
Get your AI agent running with AUREON MCP in 4 easy steps:
|
|
146
|
-
|
|
147
|
-
### 1. Create an issued API key
|
|
148
|
-
|
|
149
|
-
Issue the key on the **same** API this MCP process will call:
|
|
150
|
-
|
|
151
|
-
1.
|
|
152
|
-
2.
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
{
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
"
|
|
166
|
-
"
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
* **
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
{
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
"
|
|
189
|
-
"
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
pnpm
|
|
204
|
-
pnpm --filter @buildaureon/mcp
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
|
217
|
-
|
|
|
218
|
-
| `
|
|
219
|
-
| `
|
|
220
|
-
| `
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
|
242
|
-
|
|
|
243
|
-
| **
|
|
244
|
-
| **
|
|
245
|
-
| **
|
|
246
|
-
| **
|
|
247
|
-
| **
|
|
248
|
-
| **
|
|
249
|
-
| **
|
|
250
|
-
| **
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
### 2. Vault Deposit Path (API Key + External Signer)
|
|
296
|
-
|
|
297
|
-
1. `aureon_prepare_vault_deposit` → returns unsigned steps
|
|
298
|
-
2. Host wallet signs and broadcasts transaction on Robinhood Chain
|
|
299
|
-
3. `aureon_sync_portfolio` / `aureon_get_vault` (Re-sync marks to reflect new deposit)
|
|
300
|
-
|
|
301
|
-
More playbooks: [docs/agent-guide.md](docs/agent-guide.md).
|
|
302
|
-
|
|
303
|
-
---
|
|
304
|
-
|
|
305
|
-
## Sample Agent Prompts
|
|
306
|
-
|
|
307
|
-
Copy and paste these example prompts into Cursor or Claude Desktop:
|
|
308
|
-
|
|
309
|
-
### Portfolio Audit
|
|
310
|
-
> *"Ping AUREON, verify my wallet address with aureon_me, sync my portfolio, and give me a summary of total AUM and active objective health."*
|
|
311
|
-
|
|
312
|
-
### Setting a Compass Objective
|
|
313
|
-
> *"Create an automatic Financial Compass Objective named 'Maintain 20% WETH' targeting symbol WETH with weight 0.20 and tolerance 0.03."*
|
|
314
|
-
|
|
315
|
-
### Monitoring & Drift Restoration
|
|
316
|
-
> *"Refresh the watchdog and inspect my AUREON health. If any objective is in breach, show me the restore plan and run aureon_restore_objective."*
|
|
317
|
-
|
|
318
|
-
### Deposit Preparation
|
|
319
|
-
> *"Prepare an unsigned vault deposit for 0.1 ETH. Return the exact step payload so I can review and sign it in my wallet."*
|
|
320
|
-
|
|
321
|
-
---
|
|
322
|
-
|
|
323
|
-
## Security Model
|
|
324
|
-
|
|
325
|
-
* **Local stdio Isolation**: Run MCP **locally over stdio** only; do not expose standard I/O sockets on the public internet.
|
|
326
|
-
* **API Key Protection**: Treat `AUREON_API_KEY` like a password. Pause, revoke, or rotate keys in the Developer dashboard if compromised.
|
|
327
|
-
* **Environment Hygiene**: Never commit keys to version control. Never put wallet private keys into MCP environment variables.
|
|
328
|
-
* **Prompt Safety**: Review agent prompts before enabling write tools in untrusted or multi-user chat channels.
|
|
329
|
-
|
|
330
|
-
Deep dive details: [docs/security.md](docs/security.md).
|
|
331
|
-
|
|
332
|
-
---
|
|
333
|
-
|
|
334
|
-
## Development
|
|
335
|
-
|
|
336
|
-
To build and test `@buildaureon/mcp` locally:
|
|
337
|
-
|
|
338
|
-
```bash
|
|
339
|
-
pnpm install
|
|
340
|
-
pnpm --filter @buildaureon/mcp build
|
|
341
|
-
pnpm --filter @buildaureon/mcp test
|
|
342
|
-
pnpm --filter @buildaureon/mcp typecheck
|
|
343
|
-
```
|
|
344
|
-
|
|
345
|
-
### Script Reference
|
|
346
|
-
|
|
347
|
-
| Script | Purpose | Description |
|
|
348
|
-
| --- | --- | --- |
|
|
349
|
-
| `build` | `tsup` → `dist/` | Bundles TypeScript source into distribution ESM output |
|
|
350
|
-
| `dev` | `tsx src/index.ts` | Runs server directly from source for local development |
|
|
351
|
-
| `start` | `node dist/index.js` | Runs compiled distribution binary |
|
|
352
|
-
| `test` | `tsx --test ...` | Runs unit, smoke, and integration test suites |
|
|
353
|
-
| `typecheck` | `tsc --noEmit` | Validates TypeScript types across source files |
|
|
354
|
-
|
|
355
|
-
---
|
|
356
|
-
|
|
357
|
-
## Documentation Registry
|
|
358
|
-
|
|
359
|
-
| Document | Description & Contents |
|
|
360
|
-
| --- | --- |
|
|
361
|
-
| **[Setup Guide](docs/setup.md)** | Step-by-step setup for Cursor, Claude Desktop, npx, building from source, and troubleshooting |
|
|
362
|
-
| **[Authentication Guide](docs/auth.md)** | Issued API key vs. Wallet Bearer vs. private key boundaries |
|
|
363
|
-
| **[Tools Reference](docs/tools.md)** | Full
|
|
364
|
-
| **[Agent Playbooks](docs/agent-guide.md)** | End-to-end agent decision playbooks, turn templates, and anti-patterns |
|
|
365
|
-
| **[Architecture Deep Dive](docs/architecture.md)** | Module boundaries, file maps, and end-to-end request data flows |
|
|
366
|
-
| **[Security Model](docs/security.md)** | Credential management, threat modeling, and operational safety |
|
|
367
|
-
| **[
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
- **
|
|
397
|
-
- **
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
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
|
+
[](https://modelcontextprotocol.io)
|
|
14
|
+
[](https://github.com/buildaureon)
|
|
15
|
+
[](LICENSE)
|
|
16
|
+
[](#requirements--installation)
|
|
17
|
+
|
|
18
|
+
<br />
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npx -y @buildaureon/mcp
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
[Quickstart](#quickstart) · [Architecture](#architecture) · [Authentication](#authentication) · [Tool Surface](#tool-surface) · [Agent Workflows](#agent-workflows) · [Docs](#documentation-registry)
|
|
25
|
+
|
|
26
|
+
</div>
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Table of Contents
|
|
31
|
+
|
|
32
|
+
1. [What is AUREON MCP?](#what-is-aureon-mcp)
|
|
33
|
+
2. [Why AUREON MCP?](#why-aureon-mcp)
|
|
34
|
+
3. [Requirements & Installation](#requirements--installation)
|
|
35
|
+
4. [Architecture](#architecture)
|
|
36
|
+
5. [Quickstart](#quickstart)
|
|
37
|
+
6. [Authentication](#authentication)
|
|
38
|
+
7. [Tool Surface](#tool-surface)
|
|
39
|
+
8. [Agent Workflows](#agent-workflows)
|
|
40
|
+
9. [Sample Agent Prompts](#sample-agent-prompts)
|
|
41
|
+
10. [Security Model](#security-model)
|
|
42
|
+
11. [Development](#development)
|
|
43
|
+
12. [Documentation Registry](#documentation-registry)
|
|
44
|
+
13. [FAQ](#faq)
|
|
45
|
+
14. [Community & License](#community)
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## What is AUREON MCP?
|
|
50
|
+
|
|
51
|
+
**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.
|
|
52
|
+
|
|
53
|
+
**`@buildaureon/mcp`** is the agent adapter. It runs as a local **stdio** MCP server and maps every public `@buildaureon/sdk` client method to a named tool (`aureon_ping`, `aureon_create_objective`, `aureon_restore_objective`, …).
|
|
54
|
+
|
|
55
|
+
| You can | Through |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| Authenticate with an issued developer API key | `AUREON_API_KEY` env (recommended) |
|
|
58
|
+
| Optionally complete a wallet Bearer handshake | `aureon_get_auth_nonce` → sign → `aureon_verify_wallet` |
|
|
59
|
+
| Sync and manage the Capital Book | `aureon_sync_portfolio`, `aureon_set_portfolio`, `aureon_clear_portfolio` |
|
|
60
|
+
| Create and query Financial Compass objectives | `aureon_create_objective`, `aureon_list_objectives`, … |
|
|
61
|
+
| Read health, timeline, vault, executions | `aureon_get_health`, `aureon_list_timeline`, `aureon_get_vault`, … |
|
|
62
|
+
| Prepare non-custodial vault deposit / withdraw steps | `aureon_prepare_vault_deposit`, `aureon_prepare_vault_withdraw` |
|
|
63
|
+
| Fetch and execute restore plans | `aureon_get_restore_plan`, `aureon_restore_objective` |
|
|
64
|
+
| Rehearse market shocks | `aureon_apply_market_event`, `aureon_refresh_watchdog` |
|
|
65
|
+
| Manage developer API keys | `aureon_list_api_keys`, `aureon_create_api_key`, … |
|
|
66
|
+
|
|
67
|
+
**54 tools**: one per public `AureonClient` method. Full schemas: [docs/tools.md](docs/tools.md).
|
|
68
|
+
|
|
69
|
+
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.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Why AUREON MCP?
|
|
74
|
+
|
|
75
|
+
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:
|
|
76
|
+
|
|
77
|
+
* **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.
|
|
78
|
+
* **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.
|
|
79
|
+
* **Zero Infrastructure Overhead**: Standard I/O transport (`stdio`) means no local database, Docker containers, or background services to manage.
|
|
80
|
+
* **Honest Settlement Receipts**: Clearly distinguishes between on-chain smart vault settlements (`vault`) and ledger-local staged receipts (`staged`).
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Requirements & Installation
|
|
85
|
+
|
|
86
|
+
### Requirements
|
|
87
|
+
|
|
88
|
+
- **Node.js**: 20 or higher (ESM compatible)
|
|
89
|
+
- **Developer API Key**: Issued at [app.aureonlabs.network](https://app.aureonlabs.network) → **Developers** (official API, currently chain 46630)
|
|
90
|
+
- **Network Access**: Default official API `https://api.aureonlabs.network`. Optional `AUREON_NETWORK=mainnet` selects chain 4663 on the same host.
|
|
91
|
+
|
|
92
|
+
### Installation
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
# Using pnpm
|
|
96
|
+
pnpm add @buildaureon/mcp
|
|
97
|
+
|
|
98
|
+
# Using npm
|
|
99
|
+
npm install @buildaureon/mcp
|
|
100
|
+
|
|
101
|
+
# Or run instantly via npx without installing
|
|
102
|
+
npx -y @buildaureon/mcp
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
You do not need to clone the AUREON monorepo: only the package and an issued key for the network you will call.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Architecture
|
|
110
|
+
|
|
111
|
+
```mermaid
|
|
112
|
+
flowchart LR
|
|
113
|
+
Agent[Cursor / Claude] -->|stdio MCP| MCP["@buildaureon/mcp"]
|
|
114
|
+
MCP --> SDK["@buildaureon/sdk"]
|
|
115
|
+
SDK -->|default| Official[api.aureonlabs.network / 46630]
|
|
116
|
+
SDK -->|AUREON_NETWORK=mainnet| Main[api.aureonlabs.network / 4663]
|
|
117
|
+
Official --> VaultTN[Smart Vault testnet]
|
|
118
|
+
Main --> VaultMN[Smart Vault mainnet]
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Surface & Ownership Breakdown
|
|
122
|
+
|
|
123
|
+
| Surface | Auth | Role |
|
|
124
|
+
| --- | --- | --- |
|
|
125
|
+
| Operator utility | Wallet sign-in (Bearer) | Human operators managing vaults and approving manual restores |
|
|
126
|
+
| `@buildaureon/sdk` | Issued API key (+ optional Bearer) | Automated scripts, bots, serverless routines, and products |
|
|
127
|
+
| `@buildaureon/mcp` | Same as SDK via host `env` | AI agents operating inside Cursor, Claude Desktop, or custom MCP hosts |
|
|
128
|
+
|
|
129
|
+
### Layer Responsibilities
|
|
130
|
+
|
|
131
|
+
| Concern | Owner | Description |
|
|
132
|
+
| --- | --- | --- |
|
|
133
|
+
| HTTP, retries, types, validation, errors | `@buildaureon/sdk` | Core underlying SDK client managing network communications |
|
|
134
|
+
| Tool names, zod schemas, agent formatting | `@buildaureon/mcp` | MCP server mapping SDK methods to AI-friendly tools |
|
|
135
|
+
| stdio / JSON-RPC protocol | `@modelcontextprotocol/sdk` | Official MCP protocol framework for inter-process communication |
|
|
136
|
+
|
|
137
|
+
**Trust boundary**: The API monitors objectives and generates restore plans; private keys stay strictly on the host machine. MCP never signs chain transactions.
|
|
138
|
+
|
|
139
|
+
Deep dive: [docs/architecture.md](docs/architecture.md).
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## Quickstart
|
|
144
|
+
|
|
145
|
+
Get your AI agent running with AUREON MCP in 4 easy steps:
|
|
146
|
+
|
|
147
|
+
### 1. Create an issued API key
|
|
148
|
+
|
|
149
|
+
Issue the key on the **same** API this MCP process will call:
|
|
150
|
+
|
|
151
|
+
1. Open https://app.aureonlabs.network → **Developers**.
|
|
152
|
+
2. Create API Key → copy your key once.
|
|
153
|
+
|
|
154
|
+
That key identifies your wallet for control-plane tools. **No Bearer token required.** Issue the key on the official API this process will call.
|
|
155
|
+
|
|
156
|
+
### 2. Configure Cursor IDE
|
|
157
|
+
|
|
158
|
+
Copy [`examples/cursor.mcp.json`](examples/cursor.mcp.json) into `.cursor/mcp.json` (or merge into your global Cursor MCP config):
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"mcpServers": {
|
|
163
|
+
"aureon": {
|
|
164
|
+
"command": "npx",
|
|
165
|
+
"args": ["-y", "@buildaureon/mcp"],
|
|
166
|
+
"env": {
|
|
167
|
+
"AUREON_API_KEY": "<issued-developer-api-key>"
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Restart Cursor. Open the AI chat panel and ask: *“Ping AUREON and show my wallet with aureon_me.”*
|
|
175
|
+
|
|
176
|
+
### 3. Configure Claude Desktop
|
|
177
|
+
|
|
178
|
+
Merge [`examples/claude-desktop.json`](examples/claude-desktop.json) into Claude Desktop's configuration file:
|
|
179
|
+
|
|
180
|
+
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
181
|
+
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
182
|
+
|
|
183
|
+
```json
|
|
184
|
+
{
|
|
185
|
+
"mcpServers": {
|
|
186
|
+
"aureon": {
|
|
187
|
+
"command": "npx",
|
|
188
|
+
"args": ["-y", "@buildaureon/mcp"],
|
|
189
|
+
"env": {
|
|
190
|
+
"AUREON_API_KEY": "<issued-developer-api-key>"
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Restart Claude Desktop and test the connection.
|
|
198
|
+
|
|
199
|
+
### 4. From a local clone (maintainers)
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
pnpm install
|
|
203
|
+
pnpm --filter @buildaureon/mcp build
|
|
204
|
+
pnpm --filter @buildaureon/mcp start
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Point the host `command` / `args` at the built `dist/index.js`. See [docs/setup.md](docs/setup.md).
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## Authentication
|
|
212
|
+
|
|
213
|
+
### Recommended: Issued API key
|
|
214
|
+
|
|
215
|
+
| Variable | Required | Role |
|
|
216
|
+
| --- | --- | --- |
|
|
217
|
+
| `AUREON_API_KEY` | Yes (recommended) | Issued developer key for product access **and** wallet identity |
|
|
218
|
+
| `AUREON_NETWORK` | No | Omit for official API / testnet 46630. Set `mainnet` for chain 4663. |
|
|
219
|
+
| `AUREON_API_URL` | No | Optional override of `https://api.aureonlabs.network`. |
|
|
220
|
+
| `AUREON_AUTH_TOKEN` | No | Optional wallet Bearer (**wins** if both key and Bearer are sent) |
|
|
221
|
+
|
|
222
|
+
**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.
|
|
223
|
+
|
|
224
|
+
### Optional: Wallet Bearer session
|
|
225
|
+
|
|
226
|
+
Use `aureon_get_auth_nonce` → host wallet signs challenge → `aureon_verify_wallet`. Prefer issued keys for always-on agents.
|
|
227
|
+
|
|
228
|
+
### Preview / Dev Mode only
|
|
229
|
+
|
|
230
|
+
`aureon_dev_login` works only when the API backend has `AUREON_ALLOW_DEV_LOGIN=1` (it does not function on production).
|
|
231
|
+
|
|
232
|
+
Deep dive: [docs/auth.md](docs/auth.md).
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## Tool Surface
|
|
237
|
+
|
|
238
|
+
AUREON MCP exposes **54 tools** covering 100% of the `AureonClient` SDK surface:
|
|
239
|
+
|
|
240
|
+
| Category | Count | Tools Included | Primary Purpose |
|
|
241
|
+
| --- | --- | --- | --- |
|
|
242
|
+
| **Health** | 1 | `aureon_ping` | Check API connectivity & backend watchdog state |
|
|
243
|
+
| **Auth** | 5 | `aureon_get_auth_nonce`, `aureon_verify_wallet`, `aureon_dev_login`, `aureon_logout`, `aureon_me` | Manage wallet sessions, challenges, and identity |
|
|
244
|
+
| **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 |
|
|
245
|
+
| **Objectives** | 4 | `aureon_create_objective`, `aureon_update_objective`, `aureon_pause_objective`, `aureon_resume_objective` | Create, modify, pause, and resume Financial Compass Objectives |
|
|
246
|
+
| **Portfolio** | 3 | `aureon_set_portfolio`, `aureon_clear_portfolio`, `aureon_sync_portfolio` | Synchronize and manage live Capital Book asset marks |
|
|
247
|
+
| **Execution** | 2 | `aureon_run_execution`, `aureon_restore_objective` | Trigger policy rebalancing and execute objective restore plans |
|
|
248
|
+
| **Market** | 2 | `aureon_apply_market_event`, `aureon_refresh_watchdog` | Rehearse market shocks (e.g. price shifts) against active policy |
|
|
249
|
+
| **Vault** | 2 | `aureon_prepare_vault_deposit`, `aureon_prepare_vault_withdraw` | Generate unsigned steps for non-custodial smart vault deposits/withdrawals |
|
|
250
|
+
| **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 |
|
|
251
|
+
|
|
252
|
+
Full argument schemas: [docs/tools.md](docs/tools.md) · Playbooks: [docs/agent-guide.md](docs/agent-guide.md).
|
|
253
|
+
|
|
254
|
+
### Locked fields
|
|
255
|
+
|
|
256
|
+
- `targetSymbol` and `automationMode` are set at **create** time and cannot be modified via `aureon_update_objective`: recreate the objective instead.
|
|
257
|
+
- Default `automationMode` is `"auto"`. Use `"manual"` only when a human must Approve changes inside the utility web app.
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
## Agent Workflows
|
|
262
|
+
|
|
263
|
+
Agents perform best when following the **Read → Decide → Act** execution pattern:
|
|
264
|
+
|
|
265
|
+
```mermaid
|
|
266
|
+
flowchart TD
|
|
267
|
+
subgraph Read Phase
|
|
268
|
+
R1[1. aureon_ping] --> R2[2. aureon_me]
|
|
269
|
+
R2 --> R3[3. aureon_sync_portfolio]
|
|
270
|
+
R3 --> R4[4. aureon_get_health]
|
|
271
|
+
end
|
|
272
|
+
|
|
273
|
+
subgraph Decide Phase
|
|
274
|
+
R4 --> D1{Policy Breached?}
|
|
275
|
+
end
|
|
276
|
+
|
|
277
|
+
subgraph Act Phase
|
|
278
|
+
D1 -- Yes --> A1[aureon_get_restore_plan]
|
|
279
|
+
A1 --> A2[aureon_restore_objective]
|
|
280
|
+
A2 --> A3[aureon_list_timeline]
|
|
281
|
+
D1 -- No --> A4[Maintain current positions]
|
|
282
|
+
end
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
### 1. Control-Plane Routine (API Key Only)
|
|
286
|
+
|
|
287
|
+
1. `aureon_ping` → `aureon_me` (Verify connection and wallet identity)
|
|
288
|
+
2. `aureon_sync_portfolio` → `aureon_get_vault_status` (Fetch marks and check vault readiness)
|
|
289
|
+
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.
|
|
290
|
+
4. `aureon_create_objective` (`auto`) (Register continuous financial objective)
|
|
291
|
+
5. `aureon_refresh_watchdog` / `aureon_get_health` (Check health score and drift)
|
|
292
|
+
6. On violation after the vault is funded → `aureon_get_restore_plan` → `aureon_restore_objective`
|
|
293
|
+
7. Confirm with `aureon_list_timeline` (Verify settlement receipts)
|
|
294
|
+
|
|
295
|
+
### 2. Vault Deposit Path (API Key + External Signer)
|
|
296
|
+
|
|
297
|
+
1. `aureon_prepare_vault_deposit` → returns unsigned steps
|
|
298
|
+
2. Host wallet signs and broadcasts transaction on Robinhood Chain
|
|
299
|
+
3. `aureon_sync_portfolio` / `aureon_get_vault` (Re-sync marks to reflect new deposit)
|
|
300
|
+
|
|
301
|
+
More playbooks: [docs/agent-guide.md](docs/agent-guide.md).
|
|
302
|
+
|
|
303
|
+
---
|
|
304
|
+
|
|
305
|
+
## Sample Agent Prompts
|
|
306
|
+
|
|
307
|
+
Copy and paste these example prompts into Cursor or Claude Desktop:
|
|
308
|
+
|
|
309
|
+
### Portfolio Audit
|
|
310
|
+
> *"Ping AUREON, verify my wallet address with aureon_me, sync my portfolio, and give me a summary of total AUM and active objective health."*
|
|
311
|
+
|
|
312
|
+
### Setting a Compass Objective
|
|
313
|
+
> *"Create an automatic Financial Compass Objective named 'Maintain 20% WETH' targeting symbol WETH with weight 0.20 and tolerance 0.03."*
|
|
314
|
+
|
|
315
|
+
### Monitoring & Drift Restoration
|
|
316
|
+
> *"Refresh the watchdog and inspect my AUREON health. If any objective is in breach, show me the restore plan and run aureon_restore_objective."*
|
|
317
|
+
|
|
318
|
+
### Deposit Preparation
|
|
319
|
+
> *"Prepare an unsigned vault deposit for 0.1 ETH. Return the exact step payload so I can review and sign it in my wallet."*
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## Security Model
|
|
324
|
+
|
|
325
|
+
* **Local stdio Isolation**: Run MCP **locally over stdio** only; do not expose standard I/O sockets on the public internet.
|
|
326
|
+
* **API Key Protection**: Treat `AUREON_API_KEY` like a password. Pause, revoke, or rotate keys in the Developer dashboard if compromised.
|
|
327
|
+
* **Environment Hygiene**: Never commit keys to version control. Never put wallet private keys into MCP environment variables.
|
|
328
|
+
* **Prompt Safety**: Review agent prompts before enabling write tools in untrusted or multi-user chat channels.
|
|
329
|
+
|
|
330
|
+
Deep dive details: [docs/security.md](docs/security.md).
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## Development
|
|
335
|
+
|
|
336
|
+
To build and test `@buildaureon/mcp` locally:
|
|
337
|
+
|
|
338
|
+
```bash
|
|
339
|
+
pnpm install
|
|
340
|
+
pnpm --filter @buildaureon/mcp build
|
|
341
|
+
pnpm --filter @buildaureon/mcp test
|
|
342
|
+
pnpm --filter @buildaureon/mcp typecheck
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
### Script Reference
|
|
346
|
+
|
|
347
|
+
| Script | Purpose | Description |
|
|
348
|
+
| --- | --- | --- |
|
|
349
|
+
| `build` | `tsup` → `dist/` | Bundles TypeScript source into distribution ESM output |
|
|
350
|
+
| `dev` | `tsx src/index.ts` | Runs server directly from source for local development |
|
|
351
|
+
| `start` | `node dist/index.js` | Runs compiled distribution binary |
|
|
352
|
+
| `test` | `tsx --test ...` | Runs unit, smoke, and integration test suites |
|
|
353
|
+
| `typecheck` | `tsc --noEmit` | Validates TypeScript types across source files |
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
## Documentation Registry
|
|
358
|
+
|
|
359
|
+
| Document | Description & Contents |
|
|
360
|
+
| --- | --- |
|
|
361
|
+
| **[Setup Guide](docs/setup.md)** | Step-by-step setup for Cursor, Claude Desktop, npx, building from source, and troubleshooting |
|
|
362
|
+
| **[Authentication Guide](docs/auth.md)** | Issued API key vs. Wallet Bearer vs. private key boundaries |
|
|
363
|
+
| **[Tools Reference](docs/tools.md)** | Full 54-tool reference with arguments, schemas, and caveats |
|
|
364
|
+
| **[Agent Playbooks](docs/agent-guide.md)** | End-to-end agent decision playbooks, turn templates, and anti-patterns |
|
|
365
|
+
| **[Architecture Deep Dive](docs/architecture.md)** | Module boundaries, file maps, and end-to-end request data flows |
|
|
366
|
+
| **[Security Model](docs/security.md)** | Credential management, threat modeling, and operational safety |
|
|
367
|
+
| **[Changelog](CHANGELOG.md)** | Published versions, including 0.1.9 official API and network header |
|
|
368
|
+
| **[`@buildaureon/sdk`](https://github.com/buildaureon/aureon-sdk)** | Core TypeScript SDK documentation, types, and error definitions |
|
|
369
|
+
|
|
370
|
+
---
|
|
371
|
+
|
|
372
|
+
## FAQ
|
|
373
|
+
|
|
374
|
+
**Do I need a private key in Cursor or Claude env?**
|
|
375
|
+
No. You only need an issued `AUREON_API_KEY`. Private keys stay in your host wallet when signing prepare steps.
|
|
376
|
+
|
|
377
|
+
**Does MCP talk to a local backend server?**
|
|
378
|
+
No. Omit `AUREON_API_URL` to use the official API `https://api.aureonlabs.network` (currently chain 46630). Set `AUREON_NETWORK=mainnet` to select chain 4663 on that same host.
|
|
379
|
+
|
|
380
|
+
**Why did my restore receipt say `staged`?**
|
|
381
|
+
`staged` is a ledger-local receipt, not an on-chain vault settlement. Always describe settlement receipts accurately in agent responses.
|
|
382
|
+
|
|
383
|
+
**Can agents use Manual automation mode?**
|
|
384
|
+
Prefer Automatic (`auto`). Manual mode requires human Approval inside the operator utility app.
|
|
385
|
+
|
|
386
|
+
**What happens if an objective breaches its drift tolerance?**
|
|
387
|
+
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.
|
|
388
|
+
|
|
389
|
+
**How does MCP handle network errors or disconnects?**
|
|
390
|
+
The underlying `@buildaureon/sdk` handles HTTP retries and reports structured error objects with stable error codes back to the MCP host.
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## Community
|
|
395
|
+
|
|
396
|
+
- **Website**: https://www.aureonlabs.network
|
|
397
|
+
- **X (Twitter)**: https://x.com/buildaureon
|
|
398
|
+
- **App Utility**: https://app.aureonlabs.network
|
|
399
|
+
|
|
400
|
+
## License
|
|
401
|
+
|
|
402
|
+
MIT (see [LICENSE](LICENSE)).
|