@gala-chain/launchpad-mcp-server 1.23.1 → 1.24.1

package/docs/PROMPT-TOOL-MAPPING.md

@@ -0,0 +1,352 @@
+# Prompt-Tool Mapping Reference
+
+**Auto-generated documentation mapping MCP prompts (slash commands) to the tools they use.**
+
+This reference helps AI agents understand which tools are invoked by each prompt and how they work together.
+
+## Overview
+
+- **Total Prompts**: 14 slash commands
+- **Total Tools**: 47 MCP tools
+- **Categories**: Trading, Portfolio, Analysis
+
+---
+
+## Trading Prompts
+
+### `/analyze-token {tokenName}`
+
+**Description**: Comprehensive token analysis including pool details, price metrics, and market data
+
+**Tools Used**:
+- `gala_launchpad_fetch_pool_details` - Get pool state and supply metrics
+- `gala_launchpad_fetch_launchpad_token_spot_price` - Calculate USD spot price
+- `gala_launchpad_fetch_token_distribution` - Get holder distribution
+- `gala_launchpad_fetch_token_badges` - Get achievement badges
+
+**Workflow**:
+1. Fetches pool details (supply, status, fees)
+2. Calculates current USD spot price
+3. Analyzes holder distribution
+4. Retrieves achievement badges
+5. Compiles comprehensive analysis report
+
+---
+
+### `/buy-tokens {tokenName} {galaAmount}`
+
+**Description**: Execute token purchase with automatic slippage protection
+
+**Tools Used**:
+- `gala_launchpad_fetch_pool_details` - Verify token exists and is tradeable
+- `gala_launchpad_calculate_buy_amount` - Calculate expected output and fees
+- `gala_launchpad_buy_tokens` - Execute purchase transaction
+- `gala_launchpad_fetch_trades` - Verify transaction completion
+
+**Workflow**:
+1. Validates token pool exists
+2. Calculates exact amount with `type: 'native'` (spending GALA)
+3. Extracts `result.amount` for `expectedAmount`
+4. Executes buy with 1% slippage tolerance
+5. Confirms transaction success
+
+**Critical Pattern**:
+```typescript
+// ✅ CORRECT - Use calculated amount as expectedAmount
+const calc = await calculateBuyAmount({ tokenName, amount: '100', type: 'native' });
+await buy({ tokenName, amount: '100', expectedAmount: calc.amount, ... });
+
+// ❌ WRONG - Using input amount as expectedAmount
+await buy({ tokenName, amount: '100', expectedAmount: '100', ... }); // FAILS!
+```
+
+---
+
+### `/sell-tokens {tokenName} {tokenAmount}`
+
+**Description**: Execute token sale with slippage protection
+
+**Tools Used**:
+- `gala_launchpad_fetch_token_balance` - Verify sufficient token balance
+- `gala_launchpad_calculate_sell_amount` - Calculate expected GALA output
+- `gala_launchpad_sell_tokens` - Execute sale transaction
+- `gala_launchpad_fetch_trades` - Verify transaction completion
+
+**Workflow**:
+1. Checks user has enough tokens to sell
+2. Calculates expected GALA with `type: 'exact'` (selling exact tokens)
+3. Extracts `result.amount` for `expectedAmount`
+4. Executes sell with 1% slippage tolerance
+5. Confirms transaction success
+
+---
+
+### `/graduate-token {tokenName}`
+
+**Description**: Graduate bonding curve pool to full DEX trading
+
+**Tools Used**:
+- `gala_launchpad_fetch_pool_details` - Check if already graduated
+- `gala_launchpad_calculate_buy_amount_for_graduation` - Calculate remaining cost
+- `gala_launchpad_graduate_token` - Execute graduation (convenience method)
+- `gala_launchpad_fetch_pool_details` - Verify graduation success
+
+**Workflow**:
+1. Validates pool is not already graduated
+2. Calculates GALA needed to buy remaining tokens
+3. Executes graduation transaction (auto-calculates internally)
+4. Verifies pool status changed to "Completed"
+
+**Note**: `graduateToken()` is a convenience method that combines `calculateBuyAmountForGraduation()` + `buy()` internally.
+
+---
+
+## Portfolio Prompts
+
+### `/check-balance {tokenName?}`
+
+**Description**: Check GALA and token balances for authenticated wallet
+
+**Tools Used**:
+- `gala_launchpad_fetch_gala_balance` - Get GALA balance
+- `gala_launchpad_fetch_token_balance` - Get specific token balance (if tokenName provided)
+- `gala_launchpad_fetch_tokens_held` - Get all held tokens (if no tokenName)
+
+**Workflow**:
+1. Always fetches GALA balance
+2. If `tokenName` provided: fetches that specific token balance
+3. If no `tokenName`: fetches all tokens held by user
+4. Displays formatted balance report
+
+---
+
+### `/portfolio`
+
+**Description**: Complete portfolio overview with holdings, creations, and values
+
+**Tools Used**:
+- `gala_launchpad_fetch_gala_balance` - Get GALA balance
+- `gala_launchpad_fetch_tokens_held` - Get all tokens held
+- `gala_launchpad_fetch_tokens_created` - Get tokens created by user
+- `gala_launchpad_fetch_gala_spot_price` - Get GALA USD price
+- `gala_launchpad_fetch_launchpad_token_spot_price` - Calculate token USD values
+
+**Workflow**:
+1. Fetches GALA balance and USD value
+2. Lists all tokens held with balances
+3. Lists all tokens created by user
+4. Calculates total portfolio value in USD
+5. Generates comprehensive portfolio report
+
+---
+
+### `/profile {address?}`
+
+**Description**: View user profile with activity statistics
+
+**Tools Used**:
+- `gala_launchpad_fetch_profile` - Get profile data
+- `gala_launchpad_fetch_tokens_created` - Count created tokens
+- `gala_launchpad_fetch_trades` - Get recent trade history
+
+**Workflow**:
+1. Fetches user profile (name, image, wallet)
+2. Counts tokens created
+3. Retrieves recent trades
+4. Displays profile summary with stats
+
+---
+
+### `/trade-history {tokenName?} {limit?}`
+
+**Description**: View trade history with optional filtering
+
+**Tools Used**:
+- `gala_launchpad_fetch_trades` - Query trades with filters
+
+**Workflow**:
+1. Applies filters (tokenName, limit, sortOrder)
+2. Fetches paginated trade history
+3. Formats trade data (type, amounts, timestamps)
+4. Displays chronological trade list
+
+---
+
+## Analysis Prompts
+
+### `/discover-pools {type?} {limit?}`
+
+**Description**: Discover trending and recent token pools
+
+**Tools Used**:
+- `gala_launchpad_fetch_pools` - Query pools with filters
+
+**Workflow**:
+1. Applies pool type filter (recent, popular, trending)
+2. Sets pagination limits
+3. Fetches pool list
+4. Displays formatted pool data
+
+---
+
+### `/token-metrics {tokenName}`
+
+**Description**: Detailed token metrics and performance data
+
+**Tools Used**:
+- `gala_launchpad_fetch_pool_details` - Get pool state
+- `gala_launchpad_fetch_token_distribution` - Get holder distribution
+- `gala_launchpad_fetch_volume_data` - Get OHLCV data for charting
+- `gala_launchpad_fetch_token_badges` - Get achievement badges
+
+**Workflow**:
+1. Fetches complete pool details
+2. Analyzes token distribution metrics
+3. Retrieves historical volume data
+4. Collects achievement badges
+5. Compiles comprehensive metrics report
+
+---
+
+### `/market-overview {resolution?}`
+
+**Description**: Market-wide overview with top pools and activity
+
+**Tools Used**:
+- `gala_launchpad_fetch_pools` - Get popular and trending pools
+- `gala_launchpad_fetch_gala_spot_price` - Get current GALA price
+- `gala_launchpad_fetch_volume_data` - Get market-wide volume (if supported)
+
+**Workflow**:
+1. Fetches top pools by various metrics
+2. Gets current GALA price
+3. Calculates aggregate market metrics
+4. Displays market summary
+
+---
+
+## Tool Categories Reference
+
+### Pool Management Tools (13 tools)
+- `gala_launchpad_fetch_pools`
+- `gala_launchpad_fetch_pool_details`
+- `gala_launchpad_fetch_pool_details_for_calculation`
+- `gala_launchpad_fetch_token_distribution`
+- `gala_launchpad_fetch_token_badges`
+- `gala_launchpad_fetch_volume_data`
+- `gala_launchpad_fetch_token_spot_price`
+- `gala_launchpad_fetch_gala_spot_price`
+- `gala_launchpad_fetch_launchpad_token_spot_price`
+- `gala_launchpad_check_token_name`
+- `gala_launchpad_check_token_symbol`
+- `gala_launchpad_resolve_vault_address`
+- `gala_launchpad_resolve_token_class_key`
+
+### Trading Tools (9 tools)
+- `gala_launchpad_calculate_buy_amount`
+- `gala_launchpad_calculate_sell_amount`
+- `gala_launchpad_buy_tokens`
+- `gala_launchpad_sell_tokens`
+- `gala_launchpad_fetch_trades`
+- `gala_launchpad_calculate_initial_buy`
+- `gala_launchpad_get_bundler_transaction_result`
+- `gala_launchpad_calculate_buy_amount_for_graduation`
+- `gala_launchpad_graduate_token`
+
+### Balance Tools (6 tools)
+- `gala_launchpad_fetch_gala_balance`
+- `gala_launchpad_fetch_token_balance`
+- `gala_launchpad_fetch_tokens_held`
+- `gala_launchpad_fetch_tokens_created`
+- `gala_launchpad_fetch_profile`
+- `gala_launchpad_update_profile`
+
+### Creation Tools (4 tools)
+- `gala_launchpad_launch_token`
+- `gala_launchpad_upload_token_image`
+- `gala_launchpad_upload_profile_image`
+- `gala_launchpad_fetch_launch_token_fee`
+
+### Social Tools (2 tools)
+- `gala_launchpad_post_comment`
+- `gala_launchpad_fetch_comments`
+
+### Transfer Tools (2 tools)
+- `gala_launchpad_transfer_gala`
+- `gala_launchpad_transfer_token`
+
+### Utility Tools (6 tools)
+- `gala_launchpad_create_wallet`
+- `gala_launchpad_get_address`
+- `gala_launchpad_get_ethereum_address`
+- `gala_launchpad_get_config`
+- `gala_launchpad_get_url_by_token_name`
+- `gala_launchpad_explain_sdk_usage`
+
+---
+
+## Common Patterns
+
+### Pattern 1: Token Analysis
+Most prompts start with pool details:
+```
+fetchPoolDetails() → analyze data → fetch related metrics
+```
+
+### Pattern 2: Trading Workflow
+All trading operations follow this pattern:
+```
+calculate*Amount() → extract result.amount → execute trade → verify completion
+```
+
+### Pattern 3: Portfolio Queries
+Balance queries combine multiple data sources:
+```
+fetch balances + fetch prices → calculate values → format report
+```
+
+### Pattern 4: Validation First
+Creation and trading prompts validate before execution:
+```
+check availability/balance → calculate → execute → verify
+```
+
+---
+
+## AI Agent Best Practices
+
+### ✅ DO
+1. **Always extract `result.amount`** from calculate functions for `expectedAmount`
+2. **Check token exists** before trading (use `fetchPoolDetails`)
+3. **Verify balances** before selling (use `fetchTokenBalance`)
+4. **Use slippage protection** (1% is standard)
+5. **Confirm transactions** with `fetchTrades` after execution
+
+### ❌ DON'T
+1. **Never use input amount as `expectedAmount`** - use calculated `result.amount`
+2. **Don't skip validation** - always check token exists and user has balance
+3. **Don't ignore slippage** - transactions may fail without proper tolerance
+4. **Don't assume success** - always verify transaction completion
+5. **Don't hardcode limits** - use MCP_CONSTRAINTS constants
+
+---
+
+## Quick Reference Table
+
+| Prompt | Primary Tool | Secondary Tools | Category |
+|--------|-------------|-----------------|----------|
+| `/analyze-token` | `fetch_pool_details` | `fetch_*_price`, `fetch_distribution` | Analysis |
+| `/buy-tokens` | `buy_tokens` | `calculate_buy_amount`, `fetch_trades` | Trading |
+| `/sell-tokens` | `sell_tokens` | `calculate_sell_amount`, `fetch_balance` | Trading |
+| `/graduate-token` | `graduate_token` | `fetch_pool_details`, `calculate_*` | Trading |
+| `/check-balance` | `fetch_gala_balance` | `fetch_token_balance`, `fetch_tokens_held` | Portfolio |
+| `/portfolio` | `fetch_tokens_held` | `fetch_gala_balance`, `fetch_*_price` | Portfolio |
+| `/profile` | `fetch_profile` | `fetch_tokens_created`, `fetch_trades` | Portfolio |
+| `/trade-history` | `fetch_trades` | - | Portfolio |
+| `/discover-pools` | `fetch_pools` | - | Analysis |
+| `/token-metrics` | `fetch_pool_details` | `fetch_distribution`, `fetch_volume_data` | Analysis |
+| `/market-overview` | `fetch_pools` | `fetch_gala_spot_price` | Analysis |
+
+---
+
+**Note**: This mapping is auto-generated and reflects the current v1.5.0 implementation. Tool names and relationships may evolve in future versions.

