@gala-chain/launchpad-mcp-server 1.14.0 → 1.14.2

package/src/tools/pools/fetchAllPools.ts

@@ -0,0 +1,47 @@
+/**
+ * Fetch All Pools Tool
+ *
+ * Convenience tool that fetches all available pools with automatic pagination.
+ * Equivalent to calling fetchPools with limit: 0.
+ */
+
+import type { MCPTool } from '../../types/mcp.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+
+export const fetchAllPoolsTool: MCPTool = {
+  name: 'gala_launchpad_fetch_all_pools',
+  description: 'Fetch all available pools with automatic pagination. No page/limit parameters needed - returns ALL pools matching filters.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      search: {
+        type: 'string',
+        minLength: 1,
+        maxLength: 100,
+        description: 'Optional search query (fuzzy match filter)',
+      },
+      tokenName: {
+        type: 'string',
+        minLength: 3,
+        maxLength: 20,
+        pattern: '^[a-zA-Z0-9]{3,20}$',
+        description: 'Optional token name (exact match filter)',
+      },
+      type: {
+        type: 'string',
+        enum: ['recent', 'popular'],
+        description: 'Type of pools to fetch (default: recent)',
+      },
+    },
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const result = await sdk.fetchAllPools({
+      ...(args.search && { search: args.search }),
+      ...(args.tokenName && { tokenName: args.tokenName }),
+      ...(args.type && { type: args.type }),
+    });
+
+    return formatSuccess(result);
+  }),
+};

package/src/tools/pools/fetchAllPriceHistory.ts

@@ -0,0 +1,103 @@
+/**
+ * Fetch All Price History Tool
+ *
+ * Queries all historical token price data from DEX Backend API with automatic pagination.
+ * Uses the /price-oracle/fetch-price endpoint for complete price history retrieval.
+ */
+
+import type { MCPTool } from '../../types/mcp.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+
+export const fetchAllPriceHistoryTool: MCPTool = {
+  name: 'gala_launchpad_fetch_all_price_history',
+  description: `Fetch all historical price snapshots for DEX tokens from the DEX Backend API with automatic pagination.
+
+**Endpoint:** \`/price-oracle/fetch-price\`
+
+**Requirements:**
+- DEX Backend API must be configured (dexBackendBaseUrl in SDK config)
+- Node.js environment only (not available in browser)
+- Token parameter is required
+
+**Use Cases:**
+- Complete historical price analysis and charting
+- Full price trend identification over time periods
+- Comprehensive volatility analysis
+- Data export for external analytics
+
+**Performance:** API-based queries with automatic pagination (max 100 items per page, combined into single result).`,
+
+  inputSchema: {
+    type: 'object',
+    properties: {
+      tokenId: {
+        oneOf: [
+          {
+            type: 'string',
+            description:
+              'Pipe-delimited format: "collection|category|type|additionalKey" (e.g., "Token|Unit|GUSDC|eth:...")',
+          },
+          {
+            type: 'object',
+            properties: {
+              collection: {
+                type: 'string',
+                description: 'Token collection (e.g., "Token")',
+              },
+              category: {
+                type: 'string',
+                description: 'Token category (e.g., "Unit")',
+              },
+              type: {
+                type: 'string',
+                description: 'Token type (e.g., "GUSDC")',
+              },
+              additionalKey: {
+                type: 'string',
+                description: 'Additional key (e.g., "eth:0x...")',
+              },
+            },
+            required: ['collection', 'category', 'type', 'additionalKey'],
+            description: 'TokenClassKey object format',
+          },
+        ],
+        description: 'Token identifier (string or TokenClassKey object)',
+      },
+      from: {
+        type: 'string',
+        format: 'date-time',
+        description: 'Start date for filtering (ISO 8601 format, defaults to 30 days ago)',
+      },
+      to: {
+        type: 'string',
+        format: 'date-time',
+        description: 'End date for filtering (ISO 8601 format, defaults to now)',
+      },
+      sortOrder: {
+        type: 'string',
+        enum: ['ASC', 'DESC'],
+        description: 'Sort order for results (default: DESC for newest-first)',
+      },
+    },
+    required: ['tokenId'],
+  },
+
+  handler: withErrorHandling(async (sdk, args) => {
+    // Convert string dates to Date objects if provided
+    const options: any = {
+      tokenId: args.tokenId,
+      sortOrder: args.sortOrder,
+    };
+
+    if (args.from) {
+      options.from = new Date(args.from);
+    }
+    if (args.to) {
+      options.to = new Date(args.to);
+    }
+
+    const result = await sdk.fetchAllPriceHistory(options);
+    return formatSuccess(result);
+  }),
+};

