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

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

package/src/utils/validation.ts

@@ -0,0 +1,336 @@
+/**
+ * Validation Utilities for MCP Prompts
+ *
+ * Input validation functions for slash command arguments.
+ * Prevents malformed inputs and provides clear error messages.
+ */
+
+/**
+ * Validation error class for better error handling
+ */
+export class ValidationError extends Error {
+  constructor(
+    public field: string,
+    message: string
+  ) {
+    super(`Validation error for '${field}': ${message}`);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Validate token name format
+ *
+ * Token names must be 2-20 characters, alphanumeric with hyphens and underscores.
+ *
+ * @param name - Token name to validate
+ * @param fieldName - Field name for error messages (default: 'tokenName')
+ * @throws {ValidationError} If token name is invalid
+ *
+ * @example
+ * ```typescript
+ * validateTokenName('anime'); // ✅ Valid
+ * validateTokenName('test-123'); // ✅ Valid
+ * validateTokenName('my_token'); // ✅ Valid
+ * validateTokenName('a'); // ❌ Throws: too short
+ * validateTokenName('token@#$'); // ❌ Throws: invalid characters
+ * ```
+ */
+export function validateTokenName(name: string, fieldName = 'tokenName'): void {
+  if (!name || typeof name !== 'string') {
+    throw new ValidationError(fieldName, 'Token name is required');
+  }
+
+  if (name.length < 2 || name.length > 20) {
+    throw new ValidationError(
+      fieldName,
+      `Token name must be 2-20 characters (got ${name.length})`
+    );
+  }
+
+  const tokenNameRegex = /^[a-zA-Z0-9-_]+$/;
+  if (!tokenNameRegex.test(name)) {
+    throw new ValidationError(
+      fieldName,
+      'Token name can only contain letters, numbers, hyphens, and underscores'
+    );
+  }
+}
+
+/**
+ * Validate numeric amount
+ *
+ * Amounts must be positive numbers (integers or decimals).
+ *
+ * @param amount - Amount to validate (string or number)
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If amount is invalid
+ *
+ * @example
+ * ```typescript
+ * validateNumericAmount('100', 'galaAmount'); // ✅ Valid
+ * validateNumericAmount('99.5', 'tokenAmount'); // ✅ Valid
+ * validateNumericAmount('-5', 'amount'); // ❌ Throws: negative
+ * validateNumericAmount('abc', 'amount'); // ❌ Throws: not a number
+ * ```
+ */
+export function validateNumericAmount(
+  amount: string | number,
+  fieldName: string
+): void {
+  if (amount === null || amount === undefined || amount === '') {
+    throw new ValidationError(fieldName, 'Amount is required');
+  }
+
+  const numAmount = typeof amount === 'string' ? parseFloat(amount) : amount;
+
+  if (isNaN(numAmount)) {
+    throw new ValidationError(fieldName, `Amount must be a valid number (got: ${amount})`);
+  }
+
+  if (numAmount <= 0) {
+    throw new ValidationError(
+      fieldName,
+      `Amount must be positive (got: ${numAmount})`
+    );
+  }
+
+  if (!isFinite(numAmount)) {
+    throw new ValidationError(fieldName, 'Amount must be a finite number');
+  }
+}
+
+/**
+ * Validate slippage tolerance percentage
+ *
+ * Slippage must be between 0.01% and 100%.
+ *
+ * @param slippage - Slippage percentage to validate
+ * @param fieldName - Field name for error messages (default: 'slippage')
+ * @throws {ValidationError} If slippage is invalid
+ *
+ * @example
+ * ```typescript
+ * validateSlippage('1'); // ✅ Valid (1%)
+ * validateSlippage('0.5'); // ✅ Valid (0.5%)
+ * validateSlippage('50'); // ✅ Valid (50%)
+ * validateSlippage('0'); // ❌ Throws: too low
+ * validateSlippage('150'); // ❌ Throws: too high
+ * ```
+ */
+export function validateSlippage(
+  slippage: string | number,
+  fieldName = 'slippage'
+): void {
+  if (slippage === null || slippage === undefined || slippage === '') {
+    throw new ValidationError(fieldName, 'Slippage is required');
+  }
+
+  const numSlippage = typeof slippage === 'string' ? parseFloat(slippage) : slippage;
+
+  if (isNaN(numSlippage)) {
+    throw new ValidationError(
+      fieldName,
+      `Slippage must be a valid number (got: ${slippage})`
+    );
+  }
+
+  if (numSlippage < 0.01 || numSlippage > 100) {
+    throw new ValidationError(
+      fieldName,
+      `Slippage must be between 0.01% and 100% (got: ${numSlippage}%)`
+    );
+  }
+}
+
+/**
+ * Validate wallet address format
+ *
+ * Supports both GalaChain format (eth|0x...) and standard Ethereum format (0x...).
+ *
+ * @param address - Wallet address to validate
+ * @param fieldName - Field name for error messages (default: 'address')
+ * @throws {ValidationError} If address is invalid
+ *
+ * @example
+ * ```typescript
+ * validateAddress('eth|0x1234567890abcdef1234567890abcdef12345678'); // ✅ Valid
+ * validateAddress('0x1234567890abcdef1234567890abcdef12345678'); // ✅ Valid
+ * validateAddress('invalid'); // ❌ Throws: invalid format
+ * ```
+ */
+export function validateAddress(address: string, fieldName = 'address'): void {
+  if (!address || typeof address !== 'string') {
+    throw new ValidationError(fieldName, 'Address is required');
+  }
+
+  // GalaChain format: eth|0x{40 hex chars}
+  const galachainRegex = /^eth\|0x[a-fA-F0-9]{40}$/;
+  // Standard Ethereum format: 0x{40 hex chars}
+  const ethereumRegex = /^0x[a-fA-F0-9]{40}$/;
+
+  if (!galachainRegex.test(address) && !ethereumRegex.test(address)) {
+    throw new ValidationError(
+      fieldName,
+      'Address must be in GalaChain format (eth|0x...) or Ethereum format (0x...)'
+    );
+  }
+}
+
+/**
+ * Validate token symbol format
+ *
+ * Symbols must be 1-8 uppercase letters.
+ *
+ * @param symbol - Token symbol to validate
+ * @param fieldName - Field name for error messages (default: 'symbol')
+ * @throws {ValidationError} If symbol is invalid
+ *
+ * @example
+ * ```typescript
+ * validateTokenSymbol('GALA'); // ✅ Valid
+ * validateTokenSymbol('TEST'); // ✅ Valid
+ * validateTokenSymbol('test'); // ❌ Throws: must be uppercase
+ * validateTokenSymbol('TOOLONG123'); // ❌ Throws: too long
+ * ```
+ */
+export function validateTokenSymbol(symbol: string, fieldName = 'symbol'): void {
+  if (!symbol || typeof symbol !== 'string') {
+    throw new ValidationError(fieldName, 'Symbol is required');
+  }
+
+  if (symbol.length < 1 || symbol.length > 8) {
+    throw new ValidationError(
+      fieldName,
+      `Symbol must be 1-8 characters (got ${symbol.length})`
+    );
+  }
+
+  const symbolRegex = /^[A-Z]+$/;
+  if (!symbolRegex.test(symbol)) {
+    throw new ValidationError(
+      fieldName,
+      'Symbol must be uppercase letters only (A-Z)'
+    );
+  }
+}
+
+/**
+ * Validate pagination limit
+ *
+ * Limits must be positive integers within reasonable range (1-100).
+ *
+ * @param limit - Pagination limit to validate
+ * @param max - Maximum allowed limit (default: 100)
+ * @param fieldName - Field name for error messages (default: 'limit')
+ * @throws {ValidationError} If limit is invalid
+ *
+ * @example
+ * ```typescript
+ * validatePaginationLimit('20'); // ✅ Valid
+ * validatePaginationLimit('1'); // ✅ Valid
+ * validatePaginationLimit('0'); // ❌ Throws: too low
+ * validatePaginationLimit('150'); // ❌ Throws: too high
+ * ```
+ */
+export function validatePaginationLimit(
+  limit: string | number,
+  max = 100,
+  fieldName = 'limit'
+): void {
+  if (limit === null || limit === undefined || limit === '') {
+    throw new ValidationError(fieldName, 'Limit is required');
+  }
+
+  const numLimit = typeof limit === 'string' ? parseInt(limit, 10) : limit;
+
+  if (isNaN(numLimit) || !Number.isInteger(numLimit)) {
+    throw new ValidationError(
+      fieldName,
+      `Limit must be a valid integer (got: ${limit})`
+    );
+  }
+
+  if (numLimit < 1 || numLimit > max) {
+    throw new ValidationError(
+      fieldName,
+      `Limit must be between 1 and ${max} (got: ${numLimit})`
+    );
+  }
+}
+
+/**
+ * Validate comma-separated token list
+ *
+ * For batch operations that accept multiple token names.
+ *
+ * @param tokens - Comma-separated token names
+ * @param fieldName - Field name for error messages (default: 'tokens')
+ * @throws {ValidationError} If token list is invalid
+ *
+ * @example
+ * ```typescript
+ * validateTokenList('anime,test,dragon'); // ✅ Valid
+ * validateTokenList('token1'); // ✅ Valid (single token)
+ * validateTokenList(''); // ❌ Throws: empty list
+ * validateTokenList('token1,invalid@#$'); // ❌ Throws: invalid token name
+ * ```
+ */
+export function validateTokenList(tokens: string, fieldName = 'tokens'): string[] {
+  if (!tokens || typeof tokens !== 'string') {
+    throw new ValidationError(fieldName, 'Token list is required');
+  }
+
+  const tokenArray = tokens.split(',').map((t) => t.trim());
+
+  if (tokenArray.length === 0 || tokenArray.some((t) => !t)) {
+    throw new ValidationError(fieldName, 'Token list cannot be empty');
+  }
+
+  // Validate each token name
+  tokenArray.forEach((token, index) => {
+    try {
+      validateTokenName(token, `${fieldName}[${index}]`);
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        throw new ValidationError(
+          fieldName,
+          `Invalid token at position ${index + 1}: ${token}`
+        );
+      }
+      throw error;
+    }
+  });
+
+  return tokenArray;
+}
+
+/**
+ * Safe validation wrapper that doesn't throw
+ *
+ * Useful for non-critical validation where you want to continue with a warning.
+ *
+ * @param validationFn - Validation function to execute
+ * @returns Object with success flag and optional error
+ *
+ * @example
+ * ```typescript
+ * const result = safeValidate(() => validateTokenName('anime'));
+ * if (!result.success) {
+ *   console.warn('Validation warning:', result.error);
+ * }
+ * ```
+ */
+export function safeValidate(
+  validationFn: () => void
+): { success: boolean; error?: string } {
+  try {
+    validationFn();
+    return { success: true };
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      return { success: false, error: error.message };
+    }
+    return { success: false, error: String(error) };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": false,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "types": ["node", "jest"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests", "src/scripts", "src/**/__tests__"]
+}