# Solana Web3.js MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to develop and deploy Solana smart contracts end-to-end. This server acts as a bridge between AI language models and the Solana blockchain, providing a standardized interface for blockchain interactions.

> **Important Update**: This project is currently being migrated from Solana web3.js v1.x to v2.0 to take advantage of improved performance, better type safety, and modern functional programming patterns. See the [migration plan](/migration_plan.md) for details.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that allows AI assistants to access external tools and data sources in a secure, controlled manner. This server implements the MCP specification to expose Solana blockchain functionality to AI assistants.

## What This Server Does

This MCP server provides AI assistants with the ability to:

1. **Interact with the Solana Blockchain**: Query account data, check balances, view transaction history, and get network status from various Solana clusters (mainnet, testnet, devnet)

2. **Create and Manage Transactions**: Build, simulate, sign, and send transactions to the Solana blockchain with proper error handling and fee estimation

3. **Develop Smart Contracts**: Access templates, compile, test, and deploy Solana programs written in Rust using the Solana SDK or Pinocchio framework

4. **Manage Wallets and Keys**: Generate keypairs, derive addresses, and interact with wallet adapters while maintaining security best practices

5. **Work with Tokens**: Create, transfer, and manage SPL tokens and token accounts

## Architecture

The server exposes three types of MCP capabilities:

- **Tools**: Functions that perform actions like sending transactions, deploying programs, or generating keypairs
- **Resources**: Data sources such as documentation, code templates, and blockchain state information
- **Prompts**: Templates for guiding the AI through complex workflows like smart contract development

All blockchain interactions are performed through the [@solana/web3.js](https://github.com/solana-labs/solana-web3.js) library and related SDKs, with the MCP server acting as a secure intermediary between the AI and the blockchain.

## Installation

```bash
# Clone the repository
git clone https://github.com/FrankGenGo/solana-web3js-mcp-server.git
cd solana-web3js-mcp-server

# Install dependencies
npm install

# Build the server
npm run build

# Start the server
npm start
```

## Usage with Claude Desktop

1. Install [Claude Desktop](https://claude.ai/download)

2. Add the following to your Claude Desktop configuration file:

   **On macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   **On Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "solana": {
      "command": "node",
      "args": ["/absolute/path/to/solana-web3js-mcp-server/dist/index.js"]
    }
  }
}
```

3. Restart Claude Desktop

4. You can now ask Claude to perform Solana-related tasks, such as:
   - "Create a new Solana account and show me the keypair"
   - "What's the current balance of address X?"
   - "Help me write and deploy a simple token contract on Solana devnet"

## Security Considerations

- This server does NOT store private keys by default
- Sensitive operations (signing, deploying to mainnet) require explicit user approval
- The server follows best practices for secure blockchain interactions

## Available Tools

### Account Management (Implemented)
- `getAccountInfo`: Fetch and decode account information
- `checkAccountBalance`: Get SOL balance for an address
- `findProgramAccounts`: Find accounts owned by a program
- `getRentExemption`: Calculate minimum balance for rent exemption

### Transaction Management (Implemented)
- `createTransaction`: Build a transaction with specified instructions
- `signTransaction`: Sign a transaction with one or more keypairs
- `sendTransaction`: Send and confirm a transaction on-chain
- `simulateTransaction`: Simulate a transaction without sending it
- `getTransactionStatus`: Check the status of a transaction

### Key Management (Implemented)
- `generateKeypair`: Create a new Solana keypair
- `importKeypair`: Import an existing keypair from various formats
- `deriveKeypair`: Derive a keypair from seed, mnemonic, or path

### Program Development (Implemented)
- `deployProgram`: Deploy a program to a Solana cluster
- `upgradeProgram`: Upgrade an existing upgradeable program
- `generateProgramAddress`: Derive a program derived address (PDA)

### Token Operations (Implemented)
- `createToken`: Create a new SPL token
- `mintTokens`: Mint tokens to a token account
- `transferTokens`: Transfer tokens between accounts
- `getTokenAccountInfo`: Get token account information
- `getTokenSupply`: Get the total supply of a token

### Configuration Management (Planned)
- `getConfig`: Get current configuration settings
- `setConfig`: Update configuration parameters
- `getClusterVersion`: Get Solana cluster version

### Extended Keypair Management (Planned)
- `saveKeypair`: Save keypair to secure storage
- `recoverKeypair`: Recover keypair from seed phrase
- `verifyKeypair`: Verify keypair integrity

### Network Interaction (Planned)
- `requestAirdrop`: Request SOL from devnet/testnet faucet
- `manageStake`: Create and manage stake accounts
- `getValidators`: Get validator information

### Blockchain Data Inspection (Planned)
- `getBlock`: Get block details by slot number
- `getBlockProduction`: Get block production statistics
- `getRecentBlockhash`: Get recent blockhash with fee calculator
- `getEpochInfo`: Get current epoch information
- `getInflationRate`: Get current inflation rate

### Logging & Monitoring (Planned)
- `getLogs`: Stream and filter transaction logs
- `getProgramLogs`: Monitor program execution logs

## Development

```bash
# Run in development mode (with auto-reload)
npm run dev

# Run tests (including integration tests against devnet)
npm test

# Lint the code
npm run lint
```

### Setting Up Test Environment

The test suite includes integration tests that run against the Solana devnet. To set up your environment for testing:

1. **Install Solana CLI**: Follow the [official installation instructions](https://docs.solanalabs.com/cli/install)

2. **Generate a test keypair**:
   ```bash
   mkdir -p ~/solana-web3js-tests
   solana-keygen new --force --no-bip39-passphrase -o ~/solana-web3js-tests/test-keypair.json
   ```

3. **Fund the test keypair with devnet SOL**:
   ```bash
   solana airdrop 1 $(solana address -k ~/solana-web3js-tests/test-keypair.json) --url devnet
   ```

4. **Verify the balance**:
   ```bash
   solana balance -k ~/solana-web3js-tests/test-keypair.json --url devnet
   ```

The test suite will automatically use this keypair for integration tests against devnet.

## Project Structure

- `src/index.ts`: Main entry point (implemented)
- `src/solana-server.ts`: Core server implementation (implemented)
- `src/core/connection-manager.ts`: Solana connection management (implemented)
- `src/transport/`: Transport layer implementations
  - `src/transport/stdio.ts`: Standard I/O transport (implemented)
  - `src/transport/http.ts`: HTTP/SSE transport (implemented)
  - `src/transport/index.ts`: Transport exports (implemented)
- `src/tools/`: Tool implementations for Solana operations
  - `src/tools/accounts/`: Account management tools (implemented)
  - `src/tools/transactions/`: Transaction operations tools (implemented)
  - `src/tools/keys/`: Key management tools (implemented)
  - `src/tools/programs/`: Program development tools (implemented)
- `src/resources/`: Resource implementations for Solana data (planned)
- `src/prompts/`: Reusable prompts for common workflows (planned)
- `src/types/`: TypeScript type definitions
  - `src/types/solana.ts`: Solana-specific type definitions (partial implementation)
  - `src/types/tools.ts`: Tool input/output type definitions (planned)
  - `src/types/config.ts`: Configuration type definitions (planned)
- `src/utils/`: Utility functions and classes
  - `src/utils/errors.ts`: Error handling system (implemented)
  - `src/utils/logging.ts`: Logging system (implemented)

## Extending the Server

This server is designed to be extensible. To add new functionality:

1. Create a new tool in the appropriate file in the `tools` directory
2. Register the tool in `solana-server.ts`
3. Test the tool with both unit tests and integration tests

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT