DEPLOYMENT.md•6.67 kB
# 🚀 Deploying Aptos MCP to Smithery.ai
This guide walks you through deploying your Aptos MCP server to Smithery.ai, making it available to AI applications worldwide.
## 📋 Prerequisites
Before deploying, ensure you have:
- ✅ **GitHub Account** - Your code must be in a GitHub repository
- ✅ **Built Project** - Run `npm run build` to create the `build/` directory
- ✅ **Working MCP Server** - Test locally with `node test-mcp.js`
- ✅ **Smithery.yaml** - Configuration file (already created)
## 🔧 Pre-Deployment Checklist
### 1. Verify Project Structure
```
aptos_mcp/
├── build/ # ✅ Compiled JavaScript
├── src/ # ✅ TypeScript source
├── smithery.yaml # ✅ Smithery configuration
├── package.json # ✅ Updated with proper metadata
├── README.md # ✅ Documentation
├── LICENSE # ✅ MIT license
└── .gitignore # ✅ Excludes node_modules, etc.
```
### 2. Test Locally
```bash
# Run the test suite
node test-mcp.js
# Should show: "🎉 All tests passed!"
```
### 3. Build for Production
```bash
npm run build
```
## 📤 Step-by-Step Deployment
### Step 1: Create GitHub Repository
1. **Create a new repository** on GitHub:
- Name: `aptos-mcp` (or your preferred name)
- Description: "MCP server for Aptos blockchain"
- Public repository (required for Smithery)
2. **Push your code**:
```bash
git init
git add .
git commit -m "Initial commit: Aptos MCP server"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/aptos-mcp.git
git push -u origin main
```
### Step 2: Register on Smithery.ai
1. **Visit** [smithery.ai](https://smithery.ai)
2. **Sign up/Login** with your GitHub account
3. **Grant permissions** for Smithery to access your repositories
### Step 3: Add Your MCP Server
1. **Navigate to** "New Server" or "Add Server"
2. **Select your repository**: `YOUR_USERNAME/aptos-mcp`
3. **Smithery will automatically detect** the `smithery.yaml` file
4. **Fill in server details**:
- **Name**: `Aptos Blockchain MCP`
- **Description**: `MCP server for Aptos blockchain operations - create accounts, transfer APT, check balances, and query transactions`
- **Tags**: `aptos`, `blockchain`, `web3`, `cryptocurrency`
### Step 4: Configure Deployment
1. **Go to the Deployments tab** on your server page
2. **Click "Deploy"** - Smithery will:
- Clone your repository
- Install dependencies (`npm install`)
- Build the project (`npm run build`)
- Deploy the server
3. **Wait for deployment** (usually 2-5 minutes)
4. **Check deployment status** - should show "✅ Deployed"
### Step 5: Test Deployment
1. **Use the Smithery interface** to test your server
2. **Try the tools**:
- `create_account` - Should create a new Aptos account
- `get_apt_balance` - Should check balance for address `0x1`
- `get_account_info` - Should get account information
## ⚙️ Configuration Schema
Your deployed server will accept these configuration parameters:
### Required
- **`aptosMcpPrivateKey`** - Aptos private key (hex format with 0x prefix)
### Optional
- **`aptosMcpNetwork`** - Network (`testnet` or `mainnet`, default: `testnet`)
- **`aptosMcpNodeUrl`** - Custom node URL (optional)
- **`aptosMcpFaucetUrl`** - Custom faucet URL (optional)
### Example Configuration
```json
{
"aptosMcpPrivateKey": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"aptosMcpNetwork": "testnet"
}
```
## 🔗 Using Your Deployed Server
### In Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"aptos-mcp": {
"command": "smithery",
"args": ["@your-username/aptos-mcp"],
"env": {
"SMITHERY_CONFIG": "{\"aptosMcpPrivateKey\":\"0x...\",\"aptosMcpNetwork\":\"testnet\"}"
}
}
}
}
```
### Via Smithery Web Interface
1. Visit your server page on Smithery
2. Click "Connect"
3. Enter your configuration
4. Start using the tools!
## 🔄 Updating Your Deployment
### For Code Changes:
1. **Push changes** to your GitHub repository
2. **Go to Deployments tab** on Smithery
3. **Click "Redeploy"**
### For Configuration Changes:
1. **Update `smithery.yaml`** in your repository
2. **Push changes** to GitHub
3. **Redeploy** on Smithery
## 🛠️ Troubleshooting
### Common Issues:
**❌ "Build Failed"**
- Check that `npm run build` works locally
- Ensure all dependencies are in `package.json`
- Verify TypeScript compiles without errors
**❌ "Server Won't Start"**
- Check that `smithery.yaml` syntax is correct
- Ensure `build/index.js` exists and is executable
- Verify environment variables are properly configured
**❌ "Tools Not Working"**
- Check that private key is valid hex format
- Ensure network (testnet/mainnet) is accessible
- Test tools locally first
**❌ "Configuration Errors"**
- Verify `configSchema` in `smithery.yaml` matches your needs
- Check that required fields are marked as required
- Test with example configuration
### Debug Steps:
1. **Test locally first**:
```bash
node test-mcp.js
```
2. **Check build output**:
```bash
npm run build
ls -la build/
```
3. **Validate smithery.yaml**:
```bash
# Check YAML syntax
cat smithery.yaml
```
4. **Check Smithery logs** in the deployment interface
## 📊 Monitoring Your Server
### Smithery Dashboard
- **Usage statistics** - See how many people use your server
- **Error logs** - Monitor for issues
- **Performance metrics** - Check response times
### Server Health
- **Test tools regularly** to ensure they work
- **Monitor Aptos network status** for connectivity issues
- **Update dependencies** periodically
## 🎉 Success!
Once deployed, your Aptos MCP server will be:
- ✅ **Publicly available** on Smithery.ai
- ✅ **Discoverable** by AI applications
- ✅ **Automatically updated** when you push changes
- ✅ **Monitored** for uptime and performance
Your server will have a URL like: `https://smithery.ai/server/@your-username/aptos-mcp`
## 🔗 Next Steps
1. **Share your server** with the community
2. **Add more tools** (NFTs, custom coins, etc.)
3. **Improve documentation** based on user feedback
4. **Monitor usage** and optimize performance
5. **Consider mainnet support** for production use
## 📞 Support
- **Smithery Discord**: [Join here](https://discord.gg/Afd38S5p9A)
- **Smithery Docs**: [smithery.ai/docs](https://smithery.ai/docs)
- **GitHub Issues**: Create issues in your repository
- **Aptos Discord**: [Join here](https://discord.gg/aptoslabs)
Happy deploying! 🚀