HashPilot

Instructions

Implementation Reference

• src/tools/composite.ts:895-990 (handler)

  Primary handler function that executes the 'foundry_contract' tool. Routes to specific Foundry operations (test, create, script, call, send, anvil management) using imported foundryTools.

  export async function foundryContractManage(args: {
    operation: 'test' | 'create' | 'script' | 'call' | 'send' | 'anvil_start' | 'anvil_stop';
    // Common
    directory?: string;
    // Test-specific
    matchTest?: string;
    matchContract?: string;
    gasReport?: boolean;
    forkUrl?: string;
    verbosity?: number;
    // Create-specific
    contractName?: string;
    constructorArgs?: any[];
    rpcUrl?: string;
    privateKey?: string;
    // Script-specific
    scriptPath?: string;
    broadcast?: boolean;
    // Call/Send-specific
    address?: string;
    signature?: string;
    callArgs?: any[];
    value?: string;
    // Anvil-specific
    port?: number;
    forkBlock?: number;
  }): Promise<ToolResult> {
    try {
      logger.info('Foundry contract operation', { operation: args.operation });
  
      switch (args.operation) {
        case 'test':
          return await foundryTools.foundryTest({
            matchTest: args.matchTest,
            matchContract: args.matchContract,
            gasReport: args.gasReport,
            forkUrl: args.forkUrl,
            verbosity: args.verbosity,
            directory: args.directory,
          });
  
        case 'create':
          return await foundryTools.foundryCreate({
            contractPath: args.contractName!, // Using contractName as path
            constructorArgs: args.constructorArgs?.map(String),
            rpcUrl: args.rpcUrl!,
            privateKey: args.privateKey!,
          });
  
        case 'script':
          return await foundryTools.foundryScript({
            scriptPath: args.scriptPath!,
            rpcUrl: args.rpcUrl,
            broadcast: args.broadcast,
            privateKey: args.privateKey,
          });
  
        case 'call':
          return await foundryTools.foundryCall({
            address: args.address!,
            signature: args.signature!,
            args: args.callArgs,
            rpcUrl: args.rpcUrl,
          });
  
        case 'send':
          return await foundryTools.foundrySend({
            address: args.address!,
            signature: args.signature!,
            args: args.callArgs,
            rpcUrl: args.rpcUrl!,
            privateKey: args.privateKey!,
            value: args.value,
          });
  
        case 'anvil_start':
          return await foundryTools.foundryAnvilStart({
            port: args.port,
            forkUrl: args.forkUrl,
            chainId: args.forkBlock, // Use forkBlock as chainId if needed
          });
  
        case 'anvil_stop':
          return await foundryTools.foundryAnvilStop();
  
        default:
          throw new Error(`Unknown operation: ${args.operation}`);
      }
    } catch (error) {
      logger.error('Foundry contract operation failed', { operation: args.operation, error });
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  }

• src/tools/composite.ts:1120-1166 (schema)

  Input schema and description for the 'foundry_contract' tool, defining all supported operations and parameters.

    {
      name: 'foundry_contract',
      description: `Manage Foundry contract testing, deployment, and interaction.
  
  OPERATIONS:
  - test: Run Forge tests with fuzzing and gas reports
  - create: Deploy single contract via forge create
  - script: Execute Solidity deployment script
  - call: Call read-only function via cast (FREE)
  - send: Send state-changing transaction via cast
  - anvil_start: Start local Anvil node (can fork from network)
  - anvil_stop: Stop Anvil local node
  
  AUTO-RESOLUTION: privateKey and rpcUrl are OPTIONAL - if not provided, automatically uses MCP operator account configuration.
  
  USE FOR: Testing, deployment, gas analysis, and local development.`,
      inputSchema: {
        type: 'object' as const,
        properties: {
          operation: {
            type: 'string',
            enum: ['test', 'create', 'script', 'call', 'send', 'anvil_start', 'anvil_stop'],
            description: 'Contract operation to perform',
          },
          directory: { type: 'string', description: 'Absolute path to Foundry project directory' },
          matchTest: { type: 'string', description: 'Test name filter (for test)' },
          matchContract: { type: 'string', description: 'Contract name filter (for test)' },
          gasReport: { type: 'boolean', description: 'Generate gas report (for test)' },
          forkUrl: { type: 'string', description: 'RPC URL to fork from (for test/anvil_start)' },
          verbosity: { type: 'number', description: 'Output verbosity 1-5 (for test)' },
          contractName: { type: 'string', description: 'Contract name (for create)' },
          constructorArgs: { type: 'array', items: {}, description: 'Constructor args (for create)' },
          rpcUrl: { type: 'string', description: 'JSON-RPC URL (optional - auto-resolves from MCP network config)' },
          privateKey: { type: 'string', description: 'Private key for signing (optional - auto-uses MCP operator key)' },
          scriptPath: { type: 'string', description: 'Script path (for script)' },
          broadcast: { type: 'boolean', description: 'Broadcast transactions (for script)' },
          address: { type: 'string', description: 'Contract address (for call/send)' },
          signature: { type: 'string', description: 'Function signature (for call/send)' },
          callArgs: { type: 'array', items: {}, description: 'Function arguments (for call/send)' },
          value: { type: 'string', description: 'ETH/HBAR value (for send)' },
          port: { type: 'number', description: 'Port number (for anvil_start)' },
          forkBlock: { type: 'number', description: 'Block to fork from (for anvil_start)' },
        },
        required: ['operation'],
      },
    },
  ];

• src/index.ts:656-658 (registration)

  Tool registration in the main MCP server request handler. Dispatches calls to the foundryContractManage handler function.

  case 'foundry_contract':
    result = await foundryContractManage(args as any);
    break;