Lucent MCP server

Lucent

Tooling to author, verify, and attest ERC-7730 Clear Signing descriptors for the public registry that compatible wallets read from.

A descriptor is a JSON file that tells a wallet how to render a contract call in plain language, so users see what they are signing instead of raw hex. Lucent covers the full path: find contracts that lack a descriptor, write and harden one, check it beyond schema validity, prove it against real transactions, and produce an ERC-8176 attestation.

Hosted preflight API

Lucent's primary product surface is a call-scoped HTTP API with a stateless analysis core and bounded access/payment ledgers. It binds one unsigned EVM call (including sender) to one descriptor deployment, resolves the exact calldata selector, decodes the arguments, and runs the audit, comprehension, and danger checks only for that selected function:

make setup
make api
curl http://127.0.0.1:8780/health
open http://127.0.0.1:8780/docs

POST /v1/preflight returns call and assessment fingerprints with a safetopresent, review, or block decision. A blocked call is a successful assessment and therefore returns HTTP 200; malformed, unbound, ambiguous, or undecodable input returns a stable application/problem+json error.

The words are intentional: safetopresent never means safe to execute. Version 1 uses a deliberately narrow scalar presentation profile. Local mode can analyze caller-supplied ABI data; protected deployments can instead require a finalized runtime-bytecode match and Sourcify ABI before a verdict is returned. Hosted V1 rejects proxy-backed deployments until dispatch and upgrade-state semantics can be proven, including custom delegatecall dispatchers without EIP-1967 slots. Neither mode simulates state, detects economic exploits, or judges the counterparty. Those limits ride in every response. Full contract and deployment modes: docs/HOSTED-API.md.

Protected access and Base-USDC payments

The API and container start disabled. make api opts into loopback-only local development (open, verified source off, x402 off). Production modes are configured explicitly at startup and fail closed when their dependencies are incoherent:

idempotent result replay;

• api_key — hashed tenant keys, per-tenant token buckets, and five-minute

settlement on Base mainnet;

• x402 — official x402 v2 challenge/signature/receipt headers and exact USDC

pay-per-request fallback.

• apikeyor_x402 — subscription/quota access for integrations, with USDC

Any mode that accepts x402 requires verified-source mode. Payment proofs are verified before Lucent uses RPC/Sourcify capacity, settled only after a complete result exists. Exact retries replay the retained receipt, while a separate authorization ledger prevents the same signed EIP-3009 transfer from being rewrapped under a new idempotency key. Paid outcomes are not evicted while unexpired, and authorizations must expire within the server-owned five-minute window. The container runs one worker by default; scale-out requires a shared quota/idempotency/authorization-claim backend.

For signing agents: the MCP server

An AI agent about to sign a transaction faces exactly the question Lucent's checks answer — is this call clear enough to present, and does the screen a human would see actually describe what it does? scripts/mcp_server.py exposes that as an MCP server (JSON-RPC over stdio) so an agent can pre-flight a signature:

Shortened. The full README is on GitHub.