test-manual.md•5.42 kB
# Manual Testing Guide for Aptos MCP Server
This guide shows you how to manually test your Aptos MCP server using different methods.
## Prerequisites
1. **Build the project first:**
```bash
npm run build
```
2. **Set up environment variables:**
```bash
export APTOS_MCP_PRIVATE_KEY="0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
export APTOS_MCP_NETWORK="testnet"
```
⚠️ **Note:** Use a real private key for actual testing. The above is just an example.
## Method 1: Automated Test Script
Run the comprehensive test script:
```bash
node test-mcp.js
```
This will test all major functionality automatically.
## Method 2: Manual JSON-RPC Testing
### Step 1: Start the server
```bash
node build/index.js
```
You should see: `Aptos Blockchain MCP Server running on stdio`
### Step 2: Send JSON-RPC requests
In another terminal, you can send requests using `echo` and pipes:
#### List all available tools:
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node build/index.js
```
#### Create a new account:
```bash
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_account","arguments":{}}}' | node build/index.js
```
#### Get account balance:
```bash
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_apt_balance","arguments":{"account_address":"0x1"}}}' | node build/index.js
```
#### Get account info:
```bash
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_account_info","arguments":{"account_address":"0x1"}}}' | node build/index.js
```
## Method 3: Interactive Testing with Node.js
Create a simple interactive test:
```javascript
// Save as interactive-test.js
import { spawn } from 'child_process';
const server = spawn('node', ['build/index.js'], {
env: {
...process.env,
APTOS_MCP_PRIVATE_KEY: 'your-private-key-here',
APTOS_MCP_NETWORK: 'testnet'
},
stdio: ['pipe', 'pipe', 'inherit']
});
// Send a request
const request = {
jsonrpc: '2.0',
id: 1,
method: 'tools/list'
};
server.stdin.write(JSON.stringify(request) + '\n');
server.stdout.on('data', (data) => {
console.log('Response:', data.toString());
server.kill();
});
```
## Method 4: Testing with Real Aptos Operations
### Step 1: Get a real private key
1. Install Aptos CLI: https://aptos.dev/tools/aptos-cli/install-cli/
2. Create a new account: `aptos init`
3. Use the private key from `.aptos/config.yaml`
### Step 2: Fund your account
```bash
# Using the MCP server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"fund_account","arguments":{"account_address":"YOUR_ADDRESS","amount":1}}}' | APTOS_MCP_PRIVATE_KEY="YOUR_PRIVATE_KEY" node build/index.js
```
### Step 3: Test real operations
```bash
# Check balance
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_apt_balance","arguments":{"account_address":"YOUR_ADDRESS"}}}' | APTOS_MCP_PRIVATE_KEY="YOUR_PRIVATE_KEY" node build/index.js
# Transfer APT (create another account first)
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"transfer_apt","arguments":{"recipient_address":"RECIPIENT_ADDRESS","amount":"0.1"}}}' | APTOS_MCP_PRIVATE_KEY="YOUR_PRIVATE_KEY" node build/index.js
```
## Method 5: Integration with MCP Clients
### Claude Desktop Integration
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"aptos-mcp": {
"command": "node",
"args": ["/path/to/your/aptos_mcp/build/index.js"],
"env": {
"APTOS_MCP_PRIVATE_KEY": "your-private-key-here",
"APTOS_MCP_NETWORK": "testnet"
}
}
}
}
```
Then restart Claude Desktop and you can use natural language to interact with Aptos!
## Expected Test Results
### ✅ Successful Responses:
- **List Tools**: Should return 9 tools (create_account, get_account_info, etc.)
- **Create Account**: Should return new account details with address and keys
- **Get Balance**: Should return balance (may be 0 for new accounts)
- **Fund Account**: Should return transaction hash (testnet only)
### ⚠️ Expected Errors:
- **Invalid Account**: "Account does not exist" for non-existent addresses
- **Insufficient Balance**: When trying to transfer more than available
- **Invalid Parameters**: When required parameters are missing
## Troubleshooting
### Common Issues:
1. **"Environment validation failed"**
- Make sure `APTOS_MCP_PRIVATE_KEY` is set
- Ensure private key is in correct hex format (starts with 0x)
2. **"Failed to get account info"**
- Account might not exist on-chain yet
- Try funding the account first
3. **"Faucet service unavailable"**
- Testnet faucet might be down
- Try again later or use alternative faucet
4. **Build errors**
- Run `npm install` to ensure dependencies are installed
- Check TypeScript compilation with `npm run build`
## Security Notes
- Never use real private keys in test scripts committed to version control
- Always test on testnet first before mainnet
- Keep your private keys secure and never share them
## Next Steps
Once basic testing works:
1. Test with real Aptos accounts and transactions
2. Integrate with your preferred MCP client
3. Extend functionality with additional tools as needed
4. Consider adding more comprehensive error handling for production use