NIX_MCP_IMPLEMENTATION_PLAN.md•8.8 kB
# NIX MCP Server Implementation Plan
## Overview
Build a Python-based MCP (Model Context Protocol) server to provide NIX (Native Indexer) query capabilities through a standardized interface.
## Architecture
### Core Components
1. **MCP Server Framework**
- Use `mcp` Python library for MCP protocol implementation
- Handle tool registration and request/response flow
- Implement async request handling
2. **NIX Query Client**
- HTTP client to communicate with Rodeos endpoint (default: http://127.0.0.1:8880)
- Protobuf serialization/deserialization
- Action invocation through push_action_ro pattern
3. **Protobuf Integration**
- Generate Python protobuf classes from native_indexer.proto
- Handle message encoding/decoding
- Support for all NIX data structures
## MCP Tools Definition
### 1. Configuration Tools
#### `nix_get_global_configs`
- Description: Get all global configurations or by specific network
- Parameters:
- `blockchain` (optional): Blockchain name
- `network` (optional): Network name
- Returns: GlobalConfigs protobuf message as JSON
#### `nix_get_network_status`
- Description: Get status of a specific network
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- Returns: NetworkStatus message
### 2. Block Query Tools
#### `nix_get_blocks`
- Description: Query blocks by range or specific height
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `block_height` (optional): Specific block height
- `from_index` (optional): Start block index
- `to_index` (optional): End block index
- `max_count` (optional): Maximum blocks to return (default: 10)
- Returns: BlockMetas containing block information
#### `nix_get_min_block`
- Description: Get the minimum indexed block for a network
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- Returns: Minimum block information
### 3. Transaction Tools
#### `nix_get_transaction`
- Description: Get a specific transaction by hash
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `transaction_hash`: Transaction hash
- Returns: Transaction details
#### `nix_get_transactions`
- Description: Get latest transactions or by account
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `max_count` (optional): Maximum transactions (default: 10)
- `address` (optional): Filter by account address
- `from_index` (optional): Start block index
- `to_index` (optional): End block index
- Returns: List of transactions
#### `nix_get_raw_transactions`
- Description: Get raw transaction data
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `max_count` (optional): Maximum results
- `after_timestamp` (optional): Filter by timestamp
- `pii_token` (optional): Query by PII token
- Returns: RawTransactions result
### 4. Account Tools
#### `nix_get_account`
- Description: Get account information
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `address`: Account address
- Returns: Account details
#### `nix_get_account_balance`
- Description: Get account balances
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `address`: Account address
- Returns: Amounts (balances) for the account
#### `nix_get_account_keys`
- Description: Get account public keys
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `address`: Account address
- Returns: KeysWithMeta containing public keys
#### `nix_list_accounts`
- Description: List accounts on a network
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `max_count` (optional): Maximum accounts to return
- Returns: List of account identifiers
### 5. UTXO Tools (for Bitcoin-like chains)
#### `nix_get_utxos`
- Description: Query UTXOs by status or address
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `query_by`: "status" or "address"
- `value`: Status value or address
- `max_count` (optional): Maximum UTXOs to return
- Returns: UTXOs result
### 6. Fee Tools
#### `nix_get_fee`
- Description: Get fee specifications for a network
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `address` (optional): Specific address for fee calculation
- Returns: FeeSpecs result
### 7. Transaction Broadcast Tools
#### `nix_get_broadcast_results`
- Description: Query transaction broadcast results
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `query_by`: "transaction", "oracle", "oracle_status", or "status"
- `max_count`: Maximum results
- Additional parameters based on query_by
- Returns: TransactionBroadcastResults
### 8. Nonce Tracking Tools
#### `nix_get_nonce_tracking`
- Description: Query nonce tracking for pending transactions
- Parameters:
- `blockchain`: Blockchain name
- `network`: Network name
- `status`: Transaction status
- `max_count`: Maximum results
- Returns: NonceTrackingPendingTransactions
## Implementation Structure
```
nix-mcp/
├── pyproject.toml # UV package management
├── src/
│ ├── nix_mcp/
│ │ ├── __init__.py
│ │ ├── server.py # MCP server main entry
│ │ ├── client.py # NIX query client
│ │ ├── tools.py # MCP tool definitions
│ │ ├── protobuf/ # Generated protobuf files
│ │ │ ├── __init__.py
│ │ │ └── native_indexer_pb2.py
│ │ └── utils.py # Helper utilities
│ └── proto/ # Source proto files
│ └── native_indexer.proto
├── tests/
│ ├── __init__.py
│ ├── test_client.py
│ └── test_tools.py
└── README.md
```
## Development Steps
### Phase 1: Setup & Infrastructure
1. Initialize UV project with Python 3.11+
2. Add dependencies:
- `mcp` for MCP protocol
- `httpx` for async HTTP client
- `protobuf` for protocol buffers
- `pydantic` for data validation
3. Set up protobuf compilation from native_indexer.proto
4. Create basic MCP server skeleton
### Phase 2: NIX Client Implementation
1. Implement HTTP client for Rodeos endpoint
2. Create push_action_ro method wrapper
3. Implement protobuf encoding/decoding helpers
4. Add connection configuration (endpoint, timeout, retry)
### Phase 3: Tool Implementation
1. Implement each tool category sequentially:
- Start with configuration tools (simplest)
- Move to query tools (blocks, transactions)
- Implement account-related tools
- Add specialized tools (UTXO, fees, etc.)
2. Add comprehensive error handling
3. Implement response formatting (protobuf to JSON)
### Phase 4: Testing & Documentation
1. Create unit tests for each tool
2. Add integration tests with mock Rodeos endpoint
3. Write comprehensive documentation
4. Add example usage scripts
### Phase 5: Advanced Features
1. Add caching layer for frequently accessed data
2. Implement batch query support
3. Add streaming support for large result sets
4. Implement rate limiting and retry logic
## Configuration
```python
# Example configuration structure
{
"rodeos_endpoint": "http://127.0.0.1:8880",
"nix_contract": "nix",
"nix_query_contract": "nix.q",
"timeout": 30,
"max_retries": 3,
"cache_ttl": 60, # seconds
"batch_size": 100
}
```
## Error Handling
1. **Network Errors**: Retry with exponential backoff
2. **Contract Errors**: Parse and return meaningful error messages
3. **Protobuf Errors**: Validate and provide clear error messages
4. **MCP Protocol Errors**: Follow MCP error response format
## Security Considerations
1. Validate all input parameters
2. Implement rate limiting to prevent abuse
3. Use secure connections (HTTPS) when possible
4. Sanitize error messages to avoid information leakage
5. Add authentication/authorization if needed
## Performance Optimizations
1. Connection pooling for HTTP client
2. Async/await for concurrent requests
3. Response caching for immutable data
4. Lazy loading of protobuf definitions
5. Batch processing for multiple queries
## Monitoring & Logging
1. Structured logging with levels (DEBUG, INFO, WARN, ERROR)
2. Request/response timing metrics
3. Error rate tracking
4. Cache hit/miss ratios
5. Resource usage monitoring
## Deployment
1. Docker containerization
2. Environment variable configuration
3. Health check endpoints
4. Graceful shutdown handling
5. Auto-restart on failure
## Future Enhancements
1. GraphQL interface for complex queries
2. WebSocket support for real-time updates
3. Multi-chain aggregation
4. Query optimization engine
5. Plugin system for custom tools