@gala-chain/launchpad-mcp-server/README.md

MCP server for Gala Launchpad SDK with 41 tools - AI agents can interact with Gala Launchpad and learn SDK usage

# @gala-chain/launchpad-mcp-server

MCP (Model Context Protocol) server for Gala Launchpad SDK - Enables AI agents to interact with Gala Launchpad.

## 🚀 Features

- **41 AI-accessible tools** for complete Gala Launchpad integration
- **Type-safe** - Full TypeScript support with validated inputs
- **Production-ready** - Built on [@gala-chain/launchpad-sdk ](https://www.npmjs.com/package/@gala-chain/launchpad-sdk)
- **Easy setup** - Works with Claude Desktop and other MCP clients
- **Comprehensive** - Pool management, trading, balances, token creation, comments, transfers

## 📦 Installation

```bash
npm install -g @gala-chain/launchpad-mcp-server
```

## 🏁 Quick Start

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gala-launchpad": {
      "command": "npx",
      "args": ["-y", "@gala-chain/launchpad-mcp-server@latest"],
      "env": {
        "PRIVATE_KEY": "0x1234567890abcdef...",
        "ENVIRONMENT": "development"
      }
    }
  }
}
```

**Environment Variables:**
- `PRIVATE_KEY` (required) - Your Ethereum wallet private key
- `ENVIRONMENT` (optional) - `development` or `production` (default: development)
- `DEBUG` (optional) - `true` to enable debug logging
- `TIMEOUT` (optional) - Request timeout in milliseconds (default: 30000)

### Using with Claude Desktop

1. **Install**: `npm install -g @gala-chain/launchpad-mcp-server`
2. **Configure**: Add server to `claude_desktop_config.json` (see above)
3. **Restart Claude Desktop**
4. **Use tools**: Ask Claude to interact with Gala Launchpad!

## 🛠️ Available Tools (41 Total)

### Pool Management (8 tools)
- `gala_launchpad_fetch_pools` - Fetch token pools with filtering
- `gala_launchpad_fetch_pool_details` - Get detailed pool state
- `gala_launchpad_fetch_token_distribution` - Get holder distribution
- `gala_launchpad_fetch_token_badges` - Get achievement badges
- `gala_launchpad_fetch_volume_data` - Get OHLCV charting data
- `gala_launchpad_check_token_name` - Check name availability
- `gala_launchpad_check_token_symbol` - Check symbol availability
- `gala_launchpad_resolve_vault_address` - Get GalaChain vault address

### Trading Operations (8 tools)
- `gala_launchpad_calculate_buy_amount` - Calculate buy amounts
- `gala_launchpad_calculate_sell_amount` - Calculate sell amounts
- `gala_launchpad_buy_tokens` - Execute token purchase
- `gala_launchpad_sell_tokens` - Execute token sale
- `gala_launchpad_fetch_trades` - Get trade history
- `gala_launchpad_calculate_initial_buy` - Calculate initial buy
- `gala_launchpad_calculate_buy_amount_for_graduation` - Calculate cost to graduate pool
- `gala_launchpad_graduate_token` - One-step pool graduation

#### 🎓 Understanding Graduation Calculations

**CRITICAL:** The `amount` field in `gala_launchpad_calculate_buy_amount_for_graduation` represents **GALA cost**, NOT token quantity!

```javascript
// Example response
{
  "amount": "1594263.41948877",
  "transactionFee": "1594.26341949",
  "gasFee": "1"
}

// ❌ WRONG INTERPRETATION:
// "Need to buy 1,594,263 tokens"

// ✅ CORRECT INTERPRETATION:
// "Need to spend 1,594,263.42 GALA to buy all remaining tokens and graduate the pool"
```

**Amount Field Reference:**

| Tool | `amount` Field Represents | Example | Meaning |
|------|---------------------------|---------|---------|
| `calculate_buy_amount` | **Token quantity** received | "16843.758" | 16,843.76 tokens |
| `calculate_sell_amount` | **GALA amount** received | "125.50" | 125.50 GALA |
| `calculate_buy_amount_for_graduation` | **GALA cost** to graduate | "1594263.419" | 1,594,263.42 GALA |
| `calculate_initial_buy` | **Token quantity** from pre-buy | "3663321.363" | 3,663,321.36 tokens |

**Key Points:**
- Read the full number as-is - decimal point is NOT shifted
- Graduation amounts are typically in the hundreds of thousands to millions of GALA
- Always use `graduate_token` for convenience - it handles calculations internally
- Pool status changes from "Ongoing" to "Completed" upon successful graduation

### Balance & Portfolio (6 tools)
- `gala_launchpad_fetch_gala_balance` - Get GALA balance
- `gala_launchpad_fetch_token_balance` - Get token balance
- `gala_launchpad_fetch_tokens_held` - Get portfolio holdings
- `gala_launchpad_fetch_tokens_created` - Get created tokens
- `gala_launchpad_fetch_profile` - Get user profile
- `gala_launchpad_update_profile` - Update profile

### Token Creation (4 tools)
- `gala_launchpad_launch_token` - Create new token pool
- `gala_launchpad_upload_token_image` - Upload token image from filesystem
- `gala_launchpad_upload_profile_image` - Upload profile image from filesystem
- `gala_launchpad_fetch_launch_token_fee` - Get current GALA fee to launch a token

### Comments & Social (2 tools)
- `gala_launchpad_post_comment` - Post comment on token
- `gala_launchpad_fetch_comments` - Get token comments

### Token Transfers (2 tools)
- `gala_launchpad_transfer_gala` - Transfer GALA tokens
- `gala_launchpad_transfer_token` - Transfer launchpad tokens

### Utility Tools (2 tools)
- `gala_launchpad_get_url_by_token_name` - Generate frontend URL for a token
- `gala_launchpad_explain_sdk_usage` - Get SDK code examples and usage explanations

## 💡 Example Usage

Ask Claude (or your AI assistant):

> "Fetch the 10 most recent token pools on Gala Launchpad"

> "What's my GALA balance?"

> "Calculate how many tokens I'd get if I buy with 100 GALA on dragnrkti"

> "Buy 50 GALA worth of rocketri tokens with 5% slippage"

> "Show me all tokens I'm holding"

## 📚 SDK Usage Reference

The MCP server includes a built-in SDK documentation tool that provides complete, runnable code examples for using the SDK directly instead of through MCP tools. This is perfect for developers who want to integrate the SDK into their applications.

**Ask Claude for SDK code examples:**

> "Explain how to buy tokens using the SDK"

> "Show me the SDK code for selling tokens"

> "How do I use multiple wallets with the SDK?"

> "Show me all MCP tools and their SDK method equivalents"

**Available topics:**
- `buy-tokens` - Complete buying workflow
- `sell-tokens` - Complete selling workflow
- `pool-graduation` - Graduate bonding curve pools
- `fetch-pools` - Query pool data
- `balances` - Check GALA and token balances
- `token-creation` - Launch new tokens
- `multi-wallet` - Multi-wallet patterns
- `transfers` - Transfer tokens between wallets
- `error-handling` - Handle exceptions
- `installation` - Install and configure SDK
- `mcp-to-sdk-mapping` - Complete tool-to-method mapping

Each topic returns complete TypeScript code with explanations, making it easy to transition from MCP tools to direct SDK integration.

## 🔐 Multi-Wallet Support

All signing operations support an optional `privateKey` parameter for per-operation wallet overrides. This enables:
- Testing multi-wallet workflows
- Simulating different user behaviors
- Building multi-agent trading systems
- Operating multiple wallets from a single MCP server

### Tools Supporting privateKey Override

**Trading Operations:**
- `gala_launchpad_buy_tokens` - Buy tokens from different wallet
- `gala_launchpad_sell_tokens` - Sell tokens from different wallet

**Token Creation:**
- `gala_launchpad_launch_token` - Create token from different wallet
- `gala_launchpad_upload_token_image` - Upload image for token
- `gala_launchpad_upload_profile_image` - Upload profile image

**Transfer Operations:**
- `gala_launchpad_transfer_gala` - Transfer GALA from different wallet
- `gala_launchpad_transfer_token` - Transfer tokens from different wallet

**Social & Profile:**
- `gala_launchpad_post_comment` - Post comment from different wallet
- `gala_launchpad_update_profile` - Update profile for different wallet

### Example: Multi-Wallet Trading Scenario

Ask Claude:

> "Create a scenario where Buster's wallet buys and sells tokens:
> 1. Send Buster 1000 GALA from the main wallet
> 2. Have Buster buy 100 GALA worth of tinyevil tokens using his private key: 0x1234...
> 3. Have Buster sell 50 GALA worth back
> 4. Check both wallets' final balances"

Claude will use:
```javascript
// 1. Main wallet sends GALA to Buster
gala_launchpad_transfer_gala({
  recipientAddress: "0xBusterAddress...",
  amount: "1000"
  // No privateKey - uses main wallet
});

// 2. Buster buys tokens with his wallet
gala_launchpad_buy_tokens({
  tokenName: "tinyevil",
  amount: "100",
  type: "native",
  expectedAmount: "50000",
  slippageToleranceFactor: 0.05,
  privateKey: "0x1234..." // Buster's wallet
});

// 3. Buster sells tokens
gala_launchpad_sell_tokens({
  tokenName: "tinyevil",
  amount: "50",
  type: "native",
  expectedAmount: "48",
  slippageToleranceFactor: 0.05,
  privateKey: "0x1234..." // Buster's wallet
});
```

### Private Key Format Requirements

The `privateKey` parameter must be:
- **Format**: `'0x' + 64 hexadecimal characters`
- **Example**: `'0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'`
- **Invalid**: Raw hex without '0x', mnemonics, or addresses

### Security Considerations

When using privateKey overrides:
1. **Never expose private keys** in prompts or logs
2. **Use test wallets** for development and testing
3. **Limit fund amounts** in test wallets
4. **Monitor operations** when testing multi-wallet scenarios
5. **Validate addresses** before transfers

## 🔧 Development

### Local Development

```bash
# Clone repository
git clone https://gitlab.com/gala-games/defi/launchpad/sdk.git
cd launchpad-sdk/packages/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev
```

### Testing

```bash
npm test
```

## 📚 Documentation

- [MCP Tool Specification](../../packages/sdk/docs/MCP-TOOL-SPECIFICATION.md) - Complete tool reference
- [AI Agent Guide](../../packages/sdk/docs/AI-AGENT-GUIDE.md) - Integration patterns
- [SDK Documentation](../sdk/README.md) - Underlying SDK reference

## 🔐 Security

**Important Security Notes:**

1. **Private Keys** - Never commit private keys to version control
2. **Environment Variables** - Store credentials in `claude_desktop_config.json` securely
3. **Wallet Safety** - Use separate wallets for development and production
4. **Amount Limits** - Consider setting up trading limits for automated agents

## 🐛 Troubleshooting

### "SDK not initialized"
- Ensure `PRIVATE_KEY` is set in environment variables
- Check that private key format is valid (0x + 64 hex characters)

### "Tool not found"
- Restart Claude Desktop after configuration changes
- Verify server is listed in Claude Desktop settings

### "Connection failed"
- Check DEBUG=true logs for detailed error messages
- Verify network connectivity to Gala Launchpad backends

## 📄 License

MIT License - see [LICENSE](../../LICENSE) file for details.

## 🤝 Contributing

Contributions welcome! Please read [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

## 📞 Support

- **Issues**: [GitLab Issues](https://gitlab.com/gala-games/defi/launchpad/sdk/-/issues)
- **Documentation**: [Full Documentation](../../packages/sdk/docs/)
- **SDK Package**: [@gala-chain/launchpad-sdk](https://www.npmjs.com/package/@gala-chain/launchpad-sdk)

---

**Built with ❤️ for the Gala ecosystem**