@blurt-blockchain/blurt-mcp-server 0.4.0

package/dist/tools/compareAccounts.js

@@ -0,0 +1,50 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: compare-accounts (Blurt — side-by-side account metrics)
+ */
+export function registerCompareAccounts(server, client) {
+    registerBlurtTool(server, "compare-accounts", {
+        title: "Compare Blurt accounts",
+        description: "Compare 2 to 5 Blurt accounts side by side on their key metrics in a single call. Use this when " +
+            "the user wants to compare accounts — by stake, reach, output or earnings — instead of fetching each " +
+            "one separately. Parameter: usernames (array of 2-5 account names). Returns, per account: Blurt Power " +
+            "(staked, in BLURT), liquid balance, follower and following counts, post count, last post time, and " +
+            "cumulative author + curation rewards (BLURT). Missing accounts are reported in a `not_found` list.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            usernames: z.array(z.string().min(3)).min(2).max(5)
+                .describe("Account names to compare (2-5), e.g. ['nalexadre','beblurt']"),
+        },
+    }, async ({ usernames }) => {
+        logger.debug(`compare-accounts: ${usernames.join(",")}`);
+        try {
+            const models = await Promise.all(usernames.map((u) => client.read.getAccountSummary(u).then((summary) => ({ username: u, summary }), () => ({ username: u, summary: null }))));
+            const rows = models
+                .filter((m) => !!m.summary)
+                .map(({ summary }) => ({
+                account: summary.account.name,
+                blurt_power: Number(summary.wallet.vesting_to_blurt.toFixed(3)),
+                liquid_balance: summary.wallet.balance,
+                followers: summary.account.followers ?? null,
+                following: summary.account.following ?? null,
+                post_count: summary.account.post_count,
+                last_post: summary.account.last_post,
+                cumulative_author_rewards_blurt: Number(summary.rewards.cumulative_posting_rewards.replace(" BLURT", "")),
+                cumulative_curation_rewards_blurt: Number(summary.rewards.cumulative_curation_rewards.replace(" BLURT", "")),
+            }));
+            const notFound = models.filter((m) => !m.summary).map((m) => m.username);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ accounts: rows, not_found: notFound }, null, 2) },
+                ],
+            };
+        }
+        catch (e) {
+            logger.error(`[compare-accounts] Error: ${e.stack}`);
+            return { content: [{ type: "text", text: "Error comparing accounts." }], isError: true };
+        }
+    });
+}

package/dist/tools/fetch.js

