Metadata-Version: 2.4
Name: celo_mcp
Version: 0.1.12
Summary: A Model Context Protocol (MCP) server for Celo blockchain data access and functionality
Project-URL: Homepage, https://github.com/viral-sangani/celo-mcp
Project-URL: Repository, https://github.com/viral-sangani/celo-mcp
Project-URL: Documentation, https://github.com/viral-sangani/celo-mcp#readme
Project-URL: Issues, https://github.com/viral-sangani/celo-mcp/issues
Author-email: viral-sangani <viral.sangani2011@gmail.com>
License-File: LICENSE
Keywords: ai,blockchain,celo,llm,mcp,web3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: asyncio-throttle>=1.0.0
Requires-Dist: crawl4ai>=0.6.0
Requires-Dist: eth-abi>=5.0.0
Requires-Dist: eth-account>=0.11.0
Requires-Dist: eth-utils>=4.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: web3>=7.0.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Celo MCP Server

A Model Context Protocol (MCP) server for interacting with the Celo blockchain. This server provides comprehensive access to Celo blockchain data, token operations, NFT management, smart contract interactions, and transaction handling.

## Installation

1. Clone the repository:

```bash
git clone https://github.com/celo-org/celo-mcp
cd celo-mcp
```

2. Install dependencies:

```bash
pip install -e .
```

3. Set up environment variables (optional):

```bash
export CELO_RPC_URL="https://forno.celo.org"  # Default: Celo mainnet
export CELO_TESTNET_RPC_URL="https://alfajores-forno.celo-testnet.org"  # Alfajores testnet
```

## Usage

### Running the Server

```bash
# Run the MCP server
python -m celo_mcp.server

# Or use the CLI entry point
celo-mcp-server
```

### Available Tools

#### Blockchain Data Operations

1. **get_network_status**

   - Get current network status and connection information
   - No parameters required

2. **get_block**

   - Fetch block information by number, hash, or "latest"
   - Parameters: `block_identifier`, `include_transactions` (optional)

3. **get_transaction**

   - Get transaction details by hash
   - Parameters: `tx_hash`

4. **get_account**

   - Get account information including balance and nonce
   - Parameters: `address`

5. **get_latest_blocks**
   - Get information about recent blocks
   - Parameters: `count` (optional, default: 10, max: 100)

#### Token Operations

6. **get_token_info**

   - Get detailed token information (name, symbol, decimals, supply)
   - Parameters: `token_address`

7. **get_token_balance**

   - Get token balance for a specific address
   - Parameters: `token_address`, `address`

8. **get_celo_balances**
   - Get CELO and stable token balances for an address
   - Parameters: `address`

#### NFT Operations

9. **get_nft_info**

   - Get NFT information including metadata and collection details
   - Parameters: `contract_address`, `token_id`

10. **get_nft_balance**
    - Get NFT balance for an address (supports ERC721 and ERC1155)
    - Parameters: `contract_address`, `address`, `token_id` (optional for ERC1155)

#### Smart Contract Operations

11. **call_contract_function**

    - Call a read-only contract function
    - Parameters: `contract_address`, `function_name`, `abi`, `function_args` (optional), `from_address` (optional)

12. **estimate_contract_gas**
    - Estimate gas for a contract function call
    - Parameters: `contract_address`, `function_name`, `abi`, `from_address`, `function_args` (optional), `value` (optional)

#### Transaction Operations

13. **estimate_transaction**

    - Estimate gas and cost for a transaction
    - Parameters: `to`, `from_address`, `value` (optional), `data` (optional)

14. **get_gas_fee_data**
    - Get current gas fee data including EIP-1559 fees
    - No parameters required

## Architecture

The server is built with a modular architecture:

```
src/celo_mcp/
├── blockchain_data/     # Core blockchain data access
│   ├── client.py       # Celo blockchain client
│   ├── models.py       # Data models
│   └── service.py      # Blockchain data service
├── tokens/             # Token operations
│   ├── models.py       # Token-related models
│   └── service.py      # Token service (ERC20, Celo stable tokens)
├── nfts/              # NFT operations
│   ├── models.py       # NFT-related models
│   └── service.py      # NFT service (ERC721, ERC1155)
├── contracts/         # Smart contract interactions
│   ├── models.py       # Contract-related models
│   └── service.py      # Contract service
├── transactions/      # Transaction management
│   ├── models.py       # Transaction-related models
│   └── service.py      # Transaction service
├── server.py          # Main MCP server
└── utils.py           # Utility functions
```

## Key Features

### Token Support

- **ERC20 Standard**: Full support for ERC20 tokens
- **Celo Stable Tokens**: Built-in support for cUSD, cEUR, and cREAL
- **Balance Queries**: Get token balances with proper decimal formatting
- **Token Information**: Retrieve name, symbol, decimals, and total supply

### NFT Support

- **Multi-Standard**: Support for both ERC721 and ERC1155 standards
- **Automatic Detection**: Automatically detects NFT standard using ERC165
- **Metadata Fetching**: Retrieves and parses NFT metadata from URIs
- **IPFS Support**: Built-in IPFS gateway support for metadata
- **Collection Information**: Get collection-level information

### Smart Contract Interactions

- **Function Calls**: Call read-only contract functions
- **Gas Estimation**: Estimate gas costs for contract interactions
- **ABI Management**: Parse and manage contract ABIs
- **Event Handling**: Retrieve and decode contract events
- **Transaction Building**: Build contract transactions

### Transaction Management

- **Gas Estimation**: Accurate gas estimation for transactions
- **EIP-1559 Support**: Modern fee structure with base fee and priority fee
- **Transaction Simulation**: Simulate transactions before execution
- **Fee Calculation**: Dynamic fee calculation based on network conditions

## Error Handling

The server includes comprehensive error handling:

- Input validation for all parameters
- Network error handling with retries
- Graceful degradation for optional features
- Detailed error messages for debugging

## Caching

Performance optimization through caching:

- Contract ABI caching
- Token metadata caching
- NFT metadata caching with IPFS support
- Network data caching with appropriate TTLs

## Security Considerations

- Read-only operations by default
- No private key handling in the server
- Input validation and sanitization
- Rate limiting considerations for external API calls

## Development

### Running Tests

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=celo_mcp
```

### Code Quality

```bash
# Format code
black src/
isort src/

# Lint code
flake8 src/
mypy src/
```

## Contributing

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 MIT License - see the LICENSE file for details.

## Support

For questions, issues, or contributions, please:

1. Check the existing issues on GitHub
2. Create a new issue with detailed information
3. Join the community discussions

## Acknowledgments

- Built on the Model Context Protocol (MCP) framework
- Uses Web3.py for Ethereum/Celo blockchain interactions
- Supports the Celo ecosystem and its stable token infrastructure
