@blurt-blockchain/blurt-mcp-server 0.4.0

package/dist/tools/search.js

@@ -0,0 +1,189 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+export function registerSearchTool(server) {
+    registerBlurtTool(server, "search", {
+        title: "Search Blurt resources",
+        description: `Turn a free-form query into Blurt resource links, which you then open with the fetch tool. Use this as an entry point ` +
+            `when you have a loose query and don't know the exact tool or URI; it returns resource_link items (no data itself — call ` +
+            `fetch on a returned URI to get the data). For specific needs, the dedicated tools (get-account, get-publications, get-post, ` +
+            `get-account-posts) are usually more direct.\n\n` +
+            `Supported query patterns:\n\n` +
+            `Accounts:\n` +
+            `  - @username                    → account\n` +
+            `  - history:@username            → account history (limit respected)\n\n` +
+            `Ranked posts (Nexus getRankedPosts):\n` +
+            `  - posts:tag                    → trending posts for a tag\n` +
+            `  - posts tag                    → trending posts for a tag (space allowed)\n` +
+            `  - posts/<sort>/<tag>           → posts by sort (trending|hot|created|promoted|payout|payout_comments|muted)\n` +
+            `  - posts:<sort>:<tag>           → same as above (colon allowed)\n\n` +
+            `Single post / discussion (Nexus getPost/getDiscussion):\n` +
+            `  - post author/permlink         → the post; fetch will return full discussion JSON\n` +
+            `  - author/permlink              → shorthand for the same\n\n` +
+            `Account posts (Nexus getAccountPosts):\n` +
+            `  - account-posts/<sort>/<account>  sort in (blog|feed|posts|comments|replies|payout)\n\n` +
+            `Notes:\n` +
+            `  - Whitespace and case are ignored in most patterns.\n` +
+            `  - If nothing matches, query is interpreted as a Blurt username.`,
+        // ChatGPT expects a "query" parameter
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            query: z.string().min(1).describe("Free-form search string following the documented patterns"),
+            limit: z.number().int().min(1).max(1000).default(20).describe("Max items to return for list resources"),
+        },
+    }, async ({ query, limit }) => {
+        logger.debug(`SEARCH called with query="${query}", limit=${limit}`);
+        const content = [];
+        // --- Normalize --------------------------------------------------------
+        const raw = query.trim();
+        const lower = raw.toLowerCase();
+        const squashed = lower.replace(/\s+/g, ""); // remove spaces for patterns like "posts: tag"
+        // helpers
+        const push = (uri, name, description) => {
+            content.push({
+                type: "resource_link",
+                uri,
+                name,
+                mimeType: "application/json",
+                description,
+            });
+        };
+        // constants
+        const rankedSorts = new Set([
+            "trending",
+            "hot",
+            "created",
+            "promoted",
+            "payout",
+            "payout_comments",
+            "muted",
+        ]);
+        const acctPostSorts = new Set([
+            "blog",
+            "feed",
+            "posts",
+            "comments",
+            "replies",
+            "payout",
+        ]);
+        const sortAlias = { new: "created", newest: "created" };
+        // ---------------------------------------------------------------------
+        // 1) Single post (explicit):  post author/permlink
+        // ---------------------------------------------------------------------
+        // `(?!s)` so that "posts/..." is NOT treated as a single post "post/..."
+        let m = lower.match(/^post(?!s)[:\s]*@?([a-z0-9_.\-]+)\/+([a-z0-9_.\-]+)/);
+        if (m) {
+            const author = m[1];
+            const permlink = m[2];
+            logger.info(`SEARCH: single post → ${author}/${permlink}`);
+            push(`blurt://post/${encodeURIComponent(author)}/${encodeURIComponent(permlink)}?with_comments=true`, `Post ${author}/${permlink}`, `Blurt post with full discussion`);
+        }
+        // ---------------------------------------------------------------------
+        // 2) Account posts: account-posts/<sort>/<account>
+        // ---------------------------------------------------------------------
+        if (content.length === 0) {
+            m = lower.match(/^account[-_]?posts[:\/\s]+([a-z_]+)[:\/\s]+@?([a-z0-9_.\-]+)/);
+            if (m) {
+                let sort = m[1];
+                const account = m[2];
+                if (sortAlias[sort])
+                    sort = sortAlias[sort];
+                if (acctPostSorts.has(sort)) {
+                    logger.info(`SEARCH: account-posts → sort=${sort}, account=${account}`);
+                    const params = new URLSearchParams();
+                    params.set("limit", String(Math.min(1000, Math.max(1, limit))));
+                    push(`blurt://account-posts/${encodeURIComponent(sort)}/${encodeURIComponent(account)}?${params.toString()}`, `Account posts @${account} (${sort})`, `Nexus getAccountPosts(${sort}) for @${account}`);
+                }
+            }
+        }
+        // ---------------------------------------------------------------------
+        // 3) Ranked posts by tag: posts ...
+        //    Accept: "posts:tag", "posts tag", "posts/<sort>/<tag>", "posts:<sort>:<tag>"
+        // ---------------------------------------------------------------------
+        if (content.length === 0) {
+            // Everything after the "posts" keyword and a separator (":", "/", or space).
+            const pm = lower.match(/^posts[:\/\s]+(.+)$/);
+            if (pm) {
+                const segs = pm[1].split(/[:\/\s]+/).map(s => s.trim()).filter(Boolean);
+                let sort = "trending";
+                let tag;
+                // "posts/<sort>/<tag>" only when the first segment is a known sort (or alias);
+                // otherwise the single segment is the tag and we default to trending.
+                if (segs.length >= 2 && (rankedSorts.has(segs[0]) || sortAlias[segs[0]])) {
+                    sort = sortAlias[segs[0]] ?? segs[0];
+                    tag = segs[1];
+                }
+                else {
+                    tag = segs[0];
+                }
+                if (tag) {
+                    const params = new URLSearchParams();
+                    params.set("limit", String(Math.min(100, Math.max(1, limit))));
+                    logger.info(`SEARCH: posts sort=${sort} for tag #${tag}`);
+                    push(`blurt://posts/${encodeURIComponent(sort)}/${encodeURIComponent(tag)}?${params.toString()}`, `Publications #${tag}${sort !== "trending" ? ` (${sort})` : ""}`, `Ranked posts (${sort}) for #${tag}`);
+                }
+            }
+        }
+        // ---------------------------------------------------------------------
+        // 4) Account history: history:@username  or  history @username
+        // ---------------------------------------------------------------------
+        if (content.length === 0) {
+            m = lower.match(/^history[:\s]*@?([a-z0-9_.\-]+)$/);
+            if (m) {
+                const username = m[1];
+                const params = new URLSearchParams();
+                params.set("limit", String(Math.min(1000, Math.max(1, limit))));
+                logger.info(`SEARCH: history resource for ${username}`);
+                push(`blurt://history/${encodeURIComponent(username)}?${params.toString()}`, `History @${username}`, `Latest operations for @${username}`);
+            }
+        }
+        // ---------------------------------------------------------------------
+        // 5) Account: @username  or account-nalexadre (common fallbacks)
+        // ---------------------------------------------------------------------
+        if (content.length === 0) {
+            m = lower.match(/^@([a-z0-9_.\-]+)$/);
+            if (!m) {
+                m = lower.match(/^account[-_]([a-z0-9_.\-]+)$/);
+            }
+            if (m) {
+                const username = m[1];
+                logger.info(`SEARCH: account resource for ${username}`);
+                push(`blurt://account/${encodeURIComponent(username)}`, `Account @${username}`, `Blurt account ${username}`);
+            }
+        }
+        // ---------------------------------------------------------------------
+        // New step: Tag query starting with #
+        // ---------------------------------------------------------------------
+        if (content.length === 0 && raw.startsWith("#")) {
+            const tag = raw.slice(1).trim();
+            if (tag.length > 0) {
+                const params = new URLSearchParams();
+                params.set("limit", String(Math.min(100, Math.max(1, limit))));
+                logger.info(`SEARCH: tag query for #${tag}`);
+                push(`blurt://posts/trending/${encodeURIComponent(tag)}?${params.toString()}`, `Publications #${tag}`, `Trending posts for #${tag}`);
+            }
+        }
+        // ---------------------------------------------------------------------
+        // 6) Single post (shorthand): author/permlink (no leading keyword)
+        //    Require permlink length >= 6
+        // ---------------------------------------------------------------------
+        if (content.length === 0 && /^(?:@?[a-z0-9_.\-]+)\/(?:[a-z0-9_.\-]{6,})$/.test(lower)) {
+            const [authorRaw, permlinkRaw] = raw.replace(/^@/, "").split("/");
+            const author = authorRaw.trim();
+            const permlink = permlinkRaw.trim();
+            logger.info(`SEARCH: shorthand post → ${author}/${permlink}`);
+            push(`blurt://post/${encodeURIComponent(author)}/${encodeURIComponent(permlink)}?with_comments=true`, `Post ${author}/${permlink}`, `Blurt post with full discussion`);
+        }
+        // ---------------------------------------------------------------------
+        // 7) Fallback → interpret as username
+        // ---------------------------------------------------------------------
+        if (content.length === 0) {
+            const username = lower.replace(/^@/, "");
+            logger.info(`SEARCH: fallback → interpreting as username "${username}"`);
+            push(`blurt://account/${encodeURIComponent(username)}`, `Account @${username}`, `Blurt account ${username}`);
+        }
+        logger.debug(`SEARCH returning ${content.length} resource_links`);
+        return { content };
+    });
+}

