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

package/src/utils/tool-factory.ts

@@ -0,0 +1,303 @@
+/**
+ * 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>;
+
+/**
+ * Server-level handler that needs server instance for operations like environment switching
+ */
+type ServerLevelHandler<T = any> = (sdk: LaunchpadSDK, args: any, server: any) => 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);
+    }),
+  };
+}
+
+/**
+ * Creates a server-level tool that needs access to the MCP server instance
+ * Used for operations like environment switching that require server state management
+ *
+ * @example
+ * ```typescript
+ * export const getEnvironmentTool = createServerLevelTool({
+ *   name: 'gala_launchpad_get_environment',
+ *   description: 'Get the current environment (production, development, or testing).',
+ *   handler: (sdk, args, server) => server.getEnvironment(),
+ *   resultKey: 'environment',
+ * });
+ * ```
+ */
+export function createServerLevelTool(config: {
+  name: string;
+  description: string;
+  handler: ServerLevelHandler;
+  inputSchema?: {
+    type: 'object';
+    properties: Record<string, any>;
+    required?: string[];
+  };
+  resultKey?: string;
+}): MCPTool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: config.inputSchema || {
+      type: 'object',
+      properties: {},
+    },
+    handler: withErrorHandling(async (sdk, args, server) => {
+      const result = await config.handler(sdk, args, server);
+      // 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,
+  createServerLevelTool,
+};

package/src/utils/tool-registry.ts

@@ -0,0 +1,296 @@
+/**
+ * Tool Registry System
+ *
+ * Enhanced tool registration with auto-validation, metadata, and search capabilities.
+ * Provides runtime validation and developer-friendly tool discovery.
+ *
+ * @see Phase 3.1 of refactoring plan
+ */
+
+import type { MCPTool } from '../types/mcp.js';
+
+// =============================================================================
+// Type Definitions
+// =============================================================================
+
+/**
+ * Tool category metadata
+ */
+export interface ToolCategory {
+  name: string;
+  description: string;
+  tools: MCPTool[];
+  count: number;
+}
+
+/**
+ * Tool registry with metadata and search capabilities
+ */
+export interface ToolRegistry {
+  tools: MCPTool[];
+  categories: Map<string, ToolCategory>;
+  totalCount: number;
+  expectedCount: number;
+  isValid: boolean;
+  errors: string[];
+}
+
+/**
+ * Tool validation result
+ */
+export interface ToolValidationResult {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+// =============================================================================
+// Validation Functions
+// =============================================================================
+
+/**
+ * Validates a single tool definition
+ */
+export function validateTool(tool: MCPTool): ToolValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Required fields
+  if (!tool.name) {
+    errors.push('Tool name is required');
+  } else if (typeof tool.name !== 'string') {
+    errors.push('Tool name must be a string');
+  } else if (!tool.name.startsWith('gala_launchpad_')) {
+    warnings.push(`Tool name "${tool.name}" should start with "gala_launchpad_"`);
+  }
+
+  if (!tool.description) {
+    errors.push('Tool description is required');
+  } else if (typeof tool.description !== 'string') {
+    errors.push('Tool description must be a string');
+  }
+
+  if (!tool.inputSchema) {
+    errors.push('Tool inputSchema is required');
+  } else {
+    // Validate input schema structure
+    if (tool.inputSchema.type !== 'object') {
+      errors.push('inputSchema.type must be "object"');
+    }
+    if (!tool.inputSchema.properties) {
+      warnings.push('inputSchema.properties is empty');
+    }
+    if (tool.inputSchema.required && !Array.isArray(tool.inputSchema.required)) {
+      errors.push('inputSchema.required must be an array');
+    }
+  }
+
+  if (!tool.handler) {
+    errors.push('Tool handler is required');
+  } else if (typeof tool.handler !== 'function') {
+    errors.push('Tool handler must be a function');
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Validates all tools in a registry
+ */
+export function validateTools(tools: MCPTool[]): ToolValidationResult {
+  const allErrors: string[] = [];
+  const allWarnings: string[] = [];
+  const toolNames = new Set<string>();
+
+  tools.forEach((tool, index) => {
+    const result = validateTool(tool);
+
+    // Collect errors with tool context
+    result.errors.forEach((error) => {
+      allErrors.push(`Tool #${index + 1} (${tool.name || 'unknown'}): ${error}`);
+    });
+
+    result.warnings.forEach((warning) => {
+      allWarnings.push(`Tool #${index + 1} (${tool.name || 'unknown'}): ${warning}`);
+    });
+
+    // Check for duplicate names
+    if (tool.name) {
+      if (toolNames.has(tool.name)) {
+        allErrors.push(`Duplicate tool name: ${tool.name}`);
+      }
+      toolNames.add(tool.name);
+    }
+  });
+
+  return {
+    isValid: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings,
+  };
+}
+
+// =============================================================================
+// Registry Functions
+// =============================================================================
+
+/**
+ * Creates a tool registry with metadata and validation
+ */
+export function createToolRegistry(
+  categories: Array<{ name: string; description: string; tools: MCPTool[] }>,
+  expectedCount?: number
+): ToolRegistry {
+  const allTools: MCPTool[] = [];
+  const categoryMap = new Map<string, ToolCategory>();
+  const registryErrors: string[] = [];
+
+  // Process each category
+  categories.forEach((category) => {
+    const toolCategory: ToolCategory = {
+      name: category.name,
+      description: category.description,
+      tools: category.tools,
+      count: category.tools.length,
+    };
+
+    categoryMap.set(category.name, toolCategory);
+    allTools.push(...category.tools);
+  });
+
+  // Validate all tools
+  const validation = validateTools(allTools);
+  registryErrors.push(...validation.errors);
+
+  // Check expected count
+  const actualCount = allTools.length;
+  const hasExpectedCount = expectedCount !== undefined;
+  const countMatches = hasExpectedCount ? actualCount === expectedCount : true;
+
+  if (hasExpectedCount && !countMatches) {
+    registryErrors.push(
+      `Tool count mismatch: expected ${expectedCount}, got ${actualCount}`
+    );
+  }
+
+  return {
+    tools: allTools,
+    categories: categoryMap,
+    totalCount: actualCount,
+    expectedCount: expectedCount ?? actualCount,
+    isValid: registryErrors.length === 0,
+    errors: registryErrors,
+  };
+}
+
+/**
+ * Finds a tool by name
+ */
+export function findTool(registry: ToolRegistry, name: string): MCPTool | undefined {
+  return registry.tools.find((tool) => tool.name === name);
+}
+
+/**
+ * Finds tools by category
+ */
+export function findToolsByCategory(
+  registry: ToolRegistry,
+  categoryName: string
+): MCPTool[] {
+  const category = registry.categories.get(categoryName);
+  return category ? category.tools : [];
+}
+
+/**
+ * Searches tools by name pattern
+ */
+export function searchTools(registry: ToolRegistry, pattern: string): MCPTool[] {
+  const regex = new RegExp(pattern, 'i');
+  return registry.tools.filter((tool) => regex.test(tool.name));
+}
+
+/**
+ * Gets tool statistics by category
+ */
+export function getToolStatistics(registry: ToolRegistry): {
+  total: number;
+  byCategory: Record<string, number>;
+} {
+  const byCategory: Record<string, number> = {};
+
+  registry.categories.forEach((category, name) => {
+    byCategory[name] = category.count;
+  });
+
+  return {
+    total: registry.totalCount,
+    byCategory,
+  };
+}
+
+// =============================================================================
+// Logging and Reporting
+// =============================================================================
+
+/**
+ * Logs tool registry statistics
+ */
+export function logToolRegistry(registry: ToolRegistry): void {
+  console.log('\n📦 Tool Registry Statistics:');
+  console.log(`   Total Tools: ${registry.totalCount}/${registry.expectedCount}`);
+  console.log(`   Valid: ${registry.isValid ? '✅' : '❌'}`);
+
+  if (!registry.isValid && registry.errors.length > 0) {
+    console.log('\n❌ Validation Errors:');
+    registry.errors.forEach((error) => console.log(`   - ${error}`));
+  }
+
+  console.log('\n📂 Categories:');
+  registry.categories.forEach((category) => {
+    console.log(`   ${category.name}: ${category.count} tools`);
+  });
+
+  console.log('');
+}
+
+/**
+ * Generates markdown documentation for tool registry
+ */
+export function generateToolDocumentation(registry: ToolRegistry): string {
+  let doc = '# MCP Tool Registry\n\n';
+  doc += `**Total Tools**: ${registry.totalCount}\n\n`;
+
+  doc += '## Categories\n\n';
+  registry.categories.forEach((category) => {
+    doc += `### ${category.name} (${category.count} tools)\n\n`;
+    doc += `${category.description}\n\n`;
+
+    category.tools.forEach((tool) => {
+      doc += `- **${tool.name}**: ${tool.description}\n`;
+    });
+
+    doc += '\n';
+  });
+
+  return doc;
+}
+
+// =============================================================================
+// Export All
+// =============================================================================
+
+export const toolRegistry = {
+  createToolRegistry,
+  validateTool,
+  validateTools,
+  findTool,
+  findToolsByCategory,
+  searchTools,
+  getToolStatistics,
+  logToolRegistry,
+  generateToolDocumentation,
+};