aptos-mcp

Instructions

Creates a new Aptos gas station (fee sponsorship) project.

Args:
    project_name: Name of the gas station project

Implementation Reference

• aptos_mcp_server.py:1129-1336 (handler)

  The main handler function for the 'create_gas_station' MCP tool. It creates a complete Aptos gas station project structure including server and client TypeScript code, package.json, tsconfig.json, .env, and README.md files by calling helper functions to generate the code templates.

  @mcp.tool()
  async def create_gas_station(project_name: str) -> str:
      """
      Creates a new Aptos gas station (fee sponsorship) project.
      
      Args:
          project_name: Name of the gas station project
      """
      project_name = project_name.strip().replace(" ", "-").lower()
      
      try:
          # Create project directory
          project_dir = os.path.join(os.getcwd(), project_name)
          if os.path.exists(project_dir):
              return f"Directory {project_dir} already exists. Please choose a different name."
          
          os.makedirs(project_dir)
          
          # Create server directory
          server_dir = os.path.join(project_dir, "server")
          os.makedirs(server_dir, exist_ok=True)
          
          # Create client directory
          client_dir = os.path.join(project_dir, "client")
          os.makedirs(client_dir, exist_ok=True)
          
          # Generate server files
          server_ts_path = os.path.join(server_dir, "server.ts")
          with open(server_ts_path, "w") as f:
              f.write(generate_gas_station_server())
          
          # Generate client files
          client_ts_path = os.path.join(client_dir, "client.ts")
          with open(client_ts_path, "w") as f:
              f.write(generate_gas_station_client())
          
          # Create package.json for server
          server_package_json = {
              "name": f"{project_name}-server",
              "version": "1.0.0",
              "description": "Aptos Gas Station Server for fee sponsorship",
              "main": "server.ts",
              "scripts": {
                  "build": "tsc",
                  "start": "ts-node server.ts"
              },
              "dependencies": {
                  "@aptos-labs/ts-sdk": "^1.2.0",
                  "express": "^4.18.2",
                  "dotenv": "^16.3.1"
              },
              "devDependencies": {
                  "@types/express": "^4.17.17",
                  "ts-node": "^10.9.1",
                  "typescript": "^5.1.6"
              }
          }
          
          with open(os.path.join(server_dir, "package.json"), "w") as f:
              json.dump(server_package_json, f, indent=2)
          
          # Create package.json for client
          client_package_json = {
              "name": f"{project_name}-client",
              "version": "1.0.0",
              "description": "Aptos Gas Station Client Example",
              "main": "client.ts",
              "scripts": {
                  "build": "tsc",
                  "start": "ts-node client.ts"
              },
              "dependencies": {
                  "@aptos-labs/ts-sdk": "^1.2.0",
                  "axios": "^1.4.0"
              },
              "devDependencies": {
                  "ts-node": "^10.9.1",
                  "typescript": "^5.1.6"
              }
          }
          
          with open(os.path.join(client_dir, "package.json"), "w") as f:
              json.dump(client_package_json, f, indent=2)
          
          # Create tsconfig.json files
          tsconfig = {
              "compilerOptions": {
                  "target": "es2020",
                  "module": "commonjs",
                  "esModuleInterop": True,
                  "forceConsistentCasingInFileNames": True,
                  "strict": True,
                  "skipLibCheck": True,
                  "outDir": "dist"
              }
          }
          
          with open(os.path.join(server_dir, "tsconfig.json"), "w") as f:
              json.dump(tsconfig, f, indent=2)
          
          with open(os.path.join(client_dir, "tsconfig.json"), "w") as f:
              json.dump(tsconfig, f, indent=2)
          
          # Create .env file for server
          env_content = """# Aptos Network: DEVNET, TESTNET, MAINNET
  APTOS_NETWORK=DEVNET
  
  # Port for the server
  PORT=3000
  
  # Optional: Fund gas account on start (true/false)
  AUTO_FUND_ACCOUNT=true
  """
          
          with open(os.path.join(server_dir, ".env"), "w") as f:
              f.write(env_content)
          
          # Create README.md
          readme_content = f"""# {project_name} - Aptos Gas Station
  
  A gas station implementation for Aptos that allows fee sponsorship (fee payer) for transactions.
  
  ## Structure
  
  - `server/`: Gas station server that acts as a fee payer
  - `client/`: Example client that uses the gas station
  
  ## Server Setup
  
  1. Navigate to the server directory:
     ```
     cd server
     ```
  
  2. Install dependencies:
     ```
     npm install
     ```
  
  3. Configure your environment:
     Edit the `.env` file to customize your setup.
  
  4. Start the server:
     ```
     npm start
     ```
  
  ## Client Example
  
  The client directory contains an example of how to use the gas station to submit transactions without paying gas fees.
  
  1. Navigate to the client directory:
     ```
     cd client
     ```
  
  2. Install dependencies:
     ```
     npm install
     ```
  
  3. Run the example:
     ```
     npm start
     ```
  
  ## How It Works
  
  1. Client builds a transaction and signs it
  2. Client sends the transaction to the gas station
  3. Gas station signs the transaction as a fee payer
  4. Gas station submits the transaction to the blockchain
  5. Original transaction executes with fees paid by the gas station
  
  ## Security Considerations
  
  - Implement proper authentication for production
  - Add rate limiting to prevent abuse
  - Monitor gas usage to control costs
  """
          
          with open(os.path.join(project_dir, "README.md"), "w") as f:
              f.write(readme_content)
          
          return f"""
  Successfully created Aptos Gas Station project at {project_dir}!
  
  The project includes:
  - Server implementation (Express.js)
  - Client example code
  - Configuration files
  
  Next steps:
  1. Navigate to the server directory: `cd {project_name}/server`
  2. Install dependencies: `npm install`
  3. Configure your environment in .env
  4. Start the server: `npm start`
  
  To try the client example:
  1. Navigate to the client directory: `cd {project_name}/client`
  2. Install dependencies: `npm install`
  3. Run the example: `npm start`
  
  See the README.md file for more information.
  """
      
      except Exception as e:
          return f"Error creating gas station project: {str(e)}"

