@blockrun/mcp 0.2.2 → 0.3.0

package/README.md

@@ -122,11 +122,34 @@ blockrun list models
 blockrun show OpenAI models with pricing
 ```
 
-### Wallet Management
+### Real-Time X/Twitter Search
+
+Get live data from X/Twitter using Grok's real-time search:
+
+```
+blockrun twitter: what is @elonmusk posting about today
+
+blockrun twitter: trending AI news
+
+blockrun twitter: reactions to [recent event]
+```
+
+### Wallet & Balance
 
 ```
 blockrun setup          # First-time setup instructions
 blockrun wallet         # Check your wallet address
+blockrun balance        # Check on-chain USDC balance
+```
+
+### Budget Management
+
+Control your session spending:
+
+```
+blockrun budget check              # View current spending
+blockrun budget set $1.00          # Set $1.00 limit
+blockrun budget clear              # Remove limit
 ```
 
 ## Supported Models & Pricing
@@ -259,7 +282,10 @@ The MCP couldn't find or create a wallet. Check that `~/.blockrun/` directory is
 Some models have rate limits. Try `blockrun smart cheap` or `blockrun smart fast` to use alternative models.
 
 ### Check wallet balance
-Say `blockrun wallet` or visit: `https://basescan.org/address/YOUR_ADDRESS`
+Say `blockrun balance` to check your on-chain USDC balance, or visit: `https://basescan.org/address/YOUR_ADDRESS`
+
+### Budget limit reached
+If you've set a session budget and hit the limit, use `blockrun budget clear` to remove it or `blockrun budget set $X` to increase it.
 
 ## Configuration
 

package/dist/index.js

@@ -22,6 +22,13 @@ var walletWasCreated = false;
 var walletAddress = null;
 var client = null;
 var cachedModels = null;
