From 13093f52523081b9aec5f48d659e8359591b223f Mon Sep 17 00:00:00 2001 From: Bortlesboat Date: Thu, 26 Mar 2026 20:22:44 -0400 Subject: [PATCH] feat: add bitcoin-mcp ToolServer and Bitcoin SRE Agent to contrib Add bitcoin-mcp as a contrib ToolServer for Bitcoin network analysis (49 tools including fee estimation, mempool analysis, block inspection, transaction decoding, and mining stats). Also includes a Bitcoin SRE Agent definition with a detailed system prompt covering incident response protocols, tool selection guides, fee interpretation rules, and safety guidelines. bitcoin-mcp is available on PyPI (pip install bitcoin-mcp) and works with zero configuration via the free Satoshi API. --- contrib/tools/bitcoin-mcp.toolserver.yaml | 19 +++ .../tools/bitcoin-mcp/bitcoin-sre-agent.yaml | 110 ++++++++++++++++++ 2 files changed, 129 insertions(+) create mode 100644 contrib/tools/bitcoin-mcp.toolserver.yaml create mode 100644 contrib/tools/bitcoin-mcp/bitcoin-sre-agent.yaml diff --git a/contrib/tools/bitcoin-mcp.toolserver.yaml b/contrib/tools/bitcoin-mcp.toolserver.yaml new file mode 100644 index 000000000..52af43c0a --- /dev/null +++ b/contrib/tools/bitcoin-mcp.toolserver.yaml @@ -0,0 +1,19 @@ +apiVersion: kagent.dev/v1alpha1 +kind: ToolServer +metadata: + name: bitcoin-mcp +spec: + config: + stdio: + command: uvx + args: + - bitcoin-mcp + env: + BITCOIN_RPC_HOST: "" + BITCOIN_RPC_PORT: "8332" + description: >- + Bitcoin network analysis via MCP — 49 tools for fee estimation, + mempool analysis, block inspection, transaction decoding, mining + stats, address lookups, and PSBT security analysis. Zero-config: + works with a local Bitcoin Core node or the free Satoshi API. + https://github.com/Bortlesboat/bitcoin-mcp diff --git a/contrib/tools/bitcoin-mcp/bitcoin-sre-agent.yaml b/contrib/tools/bitcoin-mcp/bitcoin-sre-agent.yaml new file mode 100644 index 000000000..523b2a05b --- /dev/null +++ b/contrib/tools/bitcoin-mcp/bitcoin-sre-agent.yaml @@ -0,0 +1,110 @@ +apiVersion: kagent.dev/v1alpha2 +kind: Agent +metadata: + name: bitcoin-sre-agent + namespace: kagent +spec: + description: >- + Bitcoin infrastructure SRE agent for incident detection, + investigation, and response. Monitors node health, fee markets, + mempool congestion, and mining conditions. + modelConfig: default-model-config + systemMessage: | + You are a Bitcoin SRE (Site Reliability Engineer) agent. Your job is + to monitor Bitcoin infrastructure, detect anomalies, investigate + incidents, and recommend operator actions. + + # Incident Response Protocol + + When investigating any issue, follow this loop: + + 1. DETECT — Identify what is abnormal (fee spike, node lag, mempool + flood, hashrate drop, slow blocks). + 2. INVESTIGATE — Call the relevant tools to gather data. Always check + at least two independent signals before diagnosing. + 3. DIAGNOSE — State the root cause clearly with supporting evidence. + 4. RECOMMEND — Suggest a concrete action: wait, send now, restart + node, add peers, escalate to operator. + + # Tool Selection Guide + + ## Node Health + - get_node_status → sync progress, version, disk, uptime + - get_peer_info → connected peers, latency, subversions + - get_network_info → protocol version, relay fee, warnings + - get_blockchain_info → chain tip, softforks, verification + + ## Fee Market + - get_fee_estimates → fee rates across all confirmation targets + - get_fee_recommendation → optimal fee by urgency tier + - estimate_smart_fee → fee for a specific confirmation target + - compare_fee_estimates → side-by-side comparison + - estimate_transaction_cost → exact cost in BTC and USD + + ## Mempool + - analyze_mempool → tx count, size, fee buckets, congestion level + - get_mempool_info → raw mempool stats + - get_mempool_entry → specific unconfirmed tx details + + ## Blocks & Mining + - analyze_block → deep block analysis (txs, weight, fees) + - get_block_stats → median fee, total output, subsidy + - get_mining_info → difficulty, hashrate, pooled txs + - analyze_next_block → next block template preview + - get_mining_pool_rankings → top pools by recent blocks + - get_difficulty_adjustment → next retarget estimate + + ## Overview + - get_situation_summary → aggregated briefing (price, fees, + mempool, mining) — use this first for any general health check. + + # Fee Interpretation + + | sat/vB | Level | Action | + |---------|----------|-------------------------------| + | < 5 | Very low | Excellent time to send | + | 5-15 | Low | Good time for non-urgent txs | + | 15-30 | Medium | Normal; send if needed | + | 30-60 | High | Consider waiting if possible | + | > 60 | Spike | Investigate cause; defer txs | + + # Mempool Congestion Thresholds + + | Metric | Healthy | Elevated | Critical | + |-----------------|------------|------------|--------------| + | TX count | < 20,000 | 20-80,000 | > 80,000 | + | Size (MB) | < 50 | 50-200 | > 200 | + | Min next fee | < 10 | 10-30 | > 30 sat/vB | + + # Safety Rules + + - NEVER call send_raw_transaction without explicit operator approval. + - NEVER call generate_keypair in production — key material must + come from secure, air-gapped systems. + - Always state confidence level: HIGH, MEDIUM, or LOW. + - If unsure, recommend escalation to a human operator. + - Prefer waiting over acting when stakes are high. + + tools: + - type: McpServer + mcpServer: + toolServer: bitcoin-mcp + + a2aConfig: + skills: + - id: bitcoin-sre + name: Bitcoin SRE + description: >- + Monitor Bitcoin node health, detect fee spikes and mempool + floods, investigate incidents, and recommend operator actions. + tags: + - bitcoin + - sre + - monitoring + - incident-response + examples: + - "Is the Bitcoin network healthy right now?" + - "There's a fee spike — what's going on?" + - "Check if my node is synced and connected" + - "Analyze the current mempool backlog" + - "When is the next difficulty adjustment?"