NIX MCP Server

# NIX MCP Server JSON-RPC API Documentation ## Overview The NIX MCP Server implements the Model Context Protocol (MCP) and exposes a JSON-RPC 2.0 interface for querying NIX blockchain data. This document describes all available JSON-RPC methods that can be directly called to interact with the server. ## Connection The server runs in stdio mode and communicates via standard input/output using JSON-RPC 2.0 protocol. ### Starting the Server ```bash # Using uv uv run python main.py # Or with the run script ./run.sh ``` ### Connecting to the Server Send JSON-RPC messages to the server's stdin and read responses from stdout. Each message should be a complete JSON object followed by a newline. ## Message Format All messages follow the JSON-RPC 2.0 specification: ### Request Format ```json { "jsonrpc": "2.0", "method": "method_name", "params": { "param1": "value1", "param2": "value2" }, "id": 1 } ``` ### Response Format ```json { "jsonrpc": "2.0", "result": { // Response data }, "id": 1 } ``` ### Error Response Format ```json { "jsonrpc": "2.0", "error": { "code": -32000, "message": "Error message", "data": { // Additional error details } }, "id": 1 } ``` ## Available Methods ### 1. `initialize` Initialize the MCP connection and retrieve server capabilities. **Request:** ```json { "jsonrpc": "2.0", "method": "initialize", "params": { "protocolVersion": "0.1.0", "capabilities": { "tools": {} }, "clientInfo": { "name": "your-client", "version": "1.0.0" } }, "id": 1 } ``` **Response:** ```json { "jsonrpc": "2.0", "result": { "protocolVersion": "0.1.0", "capabilities": { "tools": {} }, "serverInfo": { "name": "nix-mcp", "version": "1.0.0" } }, "id": 1 } ``` ### 2. `tools/list` List all available tools provided by the server. **Request:** ```json { "jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 2 } ``` **Response:** ```json { "jsonrpc": "2.0", "result": { "tools": [ { "name": "list_queries", "description": "List all available NIX query actions from the contract ABI", "inputSchema": { "type": "object", "properties": { "contract": { "type": "string", "default": "nix.q", "description": "Contract to list queries from" }, "filter_pattern": { "type": "string", "description": "Optional filter pattern for query names" }, "environment": { "type": "string", "default": "dev", "description": "Environment (dev, uat, cdev, perf, simnext, prod, local)" } } } }, { "name": "get_query_abi", "description": "Get ABI structure and JSON template for a specific query", "inputSchema": { "type": "object", "properties": { "query_name": { "type": "string", "description": "Name of the query action" }, "contract": { "type": "string", "default": "nix.q", "description": "Contract name" }, "include_example": { "type": "boolean", "default": true, "description": "Include JSON example" }, "environment": { "type": "string", "default": "dev", "description": "Environment (dev, uat, cdev, perf, simnext, prod, local)" } }, "required": ["query_name"] } }, { "name": "query", "description": "Execute a NIX query with JSON parameters", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "description": "Query action name" }, "params": { "type": "object", "description": "JSON parameters for the query" }, "contract": { "type": "string", "default": "nix.q", "description": "Contract name" }, "environment": { "type": "string", "default": "dev", "description": "Environment (dev, uat, cdev, perf, simnext, prod, local)" } }, "required": ["action"] } } ] }, "id": 2 } ``` ### 3. `tools/call` Execute a specific tool with provided arguments. #### 3.1 Tool: `list_queries` List all available query actions from a contract ABI. **Request:** ```json { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "list_queries", "arguments": { "contract": "nix.q", "environment": "cdev", "filter_pattern": "transaction" } }, "id": 3 } ``` **Response:** ```json { "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "{\n \"contract\": \"nix.q\",\n \"environment\": \"cdev\",\n \"total_queries\": 4,\n \"queries\": [\n \"transaction\",\n \"transactionb\",\n \"transactions\",\n \"transactionsb\"\n ]\n}" } ] }, "id": 3 } ``` #### 3.2 Tool: `get_query_abi` Get the ABI structure and JSON template for a specific query action. **Request:** ```json { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get_query_abi", "arguments": { "query_name": "rawtrxspb", "contract": "nix.q", "include_example": true, "environment": "cdev" } }, "id": 4 } ``` **Response:** ```json { "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "{\n \"query\": \"rawtrxspb\",\n \"contract\": \"nix.q\",\n \"environment\": \"cdev\",\n \"action_type\": \"protobuf::native_indexer.RawTransactionsQuery\",\n \"template\": {},\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"network\": {\n \"type\": \"object\",\n \"properties\": {\n \"blockchain\": {\"type\": \"string\"},\n \"network\": {\"type\": \"string\"}\n }\n },\n \"transaction_identifier\": {\n \"type\": \"object\",\n \"properties\": {\n \"hash\": {\"type\": \"string\"}\n }\n }\n }\n },\n \"example\": {\n \"network\": {\n \"blockchain\": \"ETH\",\n \"network\": \"mainnet\"\n },\n \"transaction_identifier\": {\n \"hash\": \"0xabc123...\"\n }\n }\n}" } ] }, "id": 4 } ``` #### 3.3 Tool: `query` Execute a NIX query with JSON parameters. **Request:** ```json { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "query", "arguments": { "action": "globalconfn", "params": {}, "contract": "nix.q", "environment": "cdev" } }, "id": 5 } ``` **Response:** ```json { "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "{\n \"configs\": [\n {\n \"key\": \"some.config.key\",\n \"value\": \"config_value\"\n }\n ]\n}" } ] }, "id": 5 } ``` ## Complete Examples ### Example 1: List All Available Queries ```json // Request { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "list_queries", "arguments": { "contract": "nix.q", "environment": "dev" } }, "id": 100 } // Response will contain all available queries like: // accounts, balances, blocks, currencies, globalconfn, keys, // transaction, transactions, rawtrxspb, etc. ``` ### Example 2: Get Transaction Details ```json // Step 1: Get the ABI for transaction query { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get_query_abi", "arguments": { "query_name": "transaction", "contract": "nix.q", "environment": "cdev" } }, "id": 201 } // Step 2: Execute the query with parameters { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "query", "arguments": { "action": "transaction", "params": { "network": { "blockchain": "ETH", "network": "mainnet" }, "transaction_identifier": { "hash": "0x123abc..." } }, "contract": "nix.q", "environment": "cdev" } }, "id": 202 } ``` ### Example 3: Query with Filter ```json // Find all queries related to accounts { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "list_queries", "arguments": { "contract": "nix.q", "environment": "dev", "filter_pattern": "acct" } }, "id": 301 } ``` ## Available Environments The following environments can be specified in the `environment` parameter: - `dev` - Development environment (default) - `uat` - User Acceptance Testing environment - `cdev` - Custody Development environment - `perf` - Performance testing environment - `perf2` - Secondary performance environment - `simnext` - Simulation Next environment - `prod` - Production environment (use with caution) - `local` - Local development environment - `snapshot` - Snapshot environment Each environment has different Nodeos and Rodeos endpoints configured internally. ## Error Handling ### Common Error Responses #### Invalid Method ```json { "jsonrpc": "2.0", "error": { "code": -32601, "message": "Method not found" }, "id": 1 } ``` #### Invalid Parameters ```json { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params", "data": { "detail": "Missing required parameter: query_name" } }, "id": 1 } ``` #### Query Execution Error ```json { "jsonrpc": "2.0", "error": { "code": -32000, "message": "Query failed", "data": { "detail": "cleos failed: network.blockchain must be set" } }, "id": 1 } ``` #### Environment Not Found ```json { "jsonrpc": "2.0", "error": { "code": -32000, "message": "Invalid environment", "data": { "detail": "Unknown environment: invalid_env" } }, "id": 1 } ``` ## Notes 1. **Tool Output Format**: All tool results are returned as content arrays with text type containing the actual JSON response. 2. **Parameter Validation**: The server validates required parameters and will return an error if any are missing. 3. **Environment Selection**: If no environment is specified, the server defaults to "dev". You can override this by setting the `NODEOS_ENV` environment variable. 4. **Timeout**: Query execution has a default timeout of 30 seconds. Long-running queries may timeout. 5. **Caching**: The server caches contract ABIs in the `.abi_cache` directory to improve performance. ## Testing the API You can test the JSON-RPC API using any tool that can send JSON over stdio: ### Using Python ```python import json import subprocess # Start the server process = subprocess.Popen( ["uv", "run", "python", "main.py"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True ) # Send initialize request request = { "jsonrpc": "2.0", "method": "initialize", "params": { "protocolVersion": "0.1.0", "capabilities": {} }, "id": 1 } process.stdin.write(json.dumps(request) + "\n") process.stdin.flush() # Read response response = process.stdout.readline() print(json.loads(response)) ``` ### Using curl with a running server If the server is exposed via HTTP (using an MCP proxy), you can use curl: ```bash curl -X POST http://localhost:3000/rpc \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "list_queries", "arguments": { "environment": "dev" } }, "id": 1 }' ``` ## Additional Resources - [MCP Protocol Specification](https://modelcontextprotocol.io/docs) - [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification) - [NIX MCP Server README](../README.md)