Core API

The core module contains the foundational data structures and configuration used throughout UCAI. These models serve as contracts between modules, ensuring type safety and consistency.

Module: abi_to_mcp.core.models

Data Flow

graph LR
    A[Raw ABI JSON] --> B[Parser]
    B --> C[ABIFunction / ABIEvent]
    C --> D[Mapper]
    D --> E[MappedTool / MappedResource]
    E --> F[Generator]
    F --> G[GeneratedServer]

---

Enums

StateMutability

Represents Solidity function state mutability.

from abi_to_mcp.core.models import StateMutability

# Values
StateMutability.PURE        # Pure computation, no state read
StateMutability.VIEW        # Reads state, no modification
StateMutability.NONPAYABLE  # Modifies state, no ETH
StateMutability.PAYABLE     # Modifies state, accepts ETH

Properties

Property	Type	Description
is_read_only	bool	True for PURE and VIEW
requires_gas	bool	True for NONPAYABLE and PAYABLE

ToolType

MCP tool type based on function behavior.

from abi_to_mcp.core.models import ToolType

ToolType.READ           # Pure/view functions - no gas required
ToolType.WRITE          # Nonpayable functions - requires gas
ToolType.WRITE_PAYABLE  # Payable functions - requires gas + ETH

---

ABI Models (Parser Output)

These classes represent parsed ABI entries.

ABIParameter

A function or event parameter from the ABI.

from abi_to_mcp.core.models import ABIParameter

param = ABIParameter(
    name="amount",
    type="uint256",
    indexed=False,
    components=None,
    internal_type="uint256"
)

Attributes

Attribute	Type	Description
name	str	Parameter name (may be empty)
type	str	Solidity type string
indexed	bool	Whether indexed (events only)
components	List[ABIParameter]	Nested params for tuples
internal_type	Optional[str]	Compiler type hint

Class Methods

from_dict(data: Dict) -> ABIParameter

Create from ABI JSON dictionary.

param = ABIParameter.from_dict({
    "name": "to",
    "type": "address",
    "indexed": True
})

---

ABIFunction

A parsed contract function.

from abi_to_mcp.core.models import ABIFunction, StateMutability

func = ABIFunction(
    name="transfer",
    inputs=[...],
    outputs=[...],
    state_mutability=StateMutability.NONPAYABLE,
    selector="0xa9059cbb"
)

Attributes

Attribute	Type	Description
name	str	Function name
inputs	List[ABIParameter]	Input parameters
outputs	List[ABIParameter]	Output parameters
state_mutability	StateMutability	State mutability
selector	Optional[str]	4-byte function selector

Properties

Property	Type	Description
is_read_only	bool	True if view/pure
is_payable	bool	True if accepts ETH
requires_gas	bool	True if modifies state
tool_type	ToolType	MCP tool classification

Example

func = ABIFunction.from_dict({
    "type": "function",
    "name": "balanceOf",
    "inputs": [{"name": "account", "type": "address"}],
    "outputs": [{"name": "", "type": "uint256"}],
    "stateMutability": "view"
})

print(func.is_read_only)  # True
print(func.tool_type)     # ToolType.READ

---

ABIEvent

A parsed contract event.

from abi_to_mcp.core.models import ABIEvent

event = ABIEvent(
    name="Transfer",
    inputs=[...],
    anonymous=False
)

Attributes

Attribute	Type	Description
name	str	Event name
inputs	List[ABIParameter]	Event parameters
anonymous	bool	Whether anonymous event

Properties

Property	Type	Description
indexed_inputs	List[ABIParameter]	Only indexed params (topics)
data_inputs	List[ABIParameter]	Only non-indexed params (data)

---

ABIError

A parsed custom error.

from abi_to_mcp.core.models import ABIError

error = ABIError(
    name="InsufficientBalance",
    inputs=[...]
)

---

ParsedABI

Complete parsed ABI - the main output of the parser module.

from abi_to_mcp.core.models import ParsedABI

parsed = ParsedABI(
    functions=[...],
    events=[...],
    errors=[...],
    raw_abi=[...],
    detected_standard="ERC20"
)

Attributes