package/src/tools/pools/fetchPoolDetails.ts

@@ -0,0 +1,27 @@
+/**
+ * Fetch Pool Details Tool
+ */
+
+import type { MCPTool } from '../../types/mcp.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+
+export const fetchPoolDetailsTool: MCPTool = {
+  name: 'gala_launchpad_fetch_pool_details',
+  description: 'Get detailed pool state from GalaChain bonding curve',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      tokenName: {
+        type: 'string',
+        pattern: '^[a-z0-9_-]{2,20}$',
+        description: 'Token name',
+      },
+    },
+    required: ['tokenName'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const result = await sdk.fetchPoolDetails(args.tokenName);
+    return formatSuccess(result);
+  }),
+};

package/src/tools/pools/fetchPoolDetailsForCalculation.ts

@@ -0,0 +1,22 @@
+/**
+ * Fetch Pool Details for Calculation Tool (73% code reduction via factory pattern)
+ */
+
+import { createSimpleTokenFetchTool } from '../../utils/tool-factory.js';
+
+export const fetchPoolDetailsForCalculationTool = createSimpleTokenFetchTool({
+  name: 'gala_launchpad_fetch_pool_details_for_calculation',
+  description: `Get optimized pool details for local bonding curve calculations.
+
+Returns only essential calculation parameters:
+- currentSupply: Current token supply (computed with full precision)
+- remainingTokens: Tokens available for purchase
+- maxSupply: Maximum token supply
+- reverseBondingCurveMaxFeeFactor: Maximum reverse bonding curve fee (normalized to number)
+- reverseBondingCurveMinFeeFactor: Minimum reverse bonding curve fee (normalized to number)
+- reverseBondingCurveNetFeeFactor: Net fee factor (max - min, for convenience)
+
+This is more efficient than fetchPoolDetails as it returns only fields needed for calculations.
+Perfect for use with calculateBuyAmountLocal and calculateSellAmountLocal.`,
+  handler: (sdk, tokenName) => sdk.fetchPoolDetailsForCalculation(tokenName),
+});

package/src/tools/pools/fetchPools.ts

@@ -0,0 +1,47 @@
+/**
+ * Fetch Pools Tool
+ */
+
+import type { MCPTool } from '../../types/mcp.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+
+export const fetchPoolsTool: MCPTool = {
+  name: 'gala_launchpad_fetch_pools',
+  description: 'Fetch token pools from Gala Launchpad with filtering and pagination',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      type: {
+        type: 'string',
+        enum: ['recent', 'trending', 'user'],
+        description: 'Type of pools to fetch (default: recent)',
+      },
+      creatorAddress: {
+        type: 'string',
+        pattern: '^(0x[a-fA-F0-9]{40}|eth\\|[a-fA-F0-9]{40})$',
+        description: 'Filter by creator address (optional)',
+      },
+      page: {
+        type: 'number',
+        minimum: 1,
+        description: 'Page number (default: 1)',
+      },
+      limit: {
+        type: 'number',
+        minimum: 1,
+        maximum: 100,
+        description: 'Results per page (default: 20)',
+      },
+    },
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const result = await sdk.fetchPools({
+      type: args.type || 'recent',
+      page: args.page || 1,
+      limit: args.limit || 20,
+    });
+
+    return formatSuccess(result);
+  }),
+};

