nirium-mcp 0.5.0 → 0.6.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 +5 -5
- package/dist/index.js +126 -9
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# nirium-mcp
|
|
2
2
|
|
|
3
|
-
Model Context Protocol server for [Nirium](https://nirium.xyz) — exposes market data, autonomous treasury loop control, and x402/MPP paid
|
|
3
|
+
Model Context Protocol server for [Nirium](https://nirium.xyz) — exposes market data, autonomous treasury loop control, and x402/MPP paid endpoints to any MCP-compatible AI: Claude, GPT, Cursor, VS Code Copilot, and others.
|
|
4
4
|
|
|
5
5
|
Software-only. This server never holds funds — paid tools sign per-request payments from a Stellar wallet you control via `STELLAR_SECRET_KEY`.
|
|
6
6
|
|
|
@@ -44,12 +44,12 @@ No install needed — run directly with `npx`, or add to your MCP client config.
|
|
|
44
44
|
- `stop_loop` — stop it
|
|
45
45
|
|
|
46
46
|
**Paid via x402 — requires a funded `STELLAR_SECRET_KEY`**
|
|
47
|
-
- `get_premium_signals` — $0.02 USDC —
|
|
48
|
-
- `get_premium_market` — $0.05 USDC —
|
|
49
|
-
- `execute_paid_strategy` — $0.25 USDC —
|
|
47
|
+
- `get_premium_signals` — $0.02 USDC — **testnet only**; signals come from the autonomous loop, which runs on testnet. They reference testnet tokens, which have no monetary value, and are not a recommendation to buy, sell or hold anything. The mainnet box returns 501 without charging.
|
|
48
|
+
- `get_premium_market` — $0.05 USDC — market state with reference rates attributed to their source, fee pressure and network conditions. Factual data, no advice.
|
|
49
|
+
- `execute_paid_strategy` — $0.25 USDC — **testnet only**; execution needs a signing key and the mainnet box holds none by design, so it returns 501 without charging.
|
|
50
50
|
|
|
51
51
|
**Paid via MPP — requires a funded `STELLAR_SECRET_KEY`**
|
|
52
|
-
- `get_mpp_signals` — $0.02 USDC — same
|
|
52
|
+
- `get_mpp_signals` — $0.02 USDC — same data and same testnet-only limit as `get_premium_signals`, settled via direct Soroban SAC transfer with no external facilitator
|
|
53
53
|
- `get_mpp_market` — $0.05 USDC — same as `get_premium_market`, MPP-settled
|
|
54
54
|
|
|
55
55
|
## Environment variables
|
package/dist/index.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
// Copyright 2026 Nirium Protocol Contributors
|
|
5
5
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
6
|
// ═══════════════════════════════════════════════════════════════
|
|
7
|
-
// Nirium MCP Server v0.
|
|
7
|
+
// Nirium MCP Server v0.6.0 — x402 + MPP + node tool suite
|
|
8
8
|
// ═══════════════════════════════════════════════════════════════
|
|
9
9
|
//
|
|
10
10
|
// Exposes Nirium Protocol capabilities to any MCP-compatible AI:
|
|
@@ -130,7 +130,7 @@ else {
|
|
|
130
130
|
console.error(`[Nirium MCP] MPP tools disabled — ${PAYMENTS_DISABLED_REASON}`);
|
|
131
131
|
}
|
|
132
132
|
// ─── Server ───────────────────────────────────────────────────
|
|
133
|
-
const server = new mcp_js_1.McpServer({ name: 'nirium-mcp-server', version: '0.
|
|
133
|
+
const server = new mcp_js_1.McpServer({ name: 'nirium-mcp-server', version: '0.6.0' }, { capabilities: { tools: {} } });
|
|
134
134
|
const text = (body) => ({ content: [{ type: 'text', text: typeof body === 'string' ? body : JSON.stringify(body, null, 2) }] });
|
|
135
135
|
const fail = (message) => ({ content: [{ type: 'text', text: message }], isError: true });
|
|
136
136
|
// Un pago sin wallet o sin RPC de mainnet no puede firmarse: decirlo aquí evita
|
|
@@ -201,11 +201,11 @@ server.tool('execute_demo', 'Dry-run a strategy via Soroban simulation — no re
|
|
|
201
201
|
// Cost: $0.02 USDC per signals call, $0.05 per market call, $0.25 per execution.
|
|
202
202
|
// Requires STELLAR_SECRET_KEY env var with funded testnet wallet.
|
|
203
203
|
//
|
|
204
|
-
server.tool('get_premium_signals', 'PAID ($0.02 USDC via x402) —
|
|
204
|
+
server.tool('get_premium_signals', 'PAID ($0.02 USDC via x402) — TESTNET ONLY: signals are produced by the autonomous loop, which runs on testnet; the mainnet box has no loop and returns 501 without charging. Signals reference testnet tokens, which have no monetary value, and are not a recommendation to buy, sell or hold anything. Requires funded Stellar wallet.', {
|
|
205
205
|
count: zod_1.z.number().optional().describe('Number of signals to fetch (default: 20, max: 100)'),
|
|
206
206
|
}, async (args) => paymentsUnavailable()
|
|
207
207
|
?? callJson(`${API_URL}/api/v1/premium/signals?count=${args.count || 20}`, undefined, paidFetch));
|
|
208
|
-
server.tool('get_premium_market', 'PAID ($0.05 USDC via x402) —
|
|
208
|
+
server.tool('get_premium_market', 'PAID ($0.05 USDC via x402) — Market state with reference rates attributed to their source, network fee pressure, and a description of current network conditions. Factual data only: no recommendation, no advice, no signal to act. Requires funded Stellar wallet.', {}, async () => paymentsUnavailable()
|
|
209
209
|
?? callJson(`${API_URL}/api/v1/premium/market`, undefined, paidFetch));
|
|
210
210
|
server.tool('execute_paid_strategy', 'PAID ($0.25 USDC via x402) — Execute a DeFi strategy on Stellar via Soroban. No Nirium account required — pay per execution. Requires funded Stellar wallet.', {
|
|
211
211
|
strategy: zod_1.z.string().describe('Strategy: flash-loan-arb | path-arbitrage | cross-dex | blend-yield | soroswap-swap'),
|
|
@@ -226,8 +226,17 @@ server.tool('get_wallet_info', 'Show the x402 + MPP wallet address and payment c
|
|
|
226
226
|
x402Enabled: PAYMENTS_ENABLED,
|
|
227
227
|
mppEnabled: PAYMENTS_ENABLED,
|
|
228
228
|
...(PAYMENTS_ENABLED ? {} : { paymentsDisabledReason: PAYMENTS_DISABLED_REASON }),
|
|
229
|
-
freeTools: [
|
|
230
|
-
|
|
229
|
+
freeTools: [
|
|
230
|
+
'get_market_state', 'get_loop_status', 'execute_demo', 'get_nodes',
|
|
231
|
+
'anchor_audit_record', 'get_reporting_summary',
|
|
232
|
+
'get_treasury_info', 'get_treasury_vault', 'get_treasury_vaults', 'get_treasury_strategy_asset',
|
|
233
|
+
],
|
|
234
|
+
authenticatedTools: [
|
|
235
|
+
'start_loop', 'stop_loop',
|
|
236
|
+
'deploy_treasury_vault', 'deposit_to_treasury_vault', 'withdraw_from_treasury_vault',
|
|
237
|
+
'set_treasury_rebalance_manager', 'build_treasury_rebalance', 'execute_treasury_rebalance',
|
|
238
|
+
'submit_treasury_tx',
|
|
239
|
+
],
|
|
231
240
|
paidToolsX402: ['get_premium_signals', 'get_premium_market', 'execute_paid_strategy'],
|
|
232
241
|
paidToolsMpp: ['get_mpp_signals', 'get_mpp_market'],
|
|
233
242
|
}));
|
|
@@ -273,17 +282,125 @@ server.tool('get_reporting_summary', 'Institutional-format summary of settled pa
|
|
|
273
282
|
// Advantage over x402: no Coinbase facilitator dependency.
|
|
274
283
|
// Both x402 and MPP tools are available — client chooses.
|
|
275
284
|
//
|
|
276
|
-
server.tool('get_mpp_signals', 'PAID ($0.02 USDC via MPP Charge) —
|
|
285
|
+
server.tool('get_mpp_signals', 'PAID ($0.02 USDC via MPP Charge) — TESTNET ONLY, same data as get_premium_signals, settled via direct Soroban SAC transfer with no external facilitator. Testnet tokens have no monetary value; this is not a recommendation to buy, sell or hold anything. Requires funded Stellar wallet.', {
|
|
277
286
|
count: zod_1.z.number().optional().describe('Number of signals to fetch (default: 20, max: 100)'),
|
|
278
287
|
}, async (args) => paymentsUnavailable()
|
|
279
288
|
?? callJson(`${API_URL}/api/v1/mpp/signals?count=${args.count || 20}`, undefined, mppFetch));
|
|
280
|
-
server.tool('get_mpp_market', 'PAID ($0.05 USDC via MPP Charge) —
|
|
289
|
+
server.tool('get_mpp_market', 'PAID ($0.05 USDC via MPP Charge) — Market state settled via direct Soroban SAC transfer, no external facilitator. Reference rates with their source, fee pressure, and network conditions. Factual data only: no recommendation or advice. Requires funded Stellar wallet.', {}, async () => paymentsUnavailable()
|
|
281
290
|
?? callJson(`${API_URL}/api/v1/mpp/market`, undefined, mppFetch));
|
|
291
|
+
// ─── TREASURY (DeFindex) ───────────────────────────────────────
|
|
292
|
+
//
|
|
293
|
+
// Nirium never holds these funds. It holds the RebalanceManager role of a
|
|
294
|
+
// DeFindex vault the client deploys and owns. The four read tools below hit
|
|
295
|
+
// public GET routes — free, no key required. The write tools hit routes
|
|
296
|
+
// behind the agent's own auth (NIRIUM_API_KEY) and every one of them returns
|
|
297
|
+
// an UNSIGNED XDR *except* execute_treasury_rebalance, which is the one
|
|
298
|
+
// route the agent signs itself, with its own server-side key — never the
|
|
299
|
+
// caller's. Even then it cannot withdraw: rebalance() takes no destination
|
|
300
|
+
// address, so the funds never leave the vault.
|
|
301
|
+
//
|
|
302
|
+
server.tool('get_treasury_info', 'Treasury node metadata: what role Nirium holds on DeFindex vaults, what it can and cannot do, fees, security notes. Free.', {}, async () => callJson(`${API_URL}/api/treasury/info`));
|
|
303
|
+
server.tool('get_treasury_vault', "Read a DeFindex vault's roles, assets and managed funds. Pass `holder` to also get that account's balance in the vault's asset. Free.", {
|
|
304
|
+
vaultId: zod_1.z.string().describe('Vault contract id (C...)'),
|
|
305
|
+
holder: zod_1.z.string().optional().describe('Stellar account (G...) to check the balance of'),
|
|
306
|
+
}, async (args) => {
|
|
307
|
+
const q = args.holder ? `?holder=${encodeURIComponent(args.holder)}` : '';
|
|
308
|
+
return callJson(`${API_URL}/api/treasury/vault/${args.vaultId}${q}`);
|
|
309
|
+
});
|
|
310
|
+
server.tool('get_treasury_vaults', 'List DeFindex vaults Nirium has deployed or read, on the current network. Free.', {
|
|
311
|
+
manager: zod_1.z.string().optional().describe('Filter by vault Manager (G...)'),
|
|
312
|
+
}, async (args) => {
|
|
313
|
+
const q = args.manager ? `?manager=${encodeURIComponent(args.manager)}` : '';
|
|
314
|
+
return callJson(`${API_URL}/api/treasury/vaults${q}`);
|
|
315
|
+
});
|
|
316
|
+
server.tool('get_treasury_strategy_asset', 'Read which asset a DeFindex strategy manages, as declared by the strategy itself — pairs it correctly before deploying a vault. Free.', {
|
|
317
|
+
strategyId: zod_1.z.string().describe('Strategy contract id (C...)'),
|
|
318
|
+
}, async (args) => callJson(`${API_URL}/api/treasury/strategy/${args.strategyId}`));
|
|
319
|
+
server.tool('deploy_treasury_vault', "Build an UNSIGNED XDR to deploy a DeFindex vault. `manager` keeps control (rescue, pause, revoke); Nirium only ever holds `rebalanceManager`, which cannot withdraw or change roles. Sign the returned XDR with `caller` and broadcast it with submit_treasury_tx. Requires NIRIUM_API_KEY env var.", {
|
|
320
|
+
manager: zod_1.z.string().describe('Stellar account (G...) that owns and controls the vault'),
|
|
321
|
+
caller: zod_1.z.string().describe('Stellar account (G...) that pays to deploy and signs the returned XDR'),
|
|
322
|
+
assets: zod_1.z.array(zod_1.z.object({
|
|
323
|
+
address: zod_1.z.string().describe('Asset contract id (C...)'),
|
|
324
|
+
strategies: zod_1.z.array(zod_1.z.object({
|
|
325
|
+
address: zod_1.z.string().describe('Strategy contract id (C...)'),
|
|
326
|
+
name: zod_1.z.string(),
|
|
327
|
+
})).min(1),
|
|
328
|
+
})).min(1),
|
|
329
|
+
name: zod_1.z.string(),
|
|
330
|
+
symbol: zod_1.z.string(),
|
|
331
|
+
emergencyManager: zod_1.z.string().optional().describe('Defaults to `manager`'),
|
|
332
|
+
feeReceiver: zod_1.z.string().optional().describe('Defaults to `manager`'),
|
|
333
|
+
rebalanceManager: zod_1.z.string().optional().describe("Defaults to Nirium's configured role address; required as an explicit value on mainnet"),
|
|
334
|
+
}, async (args) => callJson(`${API_URL}/api/treasury/deploy`, {
|
|
335
|
+
method: 'POST',
|
|
336
|
+
headers: { 'Content-Type': 'application/json', ...authHeaders() },
|
|
337
|
+
body: JSON.stringify(args),
|
|
338
|
+
}));
|
|
339
|
+
server.tool('deposit_to_treasury_vault', 'Build an UNSIGNED XDR to deposit into a DeFindex vault. Sign with `from` and broadcast it with submit_treasury_tx. Requires NIRIUM_API_KEY env var.', {
|
|
340
|
+
vault: zod_1.z.string().describe('Vault contract id (C...)'),
|
|
341
|
+
from: zod_1.z.string().describe('Stellar account (G...) funding the deposit and signing the returned XDR'),
|
|
342
|
+
amounts: zod_1.z.array(zod_1.z.string()).min(1).describe('One amount per vault asset, in stroops, as strings — an i128 does not survive a JSON number'),
|
|
343
|
+
invest: zod_1.z.boolean().optional().describe('Invest the deposit into the strategy immediately. Default true.'),
|
|
344
|
+
maxSlippageBps: zod_1.z.number().optional(),
|
|
345
|
+
}, async (args) => callJson(`${API_URL}/api/treasury/deposit`, {
|
|
346
|
+
method: 'POST',
|
|
347
|
+
headers: { 'Content-Type': 'application/json', ...authHeaders() },
|
|
348
|
+
body: JSON.stringify(args),
|
|
349
|
+
}));
|
|
350
|
+
server.tool('withdraw_from_treasury_vault', 'Build an UNSIGNED XDR to withdraw from a DeFindex vault. Omit `shares` to withdraw everything the account holds. Sign with `from` and broadcast it with submit_treasury_tx. Requires NIRIUM_API_KEY env var.', {
|
|
351
|
+
vault: zod_1.z.string().describe('Vault contract id (C...)'),
|
|
352
|
+
from: zod_1.z.string().describe('Stellar account (G...) holding the vault shares and signing the returned XDR'),
|
|
353
|
+
shares: zod_1.z.string().optional().describe('Vault shares to redeem, as an integer string. Omit to withdraw everything.'),
|
|
354
|
+
maxSlippageBps: zod_1.z.number().optional(),
|
|
355
|
+
}, async (args) => callJson(`${API_URL}/api/treasury/withdraw`, {
|
|
356
|
+
method: 'POST',
|
|
357
|
+
headers: { 'Content-Type': 'application/json', ...authHeaders() },
|
|
358
|
+
body: JSON.stringify(args),
|
|
359
|
+
}));
|
|
360
|
+
server.tool('set_treasury_rebalance_manager', "Build an UNSIGNED XDR handing the RebalanceManager role to a new address. Only the vault's current Manager can sign it — the same door that grants Nirium the role also revokes it. Requires NIRIUM_API_KEY env var.", {
|
|
361
|
+
vault: zod_1.z.string().describe('Vault contract id (C...)'),
|
|
362
|
+
manager: zod_1.z.string().describe("The vault's current Manager (G...), who must sign the returned XDR"),
|
|
363
|
+
rebalanceManager: zod_1.z.string().describe('The new RebalanceManager address (G...)'),
|
|
364
|
+
}, async (args) => callJson(`${API_URL}/api/treasury/set-rebalance-manager`, {
|
|
365
|
+
method: 'POST',
|
|
366
|
+
headers: { 'Content-Type': 'application/json', ...authHeaders() },
|
|
367
|
+
body: JSON.stringify(args),
|
|
368
|
+
}));
|
|
369
|
+
const treasuryInstruction = zod_1.z.object({
|
|
370
|
+
kind: zod_1.z.enum(['Unwind', 'Invest']),
|
|
371
|
+
strategy: zod_1.z.string().describe('Strategy contract id (C...)'),
|
|
372
|
+
amount: zod_1.z.string().describe('Stroops, as a string — an i128 does not survive a JSON number'),
|
|
373
|
+
});
|
|
374
|
+
server.tool('build_treasury_rebalance', "Build an UNSIGNED rebalance XDR — Unwind/Invest between a vault's own strategies only; no other instruction is expressible, and none takes a destination address. Sign with the vault's RebalanceManager and broadcast it with submit_treasury_tx. Requires NIRIUM_API_KEY env var.", {
|
|
375
|
+
vault: zod_1.z.string().describe('Vault contract id (C...)'),
|
|
376
|
+
instructions: zod_1.z.array(treasuryInstruction).min(1),
|
|
377
|
+
caller: zod_1.z.string().optional().describe("Defaults to Nirium's configured rebalanceManager address"),
|
|
378
|
+
}, async (args) => callJson(`${API_URL}/api/treasury/rebalance`, {
|
|
379
|
+
method: 'POST',
|
|
380
|
+
headers: { 'Content-Type': 'application/json', ...authHeaders() },
|
|
381
|
+
body: JSON.stringify(args),
|
|
382
|
+
}));
|
|
383
|
+
server.tool('execute_treasury_rebalance', "Sign and submit a rebalance with Nirium's OWN RebalanceManager key, server-side, and wait for confirmation — the only treasury tool that signs anything itself, and it still cannot withdraw funds. Only available where that key actually lives; a receive-only mainnet box returns 501 by design, not a broken 500. Requires NIRIUM_API_KEY env var.", {
|
|
384
|
+
vault: zod_1.z.string().describe('Vault contract id (C...)'),
|
|
385
|
+
instructions: zod_1.z.array(treasuryInstruction).min(1),
|
|
386
|
+
caller: zod_1.z.string().optional().describe("Defaults to Nirium's configured rebalanceManager address"),
|
|
387
|
+
}, async (args) => callJson(`${API_URL}/api/treasury/rebalance/execute`, {
|
|
388
|
+
method: 'POST',
|
|
389
|
+
headers: { 'Content-Type': 'application/json', ...authHeaders() },
|
|
390
|
+
body: JSON.stringify(args),
|
|
391
|
+
}));
|
|
392
|
+
server.tool('submit_treasury_tx', 'Broadcast a treasury XDR you already signed (deploy/deposit/withdraw/rebalance/set-rebalance-manager) and wait for confirmation. Requires NIRIUM_API_KEY env var.', {
|
|
393
|
+
xdr: zod_1.z.string().describe('Signed transaction XDR'),
|
|
394
|
+
}, async (args) => callJson(`${API_URL}/api/treasury/submit`, {
|
|
395
|
+
method: 'POST',
|
|
396
|
+
headers: { 'Content-Type': 'application/json', ...authHeaders() },
|
|
397
|
+
body: JSON.stringify(args),
|
|
398
|
+
}));
|
|
282
399
|
// ─── Start ────────────────────────────────────────────────────
|
|
283
400
|
async function main() {
|
|
284
401
|
const transport = new stdio_js_1.StdioServerTransport();
|
|
285
402
|
await server.connect(transport);
|
|
286
|
-
console.error('[Nirium MCP] v0.
|
|
403
|
+
console.error('[Nirium MCP] v0.6.0 running on stdio');
|
|
287
404
|
console.error(`[Nirium MCP] Agent API: ${API_URL}`);
|
|
288
405
|
console.error(`[Nirium MCP] NIRIUM_API_KEY set: ${!!NIRIUM_API_KEY}`);
|
|
289
406
|
console.error(`[Nirium MCP] x402 enabled: ${!!STELLAR_KEY}`);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nirium-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "Model Context Protocol server for Nirium — exposes market data, autonomous loop control, and x402/MPP paid signals to any MCP-compatible AI (Claude, GPT, Cursor, VS Code Copilot).",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"bin": {
|