API Reference

This section provides detailed documentation for using abi-to-mcp as a Python library.

Overview

abi-to-mcp can be used programmatically for:

• Custom ABI processing pipelines
• Integration into build tools
• Dynamic server generation
• Testing and validation

Architecture Diagram

The following diagram shows how data flows through the different modules:

flowchart LR
    subgraph Input["📥 Input Sources"]
        FILE[("ABI File\n.json")]
        ETHERSCAN["Etherscan\nAPI"]
        SOURCIFY["Sourcify\nAPI"]
    end

    subgraph Fetchers["🔌 Fetchers Module"]
        FR[FetcherRegistry]
        FF[FileFetcher]
        EF[EtherscanFetcher]
        SF[SourcifyFetcher]
    end

    subgraph Parser["📋 Parser Module"]
        AP[ABIParser]
        FP[FunctionParser]
        EP[EventParser]
        TP[TypeParser]
    end

    subgraph Core["🎯 Core Module"]
        MODELS["Data Models\n• ABIFunction\n• ABIEvent\n• ParsedABI"]
        CONFIG["Config\n• GeneratorConfig\n• FetcherConfig"]
        ERRORS["Exceptions\n• ABIToMCPError\n• FetcherError"]
    end

    subgraph Mapper["🔄 Mapper Module"]
        TM[TypeMapper]
        FM[FunctionMapper]
        EM[EventMapper]
    end

    subgraph Generator["⚙️ Generator Module"]
        MG[MCPGenerator]
        TG[ToolGenerator]
        RG[ResourceGenerator]
    end

    subgraph Output["📦 Output"]
        SERVER["server.py"]
        TOOLS["tools.py"]
        RESOURCES["resources.py"]
        README["README.md"]
    end

    FILE --> FF
    ETHERSCAN --> EF
    SOURCIFY --> SF

    FF --> FR
    EF --> FR
    SF --> FR

    FR --> AP
    AP --> FP
    AP --> EP
    AP --> TP

    FP --> MODELS
    EP --> MODELS

    MODELS --> FM
    MODELS --> EM
    TM --> FM
    TM --> EM

    FM --> MG
    EM --> MG

    MG --> TG
    MG --> RG

    TG --> SERVER
    TG --> TOOLS
    RG --> RESOURCES
    MG --> README

    CONFIG -.-> MG
    ERRORS -.-> AP
    ERRORS -.-> FR

Module Dependencies

graph TD
    CLI["cli/"] --> CORE["core/"]
    CLI --> FETCHERS["fetchers/"]
    CLI --> PARSER["parser/"]
    CLI --> MAPPER["mapper/"]
    CLI --> GENERATOR["generator/"]

    FETCHERS --> CORE
    PARSER --> CORE
    MAPPER --> CORE
    GENERATOR --> CORE
    RUNTIME["runtime/"] --> CORE

    GENERATOR --> MAPPER
    GENERATOR --> PARSER

    UTILS["utils/"] --> CORE

    style CORE fill:#f9f,stroke:#333,stroke-width:2px
    style CLI fill:#bbf,stroke:#333,stroke-width:2px

Module Structure

abi_to_mcp/
├── core/        # Data models, config, exceptions
├── parser/      # ABI parsing
├── fetchers/    # ABI retrieval
├── mapper/      # Type mapping
├── generator/   # Code generation
├── runtime/     # Execution utilities
├── cli/         # Command-line interface
└── utils/       # Helper utilities

Quick Reference

• Parser

  ---

  Parse ABI JSON into structured Python objects.

  Parser API

• Fetchers

  ---

  Retrieve ABIs from files, Etherscan, or Sourcify.

  Fetchers API

• Mapper

  ---

  Convert Solidity types to JSON Schema.

  Mapper API

• Generator

  ---

  Generate MCP server code from parsed ABIs.

  Generator API

• Runtime

  ---

  Web3 client and transaction utilities.

  Runtime API

• Core

  ---

  Data models, configuration, and exceptions.

  Core API

• Utilities

  ---

  Validation, formatting, and logging helpers.

  Utilities API

• CLI Internals

  ---

  Command-line interface architecture.

  CLI Internals

Basic Usage

from abi_to_mcp.parser import ABIParser
from abi_to_mcp.mapper import TypeMapper, FunctionMapper
from abi_to_mcp.generator import MCPGenerator

# Parse ABI
parser = ABIParser()
parsed = parser.parse(abi_json)

# Map to MCP tools
type_mapper = TypeMapper()
func_mapper = FunctionMapper(type_mapper)
tools = [func_mapper.map_function(f) for f in parsed.functions]

# Generate server
generator = MCPGenerator()
server = generator.generate(
    parsed=parsed,
    tools=tools,
    contract_address="0x...",
    network="mainnet"
)

# Write files
for file in server.files:
    Path(file.path).write_text(file.content)

Installation for Development

pip install abi-to-mcp[dev]

This includes type stubs and development dependencies.