diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..2f01cfb --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "etherscan", + "interface": { + "displayName": "Etherscan" + }, + "plugins": [ + { + "name": "etherscan", + "source": { + "source": "local", + "path": "./" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_USE" + }, + "category": "Developer Tools" + } + ] +} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..6fb5034 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,14 @@ +{ + "name": "etherscan", + "description": "Official Etherscan plugins", + "owner": { + "name": "Etherscan" + }, + "plugins": [ + { + "name": "etherscan", + "source": "./", + "description": "Debug EVM transactions, review verified contracts, and trace on-chain money flow with Etherscan." + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..bdc5bc6 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "etherscan", + "displayName": "Etherscan", + "description": "Debug EVM transactions, review verified contracts, trace on-chain money flow, and pick the right Etherscan page, API endpoint, CLI command, or MCP tool. Uses the Etherscan CLI first.", + "author": { + "name": "Etherscan", + "url": "https://etherscan.io" + }, + "homepage": "https://github.com/etherscan/skills", + "repository": "https://github.com/etherscan/skills", + "license": "MIT", + "keywords": ["etherscan", "ethereum", "evm", "blockchain", "transactions", "smart-contracts"], + "icon": "./assets/icon.png", + "documentationUrl": "https://docs.etherscan.io", + "supportUrl": "https://etherscan.io/contactus", + "privacyPolicyUrl": "https://etherscan.io/privacypolicy", + "termsOfServiceUrl": "https://etherscan.io/terms" +} diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..4c8fb09 --- /dev/null +++ b/.codex-plugin/plugin.json @@ -0,0 +1,42 @@ +{ + "name": "etherscan", + "version": "0.1.0", + "description": "Debug EVM transactions, review verified contracts, trace on-chain money flow, and pick the right Etherscan page, API endpoint, CLI command, or MCP tool.", + "author": { + "name": "Etherscan", + "url": "https://etherscan.io" + }, + "homepage": "https://github.com/etherscan/skills", + "repository": "https://github.com/etherscan/skills", + "license": "MIT", + "keywords": [ + "etherscan", + "ethereum", + "evm", + "blockchain", + "transactions", + "smart-contracts" + ], + "skills": "./skills/", + "interface": { + "displayName": "Etherscan", + "shortDescription": "Debug transactions and review contracts with Etherscan.", + "longDescription": "Etherscan skills that explain EVM transactions, review verified contracts, trace on-chain money flow, and route a task to the right Etherscan website page, API endpoint, CLI command, or MCP tool. They use the Etherscan CLI first.", + "developerName": "Etherscan", + "category": "Developer Tools", + "capabilities": [ + "Read" + ], + "websiteURL": "https://etherscan.io", + "privacyPolicyURL": "https://etherscan.io/privacypolicy", + "termsOfServiceURL": "https://etherscan.io/terms", + "defaultPrompt": [ + "Explain what happened in this transaction with Etherscan.", + "Review this verified contract on Etherscan.", + "Trace where the funds from this address went." + ], + "brandColor": "#0784C3", + "composerIcon": "./assets/icon.png", + "logo": "./assets/icon.png" + } +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73698c9..4ca1a13 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,16 @@ skills/ examples/ # optional — example outputs ``` +## Plugin packaging + +The repo root is also a Claude Code and Codex plugin that installs every skill under `skills/`, so a new skill ships in the plugin with no extra step. The plugin files are: + +- `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` (Claude Code) +- `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` (Codex) +- `assets/icon.png` + +The Claude manifest has no `version`, so every merge to `main` becomes the new plugin version for Claude Code users the next time their marketplace updates. The Codex manifest has one; bump it to release a change to Codex users. Check the plugin with `claude plugin validate .`. + ## Adding a skill 1. Create `skills//SKILL.md`. diff --git a/README.md b/README.md index 21604cd..fd115a5 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,24 @@ ## Installation +### As a Claude Code or Codex plugin + +The plugin installs all four skills and updates them with this repo. It contains no MCP server: the skills use the [Etherscan CLI](https://docs.etherscan.io/ai/cli.md) first, and use an Etherscan MCP connection only if you have already added one. + +In Claude Code: + +```text +/plugin marketplace add etherscan/skills +/plugin install etherscan@etherscan +``` + +In Codex: + +```bash +codex plugin marketplace add etherscan/skills +codex plugin add etherscan@etherscan +``` + ### With the Skills CLI Install every skill in this repo: diff --git a/assets/icon.png b/assets/icon.png new file mode 100644 index 0000000..a7bcbb7 Binary files /dev/null and b/assets/icon.png differ diff --git a/skills/etherscan/SKILL.md b/skills/etherscan/SKILL.md index e7d3eb3..6a35a29 100644 --- a/skills/etherscan/SKILL.md +++ b/skills/etherscan/SKILL.md @@ -63,8 +63,9 @@ When the user does not specify an interface, apply these defaults. - Prefer the website for an interactive human workflow. - Prefer the API for an application integration or when the broadest endpoint coverage is required. -- Prefer the CLI for terminal automation, pipelines, or exports. -- Prefer MCP for agent-driven, read-only tool calls when an authenticated MCP connection is available. +- Prefer the CLI for terminal automation, pipelines, exports, and agent-driven read-only lookups when the agent can run shell commands and the CLI is installed, has a resolved API key, and supports the requested chain, even when an MCP connection is also available. +- Otherwise, prefer MCP when an MCP connection is available. +- Otherwise, use the API (or the website for an interactive human workflow) and tell the user that the CLI or MCP would need setup. ## Respect capability boundaries @@ -91,7 +92,10 @@ Use these representative cases to verify routing and guardrail behavior after ch | --- | --- | | Show an address in the block explorer. | Use the website reference and an interactive address page. | | Export a wallet's ERC-20 transfers to CSV from a terminal. | Use the CLI reference and its pagination and CSV support. | -| Call an agent tool to retrieve a balance. | Use MCP when live discovery advertises a matching tool; inspect its current schema before calling it. | +| An agent with shell access retrieves a balance, and both the CLI and an MCP connection are available. | Use the CLI; inspect its live help before running the command. | +| An agent with shell access retrieves a balance; the CLI is installed but has no resolved API key or does not support the chain, and an MCP connection is available. | Use MCP; tell the user the CLI needs an API key or chain support to be preferred. | +| An agent without shell access retrieves a balance. | Use MCP when live discovery advertises a matching tool; inspect its current schema before calling it. | +| An agent retrieves a balance, and neither a usable CLI nor an MCP connection is available. | Use the API reference and tell the user that the CLI or MCP would need setup; do not claim an unavailable interface. | | Integrate token-holder counts into a backend. | Use the API and discover the current endpoint from official documentation; do not invent an MCP tool. | | The Etherscan CLI is installed locally. | Mention the installed version, inspect its live help, and use it when it matches the requested environment and output. | | An MCP server is documented but live discovery is unavailable. | Report its availability as unknown; do not describe it as connected or infer its tool inventory. | diff --git a/skills/etherscan/references/mcp.md b/skills/etherscan/references/mcp.md index 71595dc..6f3cc78 100644 --- a/skills/etherscan/references/mcp.md +++ b/skills/etherscan/references/mcp.md @@ -32,13 +32,14 @@ Live discovery overrides remembered or bundled tool names and schemas. ## Durable constraints -The official guide currently identifies the production endpoint as: +The official guide currently identifies two production endpoints: ```text -https://mcp.etherscan.io/mcp +https://mcp.etherscan.io/mcp # authenticated, full tool set, counts toward the key's API plan +https://mcp-keyless.etherscan.io/mcp # no key, no PRO tools, rate limited separately ``` -Use this bearer-header shape only when the client asks for the raw authentication form: +Use this bearer-header shape for the authenticated endpoint, and only when the client asks for the raw authentication form: ```text Authorization: Bearer YourApiKeyToken @@ -52,6 +53,18 @@ Authorization: Bearer YourApiKeyToken - Treat the MCP surface as read-only unless current tool discovery and official documentation explicitly establish a state-changing capability. - Require explicit authorization for the exact payload and chain before any state-changing tool call. Do not infer write support from another Etherscan interface. +## Keep calls minimal + +- Call the narrowest tool that answers the question. Do not fetch holdings, history, labels, or funding sources only to decorate an answer. +- Query one resolved chain. Do not probe or scan other chains unless the user asks for multichain results. +- Use conservative pagination for activity lists, and say when a result is truncated or paginated. +- Treat an empty result as "no records returned for this query," not as proof that no activity exists. +- If a throttling error includes `retryAfter` or other reset details, report that timing instead of guessing one, and do not retry in a loop. + +## Render widgets only where they display + +Call a visual tool such as `render_etherscan_widget` only when current discovery advertises it, the user wants a visual result, and the host renders MCP app UI, as chat clients such as claude.ai and ChatGPT do. In a terminal or coding agent, or when unsure, answer in text instead. Copy only facts present in tool results into the widget, and never synthesize chart points from a single current value or a start and end value. + ## If verification fails - Do not invent a tool, argument, schema, limit, or capability when live discovery is unavailable.