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

# Install dependencies
npm install

# Build
npm run build

Configuration

1. Add Contract Addresses

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

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:

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:

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):

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

Connect to Claude Code

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

Test with MCP Inspector

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