Base Tools MCP - Natural Language Bridge

A Model Context Protocol server for Base Network interactions with natural language bridge capabilities. This project enables users to bridge assets between Base and other EVM-compatible chains using natural language commands, with seamless gas handling and multi-provider support.

Project Overview

The Base Tools MCP provides a conversational interface for blockchain bridging operations. Users can type commands like "Send 50 USDC to Arbitrum" and the system handles the complex cross-chain operations behind the scenes, including:

Natural language command parsing
Multi-chain routing optimization
Gas fee abstraction (pay fees in the token being bridged)
Transaction monitoring and status updates
Error recovery and handling

Project Structure

The project is organized as follows:

base-tools-mcp/
├── src/                      # Application source code
│   ├── app/                  # Next.js application
│   │   ├── api/              # API route handlers
│   │   ├── bridge/           # Bridge page components
│   │   ├── history/          # Transaction history page
│   │   ├── layout.tsx        # Root layout component
│   │   └── page.tsx          # Home page component
│   ├── components/           # React components
│   │   ├── BridgeUI.jsx      # Main bridge UI component (1200+ lines)
│   │   ├── BridgeError.jsx   # Error handling component
│   │   ├── BridgeInterface.tsx # Bridge interface component
│   │   ├── common/           # Shared UI components
│   │   ├── chat/             # Chat interface components
│   │   └── wallet/           # Wallet connection components
│   ├── hooks/                # React hooks
│   │   ├── useBridge.js      # Bridge functionality hook
│   │   ├── useNLP.js         # Natural language processing hook
│   │   └── useWallet.js      # Wallet connection hook
│   ├── lib/                  # Utility libraries
│   │   ├── bridge/           # Bridge functionality
│   │   │   ├── monitor.js    # Transaction monitoring
│   │   │   ├── providers.js  # Bridge provider integrations
│   │   │   └── socket.js     # Socket protocol integration
│   │   ├── gasless/          # Gas abstraction
│   │   │   └── biconomy.js   # Biconomy integration
│   │   ├── nlp/              # Natural language processing
│   │   │   ├── bridgeNLP.js  # NLP command parser
│   │   │   └── nlpProcessor.js # NLP engine
│   │   ├── tokens/           # Token utilities
│   │   │   └── tokenUtils.js # Token-related functions
│   │   └── utils/            # General utilities
│   ├── services/             # API services
│   ├── store/                # State management
│   └── types/                # TypeScript types
├── test/                     # Test files
│   ├── unit/                 # Unit tests
│   │   ├── bridge/           # Bridge-related tests
│   │   └── nlp/              # NLP-related tests
│   └── bridge-test.js        # Integration tests
├── server.js                 # Express server (400+ lines)
├── base-tools-mcp.js         # MCP server implementation
└── cursor-mcp-config.json    # MCP configuration

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v18 or later)
npm (v7 or later)
A modern web browser
Access to Base Network RPC endpoints

Getting Started

Installation

Clone the repository:

git clone https://github.com/yourusername/base-tools-mcp.git
cd base-tools-mcp

Install dependencies:
```
npm install
```
Set up environment variables:
```
cp .env.example .env.local
```
Then edit .env.local to add your specific configuration values.

Configuration

The following environment variables are required:

PORT=3002                # The port the server will run on
SEED_PHRASE=your_phrase  # Wallet seed phrase for testing
COINBASE_API_KEY_NAME=builder
COINBASE_API_PRIVATE_KEY=your_private_key
COINBASE_KEY_ID=your_key_id
COINBASE_PROJECT_ID=your_project_id
BASE_RPC_URL=https://mainnet.base.org  # Base network RPC URL
ETH_RPC_URL=https://ethereum.publicnode.com  # Ethereum RPC URL
ARB_RPC_URL=https://arb1.arbitrum.io/rpc  # Arbitrum RPC URL
OP_RPC_URL=https://mainnet.optimism.io  # Optimism RPC URL
POLYGON_RPC_URL=https://polygon-rpc.com  # Polygon RPC URL

Running the Application

Start the development server:
```
npm run dev
```
This starts the server on the port specified in your .env.local file (default: 3000). You can access the web interface at http://localhost:PORT.

Run tests:

npm test

For specific test files:

npm test -- --testMatch="**/src/lib/nlp/**/*.test.js"

Start the MCP server:
```
npm start
```
This runs the Model Context Protocol server for AI interactions.
All-in-one build and run:
```
npm run build
```
This runs tests and then starts the server.

Architecture

Core Components

1. Natural Language Processing (NLP) Engine

The NLP engine is responsible for parsing user commands and extracting relevant parameters:

bridgeNLP.js: Processes natural language commands and extracts parameters like source chain, destination chain, token symbol, and amount.
nlpProcessor.js: Higher-level NLP processing with intent detection and parameter validation.

Example processing flow:

"Send 100 USDC to Arbitrum" → {
  intent: "bridge",
  sourceChain: "base", // Default if not specified
  destinationChain: "arbitrum",
  tokenSymbol: "USDC",
  amount: "100"
}

2. Bridge Provider Integration

Multiple bridge protocols are supported through a provider abstraction layer:

providers.js: Generic interface for all bridge providers
socket.js: Integration with Socket protocol
Stargate Router: Direct integration with Stargate Protocol contracts

