pion-mcp 0.4.0 → 0.4.2

package/README.md

@@ -3,6 +3,8 @@
 **Model Context Protocol server for Pi Network** — connect AI agents
 (Claude, Cursor, and any MCP-compatible client) to Pi Network chain data.
 
+[![pion-mcp MCP server](https://glama.ai/mcp/servers/jleeblack/pion-mcp/badges/card.svg)](https://glama.ai/mcp/servers/jleeblack/pion-mcp)
+
 > ⚠️ **Reads: both networks. Payments: testnet only.** The chain tools query Pi
 > Mainnet or Pi Testnet, selected with `PION_NETWORK`. `send_payment` moves real
 > funds, must be explicitly armed, and *cannot* be armed on mainnet — Pi
@@ -130,8 +132,8 @@ claude mcp add pion -- node /absolute/path/to/pion-mcp/dist/index.js
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `PION_NETWORK` | `testnet` | Which chain the read tools query — `testnet` or `mainnet` |
-| `PION_HORIZON_URL` | derived from `PION_NETWORK` | Horizon base URL, overriding the above |
+| `PION_NETWORK` | `testnet` | Which chain the read tools query — `testnet` or `mainnet`. Mainnet is echoed as **REAL VALUE** in the startup banner |
+| `PION_HORIZON_URL` | derived from `PION_NETWORK` | Override for the Horizon base URL. Optional. If set alongside `PION_NETWORK` the two must name the same chain — a contradiction is a startup error, not a silent winner |
 | `PION_PLATFORM_URL` | `https://api.minepi.com` | Platform API base URL |
 | `PION_ENABLE_PAYMENTS` | unset (off) | Arms `send_payment` — see Tier C above |
 | `PION_MAX_PAYMENT_PI` | unset | Required per-payment ceiling when armed |

package/dist/index.js

@@ -50,8 +50,11 @@ if (process.argv.includes("--help") || process.argv.includes("-h")) {
         "       send_payment (only when explicitly armed — see below)",
         "",
         "Environment:",
-        "  PION_NETWORK       testnet (default) or mainnet — which chain the read tools query",
-        "  PION_HORIZON_URL   Horizon base URL, overriding PION_NETWORK's default",
+        "  PION_NETWORK       testnet (default) or mainnet — which chain the read tools",
+        "                     query. mainnet is echoed as REAL VALUE in the startup banner.",
+        "  PION_HORIZON_URL   Override for the Horizon base URL. Optional; derived from",
+        "                     PION_NETWORK when unset. If both are set they must name the",
+        "                     same chain — a contradiction is a startup error, not a guess.",
         "  PION_PLATFORM_URL  Platform API base URL (default: https://api.minepi.com)",
         "",
         "Reads work on both Pi chains. Payments do not: Pi restricts App-to-User",
@@ -72,29 +75,54 @@ if (NETWORK_ERROR) {
     console.error(`pion-mcp: ${NETWORK_ERROR.message}`);
     process.exit(1);
 }
-const server = new McpServer({ name: "pion-mcp", version: VERSION }, {
-    instructions: `Pion exposes read-only Pi Network data. get_wallet_balance, get_account_payments, ` +
-        `and query_transaction are public ledger reads from Horizon at ${HORIZON_URL} ` +
-        `(${NETWORK.label}), needing no credentials. This server is reading ` +
-        `${NETWORK.label} — every result repeats it in its "network" field, and the two Pi ` +
-        `chains are separate ledgers, so an address funded on one does not exist on the ` +
-        `other. Amounts are decimal strings; Pi itself is ` +
-        'reported as the asset "PI", custom tokens as "CODE:ISSUER", and liquidity-pool ' +
-        'shares as "pool:ID". verify_user is different: it checks a user access token ' +
-        `against the Pi Platform API at ${PLATFORM_URL} and requires the caller to supply ` +
-        "that token. No tool here can send payments, sign anything, or spend from a wallet.",
-});
-registerGetWalletBalance(server, NETWORK);
-registerGetAccountPayments(server, NETWORK);
-registerQueryTransaction(server, NETWORK);
-registerVerifyUser(server);
 // Tier C is registered only when fully armed. A disarmed server does not
 // advertise a payment tool at all, so an agent cannot try to spend and cannot
 // be talked into thinking it might succeed.
 //
 // Passed the resolved network, not the URL: arming turns on what chain this
 // *is*, and a string containing "testnet" is not the same claim.
+//
+// Resolved BEFORE the server is constructed because the instructions below
+// state whether a spend tool exists, and that claim has to be built from the
+// same answer that decides whether one is registered. Until 0.4.2 the check
+// ran afterwards and the instructions said "no tool here can send payments"
+// unconditionally — false on an armed server, which is the one configuration
+// where being wrong about it costs money.
 const payments = checkPaymentsArming(NETWORK);
+/**
+ * Server instructions — the text a client places ahead of the tool catalog.
+ *
+ * Every session pays for this in context, so it carries only what changes a
+ * decision an agent is about to make, and nothing recoverable from a tool
+ * description it will read anyway.
+ *
+ * The cross-chain sentence is the reason this exists. It previously said an
+ * address funded on one chain "does not exist on the other" — measured false
+ * on 2026-08-14 (docs/FINDINGS.md finding 5): one address held 2.06 Pi on
+ * mainnet and 32.29938 Pi on testnet simultaneously. That wording invited
+ * exactly the wrong inference, that a wrong-chain read fails loudly. It does
+ * not; it returns a plausible number. An agent needs the true version before
+ * it reports a figure, not after.
+ */
+const instructions = `Pion reads Pi Network chain data. get_wallet_balance, get_account_payments and ` +
+    `query_transaction are public Horizon reads at ${HORIZON_URL}, needing no ` +
+    `credentials. verify_user checks a caller-supplied user access token against the ` +
+    `Pi Platform API at ${PLATFORM_URL}. ` +
+    `This server reads ${NETWORK.label}, and every result carries a "network" field — ` +
+    `check it before trusting a figure. The two Pi chains are separate ledgers sharing ` +
+    `one address format, and the same address can hold different balances on each: a ` +
+    `wrong-chain read returns a plausible wrong number, not an error. Testnet Pi has no ` +
+    `monetary value. Amounts are decimal strings; Pi is "PI", tokens "CODE:ISSUER", ` +
+    `pool shares "pool:ID". ` +
+    (payments.armed
+        ? `send_payment is ARMED and can spend up to ${payments.config.maxAmountPi} Pi per ` +
+            `call from the app wallet on ${NETWORK.label}; every other tool is read-only.`
+        : "No tool here can send payments, sign anything, or spend from a wallet.");
+const server = new McpServer({ name: "pion-mcp", version: VERSION }, { instructions });
+registerGetWalletBalance(server, NETWORK);
+registerGetAccountPayments(server, NETWORK);
+registerQueryTransaction(server, NETWORK);
+registerVerifyUser(server);
 if (payments.armed) {
     registerSendPayment(server, payments.config);
 }

package/dist/tools/common.d.ts

@@ -15,9 +15,33 @@ import type { PiNetwork } from "../networks.js";
  * wrong number. That is why the network is stated rather than implied.
  */
 export declare function networkNote(network: PiNetwork): string;
-/** Stellar/Pi public key: 56 base32 characters beginning with G. */
+/**
+ * Stellar/Pi public key: 56 base32 characters beginning with G.
+ *
+ * The description states the alphabet, not just the length, because base32
+ * excludes 0/1/8/9 — the characters a human is most likely to introduce when
+ * retyping an address. It also carries an example, and a warning against
+ * reusing it: the regex here proves the *shape*, and nothing more. A different
+ * well-formed address is not rejected, it is answered, so a copied example
+ * returns a real balance belonging to someone else. That is the same silent
+ * wrong answer the network stamp exists to prevent (see `networkNote`).
+ *
+ * Note the checksum is deliberately not verified here. Strkey carries a CRC16
+ * that this regex cannot see, so a mistyped-but-well-formed address reaches
+ * Horizon and comes back as a 400 rather than a local validation error.
+ */
 export declare const walletAddress: z.ZodString;
-/** Stellar transaction hash: 64 hex characters. */
+/**
+ * Stellar transaction hash: 64 hex characters.
+ *
+ * Either case is accepted and `query_transaction` lowercases before the request,
+ * so the description says so rather than implying lower-case-only input.
+ *
+ * The "not a payment id" clause is load-bearing. Pi's A2U flow hands out a
+ * payment identifier and a txid that are different things at different layers
+ * (docs/runbook.md), and an agent holding one of them has no format cue telling
+ * it which endpoint wants which.
+ */
 export declare const transactionHash: z.ZodString;
 export declare const pagingLimit: z.ZodDefault<z.ZodNumber>;
 export declare const pagingCursor: z.ZodOptional<z.ZodString>;

package/dist/tools/common.js

@@ -22,16 +22,48 @@ export function networkNote(network) {
         "looks entirely normal. Testnet Pi has no monetary value: never present a " +
         "testnet balance as real holdings.");
 }
-/** Stellar/Pi public key: 56 base32 characters beginning with G. */
+/**
+ * Stellar/Pi public key: 56 base32 characters beginning with G.
+ *
+ * The description states the alphabet, not just the length, because base32
+ * excludes 0/1/8/9 — the characters a human is most likely to introduce when
+ * retyping an address. It also carries an example, and a warning against
+ * reusing it: the regex here proves the *shape*, and nothing more. A different
+ * well-formed address is not rejected, it is answered, so a copied example
+ * returns a real balance belonging to someone else. That is the same silent
+ * wrong answer the network stamp exists to prevent (see `networkNote`).
+ *
+ * Note the checksum is deliberately not verified here. Strkey carries a CRC16
+ * that this regex cannot see, so a mistyped-but-well-formed address reaches
+ * Horizon and comes back as a 400 rather than a local validation error.
+ */
 export const walletAddress = z
     .string()
-    .regex(/^G[A-Z2-7]{55}$/, "must be a 56-character Pi wallet address starting with G (e.g. GABC...XYZ)")
-    .describe("Pi wallet address (Stellar public key, 56 characters, starts with G)");
-/** Stellar transaction hash: 64 hex characters. */
+    .regex(/^G[A-Z2-7]{55}$/, "must be a Pi wallet address: exactly 56 characters, starting with G, the rest " +
+    "base32 (A-Z and 2-7 only — never 0, 1, 8 or 9)")
+    .describe("Pi wallet address (a Stellar public key): exactly 56 upper-case characters, " +
+    "starting with G, the rest base32 — A-Z and 2-7 only, never 0, 1, 8 or 9. " +
+    "Example: GATQBZLIAUVMND2OCPOKWGPUCNXIGKMNUU7E67YQI2MODSMCMLXBAIJA — that is a " +
+    "format sample, not a default. Pass the address you were actually given: a valid " +
+    "address that is not the intended one returns someone else's balance, not an error.");
+/**
+ * Stellar transaction hash: 64 hex characters.
+ *
+ * Either case is accepted and `query_transaction` lowercases before the request,
+ * so the description says so rather than implying lower-case-only input.
+ *
+ * The "not a payment id" clause is load-bearing. Pi's A2U flow hands out a
+ * payment identifier and a txid that are different things at different layers
+ * (docs/runbook.md), and an agent holding one of them has no format cue telling
+ * it which endpoint wants which.
+ */
 export const transactionHash = z
     .string()
-    .regex(/^[0-9a-fA-F]{64}$/, "must be a 64-character hex transaction hash")
-    .describe("Transaction hash (64 hex characters)");
+    .regex(/^[0-9a-fA-F]{64}$/, "must be a transaction hash: exactly 64 hexadecimal characters (0-9 and a-f)")
+    .describe("On-chain transaction hash: exactly 64 hexadecimal characters (0-9 and a-f). " +
+    "Upper case is accepted and normalized to lower case. This is the Stellar " +
+    "transaction hash — not a Pi payment id, not a ledger sequence number, not a memo. " +
+    "Example: f8b6d6c83dfb32452330b677d901748fb6cece6c36d9b2deff64bead6e1c6925");
 export const pagingLimit = z
     .number()
     .int()

package/dist/tools/get-account-payments.js

@@ -72,7 +72,9 @@ export function registerGetAccountPayments(server, network) {
             "a payment arrived, who funded an account, or what it recently sent. Covers " +
             "payments, account creations, path payments, and account merges. Results are " +
             "paginated: pass the returned `next_cursor` back as `cursor` for the next page. " +
-            "Reads public ledger data only. " +
+            "Reads public ledger data only. An address never funded on this chain returns a " +
+            "not-found error rather than an empty list, so an empty `payments` array means " +
+            "you have paged past the end of the history — not that the account is unused. " +
             networkNote(network),
         inputSchema: {
             address: walletAddress,

package/dist/tools/get-wallet-balance.js

@@ -22,6 +22,9 @@ export function registerGetWalletBalance(server, network) {
             "Call this whenever you need to know how much Pi an address holds, whether it " +
             "holds a particular token, or whether the account exists on-chain at all. " +
             "Reads public ledger data only — it cannot move funds and needs no credentials. " +
+            "An address that has never been funded on this chain is not an account there: the " +
+            "call returns a not-found error rather than a zero balance, so 'absent' and " +
+            "'holds nothing' stay distinguishable. " +
             networkNote(network),
         inputSchema: { address: walletAddress },
         outputSchema,

package/dist/tools/query-transaction.js

@@ -23,7 +23,9 @@ export function registerQueryTransaction(server, network) {
             "which ledger it landed in, who submitted it, the fee charged, and its memo. " +
             "Call this to verify that a specific transaction actually went through — a user " +
             "or another service claiming a payment was made is not proof; this is. " +
-            "Reads public ledger data only. " +
+            "Reads public ledger data only. A hash this chain has no record of returns a " +
+            "not-found error, which is not the same answer as `successful: false` — that " +
+            "means the transaction did reach a ledger and was rejected there. " +
             networkNote(network),
         inputSchema: { hash: transactionHash },
         outputSchema,

package/dist/tools/verify-user.js

@@ -16,16 +16,23 @@ export function registerVerifyUser(server) {
         description: "Check whether a Pi user access token is genuine and, if so, who it belongs to. " +
             "Call this to authenticate someone who claims a Pi identity — never trust a " +
             "client-supplied uid or username on its own; this is the only thing that proves it. " +
-            "Returns `valid: false` with a reason for a rejected token rather than failing. " +
+            "An invalid, expired, or wrong-app token returns `valid: false` with a reason " +
+            "rather than failing; only a transport or server fault is reported as an error. " +
             `Sends the token to the Pi Platform API (${PLATFORM_URL}/v2/me) and nothing else; ` +
             "it is not stored or logged. Note the uid is app-specific — the same person has a " +
-            "different uid under a different Pi app.",
+            "different uid under a different Pi app. Unlike this server's ledger reads, this " +
+            "is an identity check against the Platform API rather than a chain query, so the " +
+            "result carries no `network` field and does not depend on which Pi chain is " +
+            "being read.",
         inputSchema: {
             access_token: z
                 .string()
                 .min(1)
-                .describe("The user's Pi access token, obtained from Pi Browser authentication or Pi " +
-                "Sign-in OAuth. This is a credential — pass the token itself, not a uid."),
+                .describe("The user's Pi access token: an opaque bearer credential with no fixed " +
+                "length or prefix, obtained from Pi Browser authentication " +
+                "(`Pi.authenticate`) or Pi Sign-in OAuth. Pass the token string itself — " +
+                "not a uid, not a username, and not the app's server API key, which is a " +
+                "different credential this tool never accepts."),
         },
         outputSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pion-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Pion — Model Context Protocol (MCP) server for Pi Network. Read-only chain queries against Pi Mainnet and Testnet; payments are testnet-only.",
   "keywords": [
     "mcp",