@gala-chain/launchpad-mcp-server 1.22.3 → 1.23.0

package/src/utils/default-values.ts

@@ -0,0 +1,208 @@
+/**
+ * Default Value Utilities
+ *
+ * Centralized default values for tool parameters to eliminate magic numbers
+ * and ensure consistency across 47 MCP tools.
+ *
+ * @see Phase 2.2 of refactoring plan
+ */
+
+import { MCP_CONSTRAINTS } from './constraints.js';
+
+// =============================================================================
+// Pagination Defaults
+// =============================================================================
+
+/**
+ * Default pagination configuration
+ */
+export const DEFAULT_PAGINATION = {
+  page: 1,
+  limit: 20,
+} as const;
+
+/**
+ * Operation-specific default limits
+ */
+export const DEFAULT_LIMITS = {
+  trade: 20,
+  user: 20,
+  pool: 20,
+  comment: 20,
+} as const;
+
+/**
+ * Maximum limits per operation type (from MCP_CONSTRAINTS)
+ */
+export const MAX_LIMITS = {
+  trade: MCP_CONSTRAINTS.TRADE_LIMIT, // 20
+  user: MCP_CONSTRAINTS.USER_LIMIT, // 20
+  pool: MCP_CONSTRAINTS.POOL_LIMIT, // 100
+  comment: MCP_CONSTRAINTS.COMMENT_LIMIT, // 50
+} as const;
+
+// =============================================================================
+// Trading Defaults
+// =============================================================================
+
+/**
+ * Default slippage tolerance (1%)
+ */
+export const DEFAULT_SLIPPAGE_TOLERANCE = 0.01;
+
+/**
+ * Default reverse bonding curve fee slippage tolerance (1%)
+ */
+export const DEFAULT_RBC_FEE_SLIPPAGE = 0.01;
+
+/**
+ * Default pool type for fetchPools
+ */
+export const DEFAULT_POOL_TYPE = 'recent';
+
+/**
+ * Default sort order
+ */
+export const DEFAULT_SORT_ORDER = 'DESC';
+
+// =============================================================================
+// Volume Data Defaults
+// =============================================================================
+
+/**
+ * Default resolution for volume data (1 hour)
+ */
+export const DEFAULT_VOLUME_RESOLUTION = '1h';
+
+/**
+ * Resolution mapping (string to seconds)
+ */
+export const RESOLUTION_MAP: Record<string, number> = {
+  '1m': 60,
+  '5m': 300,
+  '15m': 900,
+  '1h': 3600,
+  '4h': 14400,
+  '1d': 86400,
+} as const;
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Applies default pagination values to args object
+ *
+ * @example
+ * ```typescript
+ * const params = applyPaginationDefaults(args);
+ * // { page: 1, limit: 20, ...otherArgs }
+ * ```
+ */
+export function applyPaginationDefaults<T extends Record<string, any>>(
+  args: T,
+  defaults: { page?: number; limit?: number } = DEFAULT_PAGINATION
+): T & { page: number; limit: number } {
+  return {
+    ...args,
+    page: args.page ?? defaults.page ?? DEFAULT_PAGINATION.page,
+    limit: args.limit ?? defaults.limit ?? DEFAULT_PAGINATION.limit,
+  };
+}
+
+/**
+ * Applies operation-specific pagination defaults
+ *
+ * @example
+ * ```typescript
+ * const params = applyOperationPaginationDefaults(args, 'pool');
+ * // Uses default limit of 20 for pool operations
+ * ```
+ */
+export function applyOperationPaginationDefaults<T extends Record<string, any>>(
+  args: T,
+  operationType: keyof typeof DEFAULT_LIMITS
+): T & { page: number; limit: number } {
+  return applyPaginationDefaults(args, {
+    page: DEFAULT_PAGINATION.page,
+    limit: DEFAULT_LIMITS[operationType],
+  });
+}
+
+/**
+ * Applies default slippage values to trading args
+ *
+ * @example
+ * ```typescript
+ * const params = applySlippageDefaults(args);
+ * // { slippageToleranceFactor: 0.01, maxAcceptableReverseBondingCurveFeeSlippageFactor: 0.01, ...args }
+ * ```
+ */
+export function applySlippageDefaults<T extends Record<string, any>>(
+  args: T,
+  defaults: {
+    slippageToleranceFactor?: number;
+    maxAcceptableReverseBondingCurveFeeSlippageFactor?: number;
+  } = {}
+): T & {
+  slippageToleranceFactor: number;
+  maxAcceptableReverseBondingCurveFeeSlippageFactor: number;
+} {
+  return {
+    ...args,
+    slippageToleranceFactor:
+      args.slippageToleranceFactor ??
+      defaults.slippageToleranceFactor ??
+      DEFAULT_SLIPPAGE_TOLERANCE,
+    maxAcceptableReverseBondingCurveFeeSlippageFactor:
+      args.maxAcceptableReverseBondingCurveFeeSlippageFactor ??
+      defaults.maxAcceptableReverseBondingCurveFeeSlippageFactor ??
+      DEFAULT_RBC_FEE_SLIPPAGE,
+  };
+}
+
+/**
+ * Converts volume resolution string to seconds
+ *
+ * @example
+ * ```typescript
+ * const seconds = resolutionToSeconds('1h', '1h');
+ * // 3600
+ * ```
+ */
+export function resolutionToSeconds(
+  resolution: string | undefined,
+  defaultResolution: string = DEFAULT_VOLUME_RESOLUTION
+): number {
+  return RESOLUTION_MAP[resolution ?? defaultResolution] ?? RESOLUTION_MAP[defaultResolution];
+}
+
+/**
+ * Converts ISO 8601 date string to Unix timestamp (seconds)
+ *
+ * @example
+ * ```typescript
+ * const timestamp = dateToUnixTimestamp('2024-01-15T14:30:25Z');
+ * // 1705329025
+ * ```
+ */
+export function dateToUnixTimestamp(isoDate: string | undefined): number | undefined {
+  if (!isoDate) return undefined;
+  return Math.floor(new Date(isoDate).getTime() / 1000);
+}
+
+// =============================================================================
+// Export All
+// =============================================================================
+
+export const defaultValues = {
+  pagination: DEFAULT_PAGINATION,
+  limits: DEFAULT_LIMITS,
+  maxLimits: MAX_LIMITS,
+  slippageTolerance: DEFAULT_SLIPPAGE_TOLERANCE,
+  rbcFeeSlippage: DEFAULT_RBC_FEE_SLIPPAGE,
+  poolType: DEFAULT_POOL_TYPE,
+  sortOrder: DEFAULT_SORT_ORDER,
+  volumeResolution: DEFAULT_VOLUME_RESOLUTION,
+  resolutionMap: RESOLUTION_MAP,
+};