3. Gas Abstraction

Pay for transactions using the bridged token instead of requiring ETH:

biconomy.js: Biconomy SDK integration for meta-transactions
Gas estimation: Accurate fee calculation across chains

4. Transaction Monitoring

Real-time tracking of bridge transactions:

monitor.js: Monitors transaction status across chains
Status polling with automatic retries and error handling

Data Flow

User inputs natural language command
NLP engine parses command and extracts parameters
System verifies parameters and requests clarification if needed
Bridge providers are queried for available routes
Best route is selected based on fees, speed, and reliability
Transaction is prepared and sent to the blockchain
System monitors transaction until completion
Result is displayed to the user

API Reference

Server API Endpoints

1. Process Natural Language Commands

POST /api/nlp

Request Body:

{
  "command": "bridge 100 USDC from Base to Ethereum"
}

Response:

{
  "success": true,
  "result": {
    "sourceChain": "base",
    "destinationChain": "ethereum",
    "tokenSymbol": "USDC",
    "amount": "100",
    "gasPreference": "normal"
  }
}

2. Get Wallet Balance

GET /api/balance?chain=base&token=USDC

Response:

{
  "success": true,
  "balance": "1250.50",
  "address": "0xabc...",
  "chain": "base",
  "tokenSymbol": "USDC"
}

3. Execute Bridge Transaction

POST /api/execute-bridge

Request Body:

{
  "sourceChain": "base",
  "destinationChain": "arbitrum",
  "token": "USDC",
  "amount": "10",
  "gasPreference": "normal",
  "walletAddress": "0xabc..."
}

Response:

{
  "success": true,
  "transactionHash": "0x123...",
  "estimatedTimeMinutes": 15,
  "fee": "1.25",
  "feeToken": "USDC"
}

MCP Function Reference

The Base Tools MCP server implements these functions:

get-address: Retrieve the wallet address
list-balances: Display balances for connected wallet
transfer-funds: Send funds to another address
erc20-balance: Get token balance for a specific contract
erc20-transfer: Transfer ERC20 tokens

Usage Examples

Example 1: Basic Bridge Command

bridge 100 USDC to Arbitrum

This will bridge 100 USDC from the default chain (Base) to Arbitrum.

Example 2: Specifying Source Chain

send 0.5 ETH from Ethereum to Optimism

This specifies Ethereum as the source chain, with 0.5 ETH being sent to Optimism.

Example 3: Checking Balance

check my USDC balance on Base

This queries the USDC balance on Base for the connected wallet.

Example 4: Gas Preferences

bridge 50 USDC to Polygon with fast gas

This bridges 50 USDC to Polygon with priority gas settings.

Supported Chains

Base (default source chain)
Ethereum
Arbitrum
Optimism
Polygon

Supported Tokens

ETH (Native)
USDC
USDT
DAI

Troubleshooting

Common Issues

Server Won't Start

Check if the specified port is already in use
Verify that all environment variables are set correctly
Ensure you have the correct Node.js version (v18+)

# Check if port is in use
lsof -i :3002
# Kill process using port if needed
kill -9 <PID>

Bridge Transaction Fails

Verify you have sufficient token balance
Check if the destination chain is supported
Ensure the token is supported on both chains
Verify gas settings are appropriate

NLP Command Not Recognized

Try rephrasing the command
Use the format: "bridge [amount] [token] to [destination]"
Make sure to use supported chain and token names

Logs and Debugging

To enable verbose logging:

DEBUG=true npm run dev

For transaction-specific logs:

DEBUG=bridge:* npm run dev

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a new branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (npm test)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style Guidelines

Use ES modules (import/export) instead of CommonJS (require)
Follow the existing code style and formatting
Write tests for new features
Keep components modular and focused

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Base Network for the underlying blockchain infrastructure
Stargate Protocol for cross-chain bridging capabilities
Biconomy for gas abstraction functionality
Socket for bridge aggregation services

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
lib		lib
public		public
src		src
.babelrc		.babelrc
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
README.md		README.md
base-tools-mcp.js		base-tools-mcp.js
cursor-mcp-config.json		cursor-mcp-config.json
jest.config.js		jest.config.js
jest.setup.ts		jest.setup.ts
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js
tailwind.config.ts		tailwind.config.ts
tsconfig.jest.json		tsconfig.jest.json
tsconfig.json		tsconfig.json

Stablefloww/bridge2

Folders and files

Latest commit

History

Repository files navigation

Base Tools MCP - Natural Language Bridge

Project Overview

Project Structure

Prerequisites

Getting Started

Installation

Configuration

Running the Application

Architecture

Core Components

1. Natural Language Processing (NLP) Engine

2. Bridge Provider Integration

3. Gas Abstraction

4. Transaction Monitoring

Data Flow

API Reference

Server API Endpoints

1. Process Natural Language Commands

2. Get Wallet Balance

3. Execute Bridge Transaction

MCP Function Reference

Usage Examples

Example 1: Basic Bridge Command

Example 2: Specifying Source Chain

Example 3: Checking Balance

Example 4: Gas Preferences

Supported Chains

Supported Tokens

Troubleshooting

Common Issues

Server Won't Start

Bridge Transaction Fails

NLP Command Not Recognized

Logs and Debugging

Contributing

Code Style Guidelines

License

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages