# Myth

[![npm](https://img.shields.io/npm/v/@gideondern/myth-celo-mcp)](https://www.npmjs.com/package/@gideondern/myth-celo-mcp)
[![license](https://img.shields.io/github/license/gideondern/myth-celo-mcp)](./LICENSE)
[![CI](https://github.com/gideondern/myth-celo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/gideondern/myth-celo-mcp/actions/workflows/ci.yml)

**Myth** auto-generates [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers for Celo smart contracts. Give it a verified contract address and it fetches the ABI from Blockscout, maps every function and event to an MCP tool, and launches a server your AI agent can call.

Built for Celo's agent-friendly properties: sub-cent gas, fast finality, and **stablecoin gas payment** via `feeCurrency`.

> Open source under [MIT](./LICENSE). Contributions welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md).
## Architecture

```
[Contract Address] → [Blockscout ABI] → [ABI → Zod/JSON Schema] → [MCP Server]
         ↓
 [EIP-1967 Proxy Resolver] → implementation ABI
```

| Step | Module | What it does |
|------|--------|--------------|
| 1 | `blockscout.ts` | `GET ?module=contract&action=getabi&address={addr}` |
| 2 | `abi-to-zod.ts` | Maps Solidity types → Zod validators + JSON Schema |
| 3 | `abi-events.ts` | Generates `query event` tools from ABI events |
| 4 | `celo-tx.ts` | Attaches `feeCurrency` on write txs (pay gas in cUSD/USDT) |
| 5 | `create-server.ts` | Wires tools into `@modelcontextprotocol/sdk` |
| 6 | `registry.ts` | Multi-contract registry at `~/.myth/registry.json` |

## Install

```bash
# Global CLI
npm install -g @gideondern/myth-celo-mcp

# Or run without installing
npx -y --package @gideondern/myth-celo-mcp myth --help
```

**npm:** https://www.npmjs.com/package/@gideondern/myth-celo-mcp

## Quick Start

```bash
# Infra workflow: add → list → serve
myth add -a 0x765DE816845861e75A25fCA122bb6898B8B1282a -n celo-mainnet --alias cusd
myth list
myth serve   # serves registry (uses ~/.myth/cache for fast restarts)

# Single contract without registry
myth serve -a 0x765DE816845861e75A25fCA122bb6898B8B1282a -n celo-mainnet

# HTTP transport (for remote agents)
myth serve -a 0x765DE816845861e75A25fCA122bb6898B8B1282a -n celo-mainnet --http --port 3100

# Generate a standalone package with manifest + Cursor config
myth generate -a 0x765DE816845861e75A25fCA122bb6898B8B1282a -n celo-mainnet -o ./generated/cusd
```

## Registry & ABI cache

Contracts live in `~/.myth/registry.json`. ABIs are cached in `~/.myth/cache/<network>/` (24h TTL).

```bash
myth add -a 0x765DE816845861e75A25fCA122bb6898B8B1282a -n celo-mainnet --alias cusd
myth list
myth sync cusd --force   # refresh ABI from Blockscout
myth remove cusd
myth serve               # all registry contracts (cache-first)
myth serve --http        # HTTP transport
```

Tools are prefixed by alias: `cusd_balanceOf`, `cusd_event_Transfer`, etc.

## Cursor Integration

Add to `~/.cursor/mcp.json` (already configured if you used the setup step):

```json
{
  "mcpServers": {
    "myth-cusd": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "@gideondern/myth-celo-mcp",
        "myth",
        "serve",
        "-a",
        "0x765DE816845861e75A25fCA122bb6898B8B1282a",
        "-n",
        "celo-mainnet"
      ],
      "env": {
        "MYTH_FEE_CURRENCY": "cUSD"
      }
    }
  }
}
```

Serve every contract in your registry (`~/.myth/registry.json`):

```json
{
  "mcpServers": {
    "myth-registry": {
      "command": "npx",
      "args": ["-y", "--package", "@gideondern/myth-celo-mcp", "myth", "serve", "--registry"]
    }
  }
}
```

Reload Cursor MCP after saving. For write tools, add `MYTH_PRIVATE_KEY` to `env`.

## Built-in Meta Tools

Every server includes:

| Tool | Description |
|------|-------------|
| `myth_contract_info` | Contract addresses, networks, tool counts |
| `myth_fee_currencies` | Available stablecoins per network for gas |

## Networks

| Network | Blockscout API | Default RPC |
|---------|----------------|-------------|
| `celo-mainnet` | https://celo.blockscout.com/api | https://forno.celo.org |
| `celo-sepolia` | https://celo-sepolia.blockscout.com/api | https://forno.celo-sepolia.celo-testnet.org |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `MYTH_CONTRACT_ADDRESS` | Target contract |
| `MYTH_NETWORK` | `celo-mainnet` or `celo-sepolia` |
| `MYTH_RPC_URL` | Override RPC endpoint |
| `MYTH_PRIVATE_KEY` | Wallet for write transactions |
| `MYTH_FEE_CURRENCY` | Stablecoin for gas (`cUSD`, `USDT`, or `0x...`) |
| `MYTH_REGISTRY_PATH` | Registry file (default: `~/.myth/registry.json`) |
| `MYTH_BLOCKSCOUT_API_KEY` | Optional Blockscout PRO API key |

## Programmatic API

```typescript
import {
  fetchContractAbi,
  abiToMcpTools,
  launchMythServer,
  launchHttpServer,
  addToRegistry,
} from "@gideondern/myth-celo-mcp";

await launchMythServer({
  contractAddress: "0x765DE816845861e75A25fCA122bb6898B8B1282a",
  network: "celo-mainnet",
  feeCurrency: "cUSD",
});

await launchHttpServer({
  config: { contractAddress: "0x...", network: "celo-mainnet" },
  port: 3100,
});
```

## Development

```bash
git clone https://github.com/gideondern/myth-celo-mcp.git
cd myth-celo-mcp
npm install
npm run build
node dist/cli.js add -a 0x765DE816845861e75A25fCA122bb6898B8B1282a -n celo-mainnet --alias cusd
node dist/cli.js serve
```

## References

- [celo-mcp](https://github.com/celo-org/celo-mcp) — Official Celo MCP server (Python)
- [evm-mcp-server](https://github.com/mcpdotdirect/evm-mcp-server) — Dynamic EVM tool patterns
- [Blockscout Contract API](https://docs.blockscout.com/devs/apis/rpc/contract)

## License

[MIT](./LICENSE) © [Gideon Dern](https://github.com/gideondern)