evm-agent-toolkit: Instructions file for Claude Code

EVM MCP Server — Contributor & Architecture Guide

This file orients any agent (or human) working inside this repository.

What this repo is

A professional MCP (Model Context Protocol) server that gives autonomous coding agents deterministic, schema-validated tools for EVM smart contract development.

Architecture

evm-agent-toolkit/
├── src/
│   ├── mcp/index.ts        # MCP server entry point (registerTool API)
│   ├── tools/              # Zod-validated CLI output parsers
│   ├── rules/              # System prompt injection files (.md)
│   └── hooks/              # Lifecycle hooks (UserPromptSubmit, Statusline)
├── tests/                  # Vitest unit tests for all parsers
├── bench/                  # Parser performance benchmarks
├── evals/                  # Agent evaluation framework
├── skills/                 # Markdown reference libraries (read-only knowledge base)
├── docs/                   # Design documents and proposals
├── .claude-plugin/         # Claude Code plugin manifest
├── gemini-extension.json   # Antigravity plugin manifest
├── package.json            # npm package: evm-agent-toolkit
└── tsconfig.json           # Strict TypeScript, ESM, declarations enabled

Key conventions

Naming

• Server: evm-agent-toolkit
• Tools: evm_{action}_{resource} (e.g., evm_scan_vulnerabilities)

API

• Use server.registerTool() — never server.tool() (deprecated)
• Every tool must have title, description, inputSchema (Zod), and annotations
• Use z.looseObject() — never .passthrough() (deprecated in Zod v4)
• Use z.unknown() — never z.any() (deprecated in Zod v4)
• Use catch (error: unknown) — never catch (error: any)
• All logging goes to stderr — stdio servers must never write to stdout
• Tool errors return isError: true

Build

• npm run build must pass with zero errors before any commit
• npm run test must pass all parser tests
• Output goes to build/ (gitignored)