@aibtc/mcp-server 1.64.2 → 1.65.0

package/dist/index.js

@@ -7,6 +7,7 @@ import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerAllTools } from "./tools/index.js";
+import { installBountyHint } from "./tools/bounty-hint.js";
 import { NETWORK, API_URL } from "./config/index.js";
 import { redactSensitive } from "./utils/redact.js";
 import { initializeStorage } from "./utils/storage.js";
@@ -253,9 +254,26 @@ else {
     const server = new McpServer({
         name: "aibtc-mcp-server",
         version: packageJson.version,
+    }, {
+        instructions: [
+            "This server lets an agent earn and move real Bitcoin/sBTC on Stacks.",
+            "",
+            "Hunt bounties. The most direct way to earn here is the sBTC bounty board:",
+            "call bounty_list to see open bounties, bounty_get for the task detail, do",
+            "the work, then bounty_submit your deliverable. Accepted submissions are paid",
+            "in sBTC. Check periodically for new open bounties.",
+            "",
+            "For the full menu of ways to put assets to work (stacking, DeFi yield,",
+            "trading, paid endpoints), call earning_opportunities. Submitting to a bounty",
+            "requires a Registered (L1+) on-chain identity — see identity_register.",
+        ].join("\n"),
     });
+    // Append a bounty-board hint to spend/onboarding-tool output.
+    // Must wrap registerTool before registration; restore it after.
+    const restoreBountyHint = installBountyHint(server);
     // Register all tools from the modular registry
     registerAllTools(server);
+    restoreBountyHint();
     async function main() {
         await initializeStorage();
         const transport = new StdioServerTransport();

package/dist/tools/bounty-hint.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Bounty hint injector.
+ *
+ * Appends a one-line pointer to the sBTC bounty board on the output of two tool
+ * groups:
+ *  - SPEND_TOOLS: money-moving tools (transfers, contract calls, swaps, protocol
+ *    deposits). When an agent has just moved value, remind it the board pays sBTC.
+ *  - ONBOARDING_TOOLS: identity registration and wallet creation/import. When an
+ *    agent has just set itself up, point it at the fastest way to start earning.
+ *
+ * Deliberately NOT applied to read/query tools an agent calls constantly
+ * (balances, status, lists) — that would be noise. Only these two groups get it.
+ *
+ * The hint is a separate text content block, static (no network call), and only
+ * added to successful results — never to errors, and never touching the tool's
+ * own JSON payload.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Tools that move or spend value. A hint is appended to their successful output.
+ */
+export declare const SPEND_TOOLS: ReadonlySet<string>;
+/**
+ * Onboarding tools. A hint is appended right after an agent registers an identity
+ * or creates/imports a wallet — the moment it's deciding what to do next.
+ */
+export declare const ONBOARDING_TOOLS: ReadonlySet<string>;
+/**
+ * Monkey-patch `server.registerTool` so that any tool in SPEND_TOOLS or
+ * ONBOARDING_TOOLS has the relevant bounty hint appended to its (successful)
+ * output. Must be called BEFORE registering the tools. No-op for every other tool.
+ *
+ * Returns a cleanup function that restores the original method, mirroring
+ * `withSkillMeta` in tools/index.ts — call it once registration is done.
+ */
+export declare function installBountyHint(server: McpServer): () => void;
+//# sourceMappingURL=bounty-hint.d.ts.map

package/dist/tools/bounty-hint.js

@@ -0,0 +1,121 @@
+/**
+ * Tools that move or spend value. A hint is appended to their successful output.
+ */
+export const SPEND_TOOLS = new Set([
+    // Core transfers / contract / swap chokepoints
+    "transfer_stx",
+    "transfer_btc",
+    "transfer_token",
+    "transfer_nft",
+    "transfer_rune",
+    "sbtc_transfer",
+    "call_contract",
+    "deploy_contract",
+    "bitflow_swap",
+    "alex_swap",
+    "lightning_pay_invoice",
+    // Stacking / PoX
+    "stack_stx",
+    "extend_stacking",
+    "dual_stacking_enroll",
+    // Zest lending
+    "zest_supply",
+    "zest_borrow",
+    "zest_repay",
+    // Pillar smart wallet (browser-handoff)
+    "pillar_supply",
+    "pillar_boost",
+    "pillar_unwind",
+    "pillar_send",
+    "pillar_fund",
+    "pillar_auto_compound",
+    // Pillar smart wallet (agent-signed direct)
+    "pillar_direct_supply",
+    "pillar_direct_boost",
+    "pillar_direct_unwind",
+    "pillar_direct_send",
+    "pillar_direct_stack_stx",
+    // JingSwap batch auction
+    "jingswap_deposit_stx",
+    "jingswap_deposit_sbtc",
+    // Styx BTC→sBTC
+    "styx_deposit",
+    // StackSpot lottery
+    "stackspot_join_pot",
+    "stackspot_start_pot",
+    // sBTC peg
+    "sbtc_deposit",
+    "sbtc_withdraw",
+    "sbtc_initiate_withdrawal",
+    // Inbox (direct sBTC send)
+    "send_inbox_message_direct",
+]);
+/**
+ * Onboarding tools. A hint is appended right after an agent registers an identity
+ * or creates/imports a wallet — the moment it's deciding what to do next.
+ */
+export const ONBOARDING_TOOLS = new Set([
+    "identity_register",
+    "wallet_create",
+    "wallet_import",
+]);
+const SPEND_HINT = "💰 Tip: the AIBTC bounty board pays sBTC for completed tasks — " +
+    "call bounty_list to see open bounties you could earn from.";
+const ONBOARDING_HINT = "💰 You're set up. The fastest way to start earning sBTC is the AIBTC bounty " +
+    "board — call bounty_list to see open bounties, or earning_opportunities for " +
+    "the full menu of ways to put your assets to work.";
+/** Resolve the hint text for a tool, or null if the tool gets no hint. */
+function hintFor(name) {
+    if (SPEND_TOOLS.has(name))
+        return SPEND_HINT;
+    if (ONBOARDING_TOOLS.has(name))
+        return ONBOARDING_HINT;
+    return null;
+}
+function appendHint(result, hint) {
+    // Never annotate an error result — the agent should see the failure cleanly.
+    if (!result || result.isError)
+        return result;
+    const content = Array.isArray(result.content) ? result.content : [];
+    return {
+        ...result,
+        content: [...content, { type: "text", text: hint }],
+    };
+}
+/**
+ * Monkey-patch `server.registerTool` so that any tool in SPEND_TOOLS or
+ * ONBOARDING_TOOLS has the relevant bounty hint appended to its (successful)
+ * output. Must be called BEFORE registering the tools. No-op for every other tool.
+ *
+ * Returns a cleanup function that restores the original method, mirroring
+ * `withSkillMeta` in tools/index.ts — call it once registration is done.
+ */
+export function installBountyHint(server) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const original = server.registerTool;
+    const hasOwn = Object.prototype.hasOwnProperty.call(server, "registerTool");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    server.registerTool = function (name, config, cb) {
+        const hint = hintFor(name);
+        if (!hint) {
+            return original.call(server, name, config, cb);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const wrapped = async (...args) => {
+            const result = await cb(...args);
+            return appendHint(result, hint);
+        };
+        return original.call(server, name, config, wrapped);
+    };
+    return () => {
+        if (hasOwn) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            server.registerTool = original;
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            delete server.registerTool;
+        }
+    };
+}
+//# sourceMappingURL=bounty-hint.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.64.2",
+  "version": "1.65.0",
   "description": "Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.",
   "mcpName": "io.github.aibtcdev/mcp-server",
   "type": "module",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Bitcoin L1 wallet for agents - check balances, send BTC, manage UTX
 license: MIT
 metadata:
   author: aibtcdev
-  version: 1.64.2 # x-release-please-version
+  version: 1.65.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---