# 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]