NIX MCP Server

# NIX MCP Server - Simplified Version A simplified MCP (Model Context Protocol) server for querying NIX blockchain data using JSON and ABI, without protobuf dependencies. ## Features - **Simple JSON-based queries** - No protobuf compilation required - **Dynamic ABI discovery** - Automatically fetches available queries from contracts - **Automatic ABI caching** - Caches ABIs from cdev environment on startup - **Environment switching** - Query different environments (dev, uat, prod, etc.) - **JSON file support** - Pass query parameters via JSON files - **Three core tools**: - `list_queries` - List all available queries from contract ABI - `get_query_abi` - Get query structure with JSON examples - `query` - Execute queries with JSON parameters ## Prerequisites - Python 3.11+ - `cleos` command-line tool (for blockchain queries) - Access to Rodeos and Nodeos endpoints ## Quick Start ### 1. Clone and Initialize ```bash # Clone the repository git clone <repository-url> cd nix-mcp # Run initialization script (installs uv and dependencies) ./init.sh # Or manually with uv curl -LsSf https://astral.sh/uv/install.sh | sh uv sync ``` ### 2. Configure ```bash # Copy environment template cp .env.example .env # Edit .env with your endpoints: # RODEOS_API=http://your-rodeos-endpoint:8880 # NODEOS_API=http://your-nodeos-endpoint:8888 ``` ### 3. Run the Server ```bash # Using make make run # Or directly uv run python main.py # Or with the run script ./run.sh ``` ## Available Tools ### 1. List Queries Lists all available query actions from the contract ABI. ```json { "tool": "list_queries", "params": { "contract": "nix.q", "filter_pattern": "global", "environment": "dev" } } ``` ### 2. Get Query ABI Returns the structure and JSON template for a specific query. ```json { "tool": "get_query_abi", "params": { "query_name": "globalconfn", "contract": "nix.q", "include_example": true, "environment": "dev" } } ``` ### 3. Execute Query Executes a NIX query with JSON parameters. ```json { "tool": "query", "params": { "action": "globalconfn", "params": { "blockchain": "ETH", "network": "testnet" }, "contract": "nix.q", "environment": "dev" } } ``` ## Environment Support The MCP server now supports dynamic environment switching without restarting. You can specify the target environment for each query: ### Available Environments - **dev** - Development environment (default) - **uat** - User Acceptance Testing - **cdev** - Custody Development - **perf** - Performance testing - **perf2** - Secondary performance testing - **simnext** - Simulation/Next environment - **prod** - Production environment - **local** - Local development - **snapshot** - Snapshot environment ### Example: Query Different Environments ```python # Query SOL mainnet configuration from production result = await client.query( contract="nix.q", action="globalconfn", params={ "blockchain": "SOL", "network": "mainnet" }, environment="prod" # Specify production environment ) # List queries available in UAT queries = await list_queries( contract="nix.q", environment="uat" ) ``` ## Usage Examples ### Python Client ```python from nix_mcp import SimpleNixClient import asyncio async def example(): # Create client for specific environment client = SimpleNixClient(environment="prod") # Query all global configs result = await client.query( contract="nix.q", action="globalconfs", params={} ) print(result) # Query specific network result = await client.query( contract="nix.q", action="globalconfn", params={ "blockchain": "ETH", "network": "testnet" } ) print(result) # Create client for different environment dev_client = SimpleNixClient(environment="dev") dev_result = await dev_client.query( contract="nix.q", action="globalconfs", params={} ) print(f"Dev environment result: {dev_result}") asyncio.run(example()) ``` ### Discover Available Queries ```python from nix_mcp import ABIFetcher fetcher = ABIFetcher() actions = fetcher.get_actions("nix.q") print(f"Available queries: {actions}") ``` ## Testing ```bash # Run basic tests uv run python test_simple.py # Test environment switching uv run python test_env_switching.py # Test the complete expected flow uv run python test_expected_flow.py ``` ## Claude Desktop Integration Add to your Claude Desktop configuration: ```json { "mcpServers": { "nix-mcp": { "command": "uv", "args": ["run", "python", "/full/path/to/nix-mcp/main.py"] } } } ``` ## Project Structure ``` nix-mcp/ ├── src/nix_mcp/ │ ├── simple_client.py # Core client using cleos │ ├── abi_fetcher.py # ABI fetching and parsing │ ├── tools.py # MCP tool handlers │ ├── server_fastmcp.py # FastMCP server │ └── json_templates.py # Query templates ├── main.py # Entry point ├── test_simple.py # Test script ├── .env.example # Environment template └── README.md # This file ``` ## Environment Variables - `NODEOS_ENV` - Default environment to use when not specified (dev, uat, cdev, prod, etc.) - `RODEOS_API` - Override Rodeos endpoint for all environments - `NODEOS_API` - Override Nodeos endpoint for all environments - `CLEOS_PATH` - Path to cleos binary (optional if in PATH) You can also set environment-specific overrides: - `RODEOS_API_DEV`, `RODEOS_API_UAT`, `RODEOS_API_PROD`, etc. - `NODEOS_API_DEV`, `NODEOS_API_UAT`, `NODEOS_API_PROD`, etc. ## Transaction Query Example Here's a complete example of querying a raw transaction as described in the expected flow: ### Step 1: Find the appropriate query ```python # List all available queries result = await list_queries( contract="nix.q", filter_pattern="raw", # Filter for transaction-related queries environment="cdev" ) # This will show queries like: rawtrxspb, rawtransaction, etc. ``` ### Step 2: Get the query ABI structure ```python # Get the ABI for rawtrxspb query result = await get_query_abi( query_name="rawtrxspb", contract="nix.q", environment="cdev" ) # Shows the expected input structure ``` ### Step 3: Execute the query ```python # Query for ETH mainnet transaction in cdev result = await query( action="rawtrxspb", params={ "network": { "blockchain": "ETH", "network": "mainnet" }, "transaction_identifier": { "hash": "0abe152ba84b35026451d68a55310ec58450a167a82a55fae2ff691ebc7236bf" } }, contract="nix.q", environment="cdev" ) ``` Or using a JSON file: ```python # Using pre-built JSON file result = await query( action="rawtrxspb", params="examples/raw_transaction_query.json", contract="nix.q", environment="cdev" ) ``` ### The actual cleos command executed: ```bash cleos -u $RODEOS_API push action --use-old-send-rpc --return-failure-trace 0 nix.q rawtrxspb '{"network":{"blockchain":"ETH","network":"mainnet"},"transaction_identifier":{"hash":"0abe152ba84b35026451d68a55310ec58450a167a82a55fae2ff691ebc7236bf"}}' -sj ``` ## Common Query Templates Example JSON files in `examples/` directory: - `raw_transaction_query.json` - Query raw transaction details - `global_config_query.json` - Query global configuration for a network - `network_status_query.json` - Query network status Additional query types: - Global configurations (`globalconfs`, `globalconfn`) - Network status (`nwstatus`) - Account queries (`accounts`, `balances`) - Block queries (`blocks`) - Transaction queries (`transaction`, `transactions`, `rawtrxspb`) ## Troubleshooting ### cleos not found Ensure cleos is installed and in your PATH, or set `CLEOS_PATH` in `.env` ### Connection errors Verify your `RODEOS_API` and `NODEOS_API` endpoints are accessible ### Import errors Run `uv sync` to ensure all dependencies are installed ## License [Your License]