initial commit

[j4ys0n]

No description provided.

[j4ys0n]

Automated review 🤖

Summary of Changes
This PR initializes the @missionsquad/mcp-evm project—a FastMCP-based EVM RPC server using evmdecoder. It adds core infrastructure including configuration, decoder pooling, 15 EVM tools, response normalization (including timestamp conversion), and CI workflows. The server supports hidden RPC URL injection via tool args or EVM_RPC_URL fallback, and ships pre-packaged ABIs (abis.zip) extracted at install time.

Architecture & Organization

• Modular design with dedicated files for config (src/config.ts), decoder registry (src/decoder-registry.ts), JSON/stringification (src/json.ts), response normalization (src/response-normalizer.ts), RPC URL resolution (src/rpc-url.ts), schemas (src/schemas.ts), and tool registration (src/tools.ts).
• DecoderRegistry implements LRU eviction for decoder instances per RPC URL, preventing resource exhaustion.
• Centralized config via Zod-validated environment parsing with sensible defaults from evmdecoder.
• ABI discovery prioritizes EVM_ABI_DIRECTORY, falls back to ./abis (populated from abis.zip via postinstall script).
• Tools are explicitly curated (15 total), avoiding batch-heavy operations to minimize payload size.

Key Changes & Positives

• Hidden RPC URL support via context.extraArgs.rpcUrl without exposing it in tool schemas—enhances security.
• LRU-based decoder pooling (DecoderRegistry) with per-URL isolation and clean error handling.
• Recursive timestamp normalization to human-readable UTC strings (handles numeric, hex, and string epochs).
• Response enrichment: automatically decodes missing call/event fields when possible, removes redundant input when decoded.
• Robust error handling with UserError wrapping and clear messages for missing RPC URL.
• Comprehensive test suite covering JSON normalization, RPC URL resolution, schema defaults, and method coverage.
• postinstall script extracts ABIs from abis.zip ensuring local ABI matching works out-of-the-box. 🟢

Potential Issues & Recommendations

• Issue / Risk: The abiDirectory path resolution in src/config.ts uses resolve(currentDir, '../abis') which assumes a specific directory layout; if the package is installed as a dependency, ../abis may not resolve correctly.
• Impact: ABI lookup could fail in downstream projects if ./abis isn’t adjacent to the built JS.
• Recommendation: Use process.cwd() or a configurable absolute path for defaultAbiDir, or ensure EVM_ABI_DIRECTORY is always set in non-dev contexts.
• Status: 🟡 Needs review

Language/Framework Checks

• TypeScript strict mode enabled (tsconfig.json), with ES2022 target and Node16 modules.
• Zod schemas (src/schemas.ts) enforce parameter types and defaults (e.g., decode: false for getPendingTransactions).
• Node.js >=20 requirement enforced in package.json engines field.
• Uses native node:fs, node:path, and node:url modules with ESM imports (fileURLToPath, dirname).
• stringifyResult handles bigint serialization via replacer.
• normalizeTimestamps in src/json.ts correctly distinguishes timestamp fields case-insensitively.

Security & Privacy

• RPC URL is never part of public tool schemas—only passed via hidden args or env, reducing accidental exposure.
• EVM_HTTP_VALIDATE_CERTIFICATE=false by default—should warn users in production to enable TLS validation.
• No secrets or credentials stored in code; sensitive values (e.g., NPM_TOKEN) expected as GitHub secrets.

Build/CI & Ops

• GitHub Actions workflows: build.yaml (test on PRs), publish.yaml (build/test/publish to npm on main).
• Publish workflow ignores **.md changes to avoid spurious releases.
• prepublishOnly script ensures tests and build pass before publishing.
• yarn.lock committed for reproducible installs.

Tests

• Unit tests cover timestamp normalization (test/json.test.ts), method coverage (test/method-coverage.test.ts), response enrichment (test/response-normalizer.test.ts), RPC URL resolution (test/rpc-url.test.ts), and schema defaults (test/schema-defaults.test.ts).
• Missing coverage: integration tests for actual RPC calls or decoder initialization failures. Consider adding mocks for EvmDecoder network calls.

Approval Recommendation
Approve with caveats

• Address ABI path resolution risk in src/config.ts—prefer process.cwd() or explicit env override for production deployments.
• Add warning in README about enabling EVM_HTTP_VALIDATE_CERTIFICATE=true in production.
• Consider adding integration test scaffolding for RPC connectivity (even if skipped by default).