package/dist/tools/subscribeCommunity.js

@@ -0,0 +1,39 @@
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { subscribeCommunity, withinCap, dryRunDefault } from "../utils/signer.js";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+const CAP_MAX = 30;
+const CAP_WINDOW_MS = 60 * 60 * 1000;
+/** Tool: blurt-subscribe-community (Blurt — WRITE) — subscribe/unsubscribe a community. */
+export function registerSubscribeCommunity(server, client, ctx) {
+    registerBlurtTool(server, "blurt-subscribe-community", {
+        title: "Subscribe to or leave a Blurt community",
+        description: "WRITE operation (custom_json `community`, signed with the local posting key): subscribe the " +
+            "configured account to a Blurt community, or unsubscribe from it. Use this when the user asks to " +
+            "join/follow or leave a community. Parameters: community (the community name/id, e.g. 'blurt-192372' " +
+            "— from list-communities), action ('subscribe' or 'unsubscribe', default 'subscribe'), dry_run " +
+            "(default follows BLURT_DRY_RUN_DEFAULT; false when unset). Available only on the local stdio server; rate-limited.",
+        annotations: { readOnlyHint: false, destructiveHint: false },
+        inputSchema: {
+            community: z.string().min(1).describe("Community name/id (e.g., 'blurt-192372')"),
+            action: z.enum(["subscribe", "unsubscribe"]).default("subscribe")
+                .describe("'subscribe' to join the community, 'unsubscribe' to leave (default 'subscribe')"),
+            dry_run: z.boolean().default(dryRunDefault()).describe("Preview only, without broadcasting"),
+        },
+    }, async ({ community, action, dry_run }) => {
+        logger.debug(`blurt-subscribe-community: ${action} ${community} (dry_run=${dry_run})`);
+        try {
+            if (!dry_run && !withinCap("subscribe-community", CAP_MAX, CAP_WINDOW_MS)) {
+                return { content: [{ type: "text", text: `Rate limit reached for subscribe-community (max ${CAP_MAX}/hour).` }], isError: true };
+            }
+            const result = await subscribeCommunity(client, ctx, { community, action, dryRun: dry_run });
+            if (result.done)
+                logger.info(`${action} community ${community} (tx ${result.tx_id}).`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (e) {
+            logger.error(`[blurt-subscribe-community] Error: ${e.message}`);
+            return { content: [{ type: "text", text: `Error trying to ${action} ${community}` }], isError: true };
+        }
+    });
+}

package/dist/tools/upvote.js

@@ -0,0 +1,48 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { upvote, withinCap, dryRunDefault } from "../utils/signer.js";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+const CAP_MAX = 30;
+const CAP_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * Tool: blurt-upvote (Blurt — WRITE)
+ *
+ * Signs a `vote` with the local posting key. Only registered on the local stdio
+ * server when a validated posting key is present (never over HTTP).
+ */
+export function registerUpvote(server, client, ctx) {
+    registerBlurtTool(server, "blurt-upvote", {
+        title: "Upvote a Blurt post or comment",
+        description: "WRITE operation (signs a `vote` with the local posting key): upvote a Blurt post or comment as " +
+            "the configured account. Use this when the user asks to upvote/like a specific post. Identify the " +
+            "target by author + permlink. Parameters: author, permlink, weight (vote strength in percent, " +
+            "1-100, default 100), dry_run (default follows BLURT_DRY_RUN_DEFAULT; false when unset — when true, previews the vote WITHOUT broadcasting). " +
+            "Only the configured account votes. Available only on the local stdio server; rate-limited.",
+        annotations: { readOnlyHint: false, destructiveHint: false },
+        inputSchema: {
+            author: z.string().min(1).describe("Author of the post/comment to upvote"),
+            permlink: z.string().min(1).describe("Permlink of the post/comment to upvote"),
+            weight: z.number().int().min(1).max(100).default(100).describe("Vote strength in percent (1-100)"),
+            dry_run: z.boolean().default(dryRunDefault()).describe("Preview only, without broadcasting"),
+        },
+    }, async ({ author, permlink, weight, dry_run }) => {
+        logger.debug(`blurt-upvote: ${author}/${permlink} @ ${weight}% (dry_run=${dry_run})`);
+        try {
+            if (!dry_run && !withinCap("upvote", CAP_MAX, CAP_WINDOW_MS)) {
+                return {
+                    content: [{ type: "text", text: `Rate limit reached for upvote (max ${CAP_MAX}/hour).` }],
+                    isError: true,
+                };
+            }
+            const result = await upvote(client, ctx, { author, permlink, weight, dryRun: dry_run });
+            if (result.voted)
+                logger.info(`Upvoted ${author}/${permlink} @ ${weight}% (tx ${result.tx_id}).`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (e) {
+            logger.error(`[blurt-upvote] Error: ${e.message}`);
+            return { content: [{ type: "text", text: `Error upvoting ${author}/${permlink}` }], isError: true };
+        }
+    });
+}

package/dist/utils/blurtUri.js

@@ -0,0 +1,61 @@
+// Parsing/mapping helpers for Blurt resource URIs (blurt://…) and shorthand ids.
+// Extracted from the fetch tool so they can be unit-tested without any network access.
+export function parseBlurtUri(raw) {
+    const u = new URL(raw);
+    if (u.protocol !== "blurt:")
+        throw new Error(`Unsupported URI scheme: ${u.protocol}`);
+    const kind = u.hostname;
+    const parts = u.pathname.split("/").filter(Boolean);
+    const limitParam = u.searchParams.get("limit");
+    const limit = limitParam ? Number(limitParam) : undefined;
+    const opsParam = u.searchParams.get("ops");
+    const ops = opsParam ? opsParam.split(",").map(s => s.trim()).filter(Boolean) : undefined;
+    const sort = u.searchParams.get("sort") ?? undefined;
+    const observer = u.searchParams.has("observer") ? u.searchParams.get("observer") : undefined;
+    const with_comments = u.searchParams.get("with_comments") === "true";
+    if (kind === "account")
+        return { kind, username: parts[0] };
+    if (kind === "history")
+        return { kind, username: parts[0], limit, ops };
+    if (kind === "posts") {
+        // URI shape: blurt://posts/<sort>/<tag> (sort in path, fallback to ?sort=)
+        const [sortPart, tagPart] = parts;
+        return { kind, sort: sortPart ?? sort, tag: tagPart, limit };
+    }
+    if (kind === "account-posts") {
+        const [sortPart, accountPart] = parts;
+        return { kind, sort: sortPart, account: accountPart, limit, observer };
+    }
+    if (kind === "post") {
+        const [author, permlink] = parts;
+        return { kind, author, permlink, with_comments };
+    }
+    throw new Error(`Unknown blurt resource: ${kind}`);
+}
+export function idToBlurtUri(id) {
+    if (id.startsWith("@")) {
+        const username = id.slice(1);
+        return `blurt://account/${encodeURIComponent(username)}`;
+    }
+    if (id.startsWith("#")) {
+        const tag = id.slice(1);
+        return `blurt://posts/trending/${encodeURIComponent(tag)}`;
+    }
+    if (id.startsWith("account-")) {
+        const username = id.slice("account-".length);
+        return `blurt://account/${encodeURIComponent(username)}`;
+    }
+    if (id.startsWith("history-")) {
+        const username = id.slice("history-".length);
+        return `blurt://history/${encodeURIComponent(username)}`;
+    }
+    if (id.startsWith("posts-")) {
+        const rest = id.slice("posts-".length); // ex: "trending-blurtography"
+        const [by, ...tagParts] = rest.split("-");
+        const tag = tagParts.join("-");
+        return `blurt://posts/${encodeURIComponent(by)}/${encodeURIComponent(tag)}`;
+    }
+    if (id.startsWith("blurt://"))
+        return id; // already a URI
+    return null;
+}

package/dist/utils/loadEnv.js

@@ -0,0 +1,21 @@
+// Load environment variables from a controlled location, independent of the
+// process working directory. This lets the stdio server — which a desktop app
+// launches from an arbitrary cwd — read OUR .env (or a file pointed to by
+// BLURT_ENV_FILE) instead of requiring secrets in the launcher config.
+//
+// Resolution:
+//   - BLURT_ENV_FILE (if set) → that exact path (ideally outside the repo), else
+//   - the project root .env (next to this package), regardless of cwd.
+//
+// Precedence: variables already present in the real environment (e.g. injected
+// by a launcher's `env` block) are NOT overridden by the file.
+//
+// Import this module FIRST, before anything that reads process.env.
+import { config } from "dotenv";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const here = dirname(fileURLToPath(import.meta.url)); // dist/utils (or src/utils under tsx)
+const envPath = process.env.BLURT_ENV_FILE ?? resolve(here, "../../.env");
+// `quiet` is essential: the stdio server uses stdout for the MCP protocol, and
+// dotenv otherwise prints an "injecting env …" line there, which corrupts it.
+config({ path: envPath, quiet: true });

package/dist/utils/logger.js

@@ -0,0 +1,63 @@
+import process from "process";
+const levels = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+let currentLevel = process.env.LOG_LEVEL || "info";
+// --- Helpers ---
+function shouldLog(level) {
+    return levels[level] >= levels[currentLevel];
+}
+function formatHuman(level, message) {
+    const timestamp = new Date().toISOString();
+    const color = level === "debug"
+        ? "\x1b[36m" // cyan
+        : level === "info"
+            ? "\x1b[32m" // green
+            : level === "warn"
+                ? "\x1b[33m" // yellow
+                : "\x1b[31m"; // red
+    const reset = "\x1b[0m";
+    return `[${timestamp}] ${color}[${level.toUpperCase()}]${reset} ${message}\n`;
+}
+function formatJson(level, message) {
+    return (JSON.stringify({
+        ts: new Date().toISOString(),
+        level,
+        msg: message,
+        pid: process.pid,
+    }) + "\n");
+}
+function log(level, message) {
+    if (!shouldLog(level))
+        return;
+    const formatted = process.env.NODE_ENV === "production"
+        ? formatJson(level, message)
+        : formatHuman(level, message);
+    process.stderr.write(formatted);
+}
+// --- API publique ---
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+export function debug(message) {
+    log("debug", message);
+}
+export function info(message) {
+    log("info", message);
+}
+export function warn(message) {
+    log("warn", message);
+}
+export function error(message) {
+    log("error", message);
+}
+export default {
+    debug,
+    info,
+    warn,
+    error,
+    setLogLevel,
+};

package/dist/utils/price.js

@@ -0,0 +1,21 @@
+// Shared BLURT price helper. Fetches the public price feed and caches it briefly
+// so that the price/chain-status/vote-value tools don't hammer the external API.
+const PRICE_URL = process.env.BLURT_PRICE_URL ?? "https://api.blurt.blog/price_info";
+const TTL_MS = 60_000;
+let cache = null;
+export async function getBlurtPrice() {
+    if (cache && Date.now() - cache.ts < TTL_MS)
+        return cache.data;
+    const res = await fetch(PRICE_URL, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok)
+        throw new Error(`price feed HTTP ${res.status}`);
+    const json = (await res.json());
+    const data = {
+        price_usd: Number(json.price_usd),
+        price_btc: Number(json.price_btc),
+        source: PRICE_URL,
+        fetched_at: new Date().toISOString(),
+    };
+    cache = { data, ts: Date.now() };
+    return data;
+}

package/dist/utils/rpc.js

@@ -0,0 +1,126 @@
+// Dynamic RPC node selection backed by @beblurt/blurt-nodes-checker.
+//
+// The checker continuously scores the configured Blurt RPC nodes (latency, chain
+// lag, version, reliability) and we keep the shared dblurt client pointed at the
+// healthy nodes, best-first — so a slow, stale, forked or offline node is avoided
+// instead of failing a request. dblurt's own failover then covers transient blips
+// within that healthy set.
+import { Client } from "@beblurt/dblurt";
+import { BlurtNodesChecker } from "@beblurt/blurt-nodes-checker";
+import logger from "./logger.js";
+import { BLURT_CLIENT_OPTIONS, networkOptions } from "../buildServer.js";
+/** Default public Blurt RPC nodes. The checker prunes/ranks these at runtime. */
+export const DEFAULT_RPC_URLS = [
+    "https://rpc.blurt.blog",
+    "https://blurt-rpc.saboin.com",
+    "https://rpc.beblurt.com",
+    "https://blurtrpc.dagobert.uk",
+    "https://rpc.drakernoise.com",
+];
+// Node statuses we are willing to use, in order of preference. Everything else
+// (error, stale, forked, outdated, unknown, deactivated) is excluded.
+const STATUS_RANK = {
+    online: 0,
+    experimental: 1,
+    degraded: 2,
+    throttled: 3,
+};
+function configuredUrls() {
+    const env = process.env.BLURT_RPC_URLS;
+    const urls = env ? env.split(",").map((s) => s.trim()).filter(Boolean) : DEFAULT_RPC_URLS;
+    return urls.length ? urls : DEFAULT_RPC_URLS;
+}
+/** Keep only healthy nodes, ranked best-first (score, then status, then latency). */
+function rankHealthyUrls(nodes) {
+    return nodes
+        .filter((n) => !n.deactivated && n.status in STATUS_RANK)
+        .sort((a, b) => b.score - a.score ||
+        STATUS_RANK[a.status] - STATUS_RANK[b.status] ||
+        (a.latency_avg ?? a.duration ?? Infinity) - (b.latency_avg ?? b.duration ?? Infinity))
+        .map((n) => n.url);
+}
+let client;
+let currentUrls = [];
+let checker;
+let loggedNetwork = false;
+export function rpcReadiness() {
+    const configured = configuredUrls();
+    return {
+        configured_nodes: configured.length,
+        active_nodes: currentUrls.length || configured.length,
+        node_checker_running: Boolean(checker),
+    };
+}
+/**
+ * Base client options merged with the optional testnet override. Mainnet (no
+ * override) returns the base options unchanged. Logs the active network once.
+ */
+function clientOptions() {
+    const net = networkOptions();
+    if (!loggedNetwork) {
+        loggedNetwork = true;
+        if (net.chainId || net.addressPrefix) {
+            if (!net.chainId || !net.addressPrefix) {
+                logger.warn("Partial network override: set BOTH BLURT_CHAIN_ID and BLURT_ADDRESS_PREFIX " +
+                    "for a testnet (the missing one falls back to the mainnet default).");
+            }
+            logger.info(`Using custom Blurt network (chainId=${net.chainId ?? "default"}, ` +
+                `addressPrefix=${net.addressPrefix ?? "default"}).`);
+        }
+    }
+    return { ...BLURT_CLIENT_OPTIONS, ...net };
+}
+/** The shared dblurt client, pointed at the currently-healthy RPC nodes. */
+export function getBlurtClient() {
+    if (!client) {
+        currentUrls = configuredUrls();
+        client = new Client(currentUrls, clientOptions());
+    }
+    return client;
+}
+/**
+ * A stable Client handle that always delegates to the current shared client, so
+ * a consumer that captures it once still follows the node checker's repointing.
+ * Used by the long-lived stdio server (the HTTP path calls getBlurtClient() per
+ * request and doesn't need this).
+ */
+export const liveBlurtClient = new Proxy({}, {
+    get(_target, prop) {
+        return getBlurtClient()[prop];
+    },
+});
+/**
+ * Start the background node checker. It periodically re-scores the configured
+ * nodes and repoints the shared client at the healthy ones (best-first) whenever
+ * the ranking changes. Call once, from the server entrypoint (not from tests).
+ */
+export function startNodeChecker() {
+    if (checker)
+        return;
+    const urls = configuredUrls();
+    getBlurtClient(); // ensure a client exists immediately, before the first check
+    if (urls.length < 2) {
+        logger.info("Only one RPC node configured — skipping the node checker.");
+        return;
+    }
+    checker = new BlurtNodesChecker(urls, { timeout: 5000, interval: 120000 });
+    checker.message.subscribe((nodes) => {
+        const ranked = rankHealthyUrls(nodes);
+        if (ranked.length === 0) {
+            logger.warn("Node checker: no healthy RPC node found — keeping current client.");
+            return;
+        }
+        if (ranked.join(",") !== currentUrls.join(",")) {
+            logger.info(`Node checker: RPC nodes updated -> ${ranked.join(", ")}`);
+            currentUrls = ranked;
+            client = new Client(ranked, clientOptions());
+        }
+    });
+    checker.start().catch((e) => logger.error(`Node checker failed to start: ${e.message}`));
+    logger.info(`Node checker started over ${urls.length} RPC nodes.`);
+}
+/** Stop the background node checker (e.g. for graceful shutdown). */
+export function stopNodeChecker() {
+    checker?.stop();
+    checker = undefined;
+}