• aptos_mcp_server.py:1129-1129 (registration)

  The @mcp.tool() decorator registers the create_gas_station function as an MCP tool.

  @mcp.tool()

• aptos_mcp_server.py:275-384 (helper)

  Helper function that generates the complete TypeScript code for the gas station Express server, including endpoints for signing and submitting sponsored transactions.

  def generate_gas_station_server() -> str:
      """Generate the server code for a gas station"""
      return """import express, { Request, Response } from 'express';
  import {
      Account, AccountAuthenticator,
      Aptos,
      AptosConfig,
      Deserializer,
      Network,
      NetworkToNetworkName,
      SimpleTransaction,
  } from '@aptos-labs/ts-sdk';
  import dotenv from 'dotenv';
  
  dotenv.config();
  
  const app = express();
  app.use(express.json());
  
  const PORT = process.env.PORT ? parseInt(process.env.PORT) : 3000;
  
  const APTOS_NETWORK = NetworkToNetworkName[process.env.APTOS_NETWORK || ''] || Network.DEVNET;
  
  const config = new AptosConfig({network: APTOS_NETWORK});
  const aptos = new Aptos(config);
  
  const feePayerAccount = Account.generate();
  console.log(`Gas Station Account Address: ${feePayerAccount.accountAddress.toString()}`);
  
  // Fund the feePayerAccount account
  const fundFeePayerAccount = async () => {
      console.log('=== Funding Gas Station Account ===');
      try {
          await aptos.fundAccount({
              accountAddress: feePayerAccount.accountAddress,
              amount: 100_000_000,
          });
          console.log('Gas Station Account funded successfully.');
      } catch (error) {
          console.error('Error funding Gas Station Account:', error);
          console.log('Note: Automatic funding only works on DEVNET. On other networks, manually fund this address.');
      }
  };
  
  app.post('/signAndSubmit', async (req: Request, res: Response) => {
      try {
          const {transactionBytes, senderAuthenticator} = req.body;
  
          if (!transactionBytes) {
              return res.status(400).json({error: 'transactionBytes is required'});
          }
          if (!senderAuthenticator) {
              return res.status(400).json({error: 'senderAuthenticator is required'});
          }
  
          console.log('=== Received Transaction Request ===');
  
          // Deserialize the raw transaction
          const deserializer = new Deserializer(Uint8Array.from(transactionBytes));
          const transaction = SimpleTransaction.deserialize(deserializer);
  
          console.log('=== Signing Transaction as Fee Payer ===');
  
          // Gas station signs the transaction as fee payer
          const feePayerAuthenticator = aptos.transaction.signAsFeePayer({
              signer: feePayerAccount,
              transaction,
          });
  
          const deserializedSenderAuth = AccountAuthenticator.deserialize(new Deserializer(Uint8Array.from(senderAuthenticator)));
  
          console.log('=== Submitting Sponsored Transaction ===');
          const signedTxnInput = {
              transaction,
              senderAuthenticator: deserializedSenderAuth,
              feePayerAuthenticator,
          };
          let response = await aptos.transaction.submit.simple(signedTxnInput);
          
          console.log(`Transaction submitted. Hash: ${response.hash}`);
          await aptos.waitForTransaction({transactionHash: response.hash});
          console.log('Transaction executed successfully!');
  
          return res.status(200).json({
              transactionHash: response.hash,
              message: 'Transaction sponsored and executed successfully',
              feePayerAddress: feePayerAccount.accountAddress.toString()
          });
      } catch (error) {
          console.error('Error processing transaction:', error);
          return res.status(500).json({error: String(error)});
      }
  });
  
  // Health check endpoint
  app.get('/health', (req: Request, res: Response) => {
      return res.status(200).json({
          status: 'healthy',
          network: APTOS_NETWORK,
          feePayerAddress: feePayerAccount.accountAddress.toString()
      });
  });
  
  app.listen(PORT, async () => {
      console.log(`Gas Station Server running on http://localhost:${PORT}`);
      if (process.env.AUTO_FUND_ACCOUNT === 'true') {
          await fundFeePayerAccount();
      }
  });
  """

