@gala-chain/launchpad-mcp-server 1.21.6 → 1.22.0

package/src/schemas/common-schemas.ts

@@ -0,0 +1,393 @@
+/**
+ * Common MCP Tool Schema Definitions
+ *
+ * Reusable schema components to eliminate duplication across 37 MCP tools.
+ * These schemas are imported and composed into tool-specific inputSchema definitions.
+ *
+ * UNIFIED APPROACH: Uses SDK Zod schemas as single source of truth, converting to JSON Schema for MCP.
+ *
+ * @see https://modelcontextprotocol.io/docs/concepts/tools
+ */
+
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import {
+  tokenNameSchema,
+  tokenSymbolSchema,
+  tokenDescriptionSchema,
+  flexibleAddressSchema,
+  positiveDecimalStringSchema,
+  fullNameSchema,
+  searchQuerySchema,
+  commentMessageSchema,
+  urlSchema,
+  privateKeySchema,
+  transactionIdSchema,
+  uniqueKeySchema,
+  nonNegativeDecimalStringSchema,
+  isoDateStringSchema,
+  pageNumberSchema,
+  createLimitSchema as zodCreateLimitSchema,
+} from '@gala-chain/launchpad-sdk';
+import { MCP_CONSTRAINTS } from '../utils/constraints.js';
+
+// =============================================================================
+// Helper: Convert Zod schema to MCP-compatible JSON Schema
+// =============================================================================
+
+/**
+ * Converts a Zod schema to JSON Schema format suitable for MCP tool definitions
+ * Extracts only the properties we need (type, pattern, description, etc.)
+ */
+function toMCPSchema(zodSchema: any, customDescription?: string): any {
+  const jsonSchema = zodToJsonSchema(zodSchema, { $refStrategy: 'none' });
+
+  // Extract the schema properties (removing $schema metadata)
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { $schema, ...schemaProps } = jsonSchema;
+
+  // Override description if provided
+  if (customDescription) {
+    schemaProps.description = customDescription;
+  }
+
+  return schemaProps;
+}
+
+// =============================================================================
+// Token Schemas (from SDK)
+// =============================================================================
+
+/**
+ * Token name schema - used in 11+ tools
+ *
+ * @description Generated from SDK tokenNameSchema
+ * @pattern ^[a-zA-Z0-9]{3,20}$
+ * @minLength 3
+ * @maxLength 20
+ * @example "boba", "testtoken", "mytoken123"
+ */
+export const TOKEN_NAME_SCHEMA = toMCPSchema(tokenNameSchema, 'Token name');
+
+/**
+ * Token symbol schema - used in creation tools
+ *
+ * @description Generated from SDK tokenSymbolSchema
+ * @pattern ^[A-Z]{1,8}$
+ * @minLength 1
+ * @maxLength 8
+ * @example "GALA", "TEST", "MTK"
+ */
+export const TOKEN_SYMBOL_SCHEMA = toMCPSchema(tokenSymbolSchema, 'Token symbol');
+
+/**
+ * Token description schema
+ *
+ * @description Generated from SDK tokenDescriptionSchema
+ * @minLength 1
+ * @maxLength 500
+ * @example "A revolutionary new token for decentralized gaming"
+ */
+export const TOKEN_DESCRIPTION_SCHEMA = toMCPSchema(
+  tokenDescriptionSchema,
+  'Token description'
+);
+
+// =============================================================================
+// Authentication & Address Schemas (from SDK)
+// =============================================================================
+
+/**
+ * Private key schema - used in 18+ tools
+ *
+ * @description Generated from SDK privateKeySchema
+ * @pattern ^0x[a-fA-F0-9]{64}$
+ * @example "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
+ * @security Sensitive - should never be logged or exposed
+ */
+export const PRIVATE_KEY_SCHEMA = toMCPSchema(
+  privateKeySchema,
+  'Optional private key override for this operation (format: "0x" + 64 hex characters). If provided, uses this wallet instead of the default MCP server wallet.'
+);
+
+/**
+ * Wallet address schema - supports both Ethereum (0x...) and GalaChain (eth|...) formats
+ *
+ * @description Generated from SDK flexibleAddressSchema
+ * @example "0x1234567890abcdef1234567890abcdef12345678"
+ * @example "eth|1234567890abcdef1234567890abcdef12345678"
+ */
+export const ADDRESS_SCHEMA = toMCPSchema(flexibleAddressSchema, 'Wallet address');
+
+// =============================================================================
+// Amount Schemas (from SDK)
+// =============================================================================
+
+/**
+ * Decimal amount schema - used in trading and transfer tools
+ *
+ * @description Generated from SDK positiveDecimalStringSchema
+ * @pattern ^\d+(\.\d+)?$
+ * @example "100", "1.5", "0.001"
+ * @note Must be positive (greater than zero)
+ */
+export const DECIMAL_AMOUNT_SCHEMA = toMCPSchema(
+  positiveDecimalStringSchema,
+  'Amount in standard decimal format (e.g., "1" for 1 GALA)'
+);
+
+/**
+ * Pre-buy quantity schema - used in token creation
+ *
+ * @description Generated from SDK nonNegativeDecimalStringSchema
+ * @pattern ^\d+(\.\d+)?$
+ * @example "0", "100", "1500.5"
+ * @note Can be zero or positive (non-negative)
+ */
+export const PRE_BUY_QUANTITY_SCHEMA = toMCPSchema(
+  nonNegativeDecimalStringSchema,
+  'Pre-buy quantity as decimal string (defaults to "0")'
+);
+
+/**
+ * Integer amount schema - used in token transfers
+ *
+ * @description Manual schema (not from SDK primitives)
+ * @pattern ^[0-9]+$
+ * @example "100", "1000", "5000000"
+ * @note Integer only (no decimals) - for token transfer operations
+ */
+export const INTEGER_AMOUNT_SCHEMA = {
+  type: 'string' as const,
+  pattern: '^[0-9]+$',
+  description: 'Token amount',
+};
+
+// =============================================================================
+// URL & Text Schemas (from SDK)
+// =============================================================================
+
+/**
+ * URL schema - used for social URLs and token images
+ *
+ * @description Generated from SDK urlSchema
+ * @pattern ^https?:\/\/
+ * @format uri
+ * @example "https://example.com", "https://twitter.com/username"
+ * @note Must start with http:// or https://
+ */
+export const URL_SCHEMA = toMCPSchema(urlSchema);
+
+/**
+ * Comment message schema
+ *
+ * @description Generated from SDK commentMessageSchema
+ * @minLength 1
+ * @maxLength 500
+ * @example "Great token!", "Looking forward to this project"
+ */
+export const COMMENT_MESSAGE_SCHEMA = toMCPSchema(
+  commentMessageSchema,
+  'Comment message text'
+);
+
+/**
+ * Profile name schema
+ *
+ * @description Generated from SDK fullNameSchema
+ * @pattern ^[a-zA-Z\s]+$
+ * @minLength 1
+ * @maxLength 100
+ * @example "John Doe", "Alice Smith"
+ * @note Only letters and spaces allowed
+ */
+export const FULL_NAME_SCHEMA = toMCPSchema(fullNameSchema, 'Full name');
+
+/**
+ * Search query schema - used in user tools
+ *
+ * @description Generated from SDK searchQuerySchema
+ * @minLength 1
+ * @maxLength 100
+ * @example "dragon", "test", "my token"
+ * @note Fuzzy match - case-insensitive, partial matching
+ */
+export const SEARCH_SCHEMA = toMCPSchema(
+  searchQuerySchema,
+  'Optional search query (fuzzy match filter)'
+);
+
+/**
+ * Transaction ID schema - used for getBundlerTransactionResult
+ *
+ * @description Generated from SDK transactionIdSchema
+ * @pattern ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
+ * @format uuid
+ * @example "550e8400-e29b-41d4-a716-446655440000"
+ * @note UUID v4 format - returned from buy(), sell(), launchToken()
+ */
+export const TRANSACTION_ID_SCHEMA = toMCPSchema(
+  transactionIdSchema,
+  'Transaction ID (UUID format) from buy(), sell(), or launchToken()'
+);
+
+/**
+ * Idempotency key schema - used in transfer tools
+ *
+ * @description Generated from SDK uniqueKeySchema
+ * @pattern ^galaconnect-operation-[a-z0-9-]+$
+ * @example "galaconnect-operation-abc123-def456"
+ * @note Prevents duplicate transactions - optional but recommended
+ */
+export const UNIQUE_KEY_SCHEMA = toMCPSchema(uniqueKeySchema, 'Optional idempotency key');
+
+/**
+ * Date-time schema - used in trade and volume queries
+ *
+ * @description Generated from SDK isoDateStringSchema
+ * @format date-time
+ * @example "2024-01-15T14:30:25", "2024-01-15T14:30:25Z"
+ * @note ISO 8601 format
+ */
+export const DATE_TIME_SCHEMA = toMCPSchema(isoDateStringSchema);
+
+// =============================================================================
+// Pagination Schemas (from SDK)
+// =============================================================================
+
+/**
+ * Page number schema - used in ~15 tools
+ *
+ * @description Generated from SDK pageNumberSchema
+ * @type number
+ * @minimum 1
+ * @maximum 1000
+ * @example 1, 2, 50
+ * @note Default: 1 (first page)
+ */
+export const PAGE_SCHEMA = toMCPSchema(pageNumberSchema, 'Page number (default: 1)');
+
+/**
+ * Creates a limit schema with operation-specific maximum
+ * Uses SDK Zod schemas and converts to JSON Schema
+ *
+ * @param operationType - The type of operation (trade, user, pool, comment)
+ * @param defaultLimit - Default limit value (typically 20)
+ * @returns Limit schema with appropriate maximum
+ */
+export function createLimitSchema(
+  operationType: 'trade' | 'user' | 'pool' | 'comment' | 'priceHistory',
+  defaultLimit: number = 20
+): {
+  type: 'number';
+  minimum: number;
+  maximum: number;
+  description: string;
+} {
+  const maxLimits = {
+    trade: MCP_CONSTRAINTS.TRADE_LIMIT, // 20
+    user: MCP_CONSTRAINTS.USER_LIMIT, // 20
+    pool: MCP_CONSTRAINTS.POOL_LIMIT, // 100
+    comment: MCP_CONSTRAINTS.COMMENT_LIMIT, // 50
+    priceHistory: MCP_CONSTRAINTS.PRICE_HISTORY_LIMIT, // 50
+  };
+
+  // Use SDK Zod createLimitSchema and convert to JSON Schema
+  const zodLimit = zodCreateLimitSchema(maxLimits[operationType]);
+  const jsonSchemaLimit = toMCPSchema(
+    zodLimit,
+    `Results per page (default: ${defaultLimit}, maximum: ${maxLimits[operationType]})`
+  );
+
+  return jsonSchemaLimit as {
+    type: 'number';
+    minimum: number;
+    maximum: number;
+    description: string;
+  };
+}
+
+// =============================================================================
+// Trading Schemas (manual - not in SDK primitives)
+// =============================================================================
+
+/**
+ * Slippage tolerance factor schema
+ *
+ * @description Manual schema (not from SDK primitives)
+ * @type number
+ * @minimum 0
+ * @maximum 1
+ * @example 0.01 (1%), 0.05 (5%), 0.1 (10%)
+ * @note Decimal format - protects against price movements during transaction
+ */
+export const SLIPPAGE_TOLERANCE_SCHEMA = {
+  type: 'number' as const,
+  minimum: 0,
+  maximum: 1,
+  description: 'Decimal format (0.05 = 5% slippage)',
+};
+
+/**
+ * Reverse bonding curve fee slippage schema
+ *
+ * @description Manual schema (not from SDK primitives)
+ * @type number
+ * @minimum 0
+ * @maximum 1
+ * @example 0.01 (1% - default), 0.02 (2%), 0.05 (5%)
+ * @note Applied to maxAcceptableReverseBondingCurveFee for additional protection
+ */
+export const RBC_FEE_SLIPPAGE_SCHEMA = {
+  type: 'number' as const,
+  minimum: 0,
+  maximum: 1,
+  description:
+    'Optional slippage tolerance for reverse bonding curve fee (decimal, e.g., 0.01 for 1%). Defaults to 0.01 (1%) if not provided. Applied to maxAcceptableReverseBondingCurveFee to increase max acceptable fee.',
+};
+
+/**
+ * Sort order schema
+ *
+ * @description Manual schema (not from SDK primitives)
+ * @type string
+ * @enum ['ASC', 'DESC']
+ * @example "ASC" (oldest first), "DESC" (newest first - default)
+ * @note Default: DESC (descending, newest first)
+ */
+export const SORT_ORDER_SCHEMA = {
+  type: 'string' as const,
+  enum: ['ASC', 'DESC'],
+  description: 'Sort order (default: DESC)',
+};
+
+/**
+ * Calculation mode schema - for calculateAmountMode parameter
+ *
+ * @description Manual schema (not from SDK primitives)
+ * @type string
+ * @enum ['local', 'external']
+ * @example "local" (instant client-side), "external" (network-based GalaChain)
+ * @note Default: SDK's calculateAmountMode setting
+ * @note Local mode: <1ms, 99.99% accurate | External mode: ~200ms, 100% accurate
+ */
+export const CALCULATION_MODE_SCHEMA = {
+  type: 'string' as const,
+  enum: ['local', 'external'],
+  description: `Calculation mode override (optional - defaults to SDK's calculateAmountMode).
+Use CALCULATION_MODES.LOCAL for instant client-side calculations.
+Use CALCULATION_MODES.EXTERNAL for network-based GalaChain calculations.`,
+};
+
+/**
+ * Current supply schema - for performance optimization
+ *
+ * @description Extends DECIMAL_AMOUNT_SCHEMA
+ * @pattern ^\d+(\.\d+)?$
+ * @example "1000000", "5000000.5"
+ * @note Performance optimization: provide to avoid fetching pool details twice
+ * @note Only used in local calculation mode - auto-fetched if missing
+ */
+export const CURRENT_SUPPLY_SCHEMA = {
+  ...DECIMAL_AMOUNT_SCHEMA,
+  description: 'Current token supply (optional - only used for local mode, auto-fetched if missing)',
+};

