diff options
Diffstat (limited to 'mcp-servers/token-gated-mcp-server/.claude/commands')
6 files changed, 530 insertions, 0 deletions
diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/create-tool.md b/mcp-servers/token-gated-mcp-server/.claude/commands/create-tool.md new file mode 100644 index 0000000..d83e631 --- /dev/null +++ b/mcp-servers/token-gated-mcp-server/.claude/commands/create-tool.md @@ -0,0 +1,79 @@ +--- +allowed-tools: Write, Edit, Read +description: Create a new token-gated tool with proper protection +argument-hint: "<tool-name> <token-id> [tier]" +--- + +## Create Token-Gated Tool + +Create a new FastMCP tool with token protection using the Radius MCP SDK. + +Parameters: $ARGUMENTS + +## Tool Creation Steps + +1. **Parse Arguments** + - Extract tool name, token ID, and optional tier + - Validate token ID format + - Determine appropriate access pattern + +2. **Generate Tool Implementation** + +```typescript +server.addTool({ + name: '{tool_name}', + description: '{description} (requires token {token_id})', + parameters: z.object({ + // Define your parameters here + input: z.string().describe('Input data'), + options: z.object({ + format: z.enum(['json', 'text']).optional(), + verbose: z.boolean().optional() + }).optional(), + __evmauth: z.any().optional().describe('Authentication proof') + }), + handler: radius.protect({token_id}, async (args) => { + // Tool implementation + try { + // Process the input + const result = await process{ToolName}(args.input, args.options); + + // Return MCP-formatted response + return { + content: [{ + type: 'text', + text: JSON.stringify(result, null, 2) + }] + }; + } catch (error) { + throw new Error(`{tool_name} failed: ${error.message}`); + } + }) +}); +``` + +3. **Add to Appropriate Tier** + - Map to correct token tier + - Update TOOL_REQUIREMENTS mapping + - Document access requirements + +4. **Create Test Case** + - Unit test for the tool + - Auth flow test + - Error handling test + +5. **Update Documentation** + - Add to tool registry + - Document parameters + - Include usage examples + +## Generate Complete Tool + +Based on the arguments provided, create: + +1. Tool implementation file +2. Test file +3. Documentation update +4. Integration with existing server + +The tool should follow FastMCP best practices and properly integrate with the Radius MCP SDK for token protection. diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/debug-proof.md b/mcp-servers/token-gated-mcp-server/.claude/commands/debug-proof.md new file mode 100644 index 0000000..b953131 --- /dev/null +++ b/mcp-servers/token-gated-mcp-server/.claude/commands/debug-proof.md @@ -0,0 +1,97 @@ +--- +allowed-tools: Read, Bash, Grep, WebFetch +description: Debug proof verification issues and authentication errors +--- + +## Debug Proof Verification + +Analyze and debug authentication proof issues in your token-gated MCP server. + +## Debugging Process + +1. **Check Recent Errors** + - Search for EVMAUTH errors: !`grep -r "EVMAUTH" . --include="*.log" --include="*.ts" | tail -20` + - Find proof-related issues: !`grep -r "proof\|PROOF" . --include="*.log" | tail -20` + +2. **Validate Configuration** + + ```bash + # Check all required environment variables + !echo "=== Token Gate Configuration ===" + !echo "Contract Address: ${EVMAUTH_CONTRACT_ADDRESS:-NOT SET}" + !echo "Chain ID: ${EVMAUTH_CHAIN_ID:-NOT SET}" + !echo "RPC URL: ${EVMAUTH_RPC_URL:-NOT SET}" + !echo "Token ID: ${EVMAUTH_TOKEN_ID:-NOT SET}" + !echo "Debug Mode: ${DEBUG:-false}" + !echo "Environment: ${NODE_ENV:-development}" + ``` + +3. **Test RPC Connection** + + ```bash + # Verify RPC endpoint is accessible + !curl -s -X POST ${EVMAUTH_RPC_URL:-https://rpc.testnet.radiustech.xyz} \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' | jq '.' + ``` + +4. **Analyze Proof Structure** + Check for common proof issues: + - Missing __evmauth parameter + - Expired timestamp (> 30 seconds) + - Invalid signature format (not 0x + 130 hex chars) + - Chain ID mismatch + - Contract address mismatch + - Invalid nonce format + +5. **Debug Token Verification** + - Check if RPC calls are succeeding + - Verify token balance queries + - Test cache behavior + - Validate multi-token logic + +## Common Issues and Solutions + +### EVMAUTH_PROOF_MISSING + +- **Cause**: No __evmauth in request +- **Fix**: Ensure parameter is included in tool schema + +### PROOF_EXPIRED + +- **Cause**: Proof older than 30 seconds +- **Fix**: Request fresh proof from Radius MCP Server + +### CHAIN_MISMATCH + +- **Cause**: Proof for different chain +- **Fix**: Ensure SDK and proof use same chain ID (1223953 for testnet) + +### SIGNER_MISMATCH + +- **Cause**: Signature doesn't match wallet +- **Fix**: Verify signature recovery process + +### PAYMENT_REQUIRED + +- **Cause**: User lacks required tokens +- **Fix**: Use authenticate_and_purchase to obtain tokens + +## Generate Debug Report + +Create a comprehensive debug report including: + +1. Current configuration status +2. Recent error patterns +3. Proof validation results +4. Token verification status +5. Recommended fixes + +Enable debug mode temporarily if needed: + +```typescript +const radius = new RadiusMcpSdk({ + contractAddress: process.env.EVMAUTH_CONTRACT_ADDRESS, + debug: true // Temporary for debugging +}); +``` diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/deploy-local.md b/mcp-servers/token-gated-mcp-server/.claude/commands/deploy-local.md new file mode 100644 index 0000000..f865017 --- /dev/null +++ b/mcp-servers/token-gated-mcp-server/.claude/commands/deploy-local.md @@ -0,0 +1,93 @@ +--- +allowed-tools: Bash, Read, Write +description: Deploy token-gated MCP server locally with ngrok for testing +--- + +## Deploy Locally with ngrok + +Set up and deploy your token-gated MCP server locally with ngrok for testing with claude.ai. + +## Deployment Steps + +1. **Pre-deployment Checks** + - Verify all dependencies installed: !`npm list fastmcp @radiustechsystems/mcp-sdk zod 2>/dev/null | grep -E "fastmcp|radius|zod"` + - Check TypeScript compilation: !`npx tsc --noEmit` + - Validate environment configuration + +2. **Start the MCP Server** + + ```bash + # Start server in development mode + npm run dev + ``` + + Server should start on port 3000 (or configured PORT) + +3. **Set Up ngrok Tunnel** + + ```bash + # Install ngrok if needed + # brew install ngrok (macOS) + # or download from https://ngrok.com + + # Start ngrok tunnel + ngrok http 3000 + ``` + +4. **Configure claude.ai** + - Copy the HTTPS URL from ngrok (e.g., <https://abc123.ngrok.io>) + - In claude.ai: + 1. Click the 🔌 connection icon + 2. Add MCP server + 3. Enter URL: `https://abc123.ngrok.io/mcp` + 4. Test connection + +5. **Verify Token Protection** + - Try calling a protected tool + - Should receive EVMAUTH_PROOF_MISSING error + - Error should guide to authenticate_and_purchase + +## Testing Checklist + +- [ ] Server starts without errors +- [ ] ngrok tunnel established +- [ ] claude.ai can connect +- [ ] Tools appear in claude.ai +- [ ] Token protection working +- [ ] Error messages are helpful +- [ ] Authentication flow completes + +## Troubleshooting + +### Server Won't Start + +- Check port not already in use: !`lsof -i :3000` +- Verify dependencies installed +- Check for TypeScript errors + +### ngrok Issues + +- Ensure ngrok installed and authenticated +- Check firewall settings +- Try different port if 3000 blocked + +### claude.ai Connection Failed + +- Verify URL includes `/mcp` endpoint +- Check CORS settings in server +- Ensure server is running + +### Authentication Errors + +- Verify contract address configured +- Check chain ID matches (1223953) +- Ensure RPC URL accessible + +## Generate Deployment Summary + +Create a summary including: + +1. Server URL for claude.ai +2. Available tools and their token requirements +3. Test commands to verify functionality +4. Any warnings or issues detected diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/setup-token-gate.md b/mcp-servers/token-gated-mcp-server/.claude/commands/setup-token-gate.md new file mode 100644 index 0000000..48e747f --- /dev/null +++ b/mcp-servers/token-gated-mcp-server/.claude/commands/setup-token-gate.md @@ -0,0 +1,80 @@ +--- +allowed-tools: "Write, Edit, Bash(npm install*), Bash(npm init*), Read" +description: Set up a complete token-gated MCP server with FastMCP and Radius SDK +argument-hint: "[basic|full|testnet]" +--- + +## Setup Token-Gated MCP Server + +Create a complete token-gated MCP server project with the specified configuration level: + +- **basic**: Minimal setup with one protected tool +- **full**: Complete setup with multiple tiers and examples +- **testnet**: Configured for Radius Testnet deployment + +Configuration: $ARGUMENTS + +## Tasks + +1. **Initialize Project** + - Create package.json with required dependencies + - Set up TypeScript configuration + - Create directory structure + +2. **Install Dependencies** + + ```json + { + "dependencies": { + "fastmcp": "^3.0.0", + "@radiustechsystems/mcp-sdk": "^1.0.0", + "zod": "^3.22.0", + "viem": "^2.31.0" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "tsx": "^4.0.0", + "typescript": "^5.0.0", + "prettier": "^3.0.0" + } + } + ``` + +3. **Create Server Implementation** + - Main server file with token protection + - Example tools with different token requirements + - Proper error handling and responses + +4. **Environment Configuration** + - Create .env.example with required variables + - Set up for Radius Testnet (Chain ID: 1223953) + - Configure debug settings + +5. **Create Helper Scripts** + - Development script with hot reload + - Build script for production + - Test script for auth flow validation + +6. **Documentation** + - README with setup instructions + - Token tier documentation + - Testing guide with ngrok + +## Implementation Structure + +```text +project/ +├── src/ +│ ├── index.ts # Main server file +│ ├── tools/ # Tool implementations +│ ├── config/ # Configuration +│ └── types/ # Type definitions +├── .env.example # Environment template +├── package.json # Dependencies +├── tsconfig.json # TypeScript config +├── README.md # Documentation +└── .claude/ # Claude Code config + └── CLAUDE.md # Project context +``` + +Based on the configuration level ($ARGUMENTS), create the appropriate setup with working examples and clear documentation. diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/test-auth.md b/mcp-servers/token-gated-mcp-server/.claude/commands/test-auth.md new file mode 100644 index 0000000..d9336a9 --- /dev/null +++ b/mcp-servers/token-gated-mcp-server/.claude/commands/test-auth.md @@ -0,0 +1,68 @@ +--- +allowed-tools: Bash, Read, Write, TodoWrite +description: Test the complete authentication flow end-to-end +argument-hint: "[tool-name] [token-id]" +--- + +## Test Authentication Flow + +Test the complete token-gated authentication flow for the specified tool. + +Tool: $ARGUMENTS + +## Testing Steps + +1. **Check Current Configuration** + - Verify environment variables: !`echo "Contract: $EVMAUTH_CONTRACT_ADDRESS, Chain: $EVMAUTH_CHAIN_ID"` + - Check RPC connection: !`curl -s -X POST $EVMAUTH_RPC_URL -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' | jq -r '.result'` + +2. **Start MCP Server** + - Run the server if not already running + - Note the port and endpoint + +3. **Simulate Tool Call Without Auth** + - Call the protected tool without __evmauth + - Verify EVMAUTH_PROOF_MISSING error + - Check error includes requiredTokens + +4. **Simulate Authentication** + - Mock authenticate_and_purchase response + - Generate sample proof structure + - Verify proof format is correct + +5. **Test With Valid Proof** + - Call tool with __evmauth parameter + - Verify successful execution or PAYMENT_REQUIRED + +6. **Test Error Scenarios** + - Expired proof (> 30 seconds old) + - Wrong chain ID + - Invalid signature format + - Missing required fields + +## Create Test Script + +Generate a test script that validates: + +- Token protection is properly configured +- Error messages are AI-friendly +- Authentication flow works end-to-end +- Caching behaves correctly + +## Expected Results + +✅ **Success Criteria:** + +- Tool rejects calls without auth +- Error messages guide to authenticate_and_purchase +- Valid proofs are accepted +- Token ownership is properly verified + +❌ **Common Failures:** + +- Chain ID mismatch +- Contract address not configured +- RPC connection issues +- Debug mode enabled in production + +Generate comprehensive test results and recommendations. diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/validate-config.md b/mcp-servers/token-gated-mcp-server/.claude/commands/validate-config.md new file mode 100644 index 0000000..e9208b1 --- /dev/null +++ b/mcp-servers/token-gated-mcp-server/.claude/commands/validate-config.md @@ -0,0 +1,113 @@ +--- +allowed-tools: Read, Bash, Grep +description: Validate token-gating configuration and environment setup +--- + +## Validate Token-Gating Configuration + +Comprehensive validation of your token-gated MCP server configuration. + +## Validation Checks + +### 1. Environment Variables + +```bash +# Check required variables +!echo "=== Environment Configuration ===" +!echo "Contract Address: ${EVMAUTH_CONTRACT_ADDRESS:-❌ NOT SET}" +!echo "Chain ID: ${EVMAUTH_CHAIN_ID:-❌ NOT SET}" +!echo "RPC URL: ${EVMAUTH_RPC_URL:-❌ NOT SET}" +!echo "Token ID: ${EVMAUTH_TOKEN_ID:-❌ NOT SET}" +!echo "Debug Mode: ${DEBUG:-✅ false (good for production)}" +!echo "Node Environment: ${NODE_ENV:-⚠️ NOT SET}" +``` + +### 2. Contract Address Validation + +- Check format: 0x followed by 40 hexadecimal characters +- Verify it's a valid Ethereum address +- For testnet: Should be `0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96` + +### 3. Chain ID Validation + +- Should be numeric +- For Radius Testnet: 1223953 +- Must match the network your contract is deployed on + +### 4. RPC Connection Test + +```bash +# Test RPC endpoint +!curl -s -X POST ${EVMAUTH_RPC_URL:-https://rpc.testnet.radiustech.xyz} \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' | \ + jq -r 'if .result then "✅ RPC Connected - Chain: \(.result)" else "❌ RPC Connection Failed" end' +``` + +### 5. Dependencies Check + +```bash +# Verify required packages +!echo "=== Required Dependencies ===" +!npm list fastmcp 2>/dev/null | grep fastmcp || echo "❌ fastmcp not installed" +!npm list @radiustechsystems/mcp-sdk 2>/dev/null | grep radius || echo "❌ Radius SDK not installed" +!npm list zod 2>/dev/null | grep zod || echo "❌ zod not installed" +!npm list viem 2>/dev/null | grep viem || echo "❌ viem not installed" +``` + +### 6. TypeScript Configuration + +```bash +# Check TypeScript setup +![ -f "tsconfig.json" ] && echo "✅ tsconfig.json exists" || echo "❌ tsconfig.json missing" +!npx tsc --version 2>/dev/null || echo "❌ TypeScript not installed" +``` + +### 7. Server File Analysis + +- Check for RadiusMcpSdk initialization +- Verify radius.protect() usage +- Ensure __evmauth parameter in schemas +- Validate error handling + +### 8. Security Checks + +```bash +# Security validation +!echo "=== Security Checks ===" +!grep -r "debug.*true" --include="*.ts" --include="*.js" . 2>/dev/null && echo "⚠️ Debug mode enabled in code" || echo "✅ No hardcoded debug mode" +!grep -r "0x[a-fA-F0-9]\{64\}" --include="*.ts" --include="*.js" . 2>/dev/null && echo "⚠️ Possible private key in code" || echo "✅ No private keys detected" +![ -f ".env" ] && [ ! -f ".gitignore" ] && echo "⚠️ .env exists but no .gitignore" || echo "✅ Environment files protected" +``` + +## Validation Report + +Generate a comprehensive report with: + +### ✅ Passed Checks + +- List all successful validations + +### ⚠️ Warnings + +- Non-critical issues to address + +### ❌ Failed Checks + +- Critical issues that must be fixed + +### 📋 Recommendations + +1. Configuration improvements +2. Security enhancements +3. Performance optimizations +4. Best practices to follow + +## Next Steps + +Based on validation results, provide: + +1. Immediate fixes required +2. Configuration commands to run +3. Files to update +4. Testing recommendations |