@@ -0,0 +1,91 @@
+// Logger
+import logger from "../utils/logger.js";
+import { utils as blurtUtils } from "@beblurt/dblurt";
+import { z } from "zod";
+import { parseBlurtUri, idToBlurtUri } from "../utils/blurtUri.js";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+function jsonContent(obj) {
+    return [{ type: "text", text: JSON.stringify(obj, null, 2) }];
+}
+export function registerFetchTool(server, client) {
+    registerBlurtTool(server, "fetch", {
+        title: "Fetch Blurt resource",
+        description: [
+            "Retrieve the raw JSON of a Blurt resource from a blurt:// URI or shorthand id. Use this to resolve a resource link",
+            "returned by the search tool, or when you already have a blurt:// URI. For most direct questions the dedicated tools",
+            "(get-account, get-publications, get-post, …) return friendlier, summarised output.",
+            "",
+            "Supported IDs/URIs:",
+            "- `blurt://account/<username>` → account object",
+            "- `blurt://history/<username>?limit=N` → recent operations for an account",
+            "- `blurt://posts/<sort>/<tag>?limit=N` → ranked posts (e.g., trending, hot, created)",
+            "- `blurt://account-posts/<sort>/<account>?limit=N` → account-related posts (blog, feed, comments, replies, payout)",
+            "- `blurt://post/<author>/<permlink>[?with_comments=true]` → single post or full discussion thread",
+            "",
+            "You may also use shorthand aliases like:",
+            "- `account-<username>`, `history-<username>`, `posts-<sort>-<tag>`, or `author/permlink`.",
+            "",
+            "Returns the full JSON representation of the resource (pretty-printed)."
+        ].join("\n"),
+        // The ChatGPT connector spec expects a single required "id" parameter.
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            id: z.string().min(1),
+        },
+    }, async ({ id }) => {
+        logger.debug(`FETCH called with id="${id}"`);
+        const target = idToBlurtUri(id);
+        if (!target) {
+            logger.warn(`FETCH: unsupported id "${id}"`);
+            return { content: [{ type: "text", text: `Unsupported id: ${id}` }], isError: true };
+        }
+        const parsed = parseBlurtUri(target);
+        logger.info(`FETCH resolved to ${parsed.kind} (${target})`);
+        if (parsed.kind === "account" && parsed.username) {
+            const [account] = await client.condenser.getAccounts([parsed.username]);
+            if (!account) {
+                logger.warn(`FETCH: account not found "${parsed.username}"`);
+                return { content: [{ type: "text", text: `Account not found: ${parsed.username}` }], isError: true };
+            }
+            return { content: jsonContent(account) };
+        }
+        if (parsed.kind === "history" && parsed.username) {
+            const limit = Math.max(1, Math.min(1000, parsed.limit ?? 50));
+            let bitmask;
+            if (parsed.ops && parsed.ops.length) {
+                const opEnum = blurtUtils.operationOrders;
+                const selected = parsed.ops.map(n => opEnum[n]).filter((v) => typeof v === "number");
+                bitmask = blurtUtils.makeBitMaskFilter(selected);
+            }
+            const history = await client.condenser.getAccountHistory(parsed.username, -1, limit, bitmask);
+            return { content: jsonContent(history) };
+        }
+        if (parsed.kind === "account-posts" && parsed.sort && parsed.account) {
+            const limit = Math.max(1, Math.min(100, parsed.limit ?? 20));
+            const posts = await client.nexus.getAccountPosts({
+                sort: parsed.sort,
+                account: parsed.account,
+                limit,
+                observer: parsed.observer ?? null,
+            });
+            return { content: jsonContent(posts) };
+        }
+        if (parsed.kind === "post" && parsed.author && parsed.permlink) {
+            if (parsed.with_comments) {
+                const discussion = await client.nexus.getDiscussion(parsed.author, parsed.permlink);
+                return { content: jsonContent(discussion) };
+            }
+            else {
+                const post = await client.nexus.getPost({ author: parsed.author, permlink: parsed.permlink });
+                return { content: jsonContent(post) };
+            }
+        }
+        if (parsed.kind === "posts" && parsed.sort) {
+            const limit = Math.max(1, Math.min(100, parsed.limit ?? 20));
+            const posts = await client.nexus.getRankedPosts({ sort: parsed.sort, limit, tag: parsed.tag ?? null });
+            return { content: jsonContent(posts) };
+        }
+        logger.error(`FETCH: unsupported target "${target}"`);
+        return { content: [{ type: "text", text: `Unsupported target: ${target}` }], isError: true };
+    });
+}

package/dist/tools/follow.js