Attribute	Type	Description
functions	List[ABIFunction]	All parsed functions
events	List[ABIEvent]	All parsed events
errors	List[ABIError]	All custom errors
raw_abi	List[Dict]	Original ABI JSON
detected_standard	Optional[str]	ERC standard if detected
has_constructor	bool	Has constructor
has_fallback	bool	Has fallback function
has_receive	bool	Has receive function

Properties

Property	Type	Description
read_functions	List[ABIFunction]	All read-only functions
write_functions	List[ABIFunction]	All state-modifying functions

---

Mapper Models (Mapper Output)

These classes represent MCP-compatible tool and resource definitions.

ToolParameter

A parameter in an MCP tool definition.

from abi_to_mcp.core.models import ToolParameter

param = ToolParameter(
    name="recipient",
    original_name="to",
    solidity_type="address",
    json_schema={"type": "string", "pattern": "^0x[a-fA-F0-9]{40}$"},
    python_type="str",
    description="Recipient address",
    required=True
)

Attributes

Attribute	Type	Description
name	str	Parameter name (snake_case)
original_name	str	Original Solidity name
solidity_type	str	Original Solidity type
json_schema	Dict	JSON Schema for parameter
python_type	str	Python type hint string
description	str	Human-readable description
required	bool	Whether required

---

MappedTool

A function mapped to an MCP tool definition.

from abi_to_mcp.core.models import MappedTool

tool = MappedTool(
    name="transfer",
    original_name="transfer",
    description="Transfer tokens to recipient",
    tool_type="write",
    parameters=[...],
    return_schema={...},
    return_description="Returns success boolean",
    python_signature="def transfer(recipient: str, amount: str) -> bool:"
)

Properties

Property	Type	Description
required_params	List[str]	Names of required parameters
is_read_only	bool	True if read-only tool
is_payable	bool	True if accepts ETH

---

MappedResource

An event mapped to an MCP resource definition.

from abi_to_mcp.core.models import MappedResource

resource = MappedResource(
    name="transfer_events",
    original_name="Transfer",
    description="Token transfer events",
    uri_template="contract://events/transfer",
    fields=[...],
    function_name="get_transfer_events"
)

---

GeneratedFile

A generated file in the output.

from abi_to_mcp.core.models import GeneratedFile

file = GeneratedFile(
    path="server.py",
    content="...",
    is_executable=False
)

---

GeneratedServer

Complete generated MCP server package - final output.

from abi_to_mcp.core.models import GeneratedServer

server = GeneratedServer(
    files=[...],
    tool_count=15,
    resource_count=3,
    read_tools=["balance_of", "allowance"],
    write_tools=["transfer", "approve"],
    events=["Transfer", "Approval"],
    server_name="USDC Token",
    contract_address="0xA0b86991...",
    network="mainnet"
)

Methods

get_file(path: str) -> Optional[GeneratedFile]

Get a specific file by path.

---

FetchResult

Result from fetching an ABI.

from abi_to_mcp.core.models import FetchResult

result = FetchResult(
    abi=[...],
    source="etherscan",
    source_location="0xA0b86991...",
    contract_name="FiatTokenV2_1",
    is_proxy=True,
    implementation_address="0x..."
)

---

Module: abi_to_mcp.core.config

Configuration management for all UCAI components.

NetworkConfig

Configuration for a specific network.

from abi_to_mcp.core.config import NetworkConfig

config = NetworkConfig(
    chain_id=1,
    name="Ethereum Mainnet",
    rpc="https://eth.llamarpc.com",
    explorer="https://etherscan.io",
    etherscan_api="https://api.etherscan.io/api",
    currency_symbol="ETH",
    is_testnet=False
)

---

GeneratorConfig

Configuration for MCP server generation.

from abi_to_mcp.core.config import GeneratorConfig

config = GeneratorConfig(
    output_dir=Path("./my-server"),
    overwrite=False,
    read_only=False,
    include_events=True,
    simulation_default=True,
    server_name="My Token"
)

Key Attributes

Attribute	Default	Description
output_dir	./mcp-server	Output directory
read_only	False	Only generate read tools
include_events	True	Generate event resources
simulation_default	True	Default simulation mode
generate_tests	False	Generate test files

---

FetcherConfig

Configuration for ABI fetching.

from abi_to_mcp.core.config import FetcherConfig