package/src/tools/pools/fetchPriceHistory.ts

@@ -0,0 +1,108 @@
+/**
+ * Fetch Price History Tool
+ *
+ * Queries historical token price data from DEX Backend API.
+ * Uses the /price-oracle/fetch-price endpoint for paginated price history retrieval.
+ */
+
+import type { MCPTool } from '../../types/mcp.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+import { PAGE_SCHEMA, createLimitSchema } from '../../schemas/common-schemas.js';
+
+export const fetchPriceHistoryTool: MCPTool = {
+  name: 'gala_launchpad_fetch_price_history',
+  description: `Fetch historical price snapshots for DEX tokens from the DEX Backend API.
+
+**Endpoint:** \`/price-oracle/fetch-price\`
+
+**Requirements:**
+- DEX Backend API must be configured (dexBackendBaseUrl in SDK config)
+- Node.js environment only (not available in browser)
+- Token parameter is required
+
+**Use Cases:**
+- Historical price analysis and charting
+- Price trend identification
+- Volatility analysis over time periods
+- Data export for external analytics
+
+**Performance:** API-based queries with pagination support (max 50 items per page).`,
+
+  inputSchema: {
+    type: 'object',
+    properties: {
+      tokenId: {
+        oneOf: [
+          {
+            type: 'string',
+            description:
+              'Pipe-delimited format: "collection|category|type|additionalKey" (e.g., "Token|Unit|GUSDC|eth:...")',
+          },
+          {
+            type: 'object',
+            properties: {
+              collection: {
+                type: 'string',
+                description: 'Token collection (e.g., "Token")',
+              },
+              category: {
+                type: 'string',
+                description: 'Token category (e.g., "Unit")',
+              },
+              type: {
+                type: 'string',
+                description: 'Token type (e.g., "GUSDC")',
+              },
+              additionalKey: {
+                type: 'string',
+                description: 'Additional key (e.g., "eth:0x...")',
+              },
+            },
+            required: ['collection', 'category', 'type', 'additionalKey'],
+            description: 'TokenClassKey object format',
+          },
+        ],
+        description: 'Token identifier (string or TokenClassKey object)',
+      },
+      from: {
+        type: 'string',
+        format: 'date-time',
+        description: 'Start date for filtering (ISO 8601 format, defaults to 30 days ago)',
+      },
+      to: {
+        type: 'string',
+        format: 'date-time',
+        description: 'End date for filtering (ISO 8601 format, defaults to now)',
+      },
+      sortOrder: {
+        type: 'string',
+        enum: ['ASC', 'DESC'],
+        description: 'Sort order for results (default: DESC for newest-first)',
+      },
+      page: PAGE_SCHEMA,
+      limit: createLimitSchema('priceHistory', 10),
+    },
+    required: ['tokenId'],
+  },
+
+  handler: withErrorHandling(async (sdk, args) => {
+    // Convert string dates to Date objects if provided
+    const options: any = {
+      tokenId: args.tokenId,
+      sortOrder: args.sortOrder,
+      page: args.page,
+      limit: args.limit,
+    };
+
+    if (args.from) {
+      options.from = new Date(args.from);
+    }
+    if (args.to) {
+      options.to = new Date(args.to);
+    }
+
+    const result = await sdk.fetchPriceHistory(options);
+    return formatSuccess(result);
+  }),
+};

package/src/tools/pools/fetchTokenDetails.ts