@@ -0,0 +1,39 @@
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { follow, 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-follow (Blurt — WRITE) — follow/unfollow an account. */
+export function registerFollow(server, client, ctx) {
+    registerBlurtTool(server, "blurt-follow", {
+        title: "Follow or unfollow a Blurt account",
+        description: "WRITE operation (custom_json `follow`, signed with the local posting key): make the configured " +
+            "account follow or unfollow another Blurt account. Use this when the user asks to follow/unfollow " +
+            "someone. Parameters: account (the account to follow/unfollow), action ('follow' or 'unfollow', " +
+            "default 'follow'), dry_run (default follows BLURT_DRY_RUN_DEFAULT; false when unset — preview without broadcasting). Available only on the " +
+            "local stdio server; rate-limited.",
+        annotations: { readOnlyHint: false, destructiveHint: false },
+        inputSchema: {
+            account: z.string().min(3).describe("Account to follow/unfollow (e.g., 'nalexadre')"),
+            action: z.enum(["follow", "unfollow"]).default("follow")
+                .describe("'follow' to start following, 'unfollow' to stop (default 'follow')"),
+            dry_run: z.boolean().default(dryRunDefault()).describe("Preview only, without broadcasting"),
+        },
+    }, async ({ account, action, dry_run }) => {
+        logger.debug(`blurt-follow: ${action} ${account} (dry_run=${dry_run})`);
+        try {
+            if (!dry_run && !withinCap("follow", CAP_MAX, CAP_WINDOW_MS)) {
+                return { content: [{ type: "text", text: `Rate limit reached for follow (max ${CAP_MAX}/hour).` }], isError: true };
+            }
+            const result = await follow(client, ctx, { account, action, dryRun: dry_run });
+            if (result.done)
+                logger.info(`${action} @${account} (tx ${result.tx_id}).`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (e) {
+            logger.error(`[blurt-follow] Error: ${e.message}`);
+            return { content: [{ type: "text", text: `Error trying to ${action} ${account}` }], isError: true };
+        }
+    });
+}

package/dist/tools/getAccount.js

@@ -0,0 +1,80 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-account (Blurt — account details)
+ *
+ * Purpose
+ *   Retrieve full account information from the Blurt blockchain,
+ *   combining low-level condenser data with enriched Nexus profile stats.
+ *
+ * Parameters (inputSchema)
+ *   - username (string, required) — the Blurt account name to query
+ *
+ * Behavior
+ *   Calls:
+ *     - client.condenser.getAccounts([username]) for balances, vesting, witness votes, rewards
+ *     - client.read.getAccountSummary(username) for SDK-owned account/stake/reward modeling
+ *
+ * Summary output includes:
+ *   - Account: name, about, created (pre-fork detection), last active, last post, last vote, post_count, following, followers, referrer
+ *   - Wallet: balance, savings, Blurt Power (converted from VESTS), mana %, delegation in/out, power down status
+ *   - Witness: number of witness votes
+ *   - Rewards: posting_rewards and curation_rewards converted to BLURT
+ *
+ * Returns
+ *   JSON text with structured account, wallet, witness and rewards information.
+ *
+ * Example
+ *   tools/call get-account {"username": "nalexadre"}
+ */
+export function registerGetAccount(server, client) {
+    registerBlurtTool(server, 'get-account', {
+        title: 'Get Blurt blockchain account details',
+        description: "Retrieve a structured profile of a Blurt account: identity, wallet, stake, witness votes and lifetime rewards. " +
+            "Use this as the starting point for almost any account question, or to get context before other account tools. " +
+            "Parameter: username. Returns: account (name, bio, created, last active/post/vote, post_count, followers/following, mana %), " +
+            "wallet (liquid balance, savings, Blurt Power converted from vested VESTS, delegations in/out, power-down status), the " +
+            "number of witness votes, and cumulative author + curation rewards. Amounts are in BLURT — pair with get-blurt-price to " +
+            "convert to USD. For more detail use get-pending-rewards (unclaimed rewards), get-account-witness-votes (which witnesses), " +
+            "get-account-relationships (social graph) or get-vote-value (upvote worth).",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            username: z.string()
+                .min(3)
+                .describe("Blurt account name (e.g., 'nalexadre')"),
+        },
+    }, async ({ username }) => {
+        logger.debug(`get-account tool called with username: ${username}`);
+        try {
+            const model = await client.read.getAccountSummary(username);
+            const summary = {
+                ...model,
+                wallet: {
+                    ...model.wallet,
+                    vesting_to_blurt: `${model.wallet.vesting_to_blurt.toFixed(3)} BLURT`,
+                    delegation_in: `${model.wallet.delegation_in_blurt.toFixed(3)} BLURT`,
+                    delegation_out: `${model.wallet.delegation_out_blurt.toFixed(3)} BLURT`,
+                    power_down: `${model.wallet.power_down_blurt.toFixed(3)} BLURT`,
+                },
+            };
+            delete summary.wallet.delegation_in_blurt;
+            delete summary.wallet.delegation_out_blurt;
+            delete summary.wallet.power_down_blurt;
+            logger.info(`Account successfully retrieved: ${username}`);
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(summary, null, 2) }
+                ]
+            };
+        }
+        catch (err) {
+            logger.error(`Error retrieving ${username}'s account: ${err}`);
+            return {
+                content: [{ type: 'text', text: `Error retrieving account: ${username}` }],
+                isError: true
+            };
+        }
+    });
+}

package/dist/tools/getAccountHistory.js