config = FetcherConfig(
    timeout=30.0,
    max_retries=3,
    detect_proxy=True
)

API keys are automatically loaded from environment variables:

• ETHERSCAN_API_KEY
• POLYGONSCAN_API_KEY
• ARBISCAN_API_KEY
• OPTIMISM_API_KEY
• BASESCAN_API_KEY
• BSCSCAN_API_KEY

---

RuntimeConfig

Configuration for runtime execution.

from abi_to_mcp.core.config import RuntimeConfig

config = RuntimeConfig(
    rpc_url="https://eth.llamarpc.com",
    network="mainnet",
    gas_limit_multiplier=1.2,
    simulation_required=True
)

---

AppConfig

Top-level application configuration combining all configs.

from abi_to_mcp.core.config import AppConfig, get_default_config

# Get default config (auto-loads from config files)
config = get_default_config()

# Or create manually
config = AppConfig(
    generator=GeneratorConfig(...),
    fetcher=FetcherConfig(...),
    runtime=RuntimeConfig(...),
    log_level="INFO"
)

Loading from Files

UCAI automatically searches for config files:

1. ./abi-to-mcp.toml
2. ./abi-to-mcp.json
3. ~/.config/abi-to-mcp/config.toml
4. ~/.config/abi-to-mcp/config.json

config = AppConfig.load_from_file(Path("./custom-config.toml"))

---

Module: abi_to_mcp.core.constants

Network configurations and type mappings.

NETWORKS

Dictionary of supported EVM networks.

from abi_to_mcp.core.constants import NETWORKS

# Available networks
networks = list(NETWORKS.keys())
# ['mainnet', 'sepolia', 'polygon', 'arbitrum', 'optimism', 'base', 'bsc', 'avalanche', 'fantom']

# Get network config
mainnet = NETWORKS["mainnet"]
print(mainnet["chain_id"])  # 1
print(mainnet["explorer"])  # https://etherscan.io

ERC_STANDARDS

Signatures for detecting ERC standards.

from abi_to_mcp.core.constants import ERC_STANDARDS

# ERC20 required functions
erc20 = ERC_STANDARDS["ERC20"]
print(erc20["functions"])  # ['name', 'symbol', 'decimals', 'totalSupply', ...]

---

Module: abi_to_mcp.core.exceptions

Custom exception classes for error handling.

Exception Hierarchy

ABIToMCPError (base)
├── FetcherError
│   ├── ABINotFoundError
│   ├── ContractNotVerifiedError
│   ├── NetworkError
│   └── RateLimitError
├── ABIParseError
├── ABIValidationError
├── MappingError
├── GeneratorError
└── RuntimeError
    ├── TransactionError
    ├── SimulationError
    └── GasEstimationError

Usage

from abi_to_mcp.core.exceptions import (
    ABIToMCPError,
    ABINotFoundError,
    ContractNotVerifiedError,
)

try:
    result = fetcher.fetch(address, network)
except ContractNotVerifiedError as e:
    print(f"Contract {e.address} not verified on {e.network}")
except ABINotFoundError as e:
    print(f"ABI not found: {e.source}")
except ABIToMCPError as e:
    print(f"Error: {e.message}")
    print(f"Details: {e.details}")

Common Exceptions

Exception	When Raised
ABINotFoundError	ABI source doesn't exist
ContractNotVerifiedError	Contract not verified on explorer
NetworkError	Network/HTTP errors
RateLimitError	API rate limit exceeded
ABIParseError	Invalid ABI structure
ABIValidationError	Invalid ABI entries
MappingError	Type mapping failed
GeneratorError	Code generation failed
TransactionError	Transaction failed
SimulationError	Simulation failed
---

Auto-Generated API Reference

The following sections are automatically generated from source code docstrings using mkdocstrings.

Models Module

abi_to_mcp.core.models

Shared data models for abi-to-mcp.

These models are the contracts between different modules. All agents must use these exact classes to ensure seamless integration.

StateMutability

Bases: Enum

Solidity function state mutability.

is_read_only property

Check if this mutability allows state modification.

requires_gas property

Check if this mutability requires gas.

ToolType

Bases: Enum

MCP tool type based on function behavior.

ABIParameter dataclass

A function or event parameter from the ABI.

Attributes:

Name	Type	Description
name	str	Parameter name (may be empty string in ABI)
type	str	Solidity type string (e.g., "address", "uint256", "tuple")
indexed	bool	Whether this is an indexed event parameter
components	Optional[List[ABIParameter]]	Nested parameters for tuple types
internal_type	Optional[str]	Internal type hint from compiler (optional)

from_dict(data) classmethod

Create from ABI JSON dictionary.

ABIFunction dataclass

A parsed contract function.

Attributes:

Name	Type	Description
name	str	Function name
inputs	List[ABIParameter]	List of input parameters
outputs	List[ABIParameter]	List of output parameters
state_mutability	StateMutability	Function's state mutability
selector	Optional[str]	4-byte function selector (optional)

is_read_only property

Check if function is read-only (view/pure).

is_payable property

Check if function accepts ETH.

requires_gas property

Check if function requires gas.

tool_type property

Get the MCP tool type for this function.

from_dict(data) classmethod

Create from ABI JSON dictionary.

ABIEvent dataclass

A parsed contract event.

Attributes:

Name	Type	Description
name	str	Event name
inputs	List[ABIParameter]	List of event parameters
anonymous	bool	Whether this is an anonymous event

indexed_inputs property

Get only indexed parameters (topics).

data_inputs property

Get only non-indexed parameters (data).

from_dict(data) classmethod

Create from ABI JSON dictionary.

ABIError dataclass

A parsed custom error.

Attributes:

Name	Type	Description
name	str	Error name
inputs	List[ABIParameter]	List of error parameters

from_dict(data) classmethod

Create from ABI JSON dictionary.

ParsedABI dataclass

Complete parsed ABI.

This is the main output of the parser module and input to the mapper.

Attributes:

Name	Type	Description
functions	List[ABIFunction]	All parsed functions
events	List[ABIEvent]	All parsed events
errors	List[ABIError]	All parsed custom errors
raw_abi	List[Dict[str, Any]]	Original ABI JSON for reference
detected_standard	Optional[str]	Detected ERC standard (if any)
has_constructor	bool	Whether ABI includes constructor
has_fallback	bool	Whether ABI includes fallback function
has_receive	bool	Whether ABI includes receive function

read_functions property

Get all read-only functions.

write_functions property

Get all state-modifying functions.

ToolParameter dataclass

A parameter in an MCP tool definition.

Attributes:

Name	Type	Description
name	str	Parameter name (snake_case)
original_name	str	Original Solidity parameter name
solidity_type	str	Original Solidity type
json_schema	Dict[str, Any]	JSON Schema for this parameter
python_type	str	Python type hint string
description	str	Human-readable description
required	bool	Whether this parameter is required

MappedTool dataclass

A function mapped to an MCP tool definition.

This is the output of FunctionMapper and input to ToolGenerator.

Attributes:

Name	Type	Description
name	str	Tool name (snake_case)
original_name	str	Original Solidity function name
description	str	LLM-friendly description
tool_type	str	Type of tool (read/write/write_payable)
parameters	List[ToolParameter]	List of tool parameters
return_schema	Dict[str, Any]	JSON Schema for return value
return_description	str	Description of return value
python_signature	str	Complete Python function signature

required_params property

Get names of required parameters.

is_read_only property

Check if this is a read-only tool.

is_payable property

Check if this tool accepts ETH.

ResourceField dataclass

A field in an MCP resource (event parameter).

Attributes:

Name	Type	Description
name	str	Field name (snake_case)
original_name	str	Original Solidity parameter name
solidity_type	str	Original Solidity type
json_schema	Dict[str, Any]	JSON Schema for this field
description	str	Human-readable description
indexed	bool	Whether this is an indexed parameter

MappedResource dataclass

An event mapped to an MCP resource definition.

This is the output of EventMapper and input to ResourceGenerator.

Attributes:

Name	Type	Description
name	str	Resource name (snake_case)
original_name	str	Original Solidity event name
description	str	Human-readable description
uri_template	str	MCP resource URI template
fields	List[ResourceField]	List of resource fields
function_name	str	Python function name for the handler

indexed_fields property

Get indexed fields (can be used for filtering).

data_fields property

Get non-indexed fields.

GeneratedFile dataclass