@@ -0,0 +1,77 @@
+/**
+ * Fetch Token Details Tool
+ *
+ * Queries the DEX API platform endpoint to retrieve comprehensive token metadata
+ * including image, decimals, description, verification status, network information,
+ * and trading capabilities.
+ */
+
+import type { MCPTool } from '../../types/mcp.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+
+export const fetchTokenDetailsTool: MCPTool = {
+  name: 'gala_launchpad_fetch_token_details',
+  description: `Fetch comprehensive token details from DEX API platform
+
+**Endpoint:** \`/v1/tokens?tokenclasskeys=...\`
+
+**Requirements:**
+- DEX API platform must be configured (dexApiHttp client)
+- Token identifier required in flexible format (string or object)
+
+**Use Cases:**
+- Retrieve complete token metadata and information
+- Verify token specifications (decimals, symbol, description)
+- Check verification status and trading capabilities
+- Access token image and network information
+- Analyze token details before trading
+
+**Flexible Token Identification:**
+Supports both pipe-delimited string and object formats for maximum flexibility.`,
+
+  inputSchema: {
+    type: 'object',
+    properties: {
+      tokenId: {
+        oneOf: [
+          {
+            type: 'string',
+            description:
+              'Pipe-delimited format: "collection|category|type|additionalKey" (e.g., "Token|Unit|GUSDC|eth:0x...")',
+          },
+          {
+            type: 'object',
+            properties: {
+              collection: {
+                type: 'string',
+                description: 'Token collection (e.g., "Token")',
+              },
+              category: {
+                type: 'string',
+                description: 'Token category (e.g., "Unit")',
+              },
+              type: {
+                type: 'string',
+                description: 'Token type (e.g., "GUSDC")',
+              },
+              additionalKey: {
+                type: 'string',
+                description: 'Additional key (e.g., "eth:0x...")',
+              },
+            },
+            required: ['collection', 'category', 'type', 'additionalKey'],
+            description: 'TokenClassKey object format',
+          },
+        ],
+        description: 'Token identifier in flexible format (string or object)',
+      },
+    },
+    required: ['tokenId'],
+  },
+
+  handler: withErrorHandling(async (sdk, args) => {
+    const result = await sdk.fetchTokenDetails(args.tokenId);
+    return formatSuccess(result);
+  }),
+};

package/src/tools/pools/index.ts