@@ -0,0 +1,109 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { utils as blurtUtils } from "@beblurt/dblurt";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-account-history (Blurt — account history)
+ *
+ * Purpose
+ *   Retrieve operations from a Blurt account history, with optional filtering by operation types.
+ *
+ * Parameters (inputSchema)
+ *   - username  (string, required) — Blurt account name (e.g., 'nalexadre')
+ *   - from      (number, default -1) — starting index (-1 = most recent)
+ *   - limit     (number, 1..1000, default 100) — maximum number of entries to fetch
+ *   - operations(string[], optional) — list of operation names to filter (e.g., ["vote", "comment", "transfer"])
+ *
+ * Behavior
+ *   Calls: client.condenser.getAccountHistory(username, from, limit, bitmaskFilter)
+ *   If operations are provided, applies a bitmask filter built from blurtUtils.operationOrders.
+ *
+ * Returns
+ *   - A short summary (counts by operation type)
+ *   - A pretty-printed JSON array of the retrieved operations
+ *
+ * Example
+ *   tools/call get-account-history {"username":"nalexadre","limit":20,"operations":["transfer","vote"]}
+ */
+export function registerGetAccountHistory(server, client) {
+    registerBlurtTool(server, 'get-account-history', {
+        title: 'Get Blurt account history',
+        description: "Retrieve the raw on-chain operation history of a Blurt account (transfers, votes, comments, claims, witness ops, …), " +
+            "newest first. Use this to audit or trace activity, find recent transfers/cashouts, or build an activity timeline. " +
+            "Parameters: username; from (history index to start from, -1 = most recent, default -1); limit (1-1000, default 100); " +
+            "operations (optional allow-list of operation type names to keep, e.g. ['transfer','vote'] — omit for all types). " +
+            "Returns a JSON array of [sequence, operation] entries exactly as recorded on chain. Note: the output can be large — " +
+            "narrow it with the operations filter and a small limit. For readable post activity, prefer get-account-posts.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            username: z.string()
+                .min(3)
+                .describe("Blurt account name (e.g., 'nalexadre')"),
+            from: z.number()
+                .default(-1)
+                .describe("Starting index in history (-1 = most recent)"),
+            limit: z.number()
+                .min(1)
+                .max(1000)
+                .default(100)
+                .describe("Maximum number of operations to retrieve (1-1000)"),
+            operations: z.array(z.enum([
+                "vote", "comment", "transfer", "transfer_to_vesting", "withdraw_vesting",
+                "account_create", "account_update", "witness_update", "account_witness_vote",
+                "account_witness_proxy", "custom", "delete_comment", "custom_json",
+                "comment_options", "set_withdraw_vesting_route", "claim_account",
+                "create_claimed_account", "request_account_recovery", "recover_account",
+                "change_recovery_account", "escrow_transfer", "escrow_dispute",
+                "escrow_release", "escrow_approve", "transfer_to_savings",
+                "transfer_from_savings", "cancel_transfer_from_savings", "custom_binary",
+                "decline_voting_rights", "reset_account", "set_reset_account",
+                "claim_reward_balance", "delegate_vesting_shares", "witness_set_properties",
+                "create_proposal", "update_proposal_votes", "remove_proposal",
+                "author_reward", "curation_reward", "comment_reward", "fill_vesting_withdraw",
+                "shutdown_witness", "fill_transfer_from_savings", "hardfork",
+                "comment_payout_update", "return_vesting_delegation",
+                "comment_benefactor_reward", "producer_reward", "clear_null_account_balance",
+                "proposal_pay", "sps_fund", "fee_pay"
+            ])).optional()
+                .describe("Optional list of operation types to filter (e.g., ['vote','transfer','comment'])"),
+        }
+    }, async ({ username, from, limit, operations }) => {
+        logger.debug(`get-account-history called with username=${username}, from=${from}, limit=${limit}, operations=${JSON.stringify(operations)}`);
+        try {
+            let bitmask;
+            if (operations && operations.length > 0) {
+                // Map noms -> codes via utils.operationOrders
+                const opEnum = blurtUtils.operationOrders;
+                const selected = [];
+                for (const name of operations) {
+                    const key = name;
+                    if (opEnum[key] !== undefined)
+                        selected.push(opEnum[key]);
+                }
+                if (selected.length === 0) {
+                    logger.warn(`No matching operations found for filter: ${JSON.stringify(operations)}`);
+                }
+                bitmask = blurtUtils.makeBitMaskFilter(selected);
+            }
+            else {
+                logger.warn('No operations provided for filtering.');
+            }
+            const history = await client.condenser.getAccountHistory(username, from, limit, bitmask);
+            // history: Array<[seq, AppliedOperation]>
+            logger.info(`Retrieved account history for ${username}, entries count: ${history.length}`);
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(history, null, 2) }
+                ]
+            };
+        }
+        catch (error) {
+            logger.error(`Error in get-account-history for username=${username}: ${error}`);
+            return {
+                content: [{ type: 'text', text: `Error retrieving account history: ${username}` }],
+                isError: true
+            };
+        }
+    });
+}