A generated file.

Attributes:

Name	Type	Description
path	str	Relative path within output directory
content	str	File content as string
is_executable	bool	Whether file should be executable

GeneratedServer dataclass

Complete generated MCP server package.

This is the final output of the generator module.

Attributes:

Name	Type	Description
files	List[GeneratedFile]	List of generated files
tool_count	int	Number of generated tools
resource_count	int	Number of generated resources
read_tools	List[str]	Names of read-only tools
write_tools	List[str]	Names of write tools
events	List[str]	Names of event resources
server_name	str	Name of the generated server
contract_address	str	Target contract address
network	str	Target network

get_file(path)

Get a specific file by path.

FetchResult dataclass

Result from fetching an ABI.

Attributes:

Name	Type	Description
abi	List[Dict[str, Any]]	The fetched ABI JSON
source	str	Source type ("file", "etherscan", "sourcify")
source_location	str	Specific location (path or address)
contract_name	Optional[str]	Contract name if available
compiler_version	Optional[str]	Compiler version if available
source_code	Optional[str]	Contract source code if available
is_proxy	bool	Whether this is a proxy contract
implementation_address	Optional[str]	Implementation address if proxy

Config Module

abi_to_mcp.core.config

Configuration management for abi-to-mcp.

NetworkConfig dataclass

Configuration for a specific network.

GeneratorConfig dataclass

Configuration for MCP server generation.

__post_init__()

Convert output_dir to Path if string.

FetcherConfig dataclass

Configuration for ABI fetching.

__post_init__()

Load API keys from environment if not provided.

get_api_key(network)

Get the appropriate API key for a network.

RuntimeConfig dataclass

Configuration for runtime execution.

__post_init__()

Load sensitive values from environment.

AppConfig dataclass

Top-level application configuration.

from_dict(data) classmethod

Create config from dictionary.

load_from_file(path) classmethod

Load configuration from a TOML or JSON file.

get_default_config()

Get default application configuration.

Exceptions Module

abi_to_mcp.core.exceptions

Custom exceptions for abi-to-mcp.

ABIToMCPError

Bases: Exception

Base exception for all abi-to-mcp errors.

FetcherError

Bases: ABIToMCPError

Base exception for fetcher-related errors.

ABINotFoundError

Bases: FetcherError

ABI could not be found at the specified source.

ContractNotVerifiedError

Bases: FetcherError

Contract source code is not verified on the block explorer.

NetworkError

Bases: FetcherError

Network-related error during fetching.

RateLimitError

Bases: FetcherError

Rate limit exceeded on external API.

InvalidAddressError

Bases: FetcherError

Invalid Ethereum address format.

ParserError

Bases: ABIToMCPError

Base exception for parser-related errors.

ABIParseError

Bases: ParserError

Error parsing ABI JSON.

ABIValidationError

Bases: ParserError

ABI structure is invalid.

UnsupportedTypeError

Bases: ParserError

Encountered an unsupported Solidity type.

GeneratorError

Bases: ABIToMCPError

Base exception for generator-related errors.

TemplateError

Bases: GeneratorError

Error rendering Jinja2 template.

CodeGenerationError

Bases: GeneratorError

Error generating Python code.

OutputDirectoryError

Bases: GeneratorError

Error with output directory (exists, permissions, etc.).

RuntimeError

Bases: ABIToMCPError

Base exception for runtime errors.

Web3ConnectionError

Bases: RuntimeError

Failed to connect to Web3 provider.

TransactionError

Bases: RuntimeError

Error building or sending transaction.

SimulationError

Bases: ABIToMCPError

Error during transaction simulation.

SignerError

Bases: ABIToMCPError

Error related to transaction signing.

GasEstimationError

Bases: ABIToMCPError

Error during gas estimation.

SignerNotConfiguredError

Bases: ABIToMCPError

Private key not configured for write operations.

InsufficientFundsError

Bases: RuntimeError

Insufficient funds for transaction.

CLIError

Bases: ABIToMCPError

Base exception for CLI errors.

InvalidInputError

Bases: CLIError

Invalid CLI input.

ConfigurationError

Bases: CLIError

Configuration error.

Constants Module

abi_to_mcp.core.constants

Network configurations and type mappings for abi-to-mcp.