package/src/utils/error-handler.ts

@@ -0,0 +1,69 @@
+/**
+ * Error Handler Utility
+ *
+ * Formats errors for MCP protocol responses with AI-friendly tips.
+ * Uses centralized error templates from error-templates.ts.
+ *
+ * @see src/utils/error-templates.ts
+ */
+
+import type { MCPToolResponse } from '../types/mcp.js';
+import { enhanceErrorMessage } from './error-templates.js';
+
+/**
+ * Format error for MCP response with AI-friendly tips
+ */
+export function formatError(error: unknown): MCPToolResponse {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+
+  // Sanitize sensitive information from error messages
+  const sanitized = sanitizeError(errorMessage);
+
+  // Add AI-friendly tips using centralized templates
+  const withTips = enhanceErrorMessage(sanitized);
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `Error: ${withTips}`,
+      },
+    ],
+    isError: true,
+  };
+}
+
+/**
+ * Sanitize error messages to remove sensitive information
+ */
+function sanitizeError(message: string): string {
+  // Remove private keys
+  let sanitized = message.replace(/0x[a-fA-F0-9]{64}/g, '0x***');
+
+  // Remove eth| addresses but keep format visible
+  sanitized = sanitized.replace(/(eth\|)[a-fA-F0-9]{40}/g, '$1***');
+
+  // Remove 0x addresses but keep format visible
+  sanitized = sanitized.replace(/(0x)[a-fA-F0-9]{40}/g, '$1***');
+
+  return sanitized;
+}
+
+/**
+ * Wrap handler with error handling
+ *
+ * @template TArgs - Array of argument types
+ * @param handler - Handler function to wrap with error handling
+ * @returns Wrapped handler with automatic error formatting
+ */
+export function withErrorHandling<TArgs extends unknown[]>(
+  handler: (...args: TArgs) => Promise<MCPToolResponse>
+): (...args: TArgs) => Promise<MCPToolResponse> {
+  return async (...args: TArgs): Promise<MCPToolResponse> => {
+    try {
+      return await handler(...args);
+    } catch (error) {
+      return formatError(error);
+    }
+  };
+}

