Zama fhEVM AI Agent Skill Package

Give any AI coding assistant — Claude, Cursor, Windsurf, Copilot, Cline, Codex — accurate fhEVM knowledge and real executable tools for building confidential smart contracts on Zama's fhEVM.

This package has three parts that work together:

1. An MCP server — a real npm package your AI agent can call to scaffold projects, compile contracts, deploy to Sepolia, check wallet balances, look up protocol addresses, verify contracts, encrypt values, check ACL, run tests, and decode errors
2. Rules files — drop-in config for every major AI coding tool so it stops hallucinating fhEVM code
3. Error decoder — a catalog of every known fhEVM error with root cause and exact fix

npm: @just-jelly/mcp-server — v2.2.6 — 32 tools

---

1. MCP Server

The MCP server is an npm package. Pick one of two ways to use it:

Option A — npx (no install, always latest)

npx -y @just-jelly/mcp-server

Use this config in your AI tool:

{
  "mcpServers": {
    "fhevm": {
      "command": "npx",
      "args": ["-y", "@just-jelly/mcp-server"],
      "env": {
        "FHEVM_PRIVATE_KEY": "0x_your_deployer_private_key",
        "FHEVM_RPC_URL":     "https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY",
        "ETHERSCAN_API_KEY": "optional_for_auto_verification"
      }
    }
  }
}

Option B — Global install (faster startup, no npx delay)

npm install -g @just-jelly/mcp-server

Then use fhevm-mcp as the command instead of npx:

{
  "mcpServers": {
    "fhevm": {
      "command": "fhevm-mcp",
      "args": [],
      "env": {
        "FHEVM_PRIVATE_KEY": "0x_your_deployer_private_key",
        "FHEVM_RPC_URL":     "https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY",
        "ETHERSCAN_API_KEY": "optional_for_auto_verification"
      }
    }
  }
}

Connect to your AI tool

The two key fields: FHEVM_PRIVATE_KEY and FHEVM_RPC_URL live in the MCP config env block — you never need a .env file in your project. When deploy/test tools run Hardhat, these are automatically forwarded to the subprocess.

RPC URL: Use a private RPC endpoint (Alchemy, Infura, QuickNode). The public BlastAPI fallback works for basic contract calls but rate-limits eth_getBalance. A free Alchemy Sepolia key is all you need.

Prefer not to hardcode? Set the vars in your shell profile (export FHEVM_PRIVATE_KEY=0x... in ~/.zshrc) and use a tiny wrapper script instead. See DEPLOYMENT.md for the exact pattern.

AI Tool	Where to put the config
Claude Desktop (Mac)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Code CLI	claude mcp add fhevm -- npx -y @just-jelly/mcp-server then claude mcp set-env fhevm FHEVM_PRIVATE_KEY 0x...
Cursor	.cursor/mcp.json in project root
Windsurf	~/.codeium/windsurf/mcp_config.json
OpenAI Codex	~/.codex/config.json
Cline (VS Code)	Cline sidebar → Settings → MCP Servers

31 Tools

Wallet & Config

Tool	What it does
setup_mcp_config	Generate exact config JSON for any AI tool — shows where to paste your FHEVM_PRIVATE_KEY
check_wallet_balance	Check ETH balance on Sepolia — auto-derives address from FHEVM_PRIVATE_KEY
get_faucet_links	All 5 Sepolia faucets with daily limits and requirements

Protocol Addresses

Tool	What it does
get_protocol_addresses	Full Sepolia address book: core fhEVM, Zama tokens, all 8 cToken wrappers, staking, governance, fees
verify_on_etherscan	Verify deployed contract source on Etherscan (uses ETHERSCAN_API_KEY from config)
watch_decryption_callback	Polling script + test pattern for FHE.requestDecryption() async callbacks
get_confidential_wrapper_code	Complete TypeScript for mint→wrap→transfer→balance on any cToken wrapper

Project Setup

Tool	What it does
scaffold_fhevm_project	Creates a complete Hardhat project — 4 templates: minimal, token, voting, auction
generate_hardhat_config	Generate hardhat.config.ts with all correct settings
generate_vite_config	Generate Vite config with required CORS headers for fhEVM WASM
check_dependencies	Scan package.json for common fhEVM dependency errors

Compile & Deploy

Tool	What it does
compile_solidity	Compiles contracts, returns fhEVM-specific error explanations
deploy_contract	Deploys to Sepolia or localhost — FHEVM_PRIVATE_KEY forwarded automatically
run_hardhat_tests	Runs tests with fhEVM failure analysis (mock + Sepolia modes)

Code Generation

Tool	What it does
generate_confidential_contract	Generates full contracts for 9 patterns: token, vault, voting, auction, payroll, lending, identity, game, erc7984
generate_fhevm_test	Test boilerplate with encrypt/decrypt patterns
generate_frontend_dapp	Complete React dApp with CORS config, balance reveal, transfer UI

Encryption

Tool	What it does
encrypt_value	Generates complete frontend + Node.js encryption code for any type
encrypt_multiple_values	Packs multiple values into one input proof (gas efficient)
get_encrypted_balance	Reads a ciphertext handle + generates full re-encryption frontend code
read_contract_state	Calls any view function on a deployed contract via your FHEVM_RPC_URL

ACL

Tool	What it does
check_acl_permission	Live on-chain ACL check — is this address allowed to use this handle?
explain_acl_pattern	Returns production Solidity for 6 ACL scenarios

Analysis & Errors

Tool	What it does
verify_fhevm_contract	Static analysis — finds missing allowThis, unverified inputs, wrong patterns
decode_fhevm_error	Decodes any fhEVM error → root cause + exact fix (55+ patterns, all Solidity custom errors)

