pion-mcp 0.4.0 → 0.4.1

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.1",
   "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",