@blurt-blockchain/blurt-mcp-server 0.4.0

package/dist/tools/getAccountWitnessVotes.js

@@ -0,0 +1,46 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-account-witness-votes (Blurt — which witnesses an account supports)
+ */
+export function registerGetAccountWitnessVotes(server, client) {
+    registerBlurtTool(server, "get-account-witness-votes", {
+        title: "Get an account's witness votes",
+        description: "List the witnesses an account votes for (its governance support), and the proxy it uses if any. " +
+            "Use this when the user asks 'who does X support as witness' or to audit an account's governance " +
+            "choices. Parameter: username. Returns: the list of witness account names voted for (up to 30, the " +
+            "chain maximum), the count, and the witness proxy account if the account delegated its witness " +
+            "voting (in which case it has no direct votes of its own).",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            username: z.string().min(3).describe("Account name (e.g., 'nalexadre')"),
+        },
+    }, async ({ username }) => {
+        logger.debug(`get-account-witness-votes: ${username}`);
+        try {
+            const [account] = await client.condenser.getAccounts([username]);
+            if (!account) {
+                logger.warn(`Account not found: ${username}`);
+                return { content: [{ type: "text", text: `Account not found: ${username}` }], isError: true };
+            }
+            const votes = (account.witness_votes ?? []);
+            const proxy = (account.proxy ?? "");
+            const summary = {
+                account: username,
+                proxy: proxy || null,
+                witness_votes_count: votes.length,
+                witness_votes: votes,
+                note: proxy
+                    ? `Witness voting is delegated to the proxy account "${proxy}".`
+                    : undefined,
+            };
+            return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+        }
+        catch (e) {
+            logger.error(`[get-account-witness-votes] Error: ${e.stack}`);
+            return { content: [{ type: "text", text: `Error retrieving witness votes for ${username}` }], isError: true };
+        }
+    });
+}

package/dist/tools/getBlurtPrice.js