package/src/scripts/test-all-prompts.ts

@@ -0,0 +1,184 @@
+/**
+ * Comprehensive Prompt Testing Script
+ * Tests all 14 MCP prompts with v1.5.0 enhancements
+ */
+
+import { getPrompt } from '../../dist/prompts/index.js';
+
+// Color codes for output
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const BLUE = '\x1b[34m';
+const YELLOW = '\x1b[33m';
+const RESET = '\x1b[0m';
+
+interface TestResult {
+  promptName: string;
+  success: boolean;
+  error?: string;
+  messageCount?: number;
+}
+
+const results: TestResult[] = [];
+
+function log(color: string, ...args: any[]) {
+  console.log(color, ...args, RESET);
+}
+
+function testPrompt(name: string, args: Record<string, string> = {}): TestResult {
+  try {
+    const prompt = getPrompt(name);
+
+    if (!prompt) {
+      return {
+        promptName: name,
+        success: false,
+        error: 'Prompt not found in registry',
+      };
+    }
+
+    const messages = prompt.handler(args);
+
+    if (!Array.isArray(messages) || messages.length === 0) {
+      return {
+        promptName: name,
+        success: false,
+        error: 'Handler did not return message array',
+      };
+    }
+
+    // Validate message structure
+    for (const msg of messages) {
+      if (!msg.role || !msg.content || !msg.content.type) {
+        return {
+          promptName: name,
+          success: false,
+          error: 'Invalid message structure',
+        };
+      }
+    }
+
+    return {
+      promptName: name,
+      success: true,
+      messageCount: messages.length,
+    };
+  } catch (error) {
+    return {
+      promptName: name,
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+async function runAllTests() {
+  log(BLUE, '\n🧪 Testing All 14 MCP Prompts with v1.5.0 Enhancements\n');
+  log(BLUE, '━'.repeat(80));
+
+  // Trading Prompts (4)
+  log(YELLOW, '\n📊 Trading Prompts (4)');
+  results.push(testPrompt('galachain-launchpad:analyze-token', { tokenName: 'boba' }));
+  results.push(testPrompt('galachain-launchpad:buy-tokens', { tokenName: 'boba', galaAmount: '100' }));
+  results.push(testPrompt('galachain-launchpad:sell-tokens', { tokenName: 'boba', tokenAmount: '1000' }));
+  results.push(testPrompt('galachain-launchpad:graduate-token', { tokenName: 'boba' }));
+
+  // Portfolio Prompts (5)
+  log(YELLOW, '\n💼 Portfolio Prompts (5)');
+  results.push(testPrompt('galachain-launchpad:portfolio'));
+  results.push(testPrompt('galachain-launchpad:balance', { tokenName: 'boba' }));
+  results.push(testPrompt('galachain-launchpad:tokens-held', { limit: '10' }));
+  results.push(testPrompt('galachain-launchpad:tokens-created'));
+  results.push(testPrompt('galachain-launchpad:profile'));
+
+  // Analysis Prompts (5)
+  log(YELLOW, '\n🔍 Analysis Prompts (5)');
+  results.push(testPrompt('galachain-launchpad:compare-tokens', { token1: 'boba', token2: 'testa' }));
+  results.push(testPrompt('galachain-launchpad:pool-details', { tokenName: 'boba' }));
+  results.push(testPrompt('galachain-launchpad:graduation-status', { tokens: 'boba,testa,dragon' }));
+  results.push(testPrompt('galachain-launchpad:spot-prices', { tokens: 'boba,testa' }));
+  results.push(testPrompt('galachain-launchpad:trade-history', { tokenName: 'boba' }));
+
+  // Print Results
+  log(BLUE, '\n━'.repeat(80));
+  log(BLUE, '\n📋 Test Results Summary\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  results.forEach((result) => {
+    if (result.success) {
+      log(GREEN, `✅ ${result.promptName} - ${result.messageCount} messages`);
+      passed++;
+    } else {
+      log(RED, `❌ ${result.promptName} - ${result.error}`);
+      failed++;
+    }
+  });
+
+  log(BLUE, '\n━'.repeat(80));
+  log(BLUE, `\n📊 Final Score: ${passed}/${results.length} prompts passed\n`);
+
+  if (failed === 0) {
+    log(GREEN, '🎉 ALL PROMPTS WORKING CORRECTLY WITH v1.5.0 ENHANCEMENTS!\n');
+    log(GREEN, '✅ MCP Tool Constants: Working');
+    log(GREEN, '✅ Workflow Templates: Working');
+    log(GREEN, '✅ Input Validation: Working');
+    log(GREEN, '✅ Registry Optimization: Working\n');
+  } else {
+    log(RED, `⚠️  ${failed} prompts failed validation\n`);
+  }
+
+  log(BLUE, '━'.repeat(80));
+
+  // Test specific v1.5.0 features
+  log(YELLOW, '\n🔧 Testing v1.5.0 Specific Features\n');
+
+  // Test O(1) lookup performance
+  log(BLUE, 'Testing O(1) Registry Lookup Performance...');
+  const iterations = 10000;
+  const start = Date.now();
+  for (let i = 0; i < iterations; i++) {
+    getPrompt('galachain-launchpad:analyze-token');
+  }
+  const duration = Date.now() - start;
+
+  if (duration < 100) {
+    log(GREEN, `✅ O(1) Performance: ${iterations} lookups in ${duration}ms (< 100ms threshold)`);
+  } else {
+    log(RED, `❌ O(1) Performance: ${iterations} lookups in ${duration}ms (>= 100ms threshold)`);
+  }
+
+  // Test validation error handling
+  log(BLUE, '\nTesting Input Validation Error Handling...');
+  const invalidTest = testPrompt('galachain-launchpad:analyze-token', { tokenName: 'invalid@#$' });
+  if (!invalidTest.success && invalidTest.error?.includes('Validation error')) {
+    log(GREEN, '✅ Validation: Correctly rejects invalid token names');
+  } else {
+    log(RED, '❌ Validation: Did not catch invalid token name');
+  }
+
+  const emptyTest = testPrompt('galachain-launchpad:buy-tokens', { tokenName: '', galaAmount: '100' });
+  if (!emptyTest.success && emptyTest.error?.includes('Validation error')) {
+    log(GREEN, '✅ Validation: Correctly rejects empty token names');
+  } else {
+    log(RED, '❌ Validation: Did not catch empty token name');
+  }
+
+  const negativeTest = testPrompt('galachain-launchpad:buy-tokens', { tokenName: 'boba', galaAmount: '-100' });
+  if (!negativeTest.success && negativeTest.error?.includes('Validation error')) {
+    log(GREEN, '✅ Validation: Correctly rejects negative amounts');
+  } else {
+    log(RED, '❌ Validation: Did not catch negative amount');
+  }
+
+  log(BLUE, '\n━'.repeat(80));
+  log(GREEN, '\n✨ v1.5.0 Enhancement Verification Complete!\n');
+
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+runAllTests().catch((error) => {
+  log(RED, 'Fatal error:', error);
+  process.exit(1);
+});