package/docs/examples/default-values-pattern.md

@@ -0,0 +1,240 @@
+# Default Values Utilities - Usage Examples
+
+Demonstrates how to use `default-values.ts` to eliminate magic numbers and ensure consistency across tool implementations.
+
+**See**: `src/utils/default-values.ts`
+
+---
+
+## Example 1: Pagination Defaults (BEFORE vs AFTER)
+
+### ❌ BEFORE: Magic numbers scattered throughout code
+
+```typescript
+function fetchPoolsHandlerOLD(args: any) {
+  const params = {
+    type: args.type || 'recent',
+    page: args.page || 1, // Magic number!
+    limit: args.limit || 20, // Magic number!
+  };
+  return params;
+}
+```
+
+### ✅ AFTER: Using centralized defaults
+
+```typescript
+function fetchPoolsHandlerNEW(args: any) {
+  const params = applyPaginationDefaults(args);
+  return {
+    type: args.type || 'recent',
+    ...params,
+  };
+}
+```
+
+---
+
+## Example 2: Operation-Specific Pagination (BEFORE vs AFTER)
+
+### ❌ BEFORE: Inconsistent default limits across tools
+
+```typescript
+function fetchTradesHandlerOLD(args: any) {
+  return {
+    page: args.page || 1,
+    limit: args.limit || 20, // Is this the right limit for trades?
+  };
+}
+
+function fetchPoolsHandlerOLD2(args: any) {
+  return {
+    page: args.page || 1,
+    limit: args.limit || 100, // Different limit for pools!
+  };
+}
+```
+
+### ✅ AFTER: Operation-specific defaults ensure consistency
+
+```typescript
+function fetchTradesHandlerNEW(args: any) {
+  return applyOperationPaginationDefaults(args, 'trade');
+  // Automatically uses correct limit (20) for trade operations
+}
+
+function fetchPoolsHandlerNEW2(args: any) {
+  return applyOperationPaginationDefaults(args, 'pool');
+  // Automatically uses correct limit (20 - not 100) for pool operations
+}
+```
+
+---
+
+## Example 3: Trading Slippage Defaults (BEFORE vs AFTER)
+
+### ❌ BEFORE: Magic number slippage values
+
+```typescript
+function buyTokensHandlerOLD(args: any) {
+  const slippageTolerance = args.slippageToleranceFactor || 0.01; // Magic!
+  const rbcFeeSlippage = args.maxAcceptableReverseBondingCurveFeeSlippageFactor || 0.01; // Magic!
+
+  return { slippageTolerance, rbcFeeSlippage };
+}
+```
+
+### ✅ AFTER: Using centralized slippage defaults
+
+```typescript
+function buyTokensHandlerNEW(args: any) {
+  const params = applySlippageDefaults(args);
+  return params;
+  // Automatically includes both slippage values with correct defaults
+}
+```
+
+---
+
+## Example 4: Volume Resolution (BEFORE vs AFTER)
+
+### ❌ BEFORE: Duplicate resolution mapping in every tool
+
+```typescript
+function fetchVolumeDataHandlerOLD(args: any) {
+  const resolutionMap: Record<string, number> = {
+    '1m': 60,
+    '5m': 300,
+    '15m': 900,
+    '1h': 3600, // Duplicate mapping!
+    '4h': 14400,
+    '1d': 86400,
+  };
+  const resolutionSeconds = resolutionMap[args.resolution || '1h'];
+
+  return { resolution: resolutionSeconds };
+}
+```
+
+### ✅ AFTER: Using centralized resolution mapping
+
+```typescript
+function fetchVolumeDataHandlerNEW(args: any) {
+  const resolutionSeconds = resolutionToSeconds(args.resolution, DEFAULT_VOLUME_RESOLUTION);
+
+  return { resolution: resolutionSeconds };
+}
+```
+
+---
+
+## Example 5: Date Conversion (BEFORE vs AFTER)
+
+### ❌ BEFORE: Duplicate date conversion logic
+
+```typescript
+function fetchVolumeDataHandlerOLD2(args: any) {
+  const fromTimestamp = args.from
+    ? Math.floor(new Date(args.from).getTime() / 1000) // Duplicate logic!
+    : undefined;
+  const toTimestamp = args.to
+    ? Math.floor(new Date(args.to).getTime() / 1000) // Duplicate logic!
+    : undefined;
+
+  return { from: fromTimestamp, to: toTimestamp };
+}
+```
+
+### ✅ AFTER: Using centralized date conversion
+
+```typescript
+function fetchVolumeDataHandlerNEW2(args: any) {
+  return {
+    from: dateToUnixTimestamp(args.from),
+    to: dateToUnixTimestamp(args.to),
+  };
+}
+```
+
+---
+
+## Example 6: Complete Tool Handler (BEFORE vs AFTER)
+
+### ❌ BEFORE: All magic numbers and duplicate logic (15 lines)
+
+```typescript
+async function completeToolHandlerOLD(sdk: any, args: any) {
+  const page = args.page || 1;
+  const limit = args.limit || 20;
+  const slippageTolerance = args.slippageToleranceFactor || 0.01;
+  const rbcFeeSlippage = args.maxAcceptableReverseBondingCurveFeeSlippageFactor || 0.01;
+
+  const params = {
+    page,
+    limit,
+    slippageTolerance,
+    rbcFeeSlippage,
+  };
+
+  return sdk.someMethod(params);
+}
+```
+
+### ✅ AFTER: Clean, centralized defaults (6 lines - 60% reduction)
+
+```typescript
+async function completeToolHandlerNEW(sdk: any, args: any) {
+  const params = {
+    ...applyPaginationDefaults(args),
+    ...applySlippageDefaults(args),
+  };
+
+  return sdk.someMethod(params);
+}
+```
+
+---
+
+## Summary Statistics
+
+### IMPACT ANALYSIS:
+
+**Benefits:**
+- ✅ Eliminates ~50+ instances of magic numbers (1, 20, 0.01, etc.)
+- ✅ Ensures consistency: All tools use same default values
+- ✅ Single source of truth: Change defaults in one place
+- ✅ Type safety: TypeScript ensures correct parameter types
+- ✅ Reduces code: 40-60% fewer lines in tool handlers
+
+**Before:**
+- 15 tools with `page: args.page || 1`
+- 15 tools with `limit: args.limit || 20`
+- 9 tools with slippage defaults
+- 2 tools with resolution mapping
+- Total: ~150 lines of duplicate default handling
+
+**After:**
+- All defaults centralized in default-values.ts
+- Tools use utility functions
+- Total saved: ~100 lines of duplicate code
+- Improved maintainability: Change defaults once, applies everywhere
+
+---
+
+## USAGE GUIDELINES:
+
+### 1. Pagination defaults:
+- Use `applyPaginationDefaults(args)` for generic pagination
+- Use `applyOperationPaginationDefaults(args, 'pool')` for operation-specific
+
+### 2. Trading defaults:
+- Use `applySlippageDefaults(args)` for buy/sell tools
+- Automatically applies both slippage tolerance and RBC fee slippage
+
+### 3. Volume data:
+- Use `resolutionToSeconds(args.resolution)` for resolution conversion
+- Use `dateToUnixTimestamp(args.from)` for date conversion
+
+### 4. Constants:
+- Import constants from `defaultValues` object for direct access
+- Example: `DEFAULT_PAGINATION`, `DEFAULT_SLIPPAGE_TOLERANCE`