@polymerdao/mcp-polymer/README.md

A Model Context Protocol (MCP) server for blockchain event verification using Polymer's Prove API.

# MCP Polymer

A Model Context Protocol (MCP) server for blockchain event verification using Polymer's Prove API. Enables AI agents to query blockchain events, request Polymer event proofs, query the status of a proof request, query supported chains, and more. See below for a list of available tools.

The package is published as [`@polymerdao/mcp-polymer`](https://www.npmjs.com/package/@polymerdao/mcp-polymer) on NPM.

## 🚀 Quick Start

### Prerequisites

- Node.js v18+
- npm or yarn
- Polymer API key (for blockchain proof requests)

### Claude Integration

Configure separate MCP server instances for each environment you need:

```json
{
    "mcpServers": {
        "mcp-polymer-mainnet": {
            "command": "npx",
            "args": ["@polymerdao/mcp-polymer", "--environment", "mainnet"],
            "env": {
              "POLYMER_API_KEY": "<your-mainnet-api-key>"
            }
        },
        "mcp-polymer-testnet": {
            "command": "npx",
            "args": ["@polymerdao/mcp-polymer", "--environment", "testnet"],
            "env": {
              "POLYMER_API_KEY": "<your-testnet-api-key>"
            }
        }
    }
}
```

Or for Claude Code:

```bash
claude mcp add mcp-polymer-mainnet -e POLYMER_API_KEY=<your-mainnet-api-key> -- npx @polymerdao/mcp-polymer --environment mainnet
claude mcp add mcp-polymer-testnet -e POLYMER_API_KEY=<your-testnet-api-key> -- npx @polymerdao/mcp-polymer --environment testnet
```

This allows you to connect to multiple Polymer environments simultaneously in Claude. Each MCP server instance operates independently with its own API key and environment configuration.

### Installation

```bash
npm install -g @polymerdao/mcp-polymer
```

### Basic Usage

The server communicates over stdio. Each MCP server instance runs in a specific environment.

```bash
# Set API key
export POLYMER_API_KEY=<environment_specific_api_key>
```

```bash
# Run latest version on mainnet
npx @polymerdao/mcp-polymer --environment <devnet|testnet|shadownet|mainnet>

# or alternatively
npm start -- --environment <devnet|testnet|shadownet|mainnet>
```

### Version Information

```bash
npm start -- --version
```

## 📋 MCP Tools

All tools use the API key configured via the `POLYMER_API_KEY` environment variable.

- **`get_version`**: Returns server version information.
- **`request_proof`**: Initiates a Polymer proof request for a specific blockchain event.
- **`query_proof_status`**: Checks the status of an existing proof generation job.
- **`wait_for_proof_completion`**: Polls and waits for proof completion.
- **`verify_polymer_proof`**: Verifies a complete Polymer proof including ECDSA signature and IAVL merkle tree verification. Returns detailed parsed proof data including all extracted components.
- **`get_connected_chains`**: Retrieves real-time chain connection status.
- **`get_client_updates`**: Gets client synchronization status across all chains.
- **`eth_getBlockByNumber`**: Standard Ethereum JSON-RPC method for block data retrieval.
- **`eth_getBlockByHash`**: Standard Ethereum JSON-RPC method for block data retrieval by hash.
- **`eth_getLogs`**: Retrieves event logs from a chain.
- **`get_chainlist_cache_stats`**: Gets statistics about the chainlist RPC cache.
- **`clear_chainlist_cache`**: Clears the chainlist RPC cache.
- **`get_chain_rpcs`**: Retrieves all available RPC endpoints for a chain.

## ⚙️ Configuration

Configuration is managed via command-line arguments or environment variables (prefixed with `POLYMER_`).

### Command Line Arguments

```bash
npm start -- [--environment <devnet|testnet|shadownet|mainnet>]
```

### Environment Variables

- `POLYMER_API_KEY` - API key for Polymer services (required)
- `POLYMER_ENVIRONMENT` - Environment selection (alternative to --environment)

## 🔧 Development

### Building from Source

```bash
npm install
npm run build
```

### Running Tests

```bash
npm test
```

### MCP Testing

Use [MCP Inspector](https://github.com/modelcontextprotocol/mcp-inspector) to test the server.

```bash
npx @modelcontextprotocol/inspector
```

```bash
# Install globally
npm install -g @polymerdao/mcp-polymer

# Or install locally
npm install @polymerdao/mcp-polymer
```

### GitHub Workflows

- **CI**: Runs tests on all pull requests and pushes to main/develop
- **Publish**: Automatically publishes to NPM when version tags (v*.*.*) are pushed
- **Release**: Manual workflow for creating releases and updating changelog

## 🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

### Development Setup

```bash
git clone https://github.com/polymerdao/mcp-polymer.git
cd mcp-polymer
npm install
npm run build
npm test
npm link (optional)
```

### Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## 📄 License

This project is licensed under the Apache 2.0 License.