mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Core Development

• yarn dev - Start development server (runs at http://localhost:3002/mcp)
• yarn build - Build the project using xmcp
• yarn start - Start production server from dist/

Code Quality

• yarn lint - Run ESLint on src/ directory
• yarn lint:fix - Auto-fix ESLint issues
• yarn lint:check - Run lint with max warnings = 0 (strict mode)
• yarn format - Format code with Prettier
• yarn format:check - Check if code is properly formatted

Architecture Overview

This is MCP server based on xmcp (https://xmcp.dev/docs) that provides AI assistants with access to Shape blockchain data. The architecture follows a modular tool-based design:

Core Components

Configuration & Clients (src/)

• config.ts - Environment-based configuration (chain ID, API keys, RPC URLs)
• clients.ts - Viem RPC clients for Shape mainnet/testnet and Ethereum mainnet, plus Alchemy SDK and Redis
• addresses.ts - Contract addresses for gasback and stack contracts on both networks
• types.ts - TypeScript types for all tool outputs and error responses

Tool Architecture (src/tools/) The server uses a category-based tool organization:

• gasback/ - Creator earnings analysis and reward simulation
• network/ - Chain status monitoring
• nft/ - Collection analytics and ownership data
• stack/ - Achievement tracking system

Infrastructure

• utils/cache.ts - Redis caching layer with fallback for when Redis is unavailable
• abi/ - Contract ABIs for gasback and stack contracts
• middleware.ts - Express middleware (currently minimal)

Tool Pattern

Each tool follows this structure:

export const schema = {
  /* Zod validation schema */
};
export const metadata = {
  name: string,
  description: string,
  annotations: {
    /* Tool metadata including cache TTL, categories, etc */
  },
};
export default async function toolName(params) {
  /* Implementation */
}