@gala-chain/launchpad-mcp-server 1.7.3 → 1.7.4

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,
+      },
+    ],
+  };
+}

package/src/utils/tool-factory.ts

@@ -0,0 +1,257 @@
+/**
+ * Tool Factory Pattern Utilities
+ *
+ * DRY utilities for creating MCP tools with common patterns.
+ * Eliminates duplication across 47 tool definitions.
+ *
+ * @see Phase 2.1 of refactoring plan
+ */
+
+import type { MCPTool } from '../types/mcp.js';
+import type { LaunchpadSDK } from '@gala-chain/launchpad-sdk';
+import { withErrorHandling } from './error-handler.js';
+import { formatSuccess, formatBoolean } from './response-formatter.js';
+import { TOKEN_NAME_SCHEMA } from '../schemas/common-schemas.js';
+
+// =============================================================================
+// Type Definitions
+// =============================================================================
+
+/**
+ * Handler function that takes SDK and args, returns result
+ */
+type ToolHandler<T = any> = (sdk: LaunchpadSDK, args: any) => Promise<T>;
+
+/**
+ * Simple handler that only needs SDK and tokenName
+ * Can return the result or null
+ */
+type SimpleTokenHandler<T = any> = (sdk: LaunchpadSDK, tokenName: string) => Promise<T | null>;
+
+/**
+ * Boolean check handler that returns true/false
+ */
+type BooleanCheckHandler = (sdk: LaunchpadSDK, value: string) => Promise<boolean>;
+
+/**
+ * No-parameter handler that only needs SDK, returns result
+ */
+type NoParamHandler<T = any> = (sdk: LaunchpadSDK) => T | Promise<T>;
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+/**
+ * Creates a simple fetch tool that takes tokenName and calls an SDK method
+ *
+ * @example
+ * ```typescript
+ * 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),
+ * });
+ * ```
+ */
+export function createSimpleTokenFetchTool(config: {
+  name: string;
+  description: string;
+  handler: SimpleTokenHandler;
+}): MCPTool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tokenName: TOKEN_NAME_SCHEMA,
+      },
+      required: ['tokenName'],
+    },
+    handler: withErrorHandling(async (sdk, args) => {
+      const result = await config.handler(sdk, args.tokenName);
+      return formatSuccess(result);
+    }),
+  };
+}
+
+/**
+ * Creates a boolean check tool (e.g., isTokenNameAvailable, isTokenSymbolAvailable)
+ *
+ * @example
+ * ```typescript
+ * 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',
+ *   },
+ * });
+ * ```
+ */
+export function createBooleanCheckTool(config: {
+  name: string;
+  description: string;
+  paramName: string;
+  paramSchema: any;
+  handler: BooleanCheckHandler;
+  messages: {
+    true: string;
+    false: string;
+  };
+}): MCPTool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        [config.paramName]: config.paramSchema,
+      },
+      required: [config.paramName],
+    },
+    handler: withErrorHandling(async (sdk, args) => {
+      const value = args[config.paramName];
+      const available = await config.handler(sdk, value);
+      return formatBoolean(
+        available,
+        available ? config.messages.true : config.messages.false
+      );
+    }),
+  };
+}
+
+/**
+ * Creates a generic fetch tool with custom input schema and handler
+ *
+ * @example
+ * ```typescript
+ * export const fetchPoolsTool = createFetchTool({
+ *   name: 'gala_launchpad_fetch_pools',
+ *   description: 'Fetch token pools from Gala Launchpad',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       type: { type: 'string', enum: ['recent', 'popular'] },
+ *       page: PAGE_SCHEMA,
+ *       limit: createLimitSchema('pool', 20),
+ *     },
+ *   },
+ *   handler: (sdk, args) => sdk.fetchPools({
+ *     type: args.type || 'recent',
+ *     page: args.page || 1,
+ *     limit: args.limit || 20,
+ *   }),
+ * });
+ * ```
+ */
+export function createFetchTool(config: {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, any>;
+    required?: string[];
+  };
+  handler: ToolHandler;
+}): MCPTool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: config.inputSchema,
+    handler: withErrorHandling(async (sdk, args) => {
+      const result = await config.handler(sdk, args);
+      return formatSuccess(result);
+    }),
+  };
+}
+
+/**
+ * Creates a resolution tool that maps tokenName to some resolved value
+ *
+ * @example
+ * ```typescript
+ * export const resolveVaultAddressTool = createResolutionTool({
+ *   name: 'gala_launchpad_resolve_vault_address',
+ *   description: 'Get GalaChain vault address for a token',
+ *   resolver: (sdk, tokenName) => sdk.resolveVaultAddress(tokenName),
+ *   resultKey: 'vaultAddress',
+ * });
+ * ```
+ */
+export function createResolutionTool(config: {
+  name: string;
+  description: string;
+  resolver: SimpleTokenHandler<string | any>;
+  resultKey: string;
+}): MCPTool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tokenName: TOKEN_NAME_SCHEMA,
+      },
+      required: ['tokenName'],
+    },
+    handler: withErrorHandling(async (sdk, args) => {
+      const resolvedValue = await config.resolver(sdk, args.tokenName);
+      return formatSuccess({
+        tokenName: args.tokenName,
+        [config.resultKey]: resolvedValue,
+      });
+    }),
+  };
+}
+
+/**
+ * Creates a no-parameter tool that only needs SDK instance
+ *
+ * @example
+ * ```typescript
+ * export const getAddressTool = createNoParamTool({
+ *   name: 'gala_launchpad_get_address',
+ *   description: 'Get the GalaChain address format (eth|0x...) for the authenticated wallet.',
+ *   handler: (sdk) => sdk.getAddress(),
+ *   resultKey: 'address',
+ * });
+ * ```
+ */
+export function createNoParamTool(config: {
+  name: string;
+  description: string;
+  handler: NoParamHandler;
+  resultKey?: string;
+}): MCPTool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+    handler: withErrorHandling(async (sdk) => {
+      const result = await config.handler(sdk);
+      // If resultKey provided, wrap in object; otherwise return result directly
+      return formatSuccess(config.resultKey ? { [config.resultKey]: result } : result);
+    }),
+  };
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export const toolFactory = {
+  createSimpleTokenFetchTool,
+  createBooleanCheckTool,
+  createFetchTool,
+  createResolutionTool,
+  createNoParamTool,
+};