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

package/src/utils/tool-factory.ts

@@ -1,303 +0,0 @@
-/**
- * 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

@@ -1,296 +0,0 @@
-/**
- * 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,
-};