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

package/src/utils/validation.ts

@@ -0,0 +1,371 @@
+/**
+ * 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;
+}
+
+/**
+ * Validate URL format
+ *
+ * URLs must be well-formed HTTP/HTTPS URLs.
+ *
+ * @param url - URL to validate
+ * @param fieldName - Field name for error messages (default: 'url')
+ * @throws {ValidationError} If URL is invalid
+ *
+ * @example
+ * ```typescript
+ * validateUrl('https://example.com'); // ✅ Valid
+ * validateUrl('https://twitter.com/user'); // ✅ Valid
+ * validateUrl('http://localhost:3000'); // ✅ Valid
+ * validateUrl('not-a-url'); // ❌ Throws: invalid format
+ * ```
+ */
+export function validateUrl(url: string, fieldName = 'url'): void {
+  if (!url || typeof url !== 'string') {
+    throw new ValidationError(fieldName, 'URL is required');
+  }
+
+  try {
+    const urlObj = new URL(url);
+    if (!['http:', 'https:'].includes(urlObj.protocol)) {
+      throw new ValidationError(fieldName, 'URL must use HTTP or HTTPS protocol');
+    }
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      throw error;
+    }
+    throw new ValidationError(fieldName, `Invalid URL format: ${url}`);
+  }
+}
+
+/**
+ * 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/tests/wallet-management-integration.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Integration Tests for MCP Wallet Management Tools
+ *
+ * Tests the three new wallet management tools:
+ * - gala_launchpad_has_wallet
+ * - gala_launchpad_get_wallet
+ * - gala_launchpad_set_wallet
+ */
+
+import { LaunchpadMCPServer } from '../src/server';
+import { WalletUtils } from '@gala-chain/launchpad-sdk';
+
+describe('MCP Wallet Management Integration Tests', () => {
+  let server: LaunchpadMCPServer;
+  let testPrivateKey: string;
+
+  beforeEach(async () => {
+    server = new LaunchpadMCPServer();
+    // Generate a test private key
+    const wallet = WalletUtils.generateWallet();
+    testPrivateKey = wallet.privateKey;
+  });
+
+  describe('Server Initialization Modes', () => {
+    it('should initialize in read-only mode when PRIVATE_KEY is not set', async () => {
+      const readOnlyServer = new LaunchpadMCPServer();
+      // Clear PRIVATE_KEY from environment
+      const originalKey = process.env.PRIVATE_KEY;
+      delete process.env.PRIVATE_KEY;
+
+      try {
+        await readOnlyServer.initialize();
+        // SDK should be initialized
+        expect(readOnlyServer['sdk']).toBeDefined();
+      } finally {
+        // Restore original key
+        if (originalKey) {
+          process.env.PRIVATE_KEY = originalKey;
+        }
+      }
+    });
+
+    it('should initialize in full-access mode when PRIVATE_KEY is set', async () => {
+      process.env.PRIVATE_KEY = testPrivateKey;
+
+      try {
+        await server.initialize();
+        expect(server['sdk']).toBeDefined();
+      } finally {
+        delete process.env.PRIVATE_KEY;
+      }
+    });
+
+    it('should handle missing PRIVATE_KEY gracefully', async () => {
+      const originalKey = process.env.PRIVATE_KEY;
+      delete process.env.PRIVATE_KEY;
+
+      try {
+        // Should not throw during initialization
+        const readOnlyServer = new LaunchpadMCPServer();
+        await readOnlyServer.initialize();
+        expect(readOnlyServer['sdk']).toBeDefined();
+      } finally {
+        if (originalKey) {
+          process.env.PRIVATE_KEY = originalKey;
+        }
+      }
+    });
+  });
+
+  describe('Wallet Tool Availability', () => {
+    it('should list all wallet management tools', async () => {
+      await server.initialize();
+      // Get the server instance
+      const serverInstance = server as any;
+      // The tools should be registered in the MCP server
+      expect(serverInstance.server).toBeDefined();
+    });
+
+    it('should have gala_launchpad_has_wallet tool registered', () => {
+      // Tools are registered in the tools/index.ts
+      // This is a static verification test
+      const fs = require('fs');
+      const toolsIndexPath = require.resolve('../src/tools/utils/index.ts');
+      // This is a static check - the tool should be imported
+      expect(toolsIndexPath).toBeDefined();
+    });
+
+    it('should have gala_launchpad_get_wallet tool registered', () => {
+      // This is a static verification test
+      const fs = require('fs');
+      const toolsIndexPath = require.resolve('../src/tools/utils/index.ts');
+      expect(toolsIndexPath).toBeDefined();
+    });
+
+    it('should have gala_launchpad_set_wallet tool registered', () => {
+      // This is a static verification test
+      const fs = require('fs');
+      const toolsIndexPath = require.resolve('../src/tools/utils/index.ts');
+      expect(toolsIndexPath).toBeDefined();
+    });
+  });
+
+  describe('Wallet Tool Functionality', () => {
+    beforeEach(async () => {
+      // Initialize server without wallet (read-only mode)
+      delete process.env.PRIVATE_KEY;
+      await server.initialize();
+    });
+
+    it('should handle wallet tool execution in read-only mode', async () => {
+      // In read-only mode, hasWallet should return false
+      const sdk = (server as any).sdk;
+      expect(sdk.hasWallet()).toBe(false);
+    });
+
+    it('should handle wallet tool execution in full-access mode', async () => {
+      // Create new server with wallet
+      const fullAccessServer = new LaunchpadMCPServer();
+      process.env.PRIVATE_KEY = testPrivateKey;
+
+      try {
+        await fullAccessServer.initialize();
+        const sdk = (fullAccessServer as any).sdk;
+        expect(sdk.hasWallet()).toBe(true);
+      } finally {
+        delete process.env.PRIVATE_KEY;
+      }
+    });
+
+    it('should support dynamic wallet configuration via setWallet tool', async () => {
+      const sdk = (server as any).sdk;
+
+      // Initially in read-only mode
+      expect(sdk.hasWallet()).toBe(false);
+
+      // Upgrade to full-access by setting wallet
+      const wallet = WalletUtils.generateWallet();
+      sdk.setWallet(wallet.wallet);
+
+      // Now should have wallet
+      expect(sdk.hasWallet()).toBe(true);
+      expect(sdk.getWallet()).toBeDefined();
+    });
+  });
+
+  describe('Tool Registration Count', () => {
+    it('should have exactly 57 tools registered (54 original + 3 new wallet tools)', async () => {
+      // This verifies the tool count was updated correctly
+      // The count is defined in src/tools/index.ts
+      const registryModule = require('../dist/tools/index.js');
+      expect(registryModule.tools.length).toBeGreaterThanOrEqual(57);
+    });
+  });
+
+  describe('Error Handling', () => {
+    beforeEach(async () => {
+      // Initialize server in read-only mode
+      delete process.env.PRIVATE_KEY;
+      await server.initialize();
+    });
+
+    it('should throw error when trying to perform signing operation without wallet', async () => {
+      const sdk = (server as any).sdk;
+
+      // Attempting to buy tokens should fail due to missing wallet
+      try {
+        await sdk.buyTokens('test', '10', 'native', 0.01);
+        fail('Should have thrown an error');
+      } catch (error) {
+        expect(error).toBeDefined();
+        expect(String(error)).toContain('Wallet');
+      }
+    });
+
+    it('should allow read-only operations in read-only mode', async () => {
+      const sdk = (server as any).sdk;
+
+      // Fetching pools should work without wallet (may fail due to network, but not wallet)
+      try {
+        await sdk.fetchPools({ type: 'recent', page: 1, limit: 1 });
+      } catch (error: any) {
+        // Should not be a wallet validation error
+        if (error.message) {
+          expect(error.message).not.toContain('Wallet is required');
+        }
+      }
+    });
+
+    it('should accept valid wallet in setWallet call', async () => {
+      const sdk = (server as any).sdk;
+      const wallet = WalletUtils.generateWallet();
+
+      // Should not throw
+      expect(() => {
+        sdk.setWallet(wallet.wallet);
+      }).not.toThrow();
+
+      // Wallet should be set
+      expect(sdk.hasWallet()).toBe(true);
+    });
+
+    it('should reject invalid wallet in setWallet call', async () => {
+      const sdk = (server as any).sdk;
+
+      // Should throw on invalid wallet
+      expect(() => {
+        sdk.setWallet({} as any);
+      }).toThrow();
+
+      expect(() => {
+        sdk.setWallet(null as any);
+      }).toThrow();
+
+      expect(() => {
+        sdk.setWallet('not-a-wallet' as any);
+      }).toThrow();
+    });
+  });
+
+  describe('Operational Modes', () => {
+    it('should support upgrade from read-only to full-access mode', async () => {
+      // Start in read-only mode
+      delete process.env.PRIVATE_KEY;
+      const readOnlyServer = new LaunchpadMCPServer();
+      await readOnlyServer.initialize();
+
+      const sdk = (readOnlyServer as any).sdk;
+      expect(sdk.hasWallet()).toBe(false);
+
+      // Upgrade to full-access
+      const wallet = WalletUtils.generateWallet();
+      sdk.setWallet(wallet.wallet);
+
+      expect(sdk.hasWallet()).toBe(true);
+      expect(sdk.getAddress()).toBeDefined();
+    });
+
+    it('should support switching wallets in full-access mode', async () => {
+      process.env.PRIVATE_KEY = testPrivateKey;
+      const fullAccessServer = new LaunchpadMCPServer();
+      await fullAccessServer.initialize();
+
+      const sdk = (fullAccessServer as any).sdk;
+      const address1 = sdk.getAddress();
+
+      // Switch to different wallet
+      const newWallet = WalletUtils.generateWallet();
+      sdk.setWallet(newWallet.wallet);
+      const address2 = sdk.getAddress();
+
+      expect(address1).not.toBe(address2);
+      expect(sdk.hasWallet()).toBe(true);
+
+      delete process.env.PRIVATE_KEY;
+    });
+
+    it('should maintain SDK state across operational mode transitions', async () => {
+      // Start in read-only
+      delete process.env.PRIVATE_KEY;
+      const server = new LaunchpadMCPServer();
+      await server.initialize();
+
+      const sdk = (server as any).sdk;
+
+      // Upgrade to full-access
+      const wallet = WalletUtils.generateWallet();
+      sdk.setWallet(wallet.wallet);
+
+      // SDK should still be operational
+      expect(sdk.hasWallet()).toBe(true);
+
+      // Should be able to fetch pools
+      try {
+        await sdk.fetchPools({ type: 'recent', page: 1, limit: 1 });
+      } catch (error: any) {
+        // Network error is ok, wallet error is not
+        if (error.message) {
+          expect(error.message).not.toContain('Wallet is required');
+        }
+      }
+    });
+  });
+});

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__"]
+}