@buildaureon/mcp 0.1.9 → 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 +19 -0
- package/README.md +122 -37
- package/dist/index.js.map +1 -1
- package/docs/agent-guide.md +5 -5
- package/docs/architecture.md +22 -15
- package/docs/auth.md +25 -15
- package/docs/security.md +7 -7
- package/docs/setup.md +90 -31
- package/docs/tools.md +8 -6
- package/examples/cursor.hosted.mcp.json +7 -0
- package/examples/cursor.hosted.user.mcp.json +10 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,24 @@ All notable changes to `@buildaureon/mcp` are documented in this file.
|
|
|
5
5
|
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|
6
6
|
This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.1.10] — 2026-09-13
|
|
9
|
+
|
|
10
|
+
Published on npm as `@buildaureon/mcp@0.1.10`. Depends on `@buildaureon/sdk@0.1.10`.
|
|
11
|
+
|
|
12
|
+
### Documentation
|
|
13
|
+
|
|
14
|
+
- Official hosted MCP is documented: `https://mcp.aureonlabs.network/mcp` (Streamable HTTP, 54 tools). Health: `https://mcp.aureonlabs.network/healthz`.
|
|
15
|
+
- Hosted connect is URL-only. Open tools: `aureon_ping`, `aureon_list_market_presets`, `aureon_validate_receipt`.
|
|
16
|
+
- Optional `X-Aureon-Api-Key` on the same URL for your wallet tools. Example: `examples/cursor.hosted.user.mcp.json`.
|
|
17
|
+
- Local stdio remains `npx -y @buildaureon/mcp` with your issued `AUREON_API_KEY`.
|
|
18
|
+
- Cursor hosted example: `examples/cursor.hosted.mcp.json`.
|
|
19
|
+
- README, setup, architecture, auth, security, and agent-guide no longer describe MCP as stdio-only or as a server-wallet-only hosted process.
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
|
|
23
|
+
- Omit `AUREON_NETWORK` on the official host now selects **mainnet**. Set `AUREON_NETWORK=testnet` to stay on testnet on the same host.
|
|
24
|
+
- Public Living Capital remains the testnet console. MCP default is mainnet.
|
|
25
|
+
|
|
8
26
|
## [0.1.9] — 2026-09-08
|
|
9
27
|
|
|
10
28
|
Published on npm as `@buildaureon/mcp@0.1.9`. Depends on `@buildaureon/sdk@0.1.9`.
|
|
@@ -55,6 +73,7 @@ Public npm release.
|
|
|
55
73
|
|
|
56
74
|
Initial public npm release of `@buildaureon/mcp`.
|
|
57
75
|
|
|
76
|
+
[0.1.10]: https://www.npmjs.com/package/@buildaureon/mcp/v/0.1.10
|
|
58
77
|
[0.1.9]: https://www.npmjs.com/package/@buildaureon/mcp/v/0.1.9
|
|
59
78
|
[0.1.8]: https://www.npmjs.com/package/@buildaureon/mcp/v/0.1.8
|
|
60
79
|
[0.1.7]: https://www.npmjs.com/package/@buildaureon/mcp/v/0.1.7
|
package/README.md
CHANGED
|
@@ -10,18 +10,23 @@ Exposes the full `@buildaureon/sdk` surface as tools for Cursor, Claude Desktop,
|
|
|
10
10
|
<br />
|
|
11
11
|
|
|
12
12
|
[](https://www.typescriptlang.org/)
|
|
13
|
-
[](https://modelcontextprotocol.io)
|
|
14
|
+
[](https://mcp.aureonlabs.network/mcp)
|
|
15
|
+
[](https://github.com/buildaureon)
|
|
15
16
|
[](LICENSE)
|
|
16
17
|
[](#requirements--installation)
|
|
17
18
|
|
|
18
19
|
<br />
|
|
19
20
|
|
|
20
21
|
```bash
|
|
22
|
+
# Hosted (no local process)
|
|
23
|
+
https://mcp.aureonlabs.network/mcp
|
|
24
|
+
|
|
25
|
+
# Or local stdio
|
|
21
26
|
npx -y @buildaureon/mcp
|
|
22
27
|
```
|
|
23
28
|
|
|
24
|
-
[Quickstart](#quickstart) · [Architecture](#architecture) · [Authentication](#authentication) · [Tool Surface](#tool-surface) · [Agent Workflows](#agent-workflows) · [Docs](#documentation-registry)
|
|
29
|
+
[How to connect](#how-to-connect) · [Quickstart](#quickstart) · [Architecture](#architecture) · [Authentication](#authentication) · [Tool Surface](#tool-surface) · [Agent Workflows](#agent-workflows) · [Docs](#documentation-registry)
|
|
25
30
|
|
|
26
31
|
</div>
|
|
27
32
|
|
|
@@ -30,19 +35,20 @@ npx -y @buildaureon/mcp
|
|
|
30
35
|
## Table of Contents
|
|
31
36
|
|
|
32
37
|
1. [What is AUREON MCP?](#what-is-aureon-mcp)
|
|
33
|
-
2. [
|
|
34
|
-
3. [
|
|
35
|
-
4. [
|
|
36
|
-
5. [
|
|
37
|
-
6. [
|
|
38
|
-
7. [
|
|
39
|
-
8. [
|
|
40
|
-
9. [
|
|
41
|
-
10. [
|
|
42
|
-
11. [
|
|
43
|
-
12. [
|
|
44
|
-
13. [
|
|
45
|
-
14. [
|
|
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)
|
|
46
52
|
|
|
47
53
|
---
|
|
48
54
|
|
|
@@ -50,7 +56,14 @@ npx -y @buildaureon/mcp
|
|
|
50
56
|
|
|
51
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.
|
|
52
58
|
|
|
53
|
-
**`@buildaureon/mcp`** is the agent adapter. It
|
|
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.
|
|
54
67
|
|
|
55
68
|
| You can | Through |
|
|
56
69
|
| --- | --- |
|
|
@@ -66,7 +79,66 @@ npx -y @buildaureon/mcp
|
|
|
66
79
|
|
|
67
80
|
**54 tools**: one per public `AureonClient` method. Full schemas: [docs/tools.md](docs/tools.md).
|
|
68
81
|
|
|
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.
|
|
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).
|
|
70
142
|
|
|
71
143
|
---
|
|
72
144
|
|
|
@@ -76,7 +148,7 @@ Traditional AI trading scripts execute isolated market orders without context, f
|
|
|
76
148
|
|
|
77
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.
|
|
78
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.
|
|
79
|
-
* **
|
|
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.
|
|
80
152
|
* **Honest Settlement Receipts**: Clearly distinguishes between on-chain smart vault settlements (`vault`) and ledger-local staged receipts (`staged`).
|
|
81
153
|
|
|
82
154
|
---
|
|
@@ -86,8 +158,8 @@ Traditional AI trading scripts execute isolated market orders without context, f
|
|
|
86
158
|
### Requirements
|
|
87
159
|
|
|
88
160
|
- **Node.js**: 20 or higher (ESM compatible)
|
|
89
|
-
- **Developer API Key**: Issued at [app.aureonlabs.network](https://app.aureonlabs.network) → **Developers
|
|
90
|
-
- **Network Access**: Default official API `https://api.aureonlabs.network
|
|
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.
|
|
91
163
|
|
|
92
164
|
### Installation
|
|
93
165
|
|
|
@@ -110,12 +182,15 @@ You do not need to clone the AUREON monorepo: only the package and an issued key
|
|
|
110
182
|
|
|
111
183
|
```mermaid
|
|
112
184
|
flowchart LR
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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]
|
|
119
194
|
```
|
|
120
195
|
|
|
121
196
|
### Surface & Ownership Breakdown
|
|
@@ -124,7 +199,8 @@ flowchart LR
|
|
|
124
199
|
| --- | --- | --- |
|
|
125
200
|
| Operator utility | Wallet sign-in (Bearer) | Human operators managing vaults and approving manual restores |
|
|
126
201
|
| `@buildaureon/sdk` | Issued API key (+ optional Bearer) | Automated scripts, bots, serverless routines, and products |
|
|
127
|
-
| `@buildaureon/mcp` | Same as SDK via host `env` |
|
|
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` |
|
|
128
204
|
|
|
129
205
|
### Layer Responsibilities
|
|
130
206
|
|
|
@@ -132,7 +208,7 @@ flowchart LR
|
|
|
132
208
|
| --- | --- | --- |
|
|
133
209
|
| HTTP, retries, types, validation, errors | `@buildaureon/sdk` | Core underlying SDK client managing network communications |
|
|
134
210
|
| Tool names, zod schemas, agent formatting | `@buildaureon/mcp` | MCP server mapping SDK methods to AI-friendly tools |
|
|
135
|
-
| stdio / JSON-RPC
|
|
211
|
+
| stdio / Streamable HTTP / JSON-RPC | `@modelcontextprotocol/sdk` | Official MCP protocol. Stdio is the npm package. Streamable HTTP is the official hosted process. |
|
|
136
212
|
|
|
137
213
|
**Trust boundary**: The API monitors objectives and generates restore plans; private keys stay strictly on the host machine. MCP never signs chain transactions.
|
|
138
214
|
|
|
@@ -142,7 +218,7 @@ Deep dive: [docs/architecture.md](docs/architecture.md).
|
|
|
142
218
|
|
|
143
219
|
## Quickstart
|
|
144
220
|
|
|
145
|
-
|
|
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.
|
|
146
222
|
|
|
147
223
|
### 1. Create an issued API key
|
|
148
224
|
|
|
@@ -153,9 +229,9 @@ Issue the key on the **same** API this MCP process will call:
|
|
|
153
229
|
|
|
154
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.
|
|
155
231
|
|
|
156
|
-
### 2. Configure Cursor IDE
|
|
232
|
+
### 2. Configure Cursor IDE (local stdio)
|
|
157
233
|
|
|
158
|
-
|
|
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`:
|
|
159
235
|
|
|
160
236
|
```json
|
|
161
237
|
{
|
|
@@ -215,7 +291,7 @@ Point the host `command` / `args` at the built `dist/index.js`. See [docs/setup.
|
|
|
215
291
|
| Variable | Required | Role |
|
|
216
292
|
| --- | --- | --- |
|
|
217
293
|
| `AUREON_API_KEY` | Yes (recommended) | Issued developer key for product access **and** wallet identity |
|
|
218
|
-
| `AUREON_NETWORK` | No | Omit for official API /
|
|
294
|
+
| `AUREON_NETWORK` | No | Omit for official API / mainnet. Set `testnet` to stay on testnet. |
|
|
219
295
|
| `AUREON_API_URL` | No | Optional override of `https://api.aureonlabs.network`. |
|
|
220
296
|
| `AUREON_AUTH_TOKEN` | No | Optional wallet Bearer (**wins** if both key and Bearer are sent) |
|
|
221
297
|
|
|
@@ -322,7 +398,7 @@ Copy and paste these example prompts into Cursor or Claude Desktop:
|
|
|
322
398
|
|
|
323
399
|
## Security Model
|
|
324
400
|
|
|
325
|
-
* **
|
|
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.
|
|
326
402
|
* **API Key Protection**: Treat `AUREON_API_KEY` like a password. Pause, revoke, or rotate keys in the Developer dashboard if compromised.
|
|
327
403
|
* **Environment Hygiene**: Never commit keys to version control. Never put wallet private keys into MCP environment variables.
|
|
328
404
|
* **Prompt Safety**: Review agent prompts before enabling write tools in untrusted or multi-user chat channels.
|
|
@@ -358,13 +434,15 @@ pnpm --filter @buildaureon/mcp typecheck
|
|
|
358
434
|
|
|
359
435
|
| Document | Description & Contents |
|
|
360
436
|
| --- | --- |
|
|
361
|
-
| **[Setup Guide](docs/setup.md)** |
|
|
437
|
+
| **[Setup Guide](docs/setup.md)** | Hosted URL first, then Cursor / Claude stdio, npx, source build, troubleshooting |
|
|
362
438
|
| **[Authentication Guide](docs/auth.md)** | Issued API key vs. Wallet Bearer vs. private key boundaries |
|
|
363
439
|
| **[Tools Reference](docs/tools.md)** | Full 54-tool reference with arguments, schemas, and caveats |
|
|
364
440
|
| **[Agent Playbooks](docs/agent-guide.md)** | End-to-end agent decision playbooks, turn templates, and anti-patterns |
|
|
365
441
|
| **[Architecture Deep Dive](docs/architecture.md)** | Module boundaries, file maps, and end-to-end request data flows |
|
|
366
442
|
| **[Security Model](docs/security.md)** | Credential management, threat modeling, and operational safety |
|
|
367
|
-
| **[Changelog](CHANGELOG.md)** | Published versions, including 0.1.
|
|
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 |
|
|
368
446
|
| **[`@buildaureon/sdk`](https://github.com/buildaureon/aureon-sdk)** | Core TypeScript SDK documentation, types, and error definitions |
|
|
369
447
|
|
|
370
448
|
---
|
|
@@ -374,8 +452,11 @@ pnpm --filter @buildaureon/mcp typecheck
|
|
|
374
452
|
**Do I need a private key in Cursor or Claude env?**
|
|
375
453
|
No. You only need an issued `AUREON_API_KEY`. Private keys stay in your host wallet when signing prepare steps.
|
|
376
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
|
+
|
|
377
458
|
**Does MCP talk to a local backend server?**
|
|
378
|
-
No.
|
|
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.
|
|
379
460
|
|
|
380
461
|
**Why did my restore receipt say `staged`?**
|
|
381
462
|
`staged` is a ledger-local receipt, not an on-chain vault settlement. Always describe settlement receipts accurately in agent responses.
|
|
@@ -394,8 +475,12 @@ The underlying `@buildaureon/sdk` handles HTTP retries and reports structured er
|
|
|
394
475
|
## Community
|
|
395
476
|
|
|
396
477
|
- **Website**: https://www.aureonlabs.network
|
|
478
|
+
- **Hosted MCP**: https://mcp.aureonlabs.network/mcp
|
|
479
|
+
- **Hosted health**: https://mcp.aureonlabs.network/healthz
|
|
397
480
|
- **X (Twitter)**: https://x.com/buildaureon
|
|
398
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
|
|
399
484
|
|
|
400
485
|
## License
|
|
401
486
|
|