@purseragents/mcp 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +11 -2
- package/dist/index.js +134 -0
- package/dist/units.js +1 -0
- package/package.json +19 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Purser
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @purseragents/mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An MCP server (stdio) that gives an AI agent its Purser account as tools.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
PURSER_ENGINE_URL=http://localhost:8787 PURSER_API_KEY=prs_... npx @purseragents/mcp
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Tools: `purser_account`, `purser_rules`, `purser_pay`, `purser_check_payment`, `purser_receipts`,
|
|
10
|
+
`purser_x402_fetch`, `purser_sell`, `purser_services`, `purser_invoice`, `purser_pay_invoice`, `purser_pnl`.
|
|
11
|
+
Amounts are whole units ("2.50"). Every payment goes through the account's rules and the firewall; a blocked payment
|
|
12
|
+
is reported with its reasons and nothing is sent.
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Purser MCP server (stdio). Gives an AI agent its own Purser account as tools.
|
|
4
|
+
*
|
|
5
|
+
* PURSER_ENGINE_URL=http://localhost:8787 PURSER_API_KEY=prs_... npx @purseragents/mcp
|
|
6
|
+
*
|
|
7
|
+
* Every payment goes through the account's rules and the firewall; a blocked payment is reported with its reasons.
|
|
8
|
+
*/
|
|
9
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
10
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
11
|
+
import { Purser } from "@purseragents/sdk";
|
|
12
|
+
import { z } from "zod";
|
|
13
|
+
import { formatUnits, parseUnits } from "./units.js";
|
|
14
|
+
export function createServer(purser) {
|
|
15
|
+
const server = new McpServer({ name: "purser", version: "0.1.0" });
|
|
16
|
+
let cached = null;
|
|
17
|
+
async function me() {
|
|
18
|
+
if (cached)
|
|
19
|
+
return cached;
|
|
20
|
+
const [who, cfg] = await Promise.all([purser.me(), purser.config()]);
|
|
21
|
+
const tokens = cfg.tokens ?? [];
|
|
22
|
+
cached = { safe: who.safe, usdg: tokens.find((t) => t.symbol === "USDG")?.address ?? "", tokens };
|
|
23
|
+
return cached;
|
|
24
|
+
}
|
|
25
|
+
async function token(symbol = "USDG") {
|
|
26
|
+
const m = await me();
|
|
27
|
+
const t = m.tokens.find((x) => x.symbol.toUpperCase() === symbol.toUpperCase());
|
|
28
|
+
if (!t)
|
|
29
|
+
throw new Error(`Unknown token ${symbol}. Use USDG or ETH.`);
|
|
30
|
+
return t;
|
|
31
|
+
}
|
|
32
|
+
const text = (s) => ({ content: [{ type: "text", text: s }] });
|
|
33
|
+
const reasons = (v) => v.reasons.filter((r) => r.severity !== "info").map((r) => `- ${r.title}: ${r.detail}`).join("\n");
|
|
34
|
+
const payText = (r) => {
|
|
35
|
+
const s = r.intent.status;
|
|
36
|
+
if (s === "executed")
|
|
37
|
+
return `Paid ${r.intent.money?.display ?? ""} to ${r.intent.to}. Receipt ${r.receipt?.id ?? "pending"}, transaction ${r.intent.txHash}.`;
|
|
38
|
+
if (s === "queued")
|
|
39
|
+
return `Waiting for the owner's approval: ${r.intent.summary}. Intent ${r.intent.id}. Nothing was paid yet.`;
|
|
40
|
+
if (s === "blocked")
|
|
41
|
+
return `Blocked. ${r.verdict.summary}\n${reasons(r.verdict)}\nNothing was paid. Do not try to get around this; tell the user.`;
|
|
42
|
+
if (s === "needs_cosign")
|
|
43
|
+
return `Needs a second signature before it can be paid. Intent ${r.intent.id}.`;
|
|
44
|
+
return `Status ${s}. ${r.intent.error ?? ""}`;
|
|
45
|
+
};
|
|
46
|
+
server.registerTool("purser_account", { title: "My account", description: "The agent's Purser account: balances, what it spent today and what is left, whether it is frozen." }, async () => {
|
|
47
|
+
const a = await purser.accounts.get((await me()).safe);
|
|
48
|
+
const lines = [
|
|
49
|
+
`Account ${a.safe} (${a.name})${a.frozen ? " is FROZEN: no payments are possible until the owner unfreezes it." : ""}`,
|
|
50
|
+
`Balances: ${a.balances.map((b) => b.display).join(", ")}`,
|
|
51
|
+
...a.spentToday.map((s) => `Spent today: ${s.display}${s.remaining ? `, left today: ${formatUnits(BigInt(s.remaining), s.token.decimals)} ${s.token.symbol}` : ""}`),
|
|
52
|
+
`Pending approvals: ${a.pendingApprovals}`,
|
|
53
|
+
];
|
|
54
|
+
return text(lines.join("\n"));
|
|
55
|
+
});
|
|
56
|
+
server.registerTool("purser_rules", { title: "My spending rules", description: "The owner's rules for this agent: budgets, limits, allowed hours, allowlists, approval thresholds." }, async () => {
|
|
57
|
+
const r = await purser.accounts.rules((await me()).safe);
|
|
58
|
+
const show = (v, d, sym) => (v === null ? "no cap" : `${formatUnits(BigInt(v), d)} ${sym}`);
|
|
59
|
+
const lines = r.rules.filter((x) => x.enabled).map((x) => `${x.token.symbol}: up to ${show(x.maxSingle, x.token.decimals, x.token.symbol)} per payment, ${show(x.daily, x.token.decimals, x.token.symbol)} a day, ${show(x.weekly, x.token.decimals, x.token.symbol)} a week; owner approval above ${show(x.approvalAbove, x.token.decimals, x.token.symbol)}`);
|
|
60
|
+
if (r.config.hoursUtc.length)
|
|
61
|
+
lines.push(`Allowed hours (UTC): ${r.config.hoursUtc.join(", ")}`);
|
|
62
|
+
if (r.config.payeeAllowlist)
|
|
63
|
+
lines.push(`Only these payees: ${r.allowlist.join(", ")}`);
|
|
64
|
+
if (r.config.maxPerMinute)
|
|
65
|
+
lines.push(`At most ${r.config.maxPerMinute} payments a minute`);
|
|
66
|
+
return text(lines.join("\n"));
|
|
67
|
+
});
|
|
68
|
+
const payShape = {
|
|
69
|
+
to: z.string().describe("The payee address (0x...)"),
|
|
70
|
+
amount: z.string().describe('Amount in whole units, for example "2.50"'),
|
|
71
|
+
token: z.enum(["USDG", "ETH"]).default("USDG"),
|
|
72
|
+
memo: z.string().optional().describe("What the payment is for"),
|
|
73
|
+
service: z.string().optional().describe('A service id, for example "model:frontier-1"'),
|
|
74
|
+
context: z.string().optional().describe("The request or text that led to this payment. The firewall reads it."),
|
|
75
|
+
};
|
|
76
|
+
server.registerTool("purser_pay", { title: "Pay", description: "Pay from the agent's account. The rules and the firewall check it first; the owner may need to approve.", inputSchema: payShape }, async (a) => {
|
|
77
|
+
const t = await token(a.token);
|
|
78
|
+
const r = await purser.pay({ to: a.to, amount: parseUnits(a.amount, t.decimals), token: t.address, memo: a.memo, service: a.service, trigger: a.context });
|
|
79
|
+
return text(payText(r));
|
|
80
|
+
});
|
|
81
|
+
server.registerTool("purser_check_payment", { title: "Check a payment", description: "Ask the firewall about a payment without making it.", inputSchema: payShape }, async (a) => {
|
|
82
|
+
const t = await token(a.token);
|
|
83
|
+
const v = await purser.checkPayment({ to: a.to, amount: parseUnits(a.amount, t.decimals), token: t.address, service: a.service, trigger: a.context });
|
|
84
|
+
return text(`${v.summary}${v.reasons.length ? `\n${reasons(v)}` : ""}`);
|
|
85
|
+
});
|
|
86
|
+
server.registerTool("purser_receipts", { title: "Receipts", description: "The latest receipts of this account.", inputSchema: { limit: z.number().int().min(1).max(50).default(10) } }, async ({ limit }) => {
|
|
87
|
+
const r = await purser.accounts.receipts((await me()).safe, { limit });
|
|
88
|
+
return text(r.items.map((x) => `${new Date(x.createdAt * 1000).toISOString().slice(0, 16)} ${x.direction === "in" ? "+" : "-"}${x.money.display} ${x.category} ${x.counterpartyName ?? x.counterparty}${x.memo ? ` (${x.memo})` : ""}`).join("\n") || "No receipts yet.");
|
|
89
|
+
});
|
|
90
|
+
server.registerTool("purser_x402_fetch", {
|
|
91
|
+
title: "Fetch a paid URL",
|
|
92
|
+
description: "Fetch a URL that may ask for payment over x402; pays from the account within the rules.",
|
|
93
|
+
inputSchema: { url: z.string().url(), method: z.string().default("GET"), body: z.string().optional(), max_amount: z.string().optional().describe('Most to pay in USDG, e.g. "0.50"'), context: z.string().optional() },
|
|
94
|
+
}, async (a) => {
|
|
95
|
+
const r = await purser.x402Fetch(a.url, { method: a.method, body: a.body, maxAmount: a.max_amount ? parseUnits(a.max_amount, 6) : undefined, trigger: a.context });
|
|
96
|
+
return text(`${r.paid ? "Paid and fetched." : r.status === 402 ? "Not paid." : "Fetched."} HTTP ${r.status}\n${r.body.slice(0, 8000)}`);
|
|
97
|
+
});
|
|
98
|
+
server.registerTool("purser_sell", {
|
|
99
|
+
title: "Sell a service",
|
|
100
|
+
description: "Put a service on sale over x402. Buyers pay into this account; returns the paid URL.",
|
|
101
|
+
inputSchema: { name: z.string(), description: z.string().default(""), price: z.string().describe('Price in USDG, e.g. "0.25"'), pricing: z.enum(["per_call", "per_minute", "subscription"]).default("per_call"), upstream: z.string().url().optional().describe("Where the work is done"), response: z.string().optional().describe("A fixed answer, if there is no upstream") },
|
|
102
|
+
}, async (a) => {
|
|
103
|
+
const s = await purser.store.create({ name: a.name, description: a.description, price: parseUnits(a.price, 6), model: a.pricing, upstream: a.upstream, response: a.response });
|
|
104
|
+
return text(`On sale: ${s.name} at ${s.pricing.price.display} (${s.pricing.model}). Buyers call ${s.endpoint}`);
|
|
105
|
+
});
|
|
106
|
+
server.registerTool("purser_services", { title: "My services", description: "Services this account sells, with uses and revenue." }, async () => {
|
|
107
|
+
const s = await purser.store.list((await me()).safe);
|
|
108
|
+
return text(s.items.map((x) => `${x.name}: ${x.pricing.price.display} ${x.pricing.model}, ${x.uses} uses, revenue ${x.revenue.display}, ${x.endpoint}`).join("\n") || "Nothing on sale.");
|
|
109
|
+
});
|
|
110
|
+
server.registerTool("purser_invoice", { title: "Invoice another agent", description: "Send an invoice; the payer funds an escrow and the money is released on delivery.", inputSchema: { payer: z.string(), amount: z.string().describe("USDG"), description: z.string(), due_in_hours: z.number().default(72) } }, async (a) => {
|
|
111
|
+
const inv = await purser.invoices.create({ payer: a.payer, amount: parseUnits(a.amount, 6), description: a.description, dueInSeconds: Math.round(a.due_in_hours * 3600) });
|
|
112
|
+
return text(`Invoice ${inv.id} for ${inv.money.display} sent to ${inv.payer}.`);
|
|
113
|
+
});
|
|
114
|
+
server.registerTool("purser_pay_invoice", { title: "Pay an invoice", description: "Fund the escrow for an invoice addressed to this account.", inputSchema: { id: z.string() } }, async ({ id }) => {
|
|
115
|
+
const r = await purser.invoices.pay(id);
|
|
116
|
+
return text(payText(r));
|
|
117
|
+
});
|
|
118
|
+
server.registerTool("purser_pnl", { title: "Profit and loss", description: "Income, spending, fees and profit over the last 30 days, with the biggest costs and customers." }, async () => {
|
|
119
|
+
const p = await purser.accounts.pnl((await me()).safe);
|
|
120
|
+
return text([`Income $${p.incomeUsd}, spend $${p.spendUsd}, fees $${p.feesUsd}, profit $${p.profitUsd}`, ...p.byModel.slice(0, 5).map((l) => `Model ${l.label}: $${l.spend}`), ...p.byCustomer.slice(0, 5).map((l) => `Customer ${l.label}: $${l.income}`)].join("\n"));
|
|
121
|
+
});
|
|
122
|
+
return server;
|
|
123
|
+
}
|
|
124
|
+
const isMain = import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("purser-mcp") || process.argv[1]?.endsWith("/src/index.ts") || process.argv[1]?.endsWith("/dist/index.js");
|
|
125
|
+
if (isMain) {
|
|
126
|
+
const baseUrl = process.env.PURSER_ENGINE_URL ?? "http://localhost:8787";
|
|
127
|
+
const apiKey = process.env.PURSER_API_KEY;
|
|
128
|
+
if (!apiKey) {
|
|
129
|
+
process.stderr.write("PURSER_API_KEY is not set.\n");
|
|
130
|
+
process.exit(1);
|
|
131
|
+
}
|
|
132
|
+
const server = createServer(new Purser({ baseUrl, apiKey }));
|
|
133
|
+
await server.connect(new StdioServerTransport());
|
|
134
|
+
}
|
package/dist/units.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { formatUnits, parseUnits } from "viem";
|
package/package.json
CHANGED
|
@@ -1,6 +1,21 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@purseragents/mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "MCP server that gives an AI agent its Purser account: pay, check, balance, rules, receipts, sell, invoices.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"purser-mcp": "dist/index.js"
|
|
9
|
+
},
|
|
10
|
+
"main": "./dist/index.js",
|
|
11
|
+
"files": [
|
|
12
|
+
"dist",
|
|
13
|
+
"README.md"
|
|
14
|
+
],
|
|
15
|
+
"dependencies": {
|
|
16
|
+
"@modelcontextprotocol/sdk": "1.32.2",
|
|
17
|
+
"@purseragents/sdk": "^0.1.0",
|
|
18
|
+
"zod": "4.6.7",
|
|
19
|
+
"viem": "2.57.18"
|
|
20
|
+
}
|
|
21
|
+
}
|