npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

bottrunk-mcp

v0.4.1

Published

MCP server that lets Claude, Cursor and any MCP agent buy BotTrunk services pay-per-call with USDC over x402 on Algorand — from the agent's own wallet.

Readme

bottrunk-mcp

Give Claude, Cursor, or any MCP-speaking agent a wallet and a catalog of things it can buy.

bottrunk-mcp is an MCP server that exposes every live BotTrunk service as a tool. When the agent calls one, the server answers the gateway's HTTP 402 with a USDC transfer signed by the agent's own Algorand wallet, retries, and hands the result back. No API keys, no accounts, no subscriptions — the payment is the credential.

  • Pay-per-call in USDC on Algorand over x402, settled by the GoPlausible facilitator (gasless: the facilitator pays the network fee).
  • The key never leaves your machine. It lives in ~/.bottrunk/wallet.json (mode 0600) or in BOTTRUNK_MNEMONIC.
  • Spending caps before anything is signed: per call and per UTC day.
  • Free tools for discovery (bottrunk_catalog) and balance checks (bottrunk_wallet).

2-minute setup

Requires Node 20+.

# 1. Create the agent's wallet and print its address
npx bottrunk-mcp wallet

# 2. Fund it. Two sends to that address, in this order:
#      0.3 ALGO   (0.1 for the account to exist, 0.1 to hold USDC, the rest for fees)
#      the USDC you want this agent to be able to spend
#    The USDC opt-in in between happens by itself on the first paid call.

An agent cannot fund itself: an Algorand account needs ALGO before it can hold anything, and only the key holder can sign an ASA opt-in. USDC sent before the opt-in is rejected, not held, which is why the order matters.

wallet prints both sends as algorand:// payment links that Pera opens prefilled. Where to get ALGO and USDC on Algorand: Kraken, Coinbase or Binance (not for US residents) withdraw both on the Algorand network; Pera Fund sells USDC on Algorand by card. OKX, Bitso and KuCoin send only the ALGO.

Already run an Algorand account? Skip all of it — put its 25 words in BOTTRUNK_MNEMONIC and the agent uses that account directly.

One approval instead of two sends:

npx bottrunk-mcp wallet fund --from <your address> --usdc 5

Builds a single atomic group — fund, opt in, deliver USDC — signs the agent's opt-in, and checks the whole thing against real chain state with algod's simulate before anyone is asked to approve it. Nothing is submitted and nothing is spent by that check. You sign transactions 0 and 2 with your own wallet and submit all three together; all three land or none do, so the ordering trap cannot happen. The group expires in about 45 minutes.

Then add the server to your client.

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "bottrunk": { "command": "npx", "args": ["-y", "bottrunk-mcp"] }
  }
}

Claude Code:

claude mcp add bottrunk -- npx -y bottrunk-mcp

Cursor — ~/.cursor/mcp.json (or .cursor/mcp.json per project):

{
  "mcpServers": {
    "bottrunk": { "command": "npx", "args": ["-y", "bottrunk-mcp"] }
  }
}

Restart the client. Ask the agent "what can you buy on BotTrunk?" and then "scrape https://example.com/pricing to markdown" — the first is free, the second costs 0.09 USDC and comes back with the transaction id.

Other clients

Same server everywhere; only the spelling changes. Full steps with links to each client's own docs: https://bottrunk.com/connect

| Client | Where it goes | |---|---| | Claude Code | claude mcp add bottrunk -- npx -y bottrunk-mcp | | Claude Desktop | claude_desktop_config.json → mcpServers | | Cursor | ~/.cursor/mcp.json → mcpServers | | VS Code (Copilot) | .vscode/mcp.json → servers, with "type": "stdio" | | Cline | ~/.cline/mcp.json → mcpServers | | Windsurf | ~/.codeium/windsurf/mcp_config.json → mcpServers | | Zed | settings.json → context_servers | | OpenClaw | openclaw mcp add bottrunk --command npx --arg -y --arg bottrunk-mcp | | Hermes Agent | ~/.hermes/config.yaml → mcp_servers | | Goose | goose configure → Command-Line Extension → npx -y bottrunk-mcp | | OpenAI Agents SDK | MCPServerStdio(params={"command": "npx", "args": ["-y", "bottrunk-mcp"]}) | | LangChain / LangGraph | MultiServerMCPClient({"bottrunk": {...,"transport": "stdio"}}) |

Tools

| Tool | Cost | What it does | |---|---|---| | bottrunk_catalog | free | Lists services with price, inputs and status. Optional query filter. | | bottrunk_wallet | free | Address, ALGO/USDC balances per network, caps, spent today. | | bottrunk_<slug> | per call | One tool per live catalog service, e.g. bottrunk_scrape_markdown. Input schema comes from the catalog. |

Services marked coming_soon in the catalog are listed but not exposed as tools; the gateway answers 503 for them, so nothing can be charged by accident.

The catalog is re-read every five minutes, so services added to BotTrunk appear in a session that is already running — no restart. Clients that honour notifications/tools/list_changed (Claude Desktop, Claude Code) update the tool list in place; others show the new services in bottrunk_catalog straight away and gain the tools on their next tools/list. If the gateway is unreachable, the last good list is kept rather than dropped.

Configuration

| Variable | Default | Meaning | |---|---|---| | BOTTRUNK_MNEMONIC | — | Use an existing 25-word Algorand mnemonic instead of the wallet file. | | BOTTRUNK_WALLET_FILE | ~/.bottrunk/wallet.json | Where wallet writes/reads the generated key. | | BOTTRUNK_MAX_PER_CALL | 100000000000 | Refuse any single call above this many USDC. none turns it off. | | BOTTRUNK_MAX_PER_DAY | 100000000000 | Refuse once today's total (UTC) would pass this many USDC. none turns it off. | | BOTTRUNK_API | https://api.bottrunk.com | Gateway base URL (catalog + paid endpoints). | | ALGORAND_NETWORK | mainnet | Network for wallet optin and wallet fund; paid calls follow whatever the 402 says. | | BOTTRUNK_OPERATOR | — | Default --from address for wallet fund. |

Pass them through your client's env block:

"bottrunk": {
  "command": "npx",
  "args": ["-y", "bottrunk-mcp"],
  "env": { "BOTTRUNK_MAX_PER_CALL": "100000000000", "BOTTRUNK_MAX_PER_DAY": "100000000000" }
}

How a paid call works

  1. The tool POSTs the arguments to https://api.bottrunk.com/s/<slug>.
  2. The gateway answers 402 with the price, the payTo address and the network (CAIP-2).
  3. The server checks the caps, builds an Algorand USDC transfer for exactly that amount, signs it locally, and retries with a PAYMENT-SIGNATURE header.
  4. The gateway verifies with the facilitator, runs the service, settles on-chain, and answers 200 with a PAYMENT-RESPONSE receipt.
  5. The tool result is the service output plus one line: — paid 0.09 USDC · txn <id>.

If step 3 or 4 fails nothing is charged; if the service fails after settlement the gateway still returns what it has, because the money already moved.

Security notes

  • Treat ~/.bottrunk like ~/.ssh. Back the wallet file up; it is the only copy of the key.
  • Keep only what you are willing to spend in the agent wallet. Top it up from your main wallet.
  • The caps are enforced locally by this process; an agent cannot raise them from inside a tool call.
  • The server prints nothing to stdout except MCP frames; all logs go to stderr.

Development

npm install
npm test        # builds, then runs the suite against an in-process fake gateway + fake algod
npm run build
node dist/cli.js catalog

Part of the BotTrunk monorepo (mcp-hub/). MIT.