package/src/utils/error-templates.ts

@@ -0,0 +1,273 @@
+/**
+ * Error Message Templates
+ *
+ * Centralized error messages with AI-friendly tips for common error patterns.
+ * Eliminates duplication and ensures consistent error messaging.
+ *
+ * @see Phase 3.3 of refactoring plan
+ */
+
+// =============================================================================
+// Type Definitions
+// =============================================================================
+
+/**
+ * Error template with AI-friendly tip
+ */
+export interface ErrorTemplate {
+  pattern: RegExp | string;
+  tip: string;
+  category: 'validation' | 'timeout' | 'format' | 'business-logic' | 'network';
+}
+
+// =============================================================================
+// Validation Error Templates
+// =============================================================================
+
+/**
+ * Limit validation errors
+ */
+export const LIMIT_ERRORS = {
+  trade: {
+    pattern: /Limit must be.*20/,
+    tip: `💡 AI TIP: Trade and user operations have a maximum limit of 20. Use:
+- gala_launchpad_fetch_trades: limit ≤ 20
+- gala_launchpad_fetch_tokens_held: limit ≤ 20
+- gala_launchpad_fetch_tokens_created: limit ≤ 20
+
+See docs/CONSTRAINTS-REFERENCE.md for details.`,
+    category: 'validation' as const,
+  },
+  comment: {
+    pattern: /Limit must be.*50/,
+    tip: `💡 AI TIP: Comment operations have a maximum limit of 50. Use:
+- gala_launchpad_fetch_comments: limit ≤ 50
+
+See docs/CONSTRAINTS-REFERENCE.md for details.`,
+    category: 'validation' as const,
+  },
+  pool: {
+    pattern: /Limit must be.*100/,
+    tip: `💡 AI TIP: Pool operations have a maximum limit of 100. Use:
+- gala_launchpad_fetch_pools: limit ≤ 100
+
+See docs/CONSTRAINTS-REFERENCE.md for details.`,
+    category: 'validation' as const,
+  },
+} as const;
+
+/**
+ * Token name validation errors
+ */
+export const TOKEN_NAME_ERROR: ErrorTemplate = {
+  pattern: /token name.*(invalid|validation)/i,
+  tip: `💡 AI TIP: Token names must match pattern ^[a-z0-9_-]{2,20}$:
+- Lowercase letters and numbers only
+- Dashes and underscores allowed
+- Length: 2-20 characters
+- Valid examples: 'mytoken', 'test-token', 'token_123'
+- Invalid: 'MyToken' (uppercase), 'a' (too short), 'my token' (space)`,
+  category: 'validation',
+};
+
+/**
+ * Token symbol validation errors
+ */
+export const TOKEN_SYMBOL_ERROR: ErrorTemplate = {
+  pattern: /token symbol.*(invalid|validation)/i,
+  tip: `💡 AI TIP: Token symbols must match pattern ^[A-Z0-9]{2,10}$:
+- Uppercase letters and numbers only
+- No special characters
+- Length: 2-10 characters
+- Valid examples: 'MTK', 'TEST123', 'ABC'
+- Invalid: 'mtk' (lowercase), 'A' (too short), 'MY-TOKEN' (dash)`,
+  category: 'validation',
+};
+
+/**
+ * Wallet address format errors
+ */
+export const ADDRESS_FORMAT_ERROR: ErrorTemplate = {
+  pattern: /address.*(format|validation)/i,
+  tip: `💡 AI TIP: Wallet addresses must use format:
+- Backend API: 'eth|{40-hex-chars}' (e.g., 'eth|abc123...')
+- Convert from standard: address.startsWith('0x') ? \`eth|\${address.slice(2)}\` : address
+- Most MCP tools expect 'eth|...' format`,
+  category: 'format',
+};
+
+// =============================================================================
+// Trading Error Templates
+// =============================================================================
+
+/**
+ * WebSocket/trade timeout errors
+ */
+export const TRADE_TIMEOUT_ERROR: ErrorTemplate = {
+  pattern: /(timeout|WebSocket)/i,
+  tip: `💡 AI TIP: Trade execution timeouts often indicate incorrect expectedAmount parameter.
+
+✅ CORRECT WORKFLOW:
+1. Call calculate_buy_amount() or calculate_sell_amount()
+2. Extract result.amount from response (e.g., "16843.7579794843252")
+3. Use result.amount as expectedAmount in buy() or sell()
+
+❌ WRONG: Using your input amount as expectedAmount
+✅ RIGHT: Using calculated result.amount as expectedAmount
+
+See docs/AI-AGENT-PATTERNS.md section "Gotcha #1" for examples.`,
+  category: 'timeout',
+};
+
+/**
+ * Slippage/amount errors
+ */
+export const SLIPPAGE_ERROR: ErrorTemplate = {
+  pattern: /(slippage|amount.*expected)/i,
+  tip: `💡 AI TIP: expectedAmount must be the calculated output from calculate functions, NOT your input amount.
+
+Example:
+const calc = await calculateBuyAmount({ amount: '10', type: 'native', ... });
+// calc.amount = "16843.7579794843252" <- Use THIS as expectedAmount
+await buy({ amount: '10', expectedAmount: calc.amount, ... });
+
+See docs/AI-AGENT-PATTERNS.md for complete trading workflow.`,
+  category: 'business-logic',
+};
+
+/**
+ * Type parameter confusion
+ */
+export const TRADE_TYPE_ERROR: ErrorTemplate = {
+  pattern: /type.*(native|token)/i,
+  tip: `💡 AI TIP: Trading type parameter:
+- 'native': You specify GALA amount (most common)
+  Example: "I want to spend 10 GALA" → type: 'native', amount: '10'
+- 'exact': You specify exact token amount
+  Example: "I want to buy exactly 1000 tokens" → type: 'exact', amount: '1000'
+
+See docs/AI-AGENT-PATTERNS.md section "Gotcha #3" for details.`,
+  category: 'validation',
+};
+
+// =============================================================================
+// Token Creation Error Templates
+// =============================================================================
+
+/**
+ * Social URL requirement errors
+ */
+export const SOCIAL_URL_ERROR: ErrorTemplate = {
+  pattern: /(social|URL.*required)/i,
+  tip: `💡 AI TIP: Token launch requires at least ONE social URL:
+- websiteUrl (e.g., 'https://mytoken.com')
+- twitterUrl (e.g., 'https://twitter.com/mytoken')
+- telegramUrl (e.g., 'https://t.me/mytoken')
+
+Provide at least one in launchToken() call.`,
+  category: 'validation',
+};
+
+// =============================================================================
+// Generic Error Templates
+// =============================================================================
+
+/**
+ * Generic validation error
+ */
+export const GENERIC_VALIDATION_ERROR: ErrorTemplate = {
+  pattern: /(validation|invalid)/i,
+  tip: `💡 AI TIP: Check parameter formats in docs/AI-AGENT-PATTERNS.md
+Common validation rules:
+- tokenName: ^[a-z0-9_-]{2,20}$ (lowercase, 2-20 chars)
+- tokenSymbol: ^[A-Z0-9]{2,10}$ (uppercase, 2-10 chars)
+- address: 'eth|...' or '0x...' format (auto-normalized)
+- amount: ^[0-9.]+$ (decimal string)
+- limits: See CONSTRAINTS-REFERENCE.md`,
+  category: 'validation',
+};
+
+// =============================================================================
+// Error Template Registry
+// =============================================================================
+
+/**
+ * All error templates in priority order (checked sequentially)
+ */
+export const ERROR_TEMPLATES: ErrorTemplate[] = [
+  // Specific errors first (higher priority)
+  LIMIT_ERRORS.trade,
+  LIMIT_ERRORS.comment,
+  LIMIT_ERRORS.pool,
+  TOKEN_NAME_ERROR,
+  TOKEN_SYMBOL_ERROR,
+  ADDRESS_FORMAT_ERROR,
+  TRADE_TIMEOUT_ERROR,
+  SLIPPAGE_ERROR,
+  TRADE_TYPE_ERROR,
+  SOCIAL_URL_ERROR,
+
+  // Generic errors last (lower priority)
+  GENERIC_VALIDATION_ERROR,
+];
+
+// =============================================================================
+// Template Matching Functions
+// =============================================================================
+
+/**
+ * Finds the best matching error template for a message
+ */
+export function findErrorTemplate(message: string): ErrorTemplate | null {
+  for (const template of ERROR_TEMPLATES) {
+    const pattern = template.pattern;
+
+    if (typeof pattern === 'string') {
+      if (message.includes(pattern)) {
+        return template;
+      }
+    } else if (pattern instanceof RegExp) {
+      if (pattern.test(message)) {
+        return template;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Gets the AI-friendly tip for an error message
+ */
+export function getErrorTip(message: string): string | null {
+  const template = findErrorTemplate(message);
+  return template ? template.tip : null;
+}
+
+/**
+ * Applies AI-friendly tip to error message
+ */
+export function enhanceErrorMessage(message: string): string {
+  const tip = getErrorTip(message);
+  return tip ? `${message}\n\n${tip}` : message;
+}
+
+/**
+ * Gets error category for an error message
+ */
+export function getErrorCategory(message: string): string {
+  const template = findErrorTemplate(message);
+  return template ? template.category : 'unknown';
+}
+
+// =============================================================================
+// Export All
+// =============================================================================
+
+export const errorTemplates = {
+  templates: ERROR_TEMPLATES,
+  findTemplate: findErrorTemplate,
+  getTip: getErrorTip,
+  enhance: enhanceErrorMessage,
+  getCategory: getErrorCategory,
+};

package/src/utils/response-formatter.ts

@@ -0,0 +1,51 @@
+/**
+ * Response Formatter Utility
+ *
+ * Formats SDK responses for MCP protocol
+ */
+
+import type { MCPToolResponse } from '../types/mcp.js';
+
+/**
+ * Format successful response
+ */
+export function formatSuccess(data: any): MCPToolResponse {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}
+
+/**
+ * Format boolean response
+ */
+export function formatBoolean(result: boolean, message?: string): MCPToolResponse {
+  const text = message || `Result: ${result}`;
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify({ success: result, message: text }, null, 2),
+      },
+    ],
+  };
+}
+
+/**
+ * Format simple text response
+ */
+export function formatText(text: string): MCPToolResponse {
+  return {
+    content: [
+      {
+        type: 'text',
+        text,
+      },
+    ],
+  };
+}