@@ -0,0 +1,246 @@
+/**
+ * Pool Management Tools
+ */
+
+import { POOL_TYPES } from '@gala-chain/launchpad-sdk';
+import type { MCPTool } from '../../types/mcp.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+import {
+  TOKEN_NAME_SCHEMA,
+  TOKEN_SYMBOL_SCHEMA,
+  ADDRESS_SCHEMA,
+  PAGE_SCHEMA,
+  createLimitSchema,
+  CALCULATION_MODE_SCHEMA,
+  CURRENT_SUPPLY_SCHEMA,
+} from '../../schemas/common-schemas.js';
+import { fetchPoolDetailsForCalculationTool } from './fetchPoolDetailsForCalculation.js';
+import { fetchAllPoolsTool } from './fetchAllPools.js';
+import { fetchPriceHistoryTool } from './fetchPriceHistory.js';
+import { fetchAllPriceHistoryTool } from './fetchAllPriceHistory.js';
+import { fetchTokenDetailsTool } from './fetchTokenDetails.js';
+import {
+  createSimpleTokenFetchTool,
+  createBooleanCheckTool,
+  createResolutionTool,
+  createNoParamTool,
+} from '../../utils/tool-factory.js';
+import { resolutionToSeconds, dateToUnixTimestamp, DEFAULT_VOLUME_RESOLUTION } from '../../utils/default-values.js';
+
+// 1. Fetch Pools
+export const fetchPoolsTool: MCPTool = {
+  name: 'gala_launchpad_fetch_pools',
+  description: 'Fetch token pools from Gala Launchpad with filtering and pagination',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      type: {
+        type: 'string',
+        enum: Object.values(POOL_TYPES),
+        description: 'Type of pools to fetch (default: recent)',
+      },
+      creatorAddress: {
+        ...ADDRESS_SCHEMA,
+        description: 'Filter by creator address (optional)',
+      },
+      page: PAGE_SCHEMA,
+      limit: createLimitSchema('pool', 20),
+    },
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const result = await sdk.fetchPools({
+      type: args.type || 'recent',
+      page: args.page || 1,
+      limit: args.limit || 20,
+    });
+    return formatSuccess(result);
+  }),
+};
+
+// 2. Fetch Pool Details (73% code reduction via factory pattern)
+export const fetchPoolDetailsTool = createSimpleTokenFetchTool({
+  name: 'gala_launchpad_fetch_pool_details',
+  description: 'Get detailed pool state from GalaChain bonding curve',
+  handler: (sdk, tokenName) => sdk.fetchPoolDetails(tokenName),
+});
+
+// 3. Fetch Token Distribution (73% code reduction via factory pattern)
+export const fetchTokenDistributionTool = createSimpleTokenFetchTool({
+  name: 'gala_launchpad_fetch_token_distribution',
+  description: 'Get holder distribution and supply metrics',
+  handler: (sdk, tokenName) => sdk.fetchTokenDistribution(tokenName),
+});
+
+// 4. Fetch Token Badges (73% code reduction via factory pattern)
+export const fetchTokenBadgesTool = createSimpleTokenFetchTool({
+  name: 'gala_launchpad_fetch_token_badges',
+  description: 'Get achievement badges for volume and engagement',
+  handler: (sdk, tokenName) => sdk.fetchTokenBadges(tokenName),
+});
+
+// 5. Fetch Volume Data (using centralized default values utilities)
+export const fetchVolumeDataTool: MCPTool = {
+  name: 'gala_launchpad_fetch_volume_data',
+  description: 'Get OHLCV (candlestick) data for charting',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      tokenName: TOKEN_NAME_SCHEMA,
+      from: {
+        type: 'string',
+        format: 'date-time',
+        description: 'Start date (ISO 8601)',
+      },
+      to: {
+        type: 'string',
+        format: 'date-time',
+        description: 'End date (ISO 8601)',
+      },
+      resolution: {
+        type: 'string',
+        enum: ['1m', '5m', '15m', '1h', '4h', '1d'],
+        description: 'Time resolution (default: 1h)',
+      },
+    },
+    required: ['tokenName'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const result = await sdk.fetchVolumeData({
+      tokenName: args.tokenName,
+      from: dateToUnixTimestamp(args.from),
+      to: dateToUnixTimestamp(args.to),
+      resolution: resolutionToSeconds(args.resolution, DEFAULT_VOLUME_RESOLUTION),
+    });
+    return formatSuccess(result);
+  }),
+};
+
+// 6. Fetch Token Spot Price (General DEX Tokens)
+export const fetchTokenSpotPriceTool: MCPTool = {
+  name: 'gala_launchpad_fetch_token_spot_price',
+  description: 'Fetch USD spot price for DEX tokens (GALA, SILK, MUSIC, etc.)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      symbols: {
+        oneOf: [
+          { type: 'string' },
+          {
+            type: 'array',
+            items: { type: 'string' },
+            minItems: 1
+          }
+        ],
+        description: 'Single symbol string or array of symbols (e.g., "GALA" or ["GALA", "SILK", "MUSIC"])',
+      },
+    },
+    required: ['symbols'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const result = await sdk.fetchTokenSpotPrice(args.symbols);
+    return formatSuccess(result);
+  }),
+};
+
+// 7. Fetch GALA Spot Price (45% code reduction via factory pattern)
+export const fetchGalaSpotPriceTool = createNoParamTool({
+  name: 'gala_launchpad_fetch_gala_spot_price',
+  description: 'Fetch current GALA USD spot price (convenience method)',
+  handler: (sdk) => sdk.fetchGalaSpotPrice(),
+});
+
+// 8. Fetch Launchpad Token Spot Price
+export const fetchLaunchpadTokenSpotPriceTool: MCPTool = {
+  name: 'gala_launchpad_fetch_launchpad_token_spot_price',
+  description: `Fetch USD spot price for a launchpad token by name.
+
+Performance optimization: Provide currentSupply to avoid fetching pool details twice.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      tokenName: {
+        ...TOKEN_NAME_SCHEMA,
+        description: 'Token name (e.g., "dragnrkti", "rocketri", "unicornri")',
+      },
+      calculateAmountMode: CALCULATION_MODE_SCHEMA,
+      currentSupply: CURRENT_SUPPLY_SCHEMA,
+    },
+    required: ['tokenName'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    // Build options object only if mode or supply provided
+    const options = args.calculateAmountMode || args.currentSupply
+      ? {
+          tokenName: args.tokenName,
+          calculateAmountMode: args.calculateAmountMode,
+          currentSupply: args.currentSupply,
+        }
+      : args.tokenName;
+
+    const result = await sdk.fetchLaunchpadTokenSpotPrice(options);
+    return formatSuccess(result);
+  }),
+};
+
+// 9. Check Token Name (60% code reduction via factory pattern)
+export const checkTokenNameTool = createBooleanCheckTool({
+  name: 'gala_launchpad_check_token_name',
+  description: 'Check if token name is available',
+  paramName: 'tokenName',
+  paramSchema: TOKEN_NAME_SCHEMA,
+  handler: (sdk, tokenName) => sdk.isTokenNameAvailable(tokenName),
+  messages: {
+    true: 'Token name is available',
+    false: 'Token name is already taken',
+  },
+});
+
+// 10. Check Token Symbol (60% code reduction via factory pattern)
+export const checkTokenSymbolTool = createBooleanCheckTool({
+  name: 'gala_launchpad_check_token_symbol',
+  description: 'Check if token symbol is available',
+  paramName: 'symbol',
+  paramSchema: TOKEN_SYMBOL_SCHEMA,
+  handler: (sdk, symbol) => sdk.isTokenSymbolAvailable(symbol),
+  messages: {
+    true: 'Token symbol is available',
+    false: 'Token symbol is already taken',
+  },
+});
+
+// 11. Resolve Vault Address (73% code reduction via factory pattern)
+export const resolveVaultAddressTool = createResolutionTool({
+  name: 'gala_launchpad_resolve_vault_address',
+  description: 'Get GalaChain vault address for a token (useful for debugging)',
+  resolver: (sdk, tokenName) => sdk.resolveVaultAddress(tokenName),
+  resultKey: 'vaultAddress',
+});
+
+// 12. Resolve Token Class Key (73% code reduction via factory pattern)
+export const resolveTokenClassKeyTool = createResolutionTool({
+  name: 'gala_launchpad_resolve_token_class_key',
+  description: 'Get GalaChain TokenClassKey for a launchpad token (useful for direct GalaChain operations)',
+  resolver: (sdk, tokenName) => sdk.resolveTokenClassKey(tokenName),
+  resultKey: 'tokenClassKey',
+});
+
+export const poolTools: MCPTool[] = [
+  fetchPoolsTool,
+  fetchAllPoolsTool,
+  fetchPoolDetailsTool,
+  fetchPoolDetailsForCalculationTool,
+  fetchTokenDetailsTool,
+  fetchTokenDistributionTool,
+  fetchTokenBadgesTool,
+  fetchVolumeDataTool,
+  fetchTokenSpotPriceTool,
+  fetchGalaSpotPriceTool,
+  fetchLaunchpadTokenSpotPriceTool,
+  fetchPriceHistoryTool,
+  fetchAllPriceHistoryTool,
+  checkTokenNameTool,
+  checkTokenSymbolTool,
+  resolveVaultAddressTool,
+  resolveTokenClassKeyTool,
+];