Beesknees MCP Server

The Bee's Knees

A race to the queen, monetized with Tollbooth DPYC™ Bitcoin Lightning micropayments — and run for the benefit of pollinators.

Buy a drone a seat. Fly it to a flower, carry the pollen home through the hive wall, then tunnel inward. The first bee to reach a queen takes the round. Most of what the round collects goes to pollinator welfare; the winner and the operator each take a small share.

What you're building

      YOU (operator, human in the loop)
        │                         │
        │ set & tune prices       │ drive credential intake
        ▼                         ▼
  ┌───────────────┐        ┌──────────────────────────────────────────────┐
  │ Pricing Studio│ prices │   The Bee's Knees — OPERATOR MCP              │
  │    (iOS)      ├───────▶│   FastMCP · deployed on Horizon               │
  └───────────────┘  Neon  │  ┌────────────────────────────────────────┐  │
                           │  │ geometry · board · match · settlement   │  │
   Patron (Citizen)        │  │ @runtime.paid_tool(FROZEN_UUID) tools   │  │
   + MCP client  ─────────▶│  ├────────────────────────────────────────┤  │
   (Claude, the SPA) npub  │  │ tollbooth-dpyc SDK (the wheel)          │  │
                    +sats  │  │  ledger · vault (AES-256-GCM) · pricing │  │
                           │  │  ConstraintGate · Secure Courier·audit  │  │
                           │  └────────────────────────────────────────┘  │
                           └───┬─────────┬──────────┬───────────┬─────────┘
                               ▼         ▼          ▼           ▼
                         Neon Postgres  BTCPay▶  Sponsor     Nostr relays
                         (your schema)  Lightning Authority   proofs·courier
                         ledger+board   invoices  certify +    DMs·audit
                                                  provision        │
                                                      │            ▼
                                                      └──▶ DPYC Oracle +
                                                            dpyc-community

The board

A hive is round because the field has to narrow. Ring 0 is the queen's chamber, ring 24 is the hive wall, and four open-air rings above it are meadow. Cells scale with circumference, so the wall holds about fifty and the last ring before the chamber holds six. Everyone starts spread out and converges into a scrum — 857 cells in all.

Movement is inward, outward, or sideways along a ring. Sideways is what makes it a maze rather than a set of lanes: it is how you slide onto somebody else's open shaft, or step out from under a collapse.

The one real choice

Cut your own shaft — slow, and open to everyone the moment it exists. Or ride one somebody else paid for — fast, and they can bring it down on you.

Three motions carry it. fly moves through open ground. dig cuts fresh comb and costs several cooldowns rather than one. seal buries an open cell so the bees behind must cut it again.

A bee acts once per cooldown, measured on the clock, so no amount of spending buys a faster bee. What spending buys is interference.

Why four hives and not one

Four hives of twelve, and a match starts the moment any hive holds eight.

That is a measured decision, not a taste one. Racing fifty near-identical bees to a single queen is close to a lottery: first-past-the-post among fifty is an extreme-value draw, and those are settled by variance rather than by skill. The batch runner in sim/ puts a good strategy at 1.4x uniform with fifty bees in one hive and 2.1x with twelve. Winning your own hive is skill-weighted; which of the four leaders finishes first is a fair draw, so the signal survives.

node sim/run.ts --rounds 400 --bees 12    # re-measure before changing a rule

Where the money goes

Most of what a round collects goes to pollinator conservation. The beneficiary is Pollinator Partnership — chosen over the honeybee-focused charities on purpose, because managed honeybees are livestock and are not the ones in trouble; native and wild pollinators are, and they are what Pollinator Partnership covers.

The rail is deliberately not in the software

The system computes and publishes the debt. The operator settles it and records the proof. No automated payout to a third party, and that is a design decision rather than a shortcut:

• A single round's share is small, and an on-chain network fee can exceed it. A settlement that costs more than it delivers is worse than no settlement.
• Donations route through The Giving Block, which issues a fresh address per donation that expires after 180 days unused — there is no stable destination to hold in config, and one minted early is wrong within six months.
• The beneficiary takes on-chain BTC only ("Send only BTC to this address using the Bitcoin blockchain"). Not Lightning. So the fares arrive on one rail and the donation leaves on another, by their rules rather than by choice.
• Fares arrive over Lightning, into channels. Paying out on chain is not the same balance, and no amount of code makes it one.

So the charity's share accrues per round and is settled in batches. Each settlement records the beneficiary, the amount, the date and the transaction id — and beesknees_settlement_history serves all of it free, because a claim about where the money went that costs money to check is not a claim anybody should believe. The txid is what makes it verifiable by someone who trusts nothing else here.

The beneficiary is stored, not compiled in, so it can change. Every settlement records the beneficiary it actually paid, so history stays true even when the current one changes — a patron who played because of where the money went can always check where it went.

Layout

The rules exist in three copies — this Python, the client's TypeScript, and the renderers — and nothing at runtime reports that they have drifted; the game simply starts rejecting moves a player can see are legal. tests/test_geometry.py and frontend/src/game/rules.test.ts assert the same invariants on purpose, so a drift fails a build instead of a match.

Onboarding roadmap

1. Nostr keypair — generate one (nak key generate); the nsec is the single env var the server needs (TOLLBOOTH_NOSTR_OPERATOR_NSEC).
2. Sponsor Authority — register; it provisions your Neon database.
3. Secure Courier — deliver btcpay_host, btcpay_api_key, btcpay_store_id via beesknees_request_credential_channel. Never as env vars, never in code.
4. Set prices in Pricing Studio — new tools start unpriced, and nobody can call an unpriced tool.
5. Deploy on Horizon — fastmcp.json is already wired.

Get Pricing Studio (iOS). It reads and writes the pricing model live in Neon, so prices never live in code — surge, happy-hour, loyalty discounts and free trials are the thing a flat paywall can never give you.

The app

frontend/ carries the Bee's Knees app, deployed to Cloudflare Pages with functions/mcp.js proxying /mcp same-origin. It runs a solo mode against the local engine — the whole match filled with bots but one seat — so the interface can be played before anybody has paid for anything.

The focused hive is drawn in WebGL on top of an SVG first paint. The SVG is what the server-side smoke and prerender checks see, what a browser shows on its first frame, and what the game falls back to if WebGL is lost; the stage takes over once PixiJS has loaded and drawn. Nothing about the game lives in the stage — it renders what both engines already compute.

Develop

uv venv --python python3.12          # coincurve has no 3.14 wheel
uv pip install -e ".[dev]"
ruff check . && pytest -v
python -m beesknees_mcp.server       # runs the validate_operator_tools guard

cd frontend && npm install
npm run dev                          # solo mode on http://localhost:5180
npm test && npm run smoke            # invariants, then a real first paint (the SVG one)

License

Apache-2.0