@@ -0,0 +1,43 @@
+// Logger
+import logger from "../utils/logger.js";
+import { getBlurtPrice } from "../utils/price.js";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-blurt-price (Blurt — market price)
+ *
+ * Purpose
+ *   Return the current BLURT price in USD and BTC from the public price feed
+ *   (https://api.blurt.blog/price_info).
+ *
+ * Parameters
+ *   (none)
+ *
+ * Returns
+ *   JSON: { price_usd, price_btc, source, fetched_at }
+ */
+export function registerGetBlurtPrice(server) {
+    registerBlurtTool(server, "get-blurt-price", {
+        title: "Get BLURT market price",
+        description: "Get the current market price of the BLURT token, in USD and BTC, from the public Blurt price feed. " +
+            "Call this whenever the user asks about the BLURT price or token value, or when you need to convert " +
+            "any on-chain BLURT amount (wallet balances, rewards, pending payouts, vote values) into fiat. " +
+            "Takes no parameters. Returns: price_usd, price_btc, the source URL, and an ISO fetched_at timestamp. " +
+            "The value is cached for ~60 seconds, so repeated calls are cheap.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {},
+    }, async () => {
+        logger.debug("get-blurt-price tool called");
+        try {
+            const price = await getBlurtPrice();
+            logger.info(`BLURT price: ${price.price_usd} USD`);
+            return { content: [{ type: "text", text: JSON.stringify(price, null, 2) }] };
+        }
+        catch (err) {
+            logger.error(`[get-blurt-price] Error: ${err.message}`);
+            return {
+                content: [{ type: "text", text: "Error retrieving BLURT price." }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/getChainStatus.js

@@ -0,0 +1,94 @@
+// Logger
+import logger from "../utils/logger.js";
+import { Asset } from "@beblurt/dblurt";
+import { getBlurtPrice } from "../utils/price.js";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-chain-status (Blurt — network & market overview)
+ *
+ * Purpose
+ *   Provide a dashboard-style snapshot of the Blurt blockchain combining
+ *   on-chain global properties, the content reward fund and the market price.
+ *
+ * Parameters
+ *   (none)
+ *
+ * Returns
+ *   JSON with:
+ *     - network: head block, current witness, last irreversible block, block participation %
+ *     - supply:  current BLURT supply, total vesting fund (Blurt Power backing)
+ *     - rewards: content reward pool balance, curation/author split
+ *     - market:  price_usd, price_btc, estimated market cap (supply × price)
+ *
+ * Notes
+ *   The market price is best-effort; if the external feed is unavailable the
+ *   on-chain data is still returned (market = null).
+ */
+export function registerGetChainStatus(server, client) {
+    registerBlurtTool(server, "get-chain-status", {
+        title: "Get Blurt chain status",
+        description: "Get a single-call network + market overview (dashboard) of the Blurt blockchain. " +
+            "Use this to answer questions about the state or health of the chain, its token economics, or market " +
+            "capitalization, instead of fetching several low-level properties separately. Takes no parameters. Returns:\n" +
+            "- network: head_block_number, last_irreversible_block_num, current_witness, time, block_participation_percent\n" +
+            "- supply: current_supply (total BLURT), total_vesting_fund_blurt and total_vesting_shares (the Blurt Power backing)\n" +
+            "- rewards: content_reward_balance (the post reward pool), curation_rewards_percent (author/curation split) and the reward curves\n" +
+            "- market: price_usd, price_btc, and estimated market_cap_usd (current_supply × price_usd)\n" +
+            "The market block is best-effort: it is null if the external price feed is unavailable, but the on-chain data is always returned.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {},
+    }, async () => {
+        logger.debug("get-chain-status tool called");
+        try {
+            const [dgp, rewardFund] = await Promise.all([
+                client.condenser.getDynamicGlobalProperties(),
+                client.condenser.getRewardFund("post"),
+            ]);
+            // Price is best-effort: don't fail the whole tool if the feed is down.
+            const price = await getBlurtPrice().catch((e) => {
+                logger.warn(`get-chain-status: price feed unavailable (${e.message})`);
+                return null;
+            });
+            const supply = Asset.from(dgp.current_supply).amount;
+            // recent_slots_filled is a 128-bit mask; participation_count is the populated count.
+            const participation = Number(((dgp.participation_count / 128) * 100).toFixed(1));
+            const summary = {
+                network: {
+                    head_block_number: dgp.head_block_number,
+                    last_irreversible_block_num: dgp.last_irreversible_block_num,
+                    current_witness: dgp.current_witness,
+                    time: dgp.time,
+                    block_participation_percent: participation,
+                },
+                supply: {
+                    current_supply: dgp.current_supply,
+                    total_vesting_fund_blurt: dgp.total_vesting_fund_blurt,
+                    total_vesting_shares: dgp.total_vesting_shares,
+                },
+                rewards: {
+                    content_reward_balance: rewardFund.reward_balance,
+                    curation_rewards_percent: rewardFund.percent_curation_rewards / 100,
+                    author_reward_curve: rewardFund.author_reward_curve,
+                    curation_reward_curve: rewardFund.curation_reward_curve,
+                },
+                market: price
+                    ? {
+                        price_usd: price.price_usd,
+                        price_btc: price.price_btc,
+                        market_cap_usd: Number((supply * price.price_usd).toFixed(0)),
+                        source: price.source,
+                    }
+                    : null,
+            };
+            logger.info(`Chain status retrieved (head block ${dgp.head_block_number})`);
+            return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+        }
+        catch (err) {
+            logger.error(`[get-chain-status] Error: ${err.stack}`);
+            return {
+                content: [{ type: "text", text: "Error retrieving chain status." }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/getCommunity.js

@@ -0,0 +1,75 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-community (Blurt — Nexus community details)
+ *
+ * Purpose
+ *   Retrieve detailed information about a single Blurt community.
+ *
+ * Parameters (inputSchema)
+ *   - name     (string, required) — community name (e.g., "blurt-192372")
+ *   - observer (string | null, optional) — observer account (subscription/role context)
+ *
+ * Behavior
+ *   Calls: client.nexus.getCommunity({ name, observer })
+ *
+ * Returns
+ *   - Human-readable summary (title, subscribers, authors, pending payout, team)
+ *   - Full JSON of the community object
+ */
+export function registerGetCommunity(server, client) {
+    registerBlurtTool(server, "get-community", {
+        title: "Get Blurt community details",
+        description: "Get full details about one Blurt community, identified by its 'name' (e.g. 'blurt-192372' — obtained from " +
+            "list-communities, or from a post's category). Use this when the user asks about a specific community: its size, " +
+            "purpose, rules, moderators, or activity level. " +
+            "Parameters: name (required), observer (optional account, adds the caller's subscription/role context). " +
+            "Returns a readable summary (title, subscribers, author count, pending posts and payout, admins, about/description) " +
+            "plus the full JSON object. To list or search communities first, use list-communities.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            name: z.string().min(1)
+                .describe("Community name (e.g., 'blurt-192372')"),
+            observer: z.string().nullable().optional()
+                .describe("Observer account (affects subscription/role context)"),
+        },
+    }, async ({ name, observer }) => {
+        logger.debug(`get-community: name=${name}, observer=${observer}`);
+        try {
+            const community = await client.nexus.getCommunity({ name, observer: observer ?? null });
+            if (!community) {
+                logger.warn(`Community not found: ${name}`);
+                return {
+                    content: [{ type: "text", text: `Community not found: ${name}` }],
+                    isError: true,
+                };
+            }
+            const admins = Array.isArray(community.admins)
+                ? community.admins.join(", ")
+                : "—";
+            const summary = `Community ${community.name} — ${community.title}
+- subscribers: ${community.subscribers}
+- authors: ${community.num_authors}
+- pending posts: ${community.num_pending}
+- pending payout: ${community.sum_pending} BLURT
+- lang: ${community.lang}${community.is_nsfw ? " (NSFW)" : ""}
+- admins: ${admins}
+- about: ${community.about ?? "—"}`;
+            return {
+                content: [
+                    { type: "text", text: summary },
+                    { type: "text", text: JSON.stringify(community, null, 2) },
+                ],
+            };
+        }
+        catch (e) {
+            logger.error(`[get-community] Error: ${e.stack}`);
+            return {
+                content: [{ type: "text", text: `Error retrieving community ${name}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/getDelegations.js

@@ -0,0 +1,37 @@
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/** Tool: get-delegations (Blurt) — Blurt Power an account delegates out. */
+export function registerGetDelegations(server, client) {
+    registerBlurtTool(server, "get-delegations", {
+        title: "Get a Blurt account's outgoing Blurt Power delegations",
+        description: "List the active Blurt Power (vesting) delegations an account is granting to others, with each " +
+            "amount converted from VESTS to BLURT for readability. Use this when the user asks 'who does X " +
+            "delegate to', about an account's delegated stake, or to audit how its Blurt Power is shared. " +
+            "Parameters: username (the delegator), limit (1-100, default 50). Returns: total delegated in BLURT " +
+            "and a per-delegatee list (delegatee, blurt_power, raw VESTS, min_delegation_time). Note: this is " +
+            "outgoing delegation; for an account's own stake use get-account.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            username: z.string().min(3).describe("Delegator account name (e.g., 'nalexadre')"),
+            limit: z.number().int().min(1).max(100).default(50).describe("Max delegations to return"),
+        },
+    }, async ({ username, limit }) => {
+        logger.debug(`get-delegations: ${username}, limit=${limit}`);
+        try {
+            const model = await client.read.getOutgoingDelegationSummary(username, limit);
+            const summary = {
+                ...model,
+                delegations: model.delegations.map((d) => ({
+                    ...d,
+                    blurt_power: `${d.blurt_power.toFixed(3)} BLURT`,
+                })),
+            };
+            return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+        }
+        catch (e) {
+            logger.error(`[get-delegations] Error: ${e.message}`);
+            return { content: [{ type: "text", text: `Error retrieving delegations for ${username}` }], isError: true };
+        }
+    });
+}

package/dist/tools/getPendingRewards.js

@@ -0,0 +1,53 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { Asset } from "@beblurt/dblurt";
+import { getBlurtPrice } from "../utils/price.js";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-pending-rewards (Blurt — unclaimed rewards)
+ */
+export function registerGetPendingRewards(server, client) {
+    registerBlurtTool(server, "get-pending-rewards", {
+        title: "Get a Blurt account's unclaimed rewards",
+        description: "Get the rewards an account has earned but not yet claimed (claimable now via a claim_reward " +
+            "operation). Use this when the user asks 'how much can X claim' or about pending/unclaimed earnings. " +
+            "Parameter: username. Returns: liquid BLURT reward, the reward to be received as Blurt Power " +
+            "(vesting), the combined total in BLURT, and a best-effort USD value (null if the price feed is " +
+            "unavailable). Note: these are cumulative-since-last-claim balances, distinct from an account's " +
+            "lifetime reward totals.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            username: z.string().min(3).describe("Account name (e.g., 'nalexadre')"),
+        },
+    }, async ({ username }) => {
+        logger.debug(`get-pending-rewards: ${username}`);
+        try {
+            const [account] = await client.condenser.getAccounts([username]);
+            if (!account) {
+                logger.warn(`Account not found: ${username}`);
+                return { content: [{ type: "text", text: `Account not found: ${username}` }], isError: true };
+            }
+            const liquid = Asset.from(account.reward_blurt_balance.toString()).amount;
+            const vesting = Asset.from(account.reward_vesting_blurt.toString()).amount;
+            const total = liquid + vesting;
+            const price = await getBlurtPrice().catch((e) => {
+                logger.warn(`get-pending-rewards: price feed unavailable (${e.message})`);
+                return null;
+            });
+            const summary = {
+                account: username,
+                pending_liquid_blurt: account.reward_blurt_balance,
+                pending_power_blurt: account.reward_vesting_blurt,
+                total_pending_blurt: Number(total.toFixed(3)),
+                total_pending_usd: price ? Number((total * price.price_usd).toFixed(4)) : null,
+                claimable: total > 0,
+            };
+            return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+        }
+        catch (e) {
+            logger.error(`[get-pending-rewards] Error: ${e.stack}`);
+            return { content: [{ type: "text", text: `Error retrieving pending rewards for ${username}` }], isError: true };
+        }
+    });
+}

package/dist/tools/getPost.js

@@ -0,0 +1,88 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-post (Blurt — Nexus post/discussion)
+ *
+ * Purpose
+ *   Retrieve details of a single Blurt post, with the option to also include its full discussion (comments).
+ *
+ * Parameters
+ *   - author (string, required): Blurt account name of the post’s author
+ *   - permlink (string, required): Unique permlink (slug) of the post
+ *   - with_comments (boolean, default false): If true, include the full discussion (comments)
+ *
+ * Behavior
+ *   - If with_comments = false → calls client.nexus.getPost({ author, permlink })
+ *   - If with_comments = true  → calls client.nexus.getDiscussion(author, permlink)
+ *
+ * Returns
+ *   - Human-readable summary of the post (title, author, category, created, votes, payout, comments count)
+ *   - Full JSON of the post or discussion (pretty-printed)
+ */
+export function registerGetPost(server, client) {
+    registerBlurtTool(server, "get-post", {
+        title: "Get Blurt blockchain post or discussion",
+        description: "Retrieve a single Blurt post, or its full discussion tree (post + all comments), via the Nexus API. Use this to read a " +
+            "specific post's metadata or the whole thread. Identify the post by author + permlink (from a post URL of the form " +
+            "author/permlink, or from get-account-posts / get-publications / search results). Parameters: author, permlink, " +
+            "with_comments (default false; set true to include the full discussion). Returns a readable summary (title, author/permlink, " +
+            "category, created, votes, payout, comments) plus a blurt:// resource URI — fetch that URI with the fetch tool to get the " +
+            "complete JSON. Use get-post-votes to analyse who voted on the post.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            author: z.string().describe("Blurt account name of the post’s author"),
+            permlink: z.string().describe("Unique permlink (slug) of the post"),
+            with_comments: z
+                .boolean()
+                .default(false)
+                .describe("Whether to include comments (discussion tree)"),
+        },
+    }, async ({ author, permlink, with_comments }) => {
+        logger.debug(`GET-POST via Nexus: author=${author}, permlink=${permlink}, with_comments=${with_comments}`);
+        try {
+            let result;
+            if (with_comments) {
+                result = await client.nexus.getDiscussion(author, permlink);
+            }
+            else {
+                result = await client.nexus.getPost({ author, permlink });
+            }
+            if (!result) {
+                logger.warn(`Post not found: ${author}/${permlink}`);
+                return {
+                    content: [{ type: "text", text: `Post not found: ${author}/${permlink}` }],
+                    isError: true,
+                };
+            }
+            // Extract main post (for discussion results, it's keyed as "author/permlink")
+            const post = with_comments ? result[`${author}/${permlink}`] : result;
+            const summary = `Post ${author}/${permlink} (${post.title})
+- category: ${post.category}
+- created: ${post.created}
+- votes: ${post.stats?.total_votes ?? 0}
+- payout: ${post.payout}
+- comments: ${post.children}
+- cover: ${post.json_metadata?.image ? post.json_metadata.image[0] ?? post.json_metadata.image : "none"}`;
+            const resourceUri = `blurt://post/${encodeURIComponent(author)}/${encodeURIComponent(permlink)}${with_comments ? "?with_comments=true" : ""}`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${summary}\n\nFull JSON available via resource: ${resourceUri}\nTip: use the fetch tool with this URI to get the complete JSON.`,
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            logger.error(`[get-post] Error: ${e.stack}`);
+            return {
+                content: [
+                    { type: "text", text: `Error retrieving post ${author}/${permlink}` },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/getPostReblogs.js

@@ -0,0 +1,29 @@
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/** Tool: get-post-reblogs (Blurt) — accounts that reblogged a post. */
+export function registerGetPostReblogs(server, client) {
+    registerBlurtTool(server, "get-post-reblogs", {
+        title: "Get the accounts that reblogged a Blurt post",
+        description: "List the accounts that reblogged (re-shared) a specific Blurt post, and how many. Use this when the " +
+            "user asks 'who reblogged X' or to measure how widely a post was re-shared (a reach signal distinct " +
+            "from votes). Identify the post by author + permlink. Parameters: author, permlink. Returns: count " +
+            "and the list of accounts that reblogged it. Complements get-post-votes.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            author: z.string().min(1).describe("Author of the post"),
+            permlink: z.string().min(1).describe("Permlink of the post"),
+        },
+    }, async ({ author, permlink }) => {
+        logger.debug(`get-post-reblogs: ${author}/${permlink}`);
+        try {
+            const accounts = await client.condenser.getRebloggedBy(author, permlink);
+            const summary = { author, permlink, count: accounts.length, accounts };
+            return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+        }
+        catch (e) {
+            logger.error(`[get-post-reblogs] Error: ${e.message}`);
+            return { content: [{ type: "text", text: `Error retrieving reblogs for ${author}/${permlink}` }], isError: true };
+        }
+    });
+}

package/dist/tools/getPostVotes.js

@@ -0,0 +1,78 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-post-votes (Blurt — active votes on a post)
+ *
+ * Purpose
+ *   List the votes cast on a given post/comment, ranked by weight (rshares),
+ *   useful for curation analysis.
+ *
+ * Parameters (inputSchema)
+ *   - author   (string, required) — post author
+ *   - permlink (string, required) — post permlink
+ *   - limit    (number, 1..1000, default 50) — max voters to display in the summary
+ *
+ * Behavior
+ *   Calls: client.condenser.getActiveVotes(author, permlink)
+ *
+ * Returns
+ *   - Summary: total voters, aggregate rshares, and the top voters (voter, percent, rshares, time)
+ *   - Full JSON of the active votes array
+ */
+export function registerGetPostVotes(server, client) {
+    registerBlurtTool(server, "get-post-votes", {
+        title: "Get votes on a Blurt post",
+        description: "List the individual votes cast on a Blurt post or comment, ranked by weight, for curation and engagement analysis. " +
+            "Use this to answer 'who upvoted this post', to find the biggest curators on a post, or to see how vote weight is " +
+            "distributed among voters. Identify the post by author + permlink (from a post URL of the form author/permlink, or " +
+            "from the results of get-account-posts / get-publications / get-post). " +
+            "Parameters: author, permlink, limit (max voters shown in the readable summary, 1-1000, default 50 — the full list is " +
+            "always included as JSON regardless of limit). " +
+            "Returns: total voter count, aggregate rshares, and per-voter rows (voter, percent, rshares, time) sorted by rshares " +
+            "descending. 'rshares' is the raw vote weight that determines each voter's share of the rewards; 'percent' is the " +
+            "voter's chosen vote strength (100% = full power).",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            author: z.string().min(1).describe("Post author"),
+            permlink: z.string().min(1).describe("Post permlink"),
+            limit: z.number().int().min(1).max(1000).default(50)
+                .describe("Max voters to show in the summary (full list still in JSON)"),
+        },
+    }, async ({ author, permlink, limit }) => {
+        logger.debug(`get-post-votes: ${author}/${permlink}, limit=${limit}`);
+        try {
+            const votes = await client.condenser.getActiveVotes(author, permlink);
+            if (!votes || votes.length === 0) {
+                logger.warn(`No votes for ${author}/${permlink}`);
+                return { content: [{ type: "text", text: `No votes found for ${author}/${permlink}.` }] };
+            }
+            const sorted = [...votes].sort((a, b) => Number(b.rshares) - Number(a.rshares));
+            const totalRshares = sorted.reduce((acc, v) => acc + Number(v.rshares), 0);
+            const top = sorted
+                .slice(0, limit)
+                .map((v, i) => `${i + 1}. ${v.voter} — ${v.percent / 100}% | rshares: ${v.rshares} | ${v.time}`)
+                .join("\n");
+            const summary = `Votes on ${author}/${permlink}
+- total voters: ${votes.length}
+- aggregate rshares: ${totalRshares}
+
+Top voters (showing ${Math.min(limit, sorted.length)}):
+${top}`;
+            return {
+                content: [
+                    { type: "text", text: summary },
+                    { type: "text", text: JSON.stringify(sorted, null, 2) },
+                ],
+            };
+        }
+        catch (e) {
+            logger.error(`[get-post-votes] Error: ${e.stack}`);
+            return {
+                content: [{ type: "text", text: `Error retrieving votes for ${author}/${permlink}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/getPublications.js

@@ -0,0 +1,109 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-publications (Blurt — Nexus getRankedPosts)
+ *
+ * Purpose
+ *   Returns ranked posts from Blurt’s Layer-2 Nexus API.
+ *
+ * Sort options
+ *   "trending" | "hot" | "created" | "promoted" | "payout" | "payout_comments" | "muted"
+ *
+ * Parameters (inputSchema)
+ *   - sort          (enum, default "trending")
+ *   - tag           (string | null, optional)        // filter by primary tag; null = no tag filter
+ *   - limit         (number, 1..100, default 20)
+ *   - start_author  (string | null, optional)        // pagination cursor; use together with start_permlink
+ *   - start_permlink(string | null, optional)        // pagination cursor; use together with start_author
+ *   - observer      (string | null, optional)        // observer account (affects visibility/muted content)
+ *
+ * Behavior
+ *   Calls: client.nexus.getRankedPosts({ sort, start_author, start_permlink, limit, tag, observer })
+ *   On success, returns two text contents:
+ *     1) A human-readable summary per post including:
+ *        author/permlink, title, stats.total_votes, payout (unified), app (name only, from json_metadata.app),
+ *        category, children (comment count), created, and optional json_metadata.description.
+ *     2) Pretty-printed JSON (NexusPost[]) for full downstream analysis.
+ *
+ * Notes
+ *   - “app” keeps only the application name (e.g. "beblurt" from "beblurt/1.8.8").
+ *   - “payout” is the unified numeric payout (not pending_payout_value), so it’s stable pre/post cashout.
+ *   - Returns "No publications found." when the result set is empty.
+ *
+ * Examples
+ *   tools/call get-publications {"sort":"trending","tag":"blurt","limit":10}
+ *   tools/call get-publications {"sort":"created","start_author":"alice","start_permlink":"my-post"}
+ */
+export function registerGetPublications(server, client) {
+    registerBlurtTool(server, 'get-publications', {
+        title: 'Get Blurt blockchain publications (Nexus ranked posts)',
+        description: "Retrieve ranked posts from across the Blurt blockchain via the Nexus L2 API (getRankedPosts). Use this for discovery — " +
+            "what's trending/hot/new or top payouts — optionally within a tag. Sort modes: trending (recent engagement), hot (current " +
+            "attention), created (newest), promoted (paid promotion), payout (highest total payout), payout_comments (top-paid comments), " +
+            "muted (hidden by moderators). Parameters: sort (default trending); tag (optional, filter by a single tag e.g. 'blurt'); " +
+            "limit (1-100, default 20); start_author + start_permlink (pagination cursor from the last item of a previous page); observer " +
+            "(optional, affects muted/visibility). Returns a readable per-post summary (author/permlink, title, votes, payout, app, " +
+            "category, community, created). Use get-post to open one, or get-account-posts for a specific account's posts.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            sort: z.enum([
+                "trending",
+                "hot",
+                "created",
+                "promoted",
+                "payout",
+                "payout_comments",
+                "muted"
+            ]).default("trending"),
+            tag: z.string().nullable().optional().describe("Blurt tag filter (e.g., 'blurt')"),
+            limit: z.number().int().min(1).max(100).default(20).describe("Limit the number of posts returned"),
+            start_author: z.string().nullable().optional().describe("Start author for pagination (must be used with start_permlink)"),
+            start_permlink: z.string().nullable().optional().describe("Start permlink for pagination (must be used with start_author)"),
+            observer: z.string().nullable().optional().describe("Observer account (affects visibility, muted content, etc.)"),
+        },
+    }, async ({ sort, tag, limit, start_author, start_permlink, observer }) => {
+        logger.debug(`GET-PUBLICATIONS via Nexus.getRankedPosts: sort=${sort}, tag=${tag}, limit=${limit}, start_author=${start_author}, start_permlink=${start_permlink}, observer=${observer}`);
+        try {
+            const posts = await client.nexus.getRankedPosts({
+                sort,
+                start_author: start_author ?? undefined,
+                start_permlink: start_permlink ?? undefined,
+                limit,
+                tag: tag ?? null,
+                observer: observer ?? null,
+            });
+            if (!posts || posts.length === 0) {
+                logger.warn(`No publications found (sort=${sort}, tag=${tag})`);
+                return { content: [{ type: "text", text: `No publications found.` }] };
+            }
+            // Short readable summary
+            const summary = posts
+                .map((p, i) => {
+                const appRaw = p.json_metadata?.app ?? "unknown";
+                const app = appRaw.split("/")[0];
+                const description = p.json_metadata?.description ? `\n    - description: ${p.json_metadata.description}` : "";
+                const community = p.community_title ? `\n    - community: ${p.community_title}` : "";
+                return `${i + 1}. ${p.author}/${p.permlink} (${p.title})
+            - votes: ${p.stats?.total_votes ?? 0}
+            - payout: ${p.payout} BLURT
+            - app: ${app}
+            - category: ${p.category}
+            - comments: ${p.children}
+            - created: ${p.created}${description}${community}
+            - cover: ${p.json_metadata?.image ? p.json_metadata.image[0] ?? p.json_metadata.image : "none"}`;
+            })
+                .join("\n\n");
+            return {
+                content: [
+                    { type: "text", text: `Posts ${sort} (limit=${limit}, tag=${tag ?? "all"})\n${summary}` },
+                ],
+            };
+        }
+        catch (e) {
+            logger.error(`[get-publications] Error: ${e.stack}`);
+            return { content: [{ type: "text", text: "Error retrieving publications." }], isError: true };
+        }
+    });
+}