Network & Gas

Tool	What it does
get_network_config	All Sepolia/mainnet addresses + SDK initialization code
estimate_fhe_gas	Gas cost model + optimization strategies

Tutorials

Tool	What it does
get_fhevm_tutorial	Step-by-step tutorials: quickstart, token, voting, frontend, re-encryption, on-chain-decryption, testing, deployment, OpenZeppelin
explain_fhe_type	Deep reference for every FHE type — euint8→256, ebool, eaddress, casting, ops table
explain_coprocessor	Architecture diagram, async flow, gas model, mock vs Sepolia
explain_erc7984	New — ERC-7984 + OZ Confidential Contracts reference: standard overview, IConfidentialERC20 interface, all OZ base contracts (Mintable/WithErrors/Votes/Vesting), wrap/unwrap Gateway pattern, PLACEHOLDER events, testing, migration from ERC-20
list_tools	List all 32 tools with descriptions

---

2. Rules Files

Drop-in rules for every major AI coding tool. Copy the right file(s) into your fhEVM project and the AI immediately knows how to write correct confidential contracts.

zama-fhevm-skill/
├── SKILL.md                          → Claude Code (load as a skill)
├── CLAUDE.md                         → Claude Code (auto-loaded in project)
├── AGENTS.md                         → OpenAI Codex (auto-loaded in project)
├── .cursor/rules/
│   ├── fhevm-core.mdc               → Cursor — always active (alwaysApply: true)
│   ├── fhevm-solidity.mdc           → Cursor — activates on *.sol files
│   ├── fhevm-frontend.mdc           → Cursor — activates on src/**/*.{ts,tsx}
│   └── fhevm-testing.mdc            → Cursor — activates on *.test.{ts,js}
├── .windsurfrules                    → Windsurf (auto-loaded in project)
├── .github/copilot-instructions.md  → GitHub Copilot (auto-loaded in project)
└── .clinerules/fhevm.md             → Cline / RooCode (auto-loaded in project)

Copy what you need:

# Cursor
cp -r zama-fhevm-skill/.cursor  your-project/.cursor

# Windsurf
cp zama-fhevm-skill/.windsurfrules  your-project/.windsurfrules

# GitHub Copilot
cp -r zama-fhevm-skill/.github  your-project/.github

# OpenAI Codex
cp zama-fhevm-skill/AGENTS.md  your-project/AGENTS.md

# Cline
cp -r zama-fhevm-skill/.clinerules  your-project/.clinerules

# Claude Code
cp zama-fhevm-skill/CLAUDE.md  your-project/CLAUDE.md

What the rules teach every AI tool

The rules enforce 10 patterns that AI consistently gets wrong without them:

1. FHE.allowThis() after every ciphertext assignment — without this the next tx reverts with ACL: Not allowed
2. FHE.fromExternal(enc, proof) to verify inputs before use
3. FHE.select(condition, a, b) for branching — if(ebool) is a compile error
4. Initialize mapping slots before first FHE operation — bytes32(0) reverts immediately
5. evmVersion: "cancun" in hardhat.config.ts — missing this breaks deployment
6. Inherit the correct network config contract per chain
7. chai@^4 only — v5 breaks @fhevm/hardhat-plugin
8. @fhevm/hardhat-plugin must be the first import in hardhat.config.ts
9. Plaintext divisors only — FHE.div(a, 100) not FHE.div(a, b)
10. Fresh inputProof per transaction — reusing a proof fails ZK verification

---

3. Error Decoder

zama-fhevm-skill/errors/ERRORS.md — 55+ fhEVM errors across 13 categories, each with root cause, exact code fix, and prevention rule. Sourced from real fhEVM Solidity contract source (FHE.sol, ACL.sol, InputVerifier.sol).

Also available as the decode_fhevm_error MCP tool — your AI can call it live during development.

13 categories:

• ACL / access control errors
• Handle and zero-handle errors (HandlesAlreadySavedForRequestID, NoHandleFoundForRequestID, UnsupportedHandleType)
• Input proof / ZK verification errors (InputLengthAbove64Bytes/128Bytes/256Bytes, InvalidKMSSignatures)
• Input length / type errors — real Solidity custom errors from fhEVM source
• Decryption / KMS / callback errors
• Hardhat and compilation errors
• Solidity type errors
• Gas / computation errors
• Frontend SDK / WASM errors
• Testing errors
• Deployment / network errors
• OpenZeppelin confidential contracts errors
• MCP server / config errors

---

Sepolia Addresses

Core fhEVM

Contract	Address
ACL	0x687820221192C5B662b25367F70076A37bc79b6c
KMS Verifier	0x1364cBBf2cDF5032C47d8226a6f6FBD2AFCDacAC
Input Verifier	0xbc91f3daD1A5F19F8390c400196e58073B6a0BC4
Chain ID	11155111
Relayer	https://relayer.testnet.zama.cloud

Confidential Token Wrappers (Mock — freely mintable underlying)

Symbol	Wrapper Address
cUSDCMock	0x7c5BF43B851c1dff1a4feE8dB225b87f2C223639
cUSDTMock	0x4E7B06D78965594eB5EF5414c357ca21E1554491
cWETHMock	0x46208622DA27d91db4f0393733C8BA082ed83158
cBRONMock	0xaa5612FA27c927a0c7961f5AEFEE5ba3A0F9C891
cZAMAMock	0xf2D628d2598aF4eAF94CB76a437Ff86CA78FfbFB

Use get_protocol_addresses for the full book including staking, governance, and fee contracts.

---

License

BSD-3-Clause-Clear — same as Zama's fhEVM codebase.