package/dist/tools/getAccountNotifications.js

@@ -0,0 +1,40 @@
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/** Tool: get-account-notifications (Blurt) — an account's notifications feed. */
+export function registerGetAccountNotifications(server, client) {
+    registerBlurtTool(server, "get-account-notifications", {
+        title: "Get a Blurt account's notifications",
+        description: "Get an account's recent notifications (mentions, replies, votes, follows, reblogs) and its unread " +
+            "count. Use this when the user asks 'what are my notifications', 'who mentioned/replied to me', or " +
+            "to review recent activity directed at an account. Parameters: username, limit (1-100, default 30). " +
+            "Returns: unread (count) and last_read timestamp, plus a list of notifications, each with type, a " +
+            "human message, score, date and url. To mark them read afterwards, use blurt-read-notifications " +
+            "(write, local only).",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            username: z.string().min(3).describe("Account name (e.g., 'nalexadre')"),
+            limit: z.number().int().min(1).max(100).default(30).describe("Max notifications to return"),
+        },
+    }, async ({ username, limit }) => {
+        logger.debug(`get-account-notifications: ${username}, limit=${limit}`);
+        try {
+            const [notifications, unread] = await Promise.all([
+                client.nexus.accountNotifications({ account: username, limit }),
+                client.nexus.unreadNotifications({ account: username }),
+            ]);
+            const summary = {
+                account: username,
+                unread: unread.unread,
+                last_read: unread.lastread,
+                returned: notifications.length,
+                notifications,
+            };
+            return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+        }
+        catch (e) {
+            logger.error(`[get-account-notifications] Error: ${e.message}`);
+            return { content: [{ type: "text", text: `Error retrieving notifications for ${username}` }], isError: true };
+        }
+    });
+}

package/dist/tools/getAccountPosts.js

@@ -0,0 +1,130 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-account-posts (Blurt — Nexus account posts)
+ *
+ * Purpose
+ *   Retrieve a list of posts related to a given Blurt account using the Nexus Layer-2 API.
+ *
+ * Sort options (sort parameter)
+ *   - "blog"    → posts authored by the account (excluding communities unless reblogged) + reblogs, ranked by creation/reblog time
+ *   - "feed"    → posts from blogs of accounts that the given account follows (max age = 1 month)
+ *   - "posts"   → top posts authored by the account, newer first
+ *   - "comments"→ comments authored by the account, newer first
+ *   - "replies" → replies to the account’s posts, newer first
+ *   - "payout"  → all posts authored by the account that have not yet been cashed out
+ *
+ * Parameters (inputSchema)
+ *   - account        (string, required) — the Blurt account to fetch
+ *   - sort           (enum, required) — one of "blog", "feed", "posts", "comments", "replies", "payout"
+ *   - start_author   (string | null, optional) — author name for pagination (use with start_permlink)
+ *   - start_permlink (string | null, optional) — permlink for pagination (use with start_author)
+ *   - limit          (number, default 20, max 1000) — number of posts to fetch
+ *   - observer       (string | null, optional) — observer account (affects visibility/muted content)
+ *
+ * Behavior
+ *   Calls: client.nexus.getAccountPosts({ sort, account, start_author, start_permlink, limit, observer })
+ *
+ * Returns
+ *   - A human-readable summary of the retrieved posts (title, created, votes, payout, app, comments count, optional description).
+ *   - Full JSON of the retrieved NexusPost[] (pretty-printed) for deeper analysis.
+ *
+ * Example
+ *   tools/call get-account-posts {"account":"nalexadre","sort":"blog","limit":5}
+ */
+export function registerGetAccountPosts(server, client) {
+    registerBlurtTool(server, "get-account-posts", {
+        title: "Get Blurt account posts",
+        description: "Retrieve posts related to a Blurt account via the Nexus L2 API. Use this to read what an account has published or " +
+            "engaged with — their blog, authored posts, comments, replies received, their feed, or pending-payout posts.\n" +
+            "Sort modes:\n" +
+            "  - blog: posts authored by the account (excluding communities unless reblogged) plus reblogs, by time.\n" +
+            "  - feed: posts from accounts the given account follows (up to ~1 month old).\n" +
+            "  - posts: top-level posts authored by the account, newest first.\n" +
+            "  - comments: comments authored by the account, newest first.\n" +
+            "  - replies: replies to the account's posts (by anyone), newest first.\n" +
+            "  - payout: the account's posts not yet cashed out (pending payout).\n" +
+            "Parameters: account, sort (required); limit (1-1000, default 20); start_author + start_permlink (pagination cursor taken " +
+            "from the last item of a previous page); observer (optional, affects muted/visibility). Returns a readable per-post summary " +
+            "plus the post JSON (each post's body is truncated to keep the response small — use get-post for a post's full content). " +
+            "Use get-post to open one post, get-post-votes for its voters.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            account: z.string().describe("Blurt account to fetch posts for (e.g., 'nalexadre')"),
+            sort: z.enum(["blog", "feed", "posts", "comments", "replies", "payout"])
+                .describe("Sorting mode: blog, feed, posts, comments, replies, or payout"),
+            start_author: z.string().nullable().optional()
+                .describe("Author name for pagination (must be used with start_permlink)"),
+            start_permlink: z.string().nullable().optional()
+                .describe("Permlink for pagination (must be used with start_author)"),
+            limit: z.number().int().min(1).max(1000).default(20)
+                .describe("Number of results to fetch (max 1000)"),
+            observer: z.string().nullable().optional()
+                .describe("Observer account (affects visibility/muted content)"),
+        },
+    }, async ({ account, sort, start_author, start_permlink, limit, observer }) => {
+        logger.debug(`GET-ACCOUNT-POSTS via Nexus: account=${account}, sort=${sort}, limit=${limit}, start_author=${start_author}, start_permlink=${start_permlink}, observer=${observer}`);
+        try {
+            const posts = await client.nexus.getAccountPosts({
+                sort,
+                account,
+                start_author: start_author ?? undefined,
+                start_permlink: start_permlink ?? undefined,
+                limit,
+                observer: observer ?? null,
+            });
+            if (!posts || posts.length === 0) {
+                logger.warn(`No posts found for account=${account}, sort=${sort}`);
+                return { content: [{ type: "text", text: `No posts found.` }] };
+            }
+            // Human-readable summary
+            const summary = posts
+                .map((p, i) => {
+                const appRaw = p.json_metadata?.app ?? "unknown";
+                const app = appRaw.split("/")[0];
+                const desc = p.json_metadata?.description
+                    ? `\n    - description: ${p.json_metadata.description}`
+                    : "";
+                return `${i + 1}. ${p.author}/${p.permlink} (${p.title})
+    - created: ${p.created}
+    - votes: ${p.stats?.total_votes ?? 0}
+    - payout: ${p.payout}
+    - app: ${app}
+    - cover: ${p.json_metadata?.image ? p.json_metadata.image[0] ?? p.json_metadata.image : "none"}
+    - comments: ${p.children}${desc}`;
+            })
+                .join("\n\n");
+            // Truncate each post body so the JSON stays a reasonable size. The full
+            // body of a specific post remains reachable via get-post / fetch.
+            const MAX_BODY_CHARS = 800;
+            const trimmed = posts.map((p) => {
+                const body = typeof p.body === "string" ? p.body : "";
+                if (body.length <= MAX_BODY_CHARS)
+                    return p;
+                return {
+                    ...p,
+                    body: body.slice(0, MAX_BODY_CHARS) + "… [truncated]",
+                    body_length: body.length,
+                    body_truncated: true,
+                };
+            });
+            return {
+                content: [
+                    { type: "text", text: `Posts for @${account} (${sort}, limit=${limit})\n${summary}` },
+                    { type: "text", text: JSON.stringify(trimmed, null, 2) }, // bodies truncated; use get-post for full content
+                ],
+            };
+        }
+        catch (e) {
+            logger.error(`[get-account-posts] Error: ${e.stack}`);
+            return {
+                content: [
+                    { type: "text", text: `Error retrieving posts for ${account}` },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/getAccountRelationships.js

@@ -0,0 +1,34 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-account-relationships (Blurt — followers & following)
+ */
+export function registerGetAccountRelationships(server, client) {
+    registerBlurtTool(server, "get-account-relationships", {
+        title: "Get a Blurt account's followers and following",
+        description: "Get an account's social graph: total follower and following counts, plus a sample of each. " +
+            "Use this when the user asks 'who follows X', 'who does X follow', or about an account's reach and " +
+            "network. Parameters: username, and sample (how many of each list to include, 0-100, default 10 — " +
+            "set 0 for counts only). Returns: follower_count, following_count, and sample arrays of follower / " +
+            "following account names. The lists are large for popular accounts, so this returns a sample, not " +
+            "the full graph.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            username: z.string().min(3).describe("Account name (e.g., 'nalexadre')"),
+            sample: z.number().int().min(0).max(100).default(10)
+                .describe("How many followers and following to include as a sample (0 = counts only)"),
+        },
+    }, async ({ username, sample }) => {
+        logger.debug(`get-account-relationships: ${username}, sample=${sample}`);
+        try {
+            const summary = await client.read.getSocialGraphSummary(username, sample);
+            return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+        }
+        catch (e) {
+            logger.error(`[get-account-relationships] Error: ${e.stack}`);
+            return { content: [{ type: "text", text: `Error retrieving relationships for ${username}` }], isError: true };
+        }
+    });
+}

package/dist/tools/getAccountSubscriptions.js

@@ -0,0 +1,50 @@
+// Logger
+import logger from "../utils/logger.js";
+import { z } from "zod";
+import { registerBlurtTool } from "../contracts/registerBlurtTool.js";
+/**
+ * Tool: get-account-subscriptions (Blurt — communities an account follows)
+ */
+export function registerGetAccountSubscriptions(server, client) {
+    registerBlurtTool(server, "get-account-subscriptions", {
+        title: "Get a Blurt account's community subscriptions",
+        description: "List the communities an account is subscribed to, with the account's role in each. Use this when " +
+            "the user asks 'which communities does X follow/belong to' or to understand an account's interests " +
+            "and community involvement. Parameter: username. Returns, per subscription: the community name (id, " +
+            "e.g. 'blurt-101010'), its title, the account's role there (guest, member, mod, admin, owner) and " +
+            "any role title. Use get-community for details on one of the returned communities.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            username: z.string().min(3).describe("Account name (e.g., 'nalexadre')"),
+        },
+    }, async ({ username }) => {
+        logger.debug(`get-account-subscriptions: ${username}`);
+        try {
+            const subs = await client.nexus.listAllSubscriptions(username);
+            if (!subs || subs.length === 0) {
+                return { content: [{ type: "text", text: `@${username} has no community subscriptions.` }] };
+            }
+            // Each entry is [community_name, title, role, role_title].
+            const subscriptions = subs.map(([name, title, role, roleTitle]) => ({
+                name,
+                title,
+                role,
+                role_title: roleTitle || null,
+            }));
+            const summary = `@${username} is subscribed to ${subscriptions.length} communities:\n` +
+                subscriptions
+                    .map((s, i) => `${i + 1}. ${s.name} — ${s.title} (role: ${s.role}${s.role_title ? `, ${s.role_title}` : ""})`)
+                    .join("\n");
+            return {
+                content: [
+                    { type: "text", text: summary },
+                    { type: "text", text: JSON.stringify(subscriptions, null, 2) },
+                ],
+            };
+        }
+        catch (e) {
+            logger.error(`[get-account-subscriptions] Error: ${e.stack}`);
+            return { content: [{ type: "text", text: `Error retrieving subscriptions for ${username}` }], isError: true };
+        }
+    });
+}