# Dysnomia Ecosystem Navigator — MCP Server

An MCP (Model Context Protocol) server that gives AI assistants direct access to the Dysnomia/Atropa blockchain ecosystem on PulseChain. Ask Claude about contract state, debug transactions, trace minters, and map the entire ecosystem graph — all from natural language.

## Tools

| Tool | Description |
|------|-------------|
| `list_ecosystem` | List all registered contracts with categories and descriptions |
| `get_contract_state` | Read on-chain state — balances, supply, ownership, minting status |
| `trace_minter` | Trace a minter address across all ecosystem contracts |
| `query_qing` | Look up QING territory data — ownership, metadata |
| `debug_call` | Simulate contract calls to surface reverts before spending gas |
| `map_relationships` | Map ownership and dependency graph between contracts |
| `search_events` | Query on-chain event logs filtered by contract, event, block range |

## Setup

```bash
# Install dependencies
npm install

# Build
npm run build
```

## Configuration

### 1. Add Contract Addresses

Edit `src/config.ts` and fill in the deployed addresses:

```typescript
META:  { address: "0x...", category: "core",  description: "Root coordination contract" },
RING:  { address: "0x...", category: "core",  description: "Ring structure / orbital mechanics" },
// etc.
```

Rebuild after changes: `npm run build`

### 2. Custom RPC

Set the `PULSECHAIN_RPC` environment variable to override the default RPC:

```bash
export PULSECHAIN_RPC="https://your-rpc-endpoint.com"
```

### 3. Extend ABIs

Each tool file in `src/tools/` has its own ABI definitions. Add function signatures as contracts evolve — the pattern is human-readable ABI strings:

```typescript
const MY_ABI = [
  "function MyNewFunction(uint256) view returns (address)",
];
```

## Connect to Claude Desktop

Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

```json
{
  "mcpServers": {
    "dysnomia": {
      "command": "node",
      "args": ["/absolute/path/to/dysnomia-navigator/build/index.js"],
      "env": {
        "PULSECHAIN_RPC": "https://rpc.pulsechain.com"
      }
    }
  }
}
```

## Connect to Claude Code

```bash
claude mcp add dysnomia node /absolute/path/to/dysnomia-navigator/build/index.js
```

## Test with MCP Inspector

```bash
npm run inspector
```

## Architecture

```
src/
├── index.ts          # Entry point — creates server, registers tools
├── config.ts         # RPC config, contract registry, ABIs, helpers
└── tools/
    ├── listEcosystem.ts      # list_ecosystem
    ├── getContractState.ts   # get_contract_state
    ├── traceMinter.ts        # trace_minter
    ├── queryQing.ts          # query_qing
    ├── debugCall.ts          # debug_call
    ├── mapRelationships.ts   # map_relationships
    └── searchEvents.ts       # search_events
```

## Extending

To add a new tool:

1. Create `src/tools/myNewTool.ts`
2. Export a `registerMyNewTool(server: McpServer)` function
3. Import and call it in `src/index.ts`
4. Rebuild: `npm run build`

The server uses stdio transport so it works with any MCP-compatible client.

## Phases (for context)

- **Terra**: Forming data on minters — physics actions per-QING build minter token data
- **Firma**: Personal GWATs establishing territory
- **Life**: IoT hardware + YUE extensions creating real-world activity sandboxes