• aptos_mcp_server.py:386-466 (helper)

  Helper function that generates the TypeScript client example code demonstrating how to build, sign, and submit a transaction via the gas station for fee sponsorship.

  def generate_gas_station_client() -> str:
      """Generate the client code for a gas station"""
      return """import axios from 'axios';
  import { Account, Aptos, AptosConfig, Network, } from '@aptos-labs/ts-sdk';
  
  const GAS_STATION_URL = "http://localhost:3000";
  
  const main = async () => {
      const config = new AptosConfig({ network: Network.DEVNET });
      const aptos = new Aptos(config);
  
      console.log("=== Aptos Gas Station Client Demo ===");
      
      // Create sender and recipient accounts
      const alice = Account.generate();
      const bob = Account.generate();
  
      console.log("Alice's address:", alice.accountAddress.toString());
      console.log("Bob's address:", bob.accountAddress.toString());
  
      // Fund Alice's account (the transaction sender, but not fee payer)
      console.log("\\n=== Funding Alice's account ===");
      await aptos.fundAccount({ accountAddress: alice.accountAddress, amount: 100_000_000 });
      console.log("Alice's account funded");
  
      // Build a transaction (Alice sending APT to Bob)
      console.log("\\n=== Building transaction ===");
      const transaction = await aptos.transaction.build.simple({
          sender: alice.accountAddress,
          withFeePayer: true,  // Important: Mark that this transaction will have a fee payer
          data: {
              function: "0x1::aptos_account::transfer",
              functionArguments: [bob.accountAddress, 100],  // Sending 100 octas to Bob
          },
      });
      
      console.log("Transaction built successfully");
  
      // Alice signs the transaction (but doesn't pay for gas)
      console.log("\\n=== Alice signing transaction ===");
      const senderAuthenticator = aptos.transaction.sign({ signer: alice, transaction });
      console.log("Transaction signed by Alice");
  
      // Send the transaction to the gas station for fee sponsorship
      console.log("\\n=== Sending to Gas Station for sponsorship ===");
      try {
          const response = await axios.post(
              `${GAS_STATION_URL}/signAndSubmit`,
              {
                  transactionBytes: Array.from(transaction.bcsToBytes()),
                  senderAuthenticator: Array.from(senderAuthenticator.bcsToBytes()),
              },
              {
                  headers: {
                      "Content-Type": "application/json",
                  },
              }
          );
  
          const { transactionHash, feePayerAddress } = response.data;
  
          console.log("Transaction sponsored by:", feePayerAddress);
          console.log("Transaction submitted. Hash:", transactionHash);
          
          // Wait for transaction to be executed
          console.log("\\n=== Waiting for transaction execution ===");
          const executedTx = await aptos.waitForTransaction({ transactionHash });
          console.log("Transaction executed successfully!");
          
          // Verify Bob received the funds
          console.log("\\n=== Checking Bob's balance ===");
          const bobBalance = await aptos.getAccountAPTAmount({ accountAddress: bob.accountAddress });
          console.log("Bob's balance:", bobBalance, "octas");
          
      } catch (error) {
          console.error("Error:", error.response?.data || error.message);
      }
  };
  
  main();
  """