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

package/docs/PROMPT-TOOL-MAPPING.md

@@ -1,352 +0,0 @@
-# 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

@@ -1,240 +0,0 @@
-# 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`