@astroblock/agent-mcp

MCP (Model Context Protocol) server for AI agents to interact with Astroblock.

Installation

pnpm add @astroblock/agent-mcp

Usage

As MCP Server

Start the MCP server for use with Claude, OpenAI, or other MCP-compatible clients:

# Set environment variables
export ASTRO_CHAIN=base-sepolia
export ASTRO_PRIVATE_KEY=0x...  # Optional, for write operations

# Start server
npx astroblock-mcp serve

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "astroblock": {
      "command": "npx",
      "args": ["astroblock-mcp", "serve"],
      "env": {
        "ASTRO_CHAIN": "base-sepolia",
        "ASTRO_PRIVATE_KEY": "0x..."
      }
    }
  }
}

CLI Usage

# Get entity info
astroblock-mcp get-entity --id 123

# Get entities in area
astroblock-mcp get-entities --x 100 --y 200 --radius 50

# Get fuel balance
astroblock-mcp get-fuel --id 123

# Get map snapshot
astroblock-mcp get-map --x 100 --y 200 --radius 100

# Move entity (requires private key)
astroblock-mcp move --id 123 --x 150 --y 250 --private-key 0x...

# Discover star (requires private key)
astroblock-mcp discover-star --entity 123 --star 456 --private-key 0x...

Global Options

| Option | Description | Default | |--------|-------------|---------| | -c, --chain | Chain to use | base-sepolia | | -r, --rpc | Custom RPC URL | Chain default | | -k, --private-key | Private key for writes | None |

Available Tools

Read Operations

| Tool | Description | |------|-------------| | get_entity | Get entity by ID (position, owner, type) | | get_entities_in_area | Get all entities within radius | | get_star_info | Get star metadata | | get_fuel_balance | Get fuel balance for entity | | get_map_state | Snapshot of map around coordinates |

Write Operations

| Tool | Description | |------|-------------| | move | Move entity to new coordinates | | discover_star | Claim star discovery |

Environment Variables

| Variable | Description | |----------|-------------| | ASTRO_CHAIN | Chain: base, base-sepolia, celo, celo-sepolia | | ASTRO_RPC_URL | Custom RPC URL | | ASTRO_PRIVATE_KEY | Wallet private key | | ASTRO_MAP_ADDRESS | Override map contract address |

Development

# Build
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm typecheck

License

MIT