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

package/src/tools/pools/fetchAllPriceHistory.ts

@@ -0,0 +1,119 @@
+/**
+ * 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)
+- Either tokenName OR tokenId is required (not both)
+
+**Token Identification:**
+- Use \`tokenName\` for convenience (e.g., "demonkpop") - automatically resolved to full token ID
+- Use \`tokenId\` for direct specification (e.g., "Token|Unit|DKP|eth:...")
+- Provide exactly ONE of these parameters
+
+**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: {
+      tokenName: {
+        type: 'string',
+        description:
+          'Simple token name for convenience (e.g., "demonkpop", "shoewars") - automatically resolves to full token ID. Use this OR tokenId, not both.',
+      },
+      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). Use this OR tokenName, not both.',
+      },
+      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: [],
+  },
+
+  handler: withErrorHandling(async (sdk, args) => {
+    // Convert string dates to Date objects if provided
+    const options: any = {
+      sortOrder: args.sortOrder,
+    };
+
+    // Support both tokenName and tokenId (mutual exclusivity validation happens in SDK)
+    if (args.tokenName) {
+      options.tokenName = args.tokenName;
+    } else {
+      options.tokenId = args.tokenId;
+    }
+
+    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', 'popular'],
+        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,124 @@
+/**
+ * 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)
+- Either tokenName OR tokenId is required (not both)
+
+**Token Identification:**
+- Use \`tokenName\` for convenience (e.g., "demonkpop") - automatically resolved to full token ID
+- Use \`tokenId\` for direct specification (e.g., "Token|Unit|DKP|eth:...")
+- Provide exactly ONE of these parameters
+
+**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: {
+      tokenName: {
+        type: 'string',
+        description:
+          'Simple token name for convenience (e.g., "demonkpop", "shoewars") - automatically resolves to full token ID. Use this OR tokenId, not both.',
+      },
+      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). Use this OR tokenName, not both.',
+      },
+      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: [],
+  },
+
+  handler: withErrorHandling(async (sdk, args) => {
+    // Convert string dates to Date objects if provided
+    const options: any = {
+      sortOrder: args.sortOrder,
+      page: args.page,
+      limit: args.limit,
+    };
+
+    // Support both tokenName and tokenId (mutual exclusivity validation happens in SDK)
+    if (args.tokenName) {
+      options.tokenName = args.tokenName;
+    } else {
+      options.tokenId = args.tokenId;
+    }
+
+    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);
+  }),
+};