@agent-shield/mcp 0.1.0
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/README.md +124 -0
- package/dist/config.d.ts +12 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +75 -0
- package/dist/config.js.map +1 -0
- package/dist/errors.d.ts +22 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +244 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +206 -0
- package/dist/index.js.map +1 -0
- package/dist/resources/activity.d.ts +3 -0
- package/dist/resources/activity.d.ts.map +1 -0
- package/dist/resources/activity.js +33 -0
- package/dist/resources/activity.js.map +1 -0
- package/dist/resources/index.d.ts +4 -0
- package/dist/resources/index.d.ts.map +1 -0
- package/dist/resources/index.js +10 -0
- package/dist/resources/index.js.map +1 -0
- package/dist/resources/policy.d.ts +3 -0
- package/dist/resources/policy.d.ts.map +1 -0
- package/dist/resources/policy.js +36 -0
- package/dist/resources/policy.js.map +1 -0
- package/dist/resources/spending.d.ts +3 -0
- package/dist/resources/spending.d.ts.map +1 -0
- package/dist/resources/spending.js +39 -0
- package/dist/resources/spending.js.map +1 -0
- package/dist/tools/check-spending.d.ts +24 -0
- package/dist/tools/check-spending.d.ts.map +1 -0
- package/dist/tools/check-spending.js +60 -0
- package/dist/tools/check-spending.js.map +1 -0
- package/dist/tools/check-vault.d.ts +36 -0
- package/dist/tools/check-vault.d.ts.map +1 -0
- package/dist/tools/check-vault.js +110 -0
- package/dist/tools/check-vault.js.map +1 -0
- package/dist/tools/close-position.d.ts +49 -0
- package/dist/tools/close-position.d.ts.map +1 -0
- package/dist/tools/close-position.js +65 -0
- package/dist/tools/close-position.js.map +1 -0
- package/dist/tools/create-vault.d.ts +72 -0
- package/dist/tools/create-vault.d.ts.map +1 -0
- package/dist/tools/create-vault.js +75 -0
- package/dist/tools/create-vault.js.map +1 -0
- package/dist/tools/deposit.d.ts +36 -0
- package/dist/tools/deposit.d.ts.map +1 -0
- package/dist/tools/deposit.js +35 -0
- package/dist/tools/deposit.js.map +1 -0
- package/dist/tools/execute-swap.d.ts +49 -0
- package/dist/tools/execute-swap.d.ts.map +1 -0
- package/dist/tools/execute-swap.js +58 -0
- package/dist/tools/execute-swap.js.map +1 -0
- package/dist/tools/index.d.ts +13 -0
- package/dist/tools/index.d.ts.map +1 -0
- package/dist/tools/index.js +52 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/open-position.d.ts +61 -0
- package/dist/tools/open-position.d.ts.map +1 -0
- package/dist/tools/open-position.js +70 -0
- package/dist/tools/open-position.js.map +1 -0
- package/dist/tools/reactivate-vault.d.ts +30 -0
- package/dist/tools/reactivate-vault.d.ts.map +1 -0
- package/dist/tools/reactivate-vault.js +41 -0
- package/dist/tools/reactivate-vault.js.map +1 -0
- package/dist/tools/register-agent.d.ts +30 -0
- package/dist/tools/register-agent.d.ts.map +1 -0
- package/dist/tools/register-agent.js +36 -0
- package/dist/tools/register-agent.js.map +1 -0
- package/dist/tools/revoke-agent.d.ts +24 -0
- package/dist/tools/revoke-agent.d.ts.map +1 -0
- package/dist/tools/revoke-agent.js +34 -0
- package/dist/tools/revoke-agent.js.map +1 -0
- package/dist/tools/update-policy.d.ts +72 -0
- package/dist/tools/update-policy.d.ts.map +1 -0
- package/dist/tools/update-policy.js +90 -0
- package/dist/tools/update-policy.js.map +1 -0
- package/dist/tools/withdraw.d.ts +36 -0
- package/dist/tools/withdraw.d.ts.map +1 -0
- package/dist/tools/withdraw.js +34 -0
- package/dist/tools/withdraw.js.map +1 -0
- package/dist/utils.d.ts +11 -0
- package/dist/utils.d.ts.map +1 -0
- package/dist/utils.js +69 -0
- package/dist/utils.js.map +1 -0
- package/package.json +51 -0
package/README.md
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# @agent-shield/mcp
|
|
2
|
+
|
|
3
|
+
MCP (Model Context Protocol) server for AgentShield. Lets any MCP-compatible AI tool — Claude Desktop, Cursor, Windsurf — manage on-chain Solana vaults and enforce DeFi policies via natural language.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @agent-shield/mcp
|
|
9
|
+
# or run directly
|
|
10
|
+
npx @agent-shield/mcp
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Configuration
|
|
14
|
+
|
|
15
|
+
### Environment Variables
|
|
16
|
+
|
|
17
|
+
| Variable | Required | Default | Description |
|
|
18
|
+
|----------|----------|---------|-------------|
|
|
19
|
+
| `AGENTSHIELD_WALLET_PATH` | Yes | — | Path to Solana keypair JSON (vault owner) |
|
|
20
|
+
| `AGENTSHIELD_RPC_URL` | No | devnet | Solana RPC endpoint URL |
|
|
21
|
+
| `AGENTSHIELD_AGENT_KEYPAIR_PATH` | No | — | Path to agent keypair JSON (needed for swap/position tools) |
|
|
22
|
+
|
|
23
|
+
### Claude Desktop
|
|
24
|
+
|
|
25
|
+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"mcpServers": {
|
|
30
|
+
"agent-shield": {
|
|
31
|
+
"command": "npx",
|
|
32
|
+
"args": ["@agent-shield/mcp"],
|
|
33
|
+
"env": {
|
|
34
|
+
"AGENTSHIELD_WALLET_PATH": "~/.config/solana/id.json",
|
|
35
|
+
"AGENTSHIELD_RPC_URL": "https://api.devnet.solana.com"
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Cursor
|
|
43
|
+
|
|
44
|
+
Add to `.cursor/mcp.json` in your project:
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"mcpServers": {
|
|
49
|
+
"agent-shield": {
|
|
50
|
+
"command": "npx",
|
|
51
|
+
"args": ["@agent-shield/mcp"],
|
|
52
|
+
"env": {
|
|
53
|
+
"AGENTSHIELD_WALLET_PATH": "~/.config/solana/id.json"
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Tools (12)
|
|
61
|
+
|
|
62
|
+
### Read-Only
|
|
63
|
+
|
|
64
|
+
| Tool | Description |
|
|
65
|
+
|------|-------------|
|
|
66
|
+
| `shield_check_vault` | Check vault status, owner, agent, and policy configuration |
|
|
67
|
+
| `shield_check_spending` | Check rolling 24h spending and recent transaction history |
|
|
68
|
+
|
|
69
|
+
### Owner-Signed (Write)
|
|
70
|
+
|
|
71
|
+
| Tool | Description |
|
|
72
|
+
|------|-------------|
|
|
73
|
+
| `shield_create_vault` | Create a new vault with policy configuration |
|
|
74
|
+
| `shield_deposit` | Deposit tokens into a vault |
|
|
75
|
+
| `shield_withdraw` | Withdraw tokens from a vault |
|
|
76
|
+
| `shield_register_agent` | Register an agent signing key |
|
|
77
|
+
| `shield_update_policy` | Update spending caps, token/protocol allowlists, leverage limits |
|
|
78
|
+
| `shield_revoke_agent` | Emergency kill switch — freezes vault immediately |
|
|
79
|
+
| `shield_reactivate_vault` | Unfreeze a vault, optionally with a new agent |
|
|
80
|
+
|
|
81
|
+
### Agent-Signed (Requires `AGENTSHIELD_AGENT_KEYPAIR_PATH`)
|
|
82
|
+
|
|
83
|
+
| Tool | Description |
|
|
84
|
+
|------|-------------|
|
|
85
|
+
| `shield_execute_swap` | Execute a Jupiter token swap through the vault |
|
|
86
|
+
| `shield_open_position` | Open a Flash Trade leveraged perpetual position |
|
|
87
|
+
| `shield_close_position` | Close a Flash Trade perpetual position |
|
|
88
|
+
|
|
89
|
+
## Resources (3)
|
|
90
|
+
|
|
91
|
+
Dynamic resources using vault address as URI parameter:
|
|
92
|
+
|
|
93
|
+
| URI Template | Description |
|
|
94
|
+
|-------------|-------------|
|
|
95
|
+
| `shield://vault/{address}/policy` | Current policy configuration (JSON) |
|
|
96
|
+
| `shield://vault/{address}/spending` | Rolling 24h spending state (JSON) |
|
|
97
|
+
| `shield://vault/{address}/activity` | Recent transaction history (JSON) |
|
|
98
|
+
|
|
99
|
+
## Development
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# Install dependencies
|
|
103
|
+
pnpm install
|
|
104
|
+
|
|
105
|
+
# Build
|
|
106
|
+
pnpm build
|
|
107
|
+
|
|
108
|
+
# Run tests (78 tests)
|
|
109
|
+
pnpm test
|
|
110
|
+
|
|
111
|
+
# Smoke test
|
|
112
|
+
AGENTSHIELD_WALLET_PATH=~/.config/solana/id.json node dist/index.js
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Architecture
|
|
116
|
+
|
|
117
|
+
- **Transport**: stdio only (local subprocess of the AI tool)
|
|
118
|
+
- **Credentials**: Environment variables (keypair file paths)
|
|
119
|
+
- **SDK**: Wraps `AgentShieldClient` from `@agent-shield/sdk` — every tool delegates to a client method
|
|
120
|
+
- **Error handling**: All 28 Anchor error codes mapped to human-readable messages with actionable suggestions
|
|
121
|
+
|
|
122
|
+
## License
|
|
123
|
+
|
|
124
|
+
MIT
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { Keypair } from "@solana/web3.js";
|
|
2
|
+
import { AgentShieldClient } from "@agent-shield/sdk";
|
|
3
|
+
export interface McpConfig {
|
|
4
|
+
walletPath: string;
|
|
5
|
+
rpcUrl: string;
|
|
6
|
+
agentKeypairPath?: string;
|
|
7
|
+
}
|
|
8
|
+
export declare function loadConfig(): McpConfig;
|
|
9
|
+
export declare function loadKeypair(path: string): Keypair;
|
|
10
|
+
export declare function createClient(config: McpConfig): AgentShieldClient;
|
|
11
|
+
export declare function loadAgentKeypair(config: McpConfig): Keypair;
|
|
12
|
+
//# sourceMappingURL=config.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,OAAO,EAAiB,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGtD,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,UAAU,IAAI,SAAS,CAgBtC;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOjD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAKjE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAQ3D"}
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.loadConfig = loadConfig;
|
|
37
|
+
exports.loadKeypair = loadKeypair;
|
|
38
|
+
exports.createClient = createClient;
|
|
39
|
+
exports.loadAgentKeypair = loadAgentKeypair;
|
|
40
|
+
const web3_js_1 = require("@solana/web3.js");
|
|
41
|
+
const anchor_1 = require("@coral-xyz/anchor");
|
|
42
|
+
const sdk_1 = require("@agent-shield/sdk");
|
|
43
|
+
const fs = __importStar(require("fs"));
|
|
44
|
+
function loadConfig() {
|
|
45
|
+
const walletPath = process.env.AGENTSHIELD_WALLET_PATH;
|
|
46
|
+
if (!walletPath) {
|
|
47
|
+
throw new Error("AGENTSHIELD_WALLET_PATH is required. " +
|
|
48
|
+
"Set it to the path of your Solana keypair JSON file.");
|
|
49
|
+
}
|
|
50
|
+
const rpcUrl = process.env.AGENTSHIELD_RPC_URL || (0, web3_js_1.clusterApiUrl)("devnet");
|
|
51
|
+
const agentKeypairPath = process.env.AGENTSHIELD_AGENT_KEYPAIR_PATH || undefined;
|
|
52
|
+
return { walletPath, rpcUrl, agentKeypairPath };
|
|
53
|
+
}
|
|
54
|
+
function loadKeypair(path) {
|
|
55
|
+
const resolved = path.startsWith("~")
|
|
56
|
+
? path.replace("~", process.env.HOME || "")
|
|
57
|
+
: path;
|
|
58
|
+
const raw = fs.readFileSync(resolved, "utf-8");
|
|
59
|
+
const secretKey = Uint8Array.from(JSON.parse(raw));
|
|
60
|
+
return web3_js_1.Keypair.fromSecretKey(secretKey);
|
|
61
|
+
}
|
|
62
|
+
function createClient(config) {
|
|
63
|
+
const keypair = loadKeypair(config.walletPath);
|
|
64
|
+
const wallet = new anchor_1.Wallet(keypair);
|
|
65
|
+
const connection = new web3_js_1.Connection(config.rpcUrl, "confirmed");
|
|
66
|
+
return new sdk_1.AgentShieldClient(connection, wallet);
|
|
67
|
+
}
|
|
68
|
+
function loadAgentKeypair(config) {
|
|
69
|
+
if (!config.agentKeypairPath) {
|
|
70
|
+
throw new Error("AGENTSHIELD_AGENT_KEYPAIR_PATH is required for agent-signed operations. " +
|
|
71
|
+
"Set it to the path of the agent's Solana keypair JSON file.");
|
|
72
|
+
}
|
|
73
|
+
return loadKeypair(config.agentKeypairPath);
|
|
74
|
+
}
|
|
75
|
+
//# sourceMappingURL=config.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAWA,gCAgBC;AAED,kCAOC;AAED,oCAKC;AAED,4CAQC;AArDD,6CAAqE;AACrE,8CAA2C;AAC3C,2CAAsD;AACtD,uCAAyB;AAQzB,SAAgB,UAAU;IACxB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;IACvD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,uCAAuC;YACrC,sDAAsD,CACzD,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GACV,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,IAAA,uBAAa,EAAC,QAAQ,CAAC,CAAC;IAE7D,MAAM,gBAAgB,GACpB,OAAO,CAAC,GAAG,CAAC,8BAA8B,IAAI,SAAS,CAAC;IAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AAClD,CAAC;AAED,SAAgB,WAAW,CAAC,IAAY;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QACnC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;QAC3C,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,OAAO,iBAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;AAC1C,CAAC;AAED,SAAgB,YAAY,CAAC,MAAiB;IAC5C,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,eAAM,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,IAAI,oBAAU,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC9D,OAAO,IAAI,uBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AAED,SAAgB,gBAAgB,CAAC,MAAiB;IAChD,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,0EAA0E;YACxE,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAC9C,CAAC"}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
export interface ErrorInfo {
|
|
2
|
+
code: number;
|
|
3
|
+
name: string;
|
|
4
|
+
message: string;
|
|
5
|
+
suggestion: string;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Maps all 28 AgentShield Anchor error codes (6000–6027) to
|
|
9
|
+
* human-readable messages with actionable suggestions for AI tools.
|
|
10
|
+
*/
|
|
11
|
+
declare const ERROR_MAP: Record<number, ErrorInfo>;
|
|
12
|
+
/**
|
|
13
|
+
* Look up an Anchor error code and return a structured ErrorInfo.
|
|
14
|
+
* Falls back to a generic message for unknown codes.
|
|
15
|
+
*/
|
|
16
|
+
export declare function lookupError(code: number): ErrorInfo;
|
|
17
|
+
/**
|
|
18
|
+
* Format any error into a user-friendly MCP tool response.
|
|
19
|
+
*/
|
|
20
|
+
export declare function formatError(error: unknown): string;
|
|
21
|
+
export { ERROR_MAP };
|
|
22
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,QAAA,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAsMxC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CASnD;AA6BD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAmClD;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.ERROR_MAP = void 0;
|
|
4
|
+
exports.lookupError = lookupError;
|
|
5
|
+
exports.formatError = formatError;
|
|
6
|
+
/**
|
|
7
|
+
* Maps all 28 AgentShield Anchor error codes (6000–6027) to
|
|
8
|
+
* human-readable messages with actionable suggestions for AI tools.
|
|
9
|
+
*/
|
|
10
|
+
const ERROR_MAP = {
|
|
11
|
+
6000: {
|
|
12
|
+
code: 6000,
|
|
13
|
+
name: "VaultNotActive",
|
|
14
|
+
message: "Vault is not active",
|
|
15
|
+
suggestion: "Use shield_reactivate_vault to reactivate a frozen vault, or create a new vault.",
|
|
16
|
+
},
|
|
17
|
+
6001: {
|
|
18
|
+
code: 6001,
|
|
19
|
+
name: "UnauthorizedAgent",
|
|
20
|
+
message: "Unauthorized: signer is not the registered agent",
|
|
21
|
+
suggestion: "Verify the agent keypair matches the one registered with shield_register_agent.",
|
|
22
|
+
},
|
|
23
|
+
6002: {
|
|
24
|
+
code: 6002,
|
|
25
|
+
name: "UnauthorizedOwner",
|
|
26
|
+
message: "Unauthorized: signer is not the vault owner",
|
|
27
|
+
suggestion: "This operation requires the vault owner's wallet. Check AGENTSHIELD_WALLET_PATH.",
|
|
28
|
+
},
|
|
29
|
+
6003: {
|
|
30
|
+
code: 6003,
|
|
31
|
+
name: "TokenNotAllowed",
|
|
32
|
+
message: "Token not in allowed list",
|
|
33
|
+
suggestion: "Use shield_update_policy to add the token to allowedTokens, or use an allowed token.",
|
|
34
|
+
},
|
|
35
|
+
6004: {
|
|
36
|
+
code: 6004,
|
|
37
|
+
name: "ProtocolNotAllowed",
|
|
38
|
+
message: "Protocol not in allowed list",
|
|
39
|
+
suggestion: "Use shield_update_policy to add the protocol to allowedProtocols.",
|
|
40
|
+
},
|
|
41
|
+
6005: {
|
|
42
|
+
code: 6005,
|
|
43
|
+
name: "TransactionTooLarge",
|
|
44
|
+
message: "Transaction exceeds maximum single transaction size",
|
|
45
|
+
suggestion: "Reduce the amount or use shield_update_policy to increase maxTransactionSize.",
|
|
46
|
+
},
|
|
47
|
+
6006: {
|
|
48
|
+
code: 6006,
|
|
49
|
+
name: "DailyCapExceeded",
|
|
50
|
+
message: "Daily spending cap would be exceeded",
|
|
51
|
+
suggestion: "Wait for the 24h rolling window to reset, or use shield_update_policy to increase dailySpendingCap.",
|
|
52
|
+
},
|
|
53
|
+
6007: {
|
|
54
|
+
code: 6007,
|
|
55
|
+
name: "LeverageTooHigh",
|
|
56
|
+
message: "Leverage exceeds maximum allowed",
|
|
57
|
+
suggestion: "Reduce leverage or use shield_update_policy to increase maxLeverageBps.",
|
|
58
|
+
},
|
|
59
|
+
6008: {
|
|
60
|
+
code: 6008,
|
|
61
|
+
name: "TooManyPositions",
|
|
62
|
+
message: "Maximum concurrent open positions reached",
|
|
63
|
+
suggestion: "Close an existing position before opening a new one, or increase maxConcurrentPositions.",
|
|
64
|
+
},
|
|
65
|
+
6009: {
|
|
66
|
+
code: 6009,
|
|
67
|
+
name: "PositionOpeningDisallowed",
|
|
68
|
+
message: "Cannot open new positions (policy disallows)",
|
|
69
|
+
suggestion: "Use shield_update_policy to set canOpenPositions to true.",
|
|
70
|
+
},
|
|
71
|
+
6010: {
|
|
72
|
+
code: 6010,
|
|
73
|
+
name: "SessionExpired",
|
|
74
|
+
message: "Session has expired",
|
|
75
|
+
suggestion: "The session exceeded its 20-slot window. Retry the operation — a new session will be created.",
|
|
76
|
+
},
|
|
77
|
+
6011: {
|
|
78
|
+
code: 6011,
|
|
79
|
+
name: "SessionNotAuthorized",
|
|
80
|
+
message: "Session not authorized",
|
|
81
|
+
suggestion: "The validate_and_authorize step may have failed. Check vault status and policy compliance.",
|
|
82
|
+
},
|
|
83
|
+
6012: {
|
|
84
|
+
code: 6012,
|
|
85
|
+
name: "InvalidSession",
|
|
86
|
+
message: "Invalid session: does not belong to this vault",
|
|
87
|
+
suggestion: "Ensure you are using the correct vault address for this session.",
|
|
88
|
+
},
|
|
89
|
+
6013: {
|
|
90
|
+
code: 6013,
|
|
91
|
+
name: "OpenPositionsExist",
|
|
92
|
+
message: "Vault has open positions, cannot close",
|
|
93
|
+
suggestion: "Close all open positions before closing the vault.",
|
|
94
|
+
},
|
|
95
|
+
6014: {
|
|
96
|
+
code: 6014,
|
|
97
|
+
name: "TooManyAllowedTokens",
|
|
98
|
+
message: "Policy configuration invalid: too many allowed tokens",
|
|
99
|
+
suggestion: "Maximum 10 allowed tokens. Remove tokens you no longer need.",
|
|
100
|
+
},
|
|
101
|
+
6015: {
|
|
102
|
+
code: 6015,
|
|
103
|
+
name: "TooManyAllowedProtocols",
|
|
104
|
+
message: "Policy configuration invalid: too many allowed protocols",
|
|
105
|
+
suggestion: "Maximum 10 allowed protocols. Remove protocols you no longer need.",
|
|
106
|
+
},
|
|
107
|
+
6016: {
|
|
108
|
+
code: 6016,
|
|
109
|
+
name: "AgentAlreadyRegistered",
|
|
110
|
+
message: "Agent already registered for this vault",
|
|
111
|
+
suggestion: "Use shield_revoke_agent first, then register the new agent.",
|
|
112
|
+
},
|
|
113
|
+
6017: {
|
|
114
|
+
code: 6017,
|
|
115
|
+
name: "NoAgentRegistered",
|
|
116
|
+
message: "No agent registered for this vault",
|
|
117
|
+
suggestion: "Use shield_register_agent to register an agent before executing trades.",
|
|
118
|
+
},
|
|
119
|
+
6018: {
|
|
120
|
+
code: 6018,
|
|
121
|
+
name: "VaultNotFrozen",
|
|
122
|
+
message: "Vault is not frozen (expected frozen for reactivation)",
|
|
123
|
+
suggestion: "Only frozen vaults can be reactivated. The vault may already be active.",
|
|
124
|
+
},
|
|
125
|
+
6019: {
|
|
126
|
+
code: 6019,
|
|
127
|
+
name: "VaultAlreadyClosed",
|
|
128
|
+
message: "Vault is already closed",
|
|
129
|
+
suggestion: "This vault has been permanently closed. Create a new vault instead.",
|
|
130
|
+
},
|
|
131
|
+
6020: {
|
|
132
|
+
code: 6020,
|
|
133
|
+
name: "InsufficientBalance",
|
|
134
|
+
message: "Insufficient vault balance for withdrawal",
|
|
135
|
+
suggestion: "Use shield_check_vault to verify balances. Deposit more funds or reduce the withdrawal amount.",
|
|
136
|
+
},
|
|
137
|
+
6021: {
|
|
138
|
+
code: 6021,
|
|
139
|
+
name: "DeveloperFeeTooHigh",
|
|
140
|
+
message: "Developer fee rate exceeds maximum (50 / 1,000,000 = 0.5 BPS)",
|
|
141
|
+
suggestion: "Set developerFeeRate to 50 or less (maximum 0.005%).",
|
|
142
|
+
},
|
|
143
|
+
6022: {
|
|
144
|
+
code: 6022,
|
|
145
|
+
name: "InvalidFeeDestination",
|
|
146
|
+
message: "Fee destination account invalid",
|
|
147
|
+
suggestion: "Provide a valid Solana public key for the fee destination.",
|
|
148
|
+
},
|
|
149
|
+
6023: {
|
|
150
|
+
code: 6023,
|
|
151
|
+
name: "InvalidProtocolTreasury",
|
|
152
|
+
message: "Protocol treasury account does not match expected address",
|
|
153
|
+
suggestion: "This is an internal error. The protocol treasury address is hardcoded.",
|
|
154
|
+
},
|
|
155
|
+
6024: {
|
|
156
|
+
code: 6024,
|
|
157
|
+
name: "TooManySpendEntries",
|
|
158
|
+
message: "Spend entry limit reached (too many active entries in rolling window)",
|
|
159
|
+
suggestion: "Wait for older entries to expire from the 24h rolling window.",
|
|
160
|
+
},
|
|
161
|
+
6025: {
|
|
162
|
+
code: 6025,
|
|
163
|
+
name: "InvalidAgentKey",
|
|
164
|
+
message: "Invalid agent: cannot be the zero address",
|
|
165
|
+
suggestion: "Provide a valid Solana public key for the agent.",
|
|
166
|
+
},
|
|
167
|
+
6026: {
|
|
168
|
+
code: 6026,
|
|
169
|
+
name: "AgentIsOwner",
|
|
170
|
+
message: "Invalid agent: agent cannot be the vault owner",
|
|
171
|
+
suggestion: "The agent key must be different from the vault owner. Use a separate keypair.",
|
|
172
|
+
},
|
|
173
|
+
6027: {
|
|
174
|
+
code: 6027,
|
|
175
|
+
name: "Overflow",
|
|
176
|
+
message: "Arithmetic overflow",
|
|
177
|
+
suggestion: "The amount is too large. Reduce the value and try again.",
|
|
178
|
+
},
|
|
179
|
+
};
|
|
180
|
+
exports.ERROR_MAP = ERROR_MAP;
|
|
181
|
+
/**
|
|
182
|
+
* Look up an Anchor error code and return a structured ErrorInfo.
|
|
183
|
+
* Falls back to a generic message for unknown codes.
|
|
184
|
+
*/
|
|
185
|
+
function lookupError(code) {
|
|
186
|
+
return (ERROR_MAP[code] ?? {
|
|
187
|
+
code,
|
|
188
|
+
name: "UnknownError",
|
|
189
|
+
message: `Unknown Anchor error code ${code}`,
|
|
190
|
+
suggestion: "Check the transaction logs for details.",
|
|
191
|
+
});
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Extract an Anchor error code from a thrown error.
|
|
195
|
+
* Returns null if not an Anchor program error.
|
|
196
|
+
*/
|
|
197
|
+
function extractAnchorErrorCode(error) {
|
|
198
|
+
if (error && typeof error === "object") {
|
|
199
|
+
// Anchor errors have an `error.code` or `code` property
|
|
200
|
+
const e = error;
|
|
201
|
+
if (typeof e.code === "number" && e.code >= 6000) {
|
|
202
|
+
return e.code;
|
|
203
|
+
}
|
|
204
|
+
// AnchorError format
|
|
205
|
+
if (e.error &&
|
|
206
|
+
typeof e.error === "object" &&
|
|
207
|
+
typeof e.error.errorCode === "object") {
|
|
208
|
+
const errorCode = e.error
|
|
209
|
+
.errorCode;
|
|
210
|
+
if (typeof errorCode.number === "number") {
|
|
211
|
+
return errorCode.number;
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
return null;
|
|
216
|
+
}
|
|
217
|
+
/**
|
|
218
|
+
* Format any error into a user-friendly MCP tool response.
|
|
219
|
+
*/
|
|
220
|
+
function formatError(error) {
|
|
221
|
+
// Anchor program error
|
|
222
|
+
const code = extractAnchorErrorCode(error);
|
|
223
|
+
if (code !== null) {
|
|
224
|
+
const info = lookupError(code);
|
|
225
|
+
return (`Error: ${info.message} (${info.name}, code ${info.code})\n` +
|
|
226
|
+
`Suggestion: ${info.suggestion}`);
|
|
227
|
+
}
|
|
228
|
+
// Network / RPC error
|
|
229
|
+
if (error instanceof Error) {
|
|
230
|
+
if (error.message.includes("failed to send transaction") ||
|
|
231
|
+
error.message.includes("Transaction simulation failed")) {
|
|
232
|
+
return (`Transaction failed: ${error.message}\n` +
|
|
233
|
+
"Suggestion: Check that the RPC endpoint is reachable and the account has enough SOL for fees.");
|
|
234
|
+
}
|
|
235
|
+
if (error.message.includes("Account does not exist") ||
|
|
236
|
+
error.message.includes("could not find account")) {
|
|
237
|
+
return (`Account not found: ${error.message}\n` +
|
|
238
|
+
"Suggestion: Verify the vault address is correct. The vault may not have been created yet.");
|
|
239
|
+
}
|
|
240
|
+
return `Error: ${error.message}`;
|
|
241
|
+
}
|
|
242
|
+
return `Error: ${String(error)}`;
|
|
243
|
+
}
|
|
244
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
|