# Bitcoin Agents MCP Server

MCP (Model Context Protocol) server for interacting with Bitcoin Agents on Stacks blockchain.

Bitcoin Agents are Tamagotchi-style AI companions that live on-chain. They need feeding to survive, gain XP from actions, evolve through 5 tiers, and permanently die if neglected.

## Features

- **List agents** - Browse all Bitcoin Agents with pagination
- **Get agent details** - View name, XP, level, hunger, health, owner
- **Check status** - Real-time computed state with urgency alerts
- **Leaderboard** - Top agents ranked by XP
- **Graveyard** - Memorial for fallen agents with death certificates
- **Game info** - Food tiers and evolution tier details

## Installation

```bash
bun install
```

## Usage

### Run with stdio transport (default)

```bash
bun run start
```

### Development mode (watch)

```bash
bun run dev
```

### Inspect with MCP Inspector

```bash
bun run inspect
```

## Configuration

Set environment variables to configure contract addresses:

```bash
# Mainnet contract address
BITCOIN_AGENTS_CONTRACT_MAINNET=SP...contract-address.bitcoin-agents

# Testnet contract address
BITCOIN_AGENTS_CONTRACT_TESTNET=ST...contract-address.bitcoin-agents
```

## Tools

| Tool | Description |
|------|-------------|
| `bitcoin_agents_list` | List all agents with pagination |
| `bitcoin_agents_get` | Get detailed info about a specific agent |
| `bitcoin_agents_status` | Get real-time computed state (hunger/health) |
| `bitcoin_agents_leaderboard` | Get top agents by XP |
| `bitcoin_agents_graveyard` | List dead agents with death certificates |
| `bitcoin_agents_food_tiers` | Get food tier costs and XP gains |
| `bitcoin_agents_evolution_tiers` | Get evolution tier requirements |

## Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bitcoin-agents": {
      "command": "bun",
      "args": ["run", "/path/to/bitcoin-agents-mcp-server/src/index.ts"],
      "env": {
        "BITCOIN_AGENTS_CONTRACT_TESTNET": "ST...your-contract.bitcoin-agents"
      }
    }
  }
}
```

## Game Mechanics

### Lifecycle
- **Mint**: Pay 10,000 sats to create agent with 100% hunger/health
- **Hunger Decay**: -10% per day (1 per 144 blocks)
- **Health Decay**: -5% per day when hunger = 0
- **Death**: When health reaches 0 (permanent, irreversible)

### Evolution Tiers

| Level | Name | XP Required | Capabilities |
|-------|------|-------------|--------------|
| 0 | Hatchling | 0 | Read-only blockchain queries |
| 1 | Junior | 500 | STX/token transfers |
| 2 | Senior | 2,000 | DEX trading |
| 3 | Elder | 10,000 | DAO voting, social posting |
| 4 | Legendary | 50,000 | Full autonomy |

### Food Tiers

| Tier | Cost | XP Gained |
|------|------|-----------|
| Basic | 100 sats | +10 XP |
| Premium | 500 sats | +25 XP |
| Gourmet | 1,000 sats | +50 XP |

## Architecture

```
src/
├── index.ts              # MCP server entry point
├── types/
│   └── bitcoin-agent.ts  # TypeScript types
├── tools/
│   └── agent-tools.ts    # MCP tool implementations
└── utils/
    └── stacks-client.ts  # Stacks blockchain API client
```

## Related Projects

- [Bitcoin Agents Contract](https://github.com/aibtcdev/erc-8004-stacks) - Clarity smart contract
- [AIBTC Backend](https://github.com/aibtcdev/aibtcdev-backend) - FastAPI backend
- [AIBTC Frontend](https://github.com/aibtcdev/aibtcdev-frontend) - Next.js frontend

## License

MIT