obyte-mcp 0.1.2 → 0.2.1

package/README.md

@@ -179,6 +179,59 @@ it per call.
 
 Inspect the live configuration for both networks any time with `obyte_get_network_info`.
 
+## Amounts And Decimals
+
+Raw hub data (balances, AA state vars, payment outputs, AA responses) carries amounts as
+**integers in the asset's smallest units**. The base asset has 9 decimals: `2500000000` bytes
+= `2.5 GBYTE`. Agents that skip this step report wrong numbers, so the server enforces it in
+three ways:
+
+- **Composite tools convert for you.** `obyte_analyze_address`, `obyte_analyze_aa`, and
+  `obyte_get_portfolio_summary` return a `totals_by_asset` / `balance_summary` block with
+  `symbol`, `decimals`, `raw_total`, and `display_total` (already divided by `10^decimals`).
+  Assets that cannot be resolved (e.g. no registry on testnet) are listed in
+  `unresolved_assets` with `display_total: null` — never presented as converted.
+- **Server instructions and tool descriptions** tell agents to never show raw integers and to
+  resolve decimals via `obyte_resolve_asset` / `obyte_get_decimals_by_symbol_or_asset` first,
+  and to convert user-facing amounts *into* smallest units when building AA triggers.
+- **Base aliases work without a registry**: decimals for `base`/`GBYTE`/`MBYTE`/`KBYTE`/`BYTE`
+  are answered locally, even on testnet with no registry configured.
+
+### Asset holders
+
+`obyte_get_asset_holders` returns the **top holders** of any asset (by symbol or asset id),
+sorted by balance descending, with raw and display amounts plus total supply — up to 100
+holders per call. The data comes from the Obyte explorer (a centralized convenience service,
+separate from the hub) and may lag the ledger slightly.
+
+For a human-browsable view, asset tools also return `explorer_asset_url`:
+`https://explorer.obyte.org/asset/<symbol|asset>` (testnet:
+`https://testnetexplorer.obyte.org/asset/<symbol|asset>`). Note: amounts on explorer web pages
+are **already in display units** — only hub tool outputs need decimals conversion.
+
+## Making Agents Use It Automatically
+
+You should not have to tell your agent to use this server. Two mechanisms make it proactive:
+
+1. **MCP server instructions.** At `initialize` the server sends instructions that hosts
+   (Claude Desktop, Claude Code, and others) inject into the agent's context: use `obyte_*`
+   tools whenever the user mentions Obyte, GBYTE/bytes, autonomous agents, or pastes an Obyte
+   identifier (addresses are 32-character base32 strings; unit hashes and asset ids are
+   44-character base64 strings usually ending in `=`), plus the network and decimals rules.
+2. **Trigger-rich tool descriptions.** Each tool description states when to reach for it, so
+   hosts that only surface descriptions still route correctly.
+
+For hosts that ignore server instructions (or to make it extra reliable in a specific project),
+add a line to your project memory file — `CLAUDE.md` (Claude Code) or `AGENTS.md` (Codex):
+
+```markdown
+For anything involving Obyte, GBYTE, bytes, autonomous agents (AAs), Obyte units/addresses,
+or Obyte token symbols, use the obyte MCP server tools (obyte_analyze_address,
+obyte_analyze_unit, obyte_analyze_aa, obyte_resolve_asset, obyte_get_portfolio_summary,
+obyte_prepare_aa_dry_run) without being asked. Pass network:"testnet" for testnet questions.
+Never show raw smallest-unit amounts: use display_total fields or resolve decimals first.
+```
+
 ## Configuration
 
 Precedence, highest first:
@@ -200,6 +253,7 @@ Precedence, highest first:
 | `OBYTE_REQUEST_TIMEOUT_MS` | `--timeout-ms` | both | `20000` | Hub request timeout, `1000..120000` |
 | `OBYTE_MAX_CONCURRENCY` | `--max-concurrency` | both | `4` | Concurrent hub requests, `1..10` |
 | `OBYTE_MAX_OUTPUT_BYTES` | `--max-output-bytes` | both | `262144` | Max tool output bytes, `16384..1048576` |
+| `OBYTE_NO_UPDATE_CHECK` | — | — | unset | Set to disable the npm version check (`NO_UPDATE_NOTIFIER` also respected) |
 
 Default hubs:
 
@@ -215,6 +269,22 @@ Custom hub URL policy (applies to any hub override):
 
 ## Updating
 
+### How users learn about updates
+
+The server checks the npm registry once per process (3s timeout, fail-silent, disable with
+`OBYTE_NO_UPDATE_CHECK=1`) and surfaces the result in three places:
+
+- `obyte_get_network_info` returns an `update` block (`current`, `latest`, `update_available`)
+  — agents are instructed to mention available updates to the user.
+- `obyte-mcp doctor` prints an `update` check line (informational, never fails doctor).
+- On startup an `update_available` diagnostic is written to stderr (visible in client MCP logs).
+
+Users who keep the default unpinned `npx -y obyte-mcp` config get new versions automatically on
+the next client restart — the notification mostly matters for pinned versions, `.mcpb` bundles,
+and global installs. Watch the GitHub repo (Releases) for changelogs.
+
+### How to update
+
 The server runs through `npx`, which resolves the latest published version. How to move to a
 newer release depends on how it is registered:
 
@@ -248,12 +318,13 @@ Check what you are running with `npx -y obyte-mcp --version` and `npx -y obyte-m
 
 Use these first for agent-facing tasks. All accept an optional `network`.
 
-- `obyte_analyze_address`: balances, profile units, definition, attestations, optional history.
+- `obyte_analyze_address`: balances with decimals-aware `balance_summary`, profile units, definition, attestations, optional history.
 - `obyte_analyze_unit`: joint plus optional AA response chain.
-- `obyte_analyze_aa`: AA balances, selected state vars, optional responses.
-- `obyte_resolve_asset`: resolves asset/symbol/decimals in one call.
+- `obyte_analyze_aa`: AA balances with `balance_summary`, selected state vars, optional responses.
+- `obyte_resolve_asset`: resolves asset/symbol/decimals in one call, returns `explorer_asset_url` (holders page).
+- `obyte_get_asset_holders`: top holders of an asset (explorer-sourced), raw + display amounts, supply, up to 100 per call.
 - `obyte_prepare_aa_dry_run`: validates and dry-runs an AA trigger.
-- `obyte_get_portfolio_summary`: balances for up to 20 addresses.
+- `obyte_get_portfolio_summary`: balances for up to 20 addresses with `totals_by_asset` display totals.
 
 ## Raw Hub Tools
 
@@ -491,6 +562,7 @@ Ask your MCP client:
 
 - "Check this Obyte address balances on testnet and explain the assets."
 - "Resolve this asset id to symbol and decimals on mainnet."
+- "Who holds this asset?" (resolves it and links the explorer holders page)
 - "Inspect why this AA trigger failed."
 - "Dry-run this AA trigger on testnet."
 - "Summarize AA state vars with this prefix."

package/dist/amounts.d.ts

@@ -0,0 +1,43 @@
+import type { AaStateVarsReader, SymbolOptions } from "./symbols.js";
+import type { Network } from "./types.js";
+export declare const BASE_DECIMALS = 9;
+export declare const AMOUNTS_NOTE = "Raw on-ledger amounts are integers in the asset's smallest units. display_total is already divided by 10^decimals; present display values to users, never raw integers. base is GBYTE with 9 decimals. explorer_asset_url lists the asset's description and holders (explorer amounts are already in display units).";
+/** Explorer page listing an asset's description and holders. */
+export declare function assetExplorerUrl(network: Network, symbolOrAsset: string): string;
+export interface AssetAmountSummary {
+    asset: string;
+    symbol: string | null;
+    decimals: number | null;
+    raw_total: number;
+    display_total: string | null;
+    explorer_asset_url?: string;
+}
+export interface BalanceAmountSummary {
+    totals_by_asset: Record<string, AssetAmountSummary>;
+    amounts_note: string;
+    unresolved_assets?: string[];
+}
+/**
+ * Converts a raw smallest-units integer into a human display string without
+ * floating point artifacts, e.g. formatAmount(2500000000, 9) === "2.5".
+ */
+export declare function formatAmount(rawAmount: number, decimals: number): string | null;
+/**
+ * Sums raw amounts per asset from either hub balance shape:
+ * - get_balances: { address: { asset: { stable, pending } } }
+ * - AA balances:  { asset: number }
+ */
+export declare function collectAssetTotals(balances: unknown): Record<string, number>;
+export interface SummarizeOptions extends SymbolOptions {
+    resolve?: boolean;
+    maxResolvedAssets?: number;
+    /** When set, each asset summary gets an explorer_asset_url for that network. */
+    network?: Network;
+}
+/**
+ * Builds a per-asset totals summary with symbols, decimals, and display amounts.
+ * base always resolves to GBYTE/9 without touching the registry; custom assets
+ * are resolved through the registry when available, failures degrade to nulls
+ * and are listed in unresolved_assets so agents know to resolve before display.
+ */
+export declare function summarizeBalanceAmounts(reader: AaStateVarsReader, balances: unknown, options?: SummarizeOptions): Promise<BalanceAmountSummary>;

package/dist/amounts.js

@@ -0,0 +1,117 @@
+import { MAINNET_EXPLORER, TESTNET_EXPLORER } from "./constants.js";
+import { isPlainObject } from "./jsonUtils.js";
+import { getDecimalsBySymbolOrAsset, getSymbolByAsset } from "./symbols.js";
+export const BASE_DECIMALS = 9;
+export const AMOUNTS_NOTE = "Raw on-ledger amounts are integers in the asset's smallest units. display_total is already divided by 10^decimals; present display values to users, never raw integers. base is GBYTE with 9 decimals. explorer_asset_url lists the asset's description and holders (explorer amounts are already in display units).";
+/** Explorer page listing an asset's description and holders. */
+export function assetExplorerUrl(network, symbolOrAsset) {
+    const base = network === "testnet" ? TESTNET_EXPLORER : MAINNET_EXPLORER;
+    return `${base}/asset/${encodeURIComponent(symbolOrAsset)}`;
+}
+/**
+ * Converts a raw smallest-units integer into a human display string without
+ * floating point artifacts, e.g. formatAmount(2500000000, 9) === "2.5".
+ */
+export function formatAmount(rawAmount, decimals) {
+    if (typeof rawAmount !== "number" || !Number.isFinite(rawAmount))
+        return null;
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 30)
+        return null;
+    if (decimals === 0)
+        return String(rawAmount);
+    if (!Number.isSafeInteger(rawAmount))
+        return String(rawAmount / 10 ** decimals);
+    const negative = rawAmount < 0;
+    const digits = String(Math.abs(rawAmount)).padStart(decimals + 1, "0");
+    const whole = digits.slice(0, -decimals);
+    const frac = digits.slice(-decimals).replace(/0+$/, "");
+    return `${negative ? "-" : ""}${whole}${frac ? `.${frac}` : ""}`;
+}
+/**
+ * Sums raw amounts per asset from either hub balance shape:
+ * - get_balances: { address: { asset: { stable, pending } } }
+ * - AA balances:  { asset: number }
+ */
+export function collectAssetTotals(balances) {
+    const totals = {};
+    if (!isPlainObject(balances))
+        return totals;
+    const add = (asset, value) => {
+        let raw;
+        if (typeof value === "number") {
+            raw = value;
+        }
+        else if (isPlainObject(value)) {
+            const stable = typeof value.stable === "number" ? value.stable : 0;
+            const pending = typeof value.pending === "number" ? value.pending : 0;
+            raw = stable + pending;
+        }
+        if (raw !== undefined)
+            totals[asset] = (totals[asset] ?? 0) + raw;
+    };
+    for (const [key, entry] of Object.entries(balances)) {
+        const values = isPlainObject(entry) ? Object.values(entry) : [];
+        if (values.length > 0 && values.every((value) => isPlainObject(value))) {
+            // Address -> asset map (get_balances shape); sum across addresses.
+            for (const [asset, value] of Object.entries(entry))
+                add(asset, value);
+        }
+        else {
+            add(key, entry);
+        }
+    }
+    return totals;
+}
+/**
+ * Builds a per-asset totals summary with symbols, decimals, and display amounts.
+ * base always resolves to GBYTE/9 without touching the registry; custom assets
+ * are resolved through the registry when available, failures degrade to nulls
+ * and are listed in unresolved_assets so agents know to resolve before display.
+ */
+export async function summarizeBalanceAmounts(reader, balances, options = {}) {
+    const totals = collectAssetTotals(balances);
+    const customAssets = Object.keys(totals).filter((asset) => asset !== "base");
+    const maxResolved = options.maxResolvedAssets ?? 10;
+    const toResolve = options.resolve === false ? [] : customAssets.slice(0, maxResolved);
+    const resolved = new Map(await Promise.all(toResolve.map(async (asset) => {
+        const [symbol, decimals] = await Promise.all([
+            getSymbolByAsset(reader, asset, options).catch(() => null),
+            getDecimalsBySymbolOrAsset(reader, asset, options).catch(() => null)
+        ]);
+        return [asset, { symbol, decimals }];
+    })));
+    const totalsByAsset = {};
+    const unresolved = [];
+    for (const [asset, rawTotal] of Object.entries(totals)) {
+        if (asset === "base") {
+            totalsByAsset[asset] = {
+                asset,
+                symbol: "GBYTE",
+                decimals: BASE_DECIMALS,
+                raw_total: rawTotal,
+                display_total: formatAmount(rawTotal, BASE_DECIMALS),
+                ...(options.network ? { explorer_asset_url: assetExplorerUrl(options.network, "GBYTE") } : {})
+            };
+            continue;
+        }
+        const info = resolved.get(asset);
+        const decimals = info?.decimals ?? null;
+        const symbol = info?.symbol ?? null;
+        totalsByAsset[asset] = {
+            asset,
+            symbol,
+            decimals,
+            raw_total: rawTotal,
+            display_total: decimals === null ? null : formatAmount(rawTotal, decimals),
+            // Unknown assets get a prefix fallback "symbol"; only registry-confirmed symbols make clean explorer URLs.
+            ...(options.network ? { explorer_asset_url: assetExplorerUrl(options.network, decimals !== null && symbol ? symbol : asset) } : {})
+        };
+        if (decimals === null)
+            unresolved.push(asset);
+    }
+    const summary = { totals_by_asset: totalsByAsset, amounts_note: AMOUNTS_NOTE };
+    if (unresolved.length > 0)
+        summary.unresolved_assets = unresolved;
+    return summary;
+}
+//# sourceMappingURL=amounts.js.map

package/dist/amounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amounts.js","sourceRoot":"","sources":["../src/amounts.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -1,8 +1,10 @@
 export declare const PACKAGE_NAME = "obyte-mcp";
-export declare const PACKAGE_VERSION = "0.1.2";
+export declare const PACKAGE_VERSION = "0.2.1";
 export declare const MAINNET_HUB = "https://obyte.org/api";
 export declare const TESTNET_HUB = "https://testnet.obyte.org/api";
 export declare const MAINNET_TOKEN_REGISTRY_ADDRESS = "O6H6ZIFI57X3PLTYHOCVYPP5A553CYFQ";
+export declare const MAINNET_EXPLORER = "https://explorer.obyte.org";
+export declare const TESTNET_EXPLORER = "https://testnetexplorer.obyte.org";
 export declare const DEFAULT_TIMEOUT_MS = 20000;
 export declare const MIN_TIMEOUT_MS = 1000;
 export declare const MAX_TIMEOUT_MS = 120000;

package/dist/constants.js

@@ -1,8 +1,10 @@
 export const PACKAGE_NAME = "obyte-mcp";
-export const PACKAGE_VERSION = "0.1.2";
+export const PACKAGE_VERSION = "0.2.1";
 export const MAINNET_HUB = "https://obyte.org/api";
 export const TESTNET_HUB = "https://testnet.obyte.org/api";
 export const MAINNET_TOKEN_REGISTRY_ADDRESS = "O6H6ZIFI57X3PLTYHOCVYPP5A553CYFQ";
+export const MAINNET_EXPLORER = "https://explorer.obyte.org";
+export const TESTNET_EXPLORER = "https://testnetexplorer.obyte.org";
 export const DEFAULT_TIMEOUT_MS = 20_000;
 export const MIN_TIMEOUT_MS = 1_000;
 export const MAX_TIMEOUT_MS = 120_000;

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AAEvC,MAAM,CAAC,MAAM,WAAW,GAAG,uBAAuB,CAAC;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,+BAA+B,CAAC;AAC3D,MAAM,CAAC,MAAM,8BAA8B,GAAG,kCAAkC,CAAC;AAEjF,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACzC,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;AACpC,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACrD,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,IAAI,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AAEvC,MAAM,CAAC,MAAM,WAAW,GAAG,uBAAuB,CAAC;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,+BAA+B,CAAC;AAC3D,MAAM,CAAC,MAAM,8BAA8B,GAAG,kCAAkC,CAAC;AAEjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAC7D,MAAM,CAAC,MAAM,gBAAgB,GAAG,mCAAmC,CAAC;AAEpE,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACzC,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;AACpC,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACrD,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,IAAI,CAAC"}

package/dist/doctor.js

@@ -1,6 +1,7 @@
 import { buildRuntimeConfig } from "./config.js";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "./constants.js";
 import { ObyteMcpError } from "./errors.js";
+import { checkForUpdate } from "./updateCheck.js";
 export async function runDoctor(cliOptions, options) {
     const checks = [];
     let config;
@@ -16,6 +17,17 @@ export async function runDoctor(cliOptions, options) {
             message: error instanceof ObyteMcpError ? error.message : String(error)
         });
     }
+    // Informational only: an available update never fails doctor.
+    const update = await checkForUpdate();
+    checks.push({
+        name: "update",
+        ok: true,
+        message: update.update_available === true
+            ? `Update available: ${update.latest} (running ${update.current})`
+            : update.update_available === false
+                ? `Up to date (${update.current})`
+                : (update.note ?? "Update check skipped")
+    });
     const result = {
         package: PACKAGE_NAME,
         version: PACKAGE_VERSION,

package/dist/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAa5C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,UAAsB,EAAE,OAAsB;IAC5E,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,IAAI,MAAe,CAAC;IAEpB,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACrD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAC;IAChF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,QAAQ;YACd,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,KAAK,YAAY,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SACxE,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG;QACb,OAAO,EAAE,YAAY;QACrB,OAAO,EAAE,eAAe;QACxB,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM;QACN,MAAM;KACP,CAAC;IAEF,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC/D,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,IAAI,eAAe,WAAW,CAAC,CAAC;QACpE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,gBAAgB;IACvB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,IAAI,KAAK,IAAI,EAAE,EAAE,CAAC;QAChB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,kCAAkC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;AACzG,CAAC"}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/explorerClient.d.ts

@@ -0,0 +1,39 @@
+import type { Network } from "./types.js";
+/**
+ * Reads top asset holders from the Obyte explorer's Nuxt payload endpoint
+ * (/asset/<symbol|asset>/_payload.json). The explorer is a centralized
+ * convenience service separate from the hub; treat its data accordingly.
+ */
+export interface AssetHolder {
+    address: string;
+    raw_balance: number;
+    display_balance: string | null;
+}
+export interface AssetHoldersResult {
+    input: string;
+    network: Network;
+    asset: string | null;
+    name: string | null;
+    decimals: number | null;
+    supply_raw: number | null;
+    supply_display: string | null;
+    holders: AssetHolder[];
+    holders_returned: number;
+    more_holders_available: boolean;
+    explorer_asset_url: string;
+    source_note: string;
+}
+export interface FetchHoldersOptions {
+    network: Network;
+    value: string;
+    limit: number;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function fetchAssetHolders(options: FetchHoldersOptions): Promise<AssetHoldersResult>;
+/**
+ * Resolves Nuxt's devalue payload: a flat array where object values and array
+ * items are indices into the same array. Known reactive wrappers are unwrapped;
+ * devalue's negative sentinels map to undefined.
+ */
+export declare function decodeNuxtPayload(payload: unknown): unknown;

package/dist/explorerClient.js

@@ -0,0 +1,115 @@
+import { BASE_DECIMALS, assetExplorerUrl, formatAmount } from "./amounts.js";
+import { MAINNET_EXPLORER, TESTNET_EXPLORER } from "./constants.js";
+import { ObyteMcpError } from "./errors.js";
+import { isPlainObject } from "./jsonUtils.js";
+const SOURCE_NOTE = "Data from the Obyte explorer (a centralized convenience service, not the hub), sorted by balance descending and may lag the ledger slightly. raw amounts are smallest units; display values are already divided by 10^decimals.";
+export async function fetchAssetHolders(options) {
+    const value = normalizeAlias(options.value);
+    const base = options.network === "testnet" ? TESTNET_EXPLORER : MAINNET_EXPLORER;
+    const url = `${base}/asset/${encodeURIComponent(value)}/_payload.json`;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+    let response;
+    try {
+        response = await fetchImpl(url, { headers: { Accept: "application/json" }, signal: controller.signal });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new ObyteMcpError("TIMEOUT", `Explorer request timed out after ${options.timeoutMs}ms`, { url });
+        }
+        throw new ObyteMcpError("NETWORK_ERROR", "Explorer request failed", { url });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        throw new ObyteMcpError("NETWORK_ERROR", `Explorer responded with HTTP ${response.status}`, { url });
+    }
+    const payload = (await response.json());
+    const entry = extractAssetEntry(decodeNuxtPayload(payload), value);
+    if (entry.notFound === true) {
+        throw new ObyteMcpError("HUB_ERROR", `Asset "${options.value}" was not found on the ${options.network} explorer`, { url });
+    }
+    const holdersRaw = Array.isArray(entry.holders) ? entry.holders : [];
+    const isBase = entry.assetUnit === "bytes" || value === "GBYTE";
+    const decimals = isBase ? BASE_DECIMALS : typeof entry.decimals === "number" ? entry.decimals : null;
+    const name = isBase ? "GBYTE" : typeof entry.name === "string" ? entry.name : null;
+    const supplyRaw = typeof entry.supply === "number" ? entry.supply : null;
+    const holders = [];
+    let assetId = null;
+    for (const item of holdersRaw.slice(0, options.limit)) {
+        if (!isPlainObject(item) || typeof item.address !== "string" || typeof item.balance !== "number")
+            continue;
+        if (assetId === null && typeof item.asset === "string")
+            assetId = item.asset === "bytes" ? "base" : item.asset;
+        holders.push({
+            address: item.address,
+            raw_balance: item.balance,
+            display_balance: decimals === null ? null : formatAmount(item.balance, decimals)
+        });
+    }
+    return {
+        input: options.value,
+        network: options.network,
+        asset: assetId,
+        name,
+        decimals,
+        supply_raw: supplyRaw,
+        supply_display: supplyRaw !== null && decimals !== null ? formatAmount(supplyRaw, decimals) : null,
+        holders,
+        holders_returned: holders.length,
+        more_holders_available: entry.endHolders === false || holdersRaw.length > holders.length,
+        explorer_asset_url: assetExplorerUrl(options.network, value),
+        source_note: SOURCE_NOTE
+    };
+}
+function normalizeAlias(value) {
+    const trimmed = value.trim();
+    return trimmed === "base" || trimmed === "bytes" ? "GBYTE" : trimmed;
+}
+function extractAssetEntry(decoded, value) {
+    const data = isPlainObject(decoded) ? decoded.data : undefined;
+    if (isPlainObject(data)) {
+        const exact = data[`asset:${value}`];
+        if (isPlainObject(exact))
+            return exact;
+        for (const [key, entry] of Object.entries(data)) {
+            if (key.startsWith("asset:") && isPlainObject(entry))
+                return entry;
+        }
+    }
+    throw new ObyteMcpError("INTERNAL_ERROR", "Unexpected explorer payload shape", { value });
+}
+/**
+ * Resolves Nuxt's devalue payload: a flat array where object values and array
+ * items are indices into the same array. Known reactive wrappers are unwrapped;
+ * devalue's negative sentinels map to undefined.
+ */
+export function decodeNuxtPayload(payload) {
+    if (!Array.isArray(payload) || payload.length === 0) {
+        throw new ObyteMcpError("INTERNAL_ERROR", "Explorer payload is not a Nuxt data array");
+    }
+    const wrappers = new Set(["ShallowReactive", "Reactive", "Ref", "ShallowRef"]);
+    const resolve = (index, depth) => {
+        if (depth > 16 || index < 0 || index >= payload.length)
+            return undefined;
+        const value = payload[index];
+        if (isPlainObject(value)) {
+            const result = {};
+            for (const [key, ref] of Object.entries(value)) {
+                result[key] = typeof ref === "number" ? resolve(ref, depth + 1) : ref;
+            }
+            return result;
+        }
+        if (Array.isArray(value)) {
+            if (value.length === 2 && typeof value[0] === "string" && wrappers.has(value[0]) && typeof value[1] === "number") {
+                return resolve(value[1], depth + 1);
+            }
+            return value.map((ref) => (typeof ref === "number" ? resolve(ref, depth + 1) : ref));
+        }
+        return value;
+    };
+    return resolve(0, 0);
+}
+//# sourceMappingURL=explorerClient.js.map

package/dist/explorerClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorerClient.js","sourceRoot":"","sources":["../src/explorerClient.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -2,7 +2,7 @@
 import { PACKAGE_NAME, PACKAGE_VERSION } from "./constants.js";
 import { parseCliArgs } from "./cliArgs.js";
 import { buildRuntimeConfig } from "./config.js";
-import { ObyteMcpError, toObyteMcpError } from "./errors.js";
+import { toObyteMcpError } from "./errors.js";
 import { runDoctor } from "./doctor.js";
 import { runInstall } from "./install.js";
 import { runServer } from "./server.js";
@@ -74,8 +74,7 @@ The default command starts MCP stdio. Do not print logs to stdout in this mode.
 }
 main().catch((error) => {
     const normalized = toObyteMcpError(error);
-    const body = normalized instanceof ObyteMcpError ? normalized : toObyteMcpError(error);
-    process.stderr.write(`${body.code}: ${body.message}\n`);
+    process.stderr.write(`${normalized.code}: ${normalized.message}\n`);
     process.exitCode = 1;
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnD,IAAI,MAAM,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjC,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,IAAI,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC/B,MAAM,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACjD,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/C,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,QAAQ;IACf,OAAO,GAAG,YAAY,IAAI,eAAe;;;;;;;;IAQvC,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,YAAY;;;;;;;;;;;;;;;;;;;;;;;;CAwBf,CAAC;AACF,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,UAAU,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,UAAU,YAAY,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IACvF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IACxD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnD,IAAI,MAAM,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjC,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,IAAI,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC/B,MAAM,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACjD,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/C,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,QAAQ;IACf,OAAO,GAAG,YAAY,IAAI,eAAe;;;;;;;;IAQvC,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,YAAY;;;;;;;;;;;;;;;;;;;;;;;;CAwBf,CAAC;AACF,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,UAAU,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,IAAI,KAAK,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;IACpE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/install.js

@@ -99,19 +99,39 @@ function failWithSnippet(client, config, serverName, detail) {
     return { client, status: "failed", detail };
 }
 function runCli(command, args) {
-    const candidates = process.platform === "win32" ? [command, `${command}.cmd`, `${command}.exe`] : [command];
-    for (const bin of candidates) {
-        const result = spawnSync(bin, args, { stdio: "inherit", encoding: "utf8" });
-        if (result.error) {
-            if (result.error.code === "ENOENT")
-                continue;
-            return { ok: false, missing: false, message: result.error.message };
+    if (process.platform === "win32")
+        return runCliWindows(command, args);
+    const result = spawnSync(command, args, { stdio: "inherit" });
+    if (result.error) {
+        if (result.error.code === "ENOENT") {
+            return { ok: false, missing: true, message: `${command} not found on PATH` };
         }
-        if (result.status === 0)
-            return { ok: true, missing: false, message: "ok" };
-        return { ok: false, missing: false, message: `exited with code ${result.status ?? "unknown"}` };
+        return { ok: false, missing: false, message: result.error.message };
+    }
+    if (result.status === 0)
+        return { ok: true, missing: false, message: "ok" };
+    return { ok: false, missing: false, message: `exited with code ${result.status ?? "unknown"}` };
+}
+function runCliWindows(command, args) {
+    // npm-installed CLIs (claude, code, codex) are .cmd shims on Windows; modern Node
+    // refuses to spawn them without a shell (CVE-2024-27980). Probe with where.exe,
+    // then run through the shell with cmd-style quoting.
+    const probe = spawnSync("where", [command], { stdio: "ignore" });
+    if (probe.error || probe.status !== 0) {
+        return { ok: false, missing: true, message: `${command} not found on PATH` };
     }
-    return { ok: false, missing: true, message: `${command} not found on PATH` };
+    const line = [command, ...args.map(quoteForCmd)].join(" ");
+    const result = spawnSync(line, { stdio: "inherit", shell: true });
+    if (result.error)
+        return { ok: false, missing: false, message: result.error.message };
+    if (result.status === 0)
+        return { ok: true, missing: false, message: "ok" };
+    return { ok: false, missing: false, message: `exited with code ${result.status ?? "unknown"}` };
+}
+function quoteForCmd(value) {
+    if (/^[A-Za-z0-9._:\\/=-]+$/.test(value))
+        return value;
+    return `"${value.replace(/"/g, '\\"')}"`;
 }
 export function claudeDesktopConfigPath() {
     const home = homedir();