+var sessionBudget = { limit: null, spent: 0, calls: 0 };
+var USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var BASE_RPC_URLS = [
+  "https://mainnet.base.org",
+  "https://base.llamarpc.com",
+  "https://1rpc.io/base"
+];
 function getOrCreateWalletKey() {
   const envKey = process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY;
   if (envKey) {
@@ -130,9 +137,47 @@ SECURITY NOTE:
 ================================================================================
 `;
 }
+async function getUsdcBalance(address) {
+  const data = {
+    jsonrpc: "2.0",
+    method: "eth_call",
+    params: [{
+      to: USDC_ADDRESS,
+      data: `0x70a08231000000000000000000000000${address.slice(2)}`
+    }, "latest"],
+    id: 1
+  };
+  for (const rpcUrl of BASE_RPC_URLS) {
+    try {
+      const response = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(data)
+      });
+      const result = await response.json();
+      if (result.result) {
+        return parseInt(result.result, 16) / 1e6;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function recordSpending(cost) {
+  sessionBudget.spent += cost;
+  sessionBudget.calls += 1;
+}
+function checkBudget() {
+  if (sessionBudget.limit === null) {
+    return { allowed: true, remaining: null };
+  }
+  const remaining = sessionBudget.limit - sessionBudget.spent;
+  return { allowed: remaining > 0, remaining };
+}
 var server = new McpServer({
   name: "blockrun-mcp",
-  version: "0.2.0"
+  version: "0.3.0"
 });
 server.registerTool(
   "blockrun_chat",
@@ -433,6 +478,181 @@ Returns:
     return { content: [{ type: "text", text: getWalletSetupInstructions() }] };
   }
 );
+server.registerTool(
+  "blockrun_twitter",
+  {
+    description: `Search real-time X/Twitter data using Grok's live search.
+
+Use this tool for:
+- Checking what people are saying about a topic
+- Finding recent tweets from specific accounts
+- Getting trending discussions
+- Real-time news and events
+
+Example queries:
+- "what is @elonmusk posting about today"
+- "trending AI news"
+- "reactions to [event]"`,
+    inputSchema: {
+      query: z.string().describe("Search query - can include @handles, topics, or natural language questions"),
+      max_results: z.number().optional().default(10).describe("Maximum number of results to return (1-25)")
+    },
+    outputSchema: {
+      query: z.string(),
+      model: z.string(),
+      response: z.string()
+    }
+  },
+  async ({ query, max_results }) => {
+    const budget = checkBudget();
+    if (!budget.allowed) {
+      return {
+        content: [{ type: "text", text: `Budget limit reached. Spent $${sessionBudget.spent.toFixed(4)} of $${sessionBudget.limit?.toFixed(2)} limit.
+
+Use blockrun_budget to check or adjust your budget.` }],
+        isError: true
+      };
+    }
+    try {
+      const llm = getClient();
+      const model = "xai/grok-3";
+      const system = `You are a real-time X/Twitter search assistant.
+When searching, focus on:
+- Recent and relevant posts
+- Key accounts and verified sources
+- Engagement metrics when relevant
+Format your response clearly with sources when available.
+Max results requested: ${max_results}`;
+      const response = await llm.chat(model, query, {
+        system,
+        search: true
+      });
+      recordSpending(2e-3);
+      return {
+        content: [{ type: "text", text: `[X/Twitter Search via Grok]
+
+${response}` }],
+        structuredContent: { query, model, response }
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: "text", text: formatError(errorMessage) }],
+        isError: true
+      };
+    }
+  }
+);
+server.registerTool(
+  "blockrun_balance",
+  {
+    description: `Check your on-chain USDC balance on Base network.
+
+Returns:
+- Current USDC balance
+- Wallet address
+- Link to view on Basescan
+
+Use this to see how much funding you have available for BlockRun API calls.`,
+    inputSchema: {},
+    outputSchema: {
+      address: z.string(),
+      balance: z.number().nullable(),
+      network: z.string(),
+      basescanUrl: z.string()
+    }
+  },
+  async () => {
+    const llm = getClient();
+    const address = llm.getWalletAddress();
+    const balance = await getUsdcBalance(address);
+    const balanceStr = balance !== null ? `$${balance.toFixed(6)} USDC` : "Unable to fetch (try again)";
+    const text = `BlockRun Wallet Balance
+=======================
+
+Address: ${address}
+Balance: ${balanceStr}
+Network: Base (Chain ID: 8453)
+
+View on Basescan: https://basescan.org/address/${address}
+
+${balance !== null && balance < 1 ? "\u26A0\uFE0F  Low balance. Consider adding funds to continue using BlockRun." : ""}`;
+    return {
+      content: [{ type: "text", text }],
+      structuredContent: {
+        address,
+        balance,
+        network: "Base",
+        basescanUrl: `https://basescan.org/address/${address}`
+      }
+    };
+  }
+);
+server.registerTool(
+  "blockrun_budget",
+  {
+    description: `Manage your session spending budget.
+
+Actions:
+- check: View current spending and budget status
+- set: Set a spending limit (e.g., $1.00)
+- clear: Remove spending limit (unlimited)
+
+Use this to control how much you spend per session on BlockRun API calls.`,
+    inputSchema: {
+      action: z.enum(["check", "set", "clear"]).describe("Budget action to perform"),
+      amount: z.number().optional().describe("Budget limit in USD (required for 'set' action)")
+    },
+    outputSchema: {
+      limit: z.number().nullable(),
+      spent: z.number(),
+      calls: z.number(),
+      remaining: z.number().nullable()
+    }
+  },
+  async ({ action, amount }) => {
+    switch (action) {
+      case "set":
+        if (amount === void 0 || amount <= 0) {
+          return {
+            content: [{ type: "text", text: "Error: Please provide a positive amount for the budget limit (e.g., amount: 1.00 for $1.00)" }],
+            isError: true
+          };
+        }
+        sessionBudget.limit = amount;
+        break;
+      case "clear":
+        sessionBudget.limit = null;
+        break;
+      case "check":
+      default:
+        break;
+    }
+    const remaining = sessionBudget.limit !== null ? sessionBudget.limit - sessionBudget.spent : null;
+    const limitStr = sessionBudget.limit !== null ? `$${sessionBudget.limit.toFixed(2)}` : "Unlimited";
+    const remainingStr = remaining !== null ? `$${remaining.toFixed(4)}` : "N/A";
+    const text = `BlockRun Session Budget
+=======================
+
+Limit: ${limitStr}
+Spent: $${sessionBudget.spent.toFixed(4)}
+Calls: ${sessionBudget.calls}
+Remaining: ${remainingStr}
+
+${action === "set" ? `\u2705 Budget set to $${amount?.toFixed(2)}` : ""}
+${action === "clear" ? "\u2705 Budget limit removed (unlimited spending)" : ""}
+${remaining !== null && remaining < 0.01 ? "\u26A0\uFE0F  Budget nearly exhausted!" : ""}`;
+    return {
+      content: [{ type: "text", text }],
+      structuredContent: {
+        limit: sessionBudget.limit,
+        spent: sessionBudget.spent,
+        calls: sessionBudget.calls,
+        remaining
+      }
+    };
+  }
+);
 server.registerResource(
   "wallet",
   "blockrun://wallet",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/mcp",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "mcpName": "io.github.BlockRunAI/blockrun-mcp",
   "description": "BlockRun MCP Server - Access 30+ AI models via x402 micropayments. No API keys needed.",
   "type": "module",