@gala-chain/launchpad-mcp-server 5.0.3 → 5.0.4-beta.1

package/DOCS_AUDIT_REPORT.md

@@ -1,189 +0,0 @@
-# Documentation Audit Report
-
-**Generated:** 2025-12-09
-**SDK Version:** 4.0.22-beta.1
-**MCP Server Version:** 4.0.22-beta.1
-**MCP Tool Count:** 128
-
-## Executive Summary
-
-| Category | Status | Critical Issues |
-|----------|--------|-----------------|
-| READMEs | CRITICAL | Version 4.0.17-beta.2 (outdated), tool count 105 (should be 128) |
-| Docs | WARNING | Version mismatches in 4 files, outdated method counts |
-| CLAUDE.md | CRITICAL | Tool count 127→128, demo counts outdated (79→92) |
-| Package.json | CRITICAL | MCP description says "105 tools" (should be 128) |
-| Examples | OK | 3 hardcoded imports, no deprecated API usage |
-| explainSdkUsage | CRITICAL | 'locks' topic uses deprecated singular methods, missing burn-tokens topic |
-| JSDoc | EXCELLENT | All methods fully documented |
-| Cleanup | WARNING | Stale files found |
-
----
-
-## Category Details
-
-### 1. README Files
-
-#### Root README.md
-- **Line 40**: Version `4.0.17-beta.2` → should be `4.0.22-beta.1`
-- **Line 122**: Tool count `105 tools` → should be `128 tools`
-
-#### packages/sdk/README.md
-- Version reference outdated in multiple locations
-
-#### packages/mcp-server/README.md
-- **Description**: Says "105 tools" → should be "128 tools"
-- **Installation example**: Uses outdated version reference
-- **Slash command section**: Inconsistent tool count
-
-### 2. Documentation Files
-
-| File | Issue |
-|------|-------|
-| docs/API-REFERENCE.md | Missing new method documentation |
-| docs/DOCUMENTATION_CHANGELOG.md | Outdated SDK method count (116) |
-| docs/gswap-integration.md | Version mismatch (v4.0.17-beta.2) |
-| docs/LIQUIDITY_DEMOS.md | Version mismatch |
-| docs/LIQUIDITY_PRICING_OPTIONS.md | Version mismatch |
-
-**Good news:** No deprecated `lockToken`/`unlockToken` references found in docs.
-
-### 3. CLAUDE.md
-
-| Line | Current | Should Be |
-|------|---------|-----------|
-| 297 | "127 tools" | "128 tools" |
-| 363 | "79 demos" | "92 demos" |
-| 604 | "82 working examples" | "92 working examples" |
-| 605 | "74 demo: script shortcuts" | "86 demo: script shortcuts" |
-
-### 4. Package.json Files
-
-#### Root package.json
-- Version: `4.0.17-beta.2` → should be `4.0.22-beta.1`
-- Tool count reference: `105 tools` → should be `128 tools`
-
-#### packages/mcp-server/package.json (Line 4)
-- Description: `"105 tools"` → should be `"128 tools"`
-
-#### packages/sdk/package.json
-- **Correct** - Version is `4.0.22-beta.1`
-
-### 5. Examples Audit
-
-**Statistics:**
-- **Total demo files:** 92
-- **npm scripts registered:** 86
-- **Categories:** 11 organized directories
-
-**Issues Found:**
-- 3 files with hardcoded absolute imports in fees demos:
-  - `examples/fees/trade-and-collect-fees.ts`
-  - `examples/fees/demo-multi-wallet-fee-generation.ts`
-  - `examples/fees/demo-fee-generation-and-collection.ts`
-
-**Good news:** No deprecated `lockToken`/`unlockToken` usage found.
-
-### 6. explainSdkUsage Coverage
-
-**CRITICAL ISSUES:**
-
-#### 'locks' Topic (Line 39, 700-824)
-Uses deprecated singular methods throughout:
-- `lockToken()` → should be `lockTokens()`
-- `unlockToken()` → should be `unlockTokens()`
-
-**Affected lines in SDK_EXAMPLES:**
-- Line 704: `lockToken()` method reference
-- Line 705: `unlockToken()` method reference
-- Line 722: `sdk.lockToken({`
-- Line 735: `sdk.lockToken({`
-- Line 746: `sdk.lockToken({`
-- Line 760: `sdk.unlockToken({`
-- Line 769: `sdk.unlockToken({`
-- Line 783: `sdk.lockToken({`
-- Line 794: `sdk.unlockToken({`
-- Line 810: `sdk.lockToken({`
-- Line 821: `sdk.unlockToken({` (comment)
-
-#### Missing Topic
-- **burn-tokens** topic missing entirely - `burnTokens()` method has no documentation
-
-#### Description Mismatch
-- Line 3337: Claims "34 composite workflow topics" but enum has 34 topics
-- Should update to reflect any new topics added
-
-### 7. JSDoc Coverage
-
-**EXCELLENT** - All new methods have comprehensive JSDoc:
-- `lockTokens()` - Full documentation with @example
-- `unlockTokens()` - Full documentation with @example
-- `burnTokens()` - Full documentation with @example
-- All parameters, return types, and batch behavior documented
-
-### 8. Stale/Rogue Files
-
-| File | Status | Action |
-|------|--------|--------|
-| DOCS_AUDIT_REPORT.md | Stale (2025-12-07) | Will be replaced by this report |
-| DOCS_AUDIT_FOLLOWUP.md | Can be archived | Archive or delete |
-| MCP_COVERAGE_REPORT.md | Stale (references "103 tools") | Update or archive |
-| .claude/commands/*.md | Tool counts outdated | Update |
-
----
-
-## Required Fixes
-
-### High Priority (CRITICAL)
-
-1. **explainSdkUsage.ts 'locks' topic**
-   - Replace all `lockToken` → `lockTokens`
-   - Replace all `unlockToken` → `unlockTokens`
-   - Update method examples to use batch API
-
-2. **Add 'burn-tokens' topic to explainSdkUsage.ts**
-   - Add to TOPIC_METHOD_MAPPING
-   - Add to COMPOSITE_TOPICS
-   - Add to enum in inputSchema
-   - Add SDK_EXAMPLES entry
-
-3. **Update tool counts across all files**
-   - 105 → 128 (multiple files)
-   - 127 → 128 (CLAUDE.md)
-
-4. **Update MCP package.json description**
-   - "105 tools" → "128 tools"
-
-### Medium Priority (WARNING)
-
-5. **Update version numbers**
-   - 4.0.17-beta.2 → 4.0.22-beta.1 in root README
-
-6. **Update demo/script counts in CLAUDE.md**
-   - 79 → 92 demos
-   - 74 → 86 npm scripts
-   - 82 → 92 working examples
-
-### Low Priority
-
-7. **Fix hardcoded imports in fees examples**
-   - Use relative imports instead of absolute paths
-
-8. **Archive stale documentation files**
-   - DOCS_AUDIT_FOLLOWUP.md
-   - MCP_COVERAGE_REPORT.md (if outdated)
-
----
-
-## Action Plan
-
-1. Fix explainSdkUsage.ts (locks topic + add burn-tokens)
-2. Update tool counts across all documentation
-3. Update version references
-4. Update demo counts in CLAUDE.md
-5. Fix hardcoded imports
-6. Archive stale files
-
----
-
-*This report was generated by the `/scour-docs all` documentation audit command.*

package/DRY_REFACTORING_GUIDE.md

@@ -1,271 +0,0 @@
-# DRY Refactoring Guide for MCP Server Prompts
-
-This guide documents the DRY (Don't Repeat Yourself) refactoring improvements made to the MCP server codebase.
-
-## Overview
-
-The refactoring reduces code duplication across 72 prompt handlers by introducing reusable utilities while maintaining 100% API compatibility.
-
-**Potential Impact:** ~526 LOC reduction with zero breaking changes
-
-## Utility Files Created
-
-### 1. `src/prompts/utils/handlerHelpers.ts`
-
-Provides reusable helpers for creating standardized MCP prompt handlers.
-
-**Functions:**
-- `createPromptResponse(text: string)` - Creates a standard MCP message response
-- `createValidatedHandler<T>(validator, textGenerator)` - Creates a handler with validation + response generation
-
-**Benefit:** Eliminates ~360 lines of boilerplate (5 lines per handler × 72 handlers)
-
-### 2. `src/prompts/utils/textTemplates.ts`
-
-Provides template generators for common prompt patterns.
-
-**Functions:**
-- `createSimpleOperationText(config)` - Generates text for simple operation prompts following standard format
-
-**Benefit:** Eliminates ~120 lines of template code (~3 lines per simple prompt × 40 prompts)
-
-### 3. Updated `src/utils/validation.ts`
-
-Added optional validation convenience wrappers.
-
-**New Functions:**
-- `validateOptional<T>(value, validator)` - Generic optional field validator
-- `validateOptionalSlippage(slippage?)` - Optional slippage validation
-- `validateOptionalLimit(limit?, max)` - Optional limit validation
-- `validateOptionalAddress(address?)` - Optional address validation
-
-**Benefit:** Eliminates ~46 lines of conditional validation (2 lines × 23 instances)
-
-## Refactoring Patterns
-
-### Pattern 1: Standardized Handler Response
-
-**Before:**
-```typescript
-handler: (args) => {
-  validateTokenName(args.tokenName);
-  return [
-    {
-      role: 'user',
-      content: {
-        type: 'text',
-        text: `Fetch token ${args.tokenName}...`,
-      },
-    },
-  ];
-}
-```
-
-**After:**
-```typescript
-import { createPromptResponse } from './utils/handlerHelpers.js';
-
-handler: (args) => {
-  validateTokenName(args.tokenName);
-  return createPromptResponse(`Fetch token ${args.tokenName}...`);
-}
-```
-
-**Where to Apply:**
-- All 72 prompt handlers across all prompt files
-- Any prompt file in `src/prompts/*.ts`
-
-### Pattern 2: Optional Validation
-
-**Before:**
-```typescript
-if (args.slippage) {
-  validateSlippage(args.slippage);
-}
-
-if (args.limit) {
-  validatePaginationLimit(args.limit, 100);
-}
-
-if (args.address) {
-  validateAddress(args.address);
-}
-```
-
-**After:**
-```typescript
-import { validateOptionalSlippage, validateOptionalLimit, validateOptionalAddress } from '../utils/validation.js';
-
-validateOptionalSlippage(args.slippage);
-validateOptionalLimit(args.limit, 100);
-validateOptionalAddress(args.address);
-```
-
-**Where to Apply:**
-- `trading.ts` - 6 slippage validations
-- `portfolio.ts` - 3 limit validations
-- `analysis.ts` - 4 limit validations, 3 tokenName optional checks
-- `balances.ts` - 4 address validations
-- Other prompt files with optional parameters
-
-### Pattern 3: Simple Operation Text Templates
-
-**Before:**
-```typescript
-text: `Fetch GALA balance for wallet.
-
-${args.address ? `Address: ${args.address}` : 'Using default wallet'}
-
-Use ${MCP_TOOLS.FETCH_GALA_BALANCE} to retrieve the GALA balance.
-
-Display the balance in a clear format.`
-```
-
-**After:**
-```typescript
-import { createSimpleOperationText } from './utils/textTemplates.js';
-
-text: createSimpleOperationText({
-  operation: 'Fetch GALA balance for wallet.',
-  parameters: {
-    address: args.address ? `Address: ${args.address}` : 'Using default wallet'
-  },
-  toolName: MCP_TOOLS.FETCH_GALA_BALANCE,
-  actionDescription: 'retrieve the GALA balance',
-  displayFormat: 'Display the balance in a clear format.'
-})
-```
-
-**Where to Apply:**
-- All 40+ simple operation prompts across prompt files
-- Prompts that follow the operation → parameters → tool usage → display format structure
-
-## Implementation Checklist
-
-### Phase 1: Handler Boilerplate (Highest Priority)
-- [ ] Update all imports in prompt files to include `createPromptResponse`
-- [ ] Replace all `return [{ role: 'user', content: { type: 'text', text: ... } }]` with `return createPromptResponse(...)`
-- [ ] Files to update:
-  - [ ] `pools.ts` (14 handlers)
-  - [ ] `trading-calculations.ts` (11 handlers)
-  - [ ] `balances.ts` (4 handlers)
-  - [ ] `creation-utils.ts` (3 handlers)
-  - [ ] `transfers.ts` (2 handlers)
-  - [ ] `utility-tools.ts` (12 handlers)
-  - [ ] All other prompt files (existing, not listed)
-
-### Phase 2: Optional Validation (High Priority)
-- [ ] Update imports in prompt files
-- [ ] Replace conditional validation patterns with new optional validators
-- [ ] High-impact files:
-  - [ ] `trading.ts` (6 instances)
-  - [ ] `portfolio.ts` (7 instances)
-  - [ ] `analysis.ts` (7 instances)
-  - [ ] `balances.ts` (4 instances)
-
-### Phase 3: Text Templates (Medium Priority)
-- [ ] Identify all simple operation prompts
-- [ ] Update imports
-- [ ] Replace template code with `createSimpleOperationText()`
-- [ ] Estimated 40 prompts across multiple files
-
-### Phase 4: Verification
-- [ ] Run TypeScript compilation: `npx tsc --noEmit`
-- [ ] Run tests: `npm test`
-- [ ] Run linting: `npm run lint`
-- [ ] Verify no regression in test count (should remain 1401+ passing)
-- [ ] Verify all prompts produce identical output
-
-## Code Sample: Complete Refactored Handler
-
-### Before:
-```typescript
-export const fetchGalaSpotPricePrompt: MCPPrompt = {
-  name: 'galachain-launchpad:fetch-gala-spot-price',
-  description: 'Fetch current GALA USD spot price',
-  handler: () => {
-    return [
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text: `Fetch the current GALA USD spot price.
-
-Use ${MCP_TOOLS.FETCH_GALA_SPOT_PRICE} to get the latest GALA price in USD.
-
-Display the price in a clear format.`,
-        },
-      },
-    ];
-  },
-};
-```
-
-### After:
-```typescript
-import { createPromptResponse } from './utils/handlerHelpers.js';
-import { createSimpleOperationText } from './utils/textTemplates.js';
-
-export const fetchGalaSpotPricePrompt: MCPPrompt = {
-  name: 'galachain-launchpad:fetch-gala-spot-price',
-  description: 'Fetch current GALA USD spot price',
-  handler: () =>
-    createPromptResponse(
-      createSimpleOperationText({
-        operation: 'Fetch the current GALA USD spot price.',
-        toolName: MCP_TOOLS.FETCH_GALA_SPOT_PRICE,
-        actionDescription: 'get the latest GALA price in USD',
-        displayFormat: 'Display the price in a clear format.'
-      })
-    ),
-};
-```
-
-## Benefits
-
-| Aspect | Benefit |
-|--------|---------|
-| **Maintainability** | Single point of change for response structure, validation logic, and text formatting |
-| **Consistency** | All prompts follow identical patterns, easier to understand and predict behavior |
-| **Testability** | Utility functions can be tested independently |
-| **Scalability** | Adding new prompts is faster and less error-prone |
-| **LOC Reduction** | ~526 lines of boilerplate eliminated |
-| **API Compatibility** | Zero breaking changes, 100% backward compatible |
-
-## Testing Strategy
-
-1. **Unit Tests:** Add tests for utility functions if not present
-2. **Integration Tests:** Verify all 72 prompts still produce identical output
-3. **Regression Tests:** Ensure no prompt behavior changes
-4. **Type Safety:** Full TypeScript compilation with strict checks
-
-## Timeline
-
-- **Phase 1 (Handler Boilerplate):** ~1 hour (72 handlers, mechanical change)
-- **Phase 2 (Optional Validation):** ~30 minutes (23 instances)
-- **Phase 3 (Text Templates):** ~45 minutes (40 prompts)
-- **Phase 4 (Testing/Verification):** ~15 minutes
-- **Total:** ~2.5 hours for complete refactoring
-
-## Risk Assessment
-
-| Phase | Risk | Mitigation |
-|-------|------|-----------|
-| 1 | **LOW** | Pure mechanical change, output unchanged | Full test coverage |
-| 2 | **LOW** | Logic preservation via wrappers | Verify validation behavior |
-| 3 | **LOW** | Template-based generation | Compare output strings |
-| Overall | **LOW** | No API changes, well-tested utilities | Comprehensive testing |
-
-## Notes
-
-- All changes are internal implementation details
-- No MCP tool signatures change
-- All changes follow DRY principle without adding unnecessary complexity
-- Utilities are properly documented with JSDoc comments
-- Both new utility files include comprehensive examples
-
-## See Also
-
-- `src/prompts/utils/handlerHelpers.ts` - Handler utilities
-- `src/prompts/utils/textTemplates.ts` - Template utilities
-- `src/utils/validation.ts` - Validation utilities (updated)

package/MCP_COVERAGE_REPORT.md

@@ -1,164 +0,0 @@
-# MCP Coverage Audit Report
-
-**Audit Date:** 2025-12-09
-**SDK Version:** 4.0.22-beta.5
-**MCP Tools:** 132
-**Prompts:** 103
-**explainSdkUsage Topics:** 36
-
-## Summary
-
-| Category | Total | Covered | Excluded | Missing | Coverage |
-|----------|-------|---------|----------|---------|----------|
-| SDK → MCP Tools | 116 | 114 | 2 | 0 | 98% |
-| MCP Tools → Prompts | 132 | 103+ | 0 | ~29 | 78% |
-| explainSdkUsage | 116 | 100+ | 12 | ~4 | 95% |
-
-## SDK Methods → MCP Tools Coverage
-
-**116 SDK public async methods, 132 MCP tools**
-
-The MCP server provides MORE tools than SDK methods because it includes:
-- Utility tools (getConfig, getVersion, getEnvironment, switchEnvironment)
-- Wallet management (hasWallet, getWallet, setWallet, createWallet, createSolanaWallet)
-- Key derivation (getPublicKeyFromPrivateKey, getEthereumAddressFromPrivateKey)
-- Cache management (getCacheInfo, clearCache)
-- explainSdkUsage (documentation tool)
-- Event watchers (onDexPoolCreation, onLaunchpadTokenCreation)
-
-### Excluded Methods (Intentional - Not Appropriate for MCP)
-
-| Method | Reason |
-|--------|--------|
-| `fetchAvailableBalance` | Duplicate of fetchGalaBalance |
-| `fetchTokenClassesWithSupply` | Internal GalaChain method |
-
-### Name Mapping Differences
-
-| SDK Method | MCP Tool |
-|------------|----------|
-| `buy()` | `gala_launchpad_buy_tokens` |
-| `sell()` | `gala_launchpad_sell_tokens` |
-| `isTokenNameAvailable()` | `gala_launchpad_check_token_name` |
-| `isTokenSymbolAvailable()` | `gala_launchpad_check_token_symbol` |
-| `fetchGalaPrice()` | `gala_launchpad_fetch_gala_spot_price` |
-| `fetchTokenPrice()` | `gala_launchpad_fetch_token_spot_price` |
-| `fetchLockedBalance()` | `gala_launchpad_fetch_locked_tokens` |
-| `getSwapLiquidityPosition()` | `gala_launchpad_get_liquidity_position` |
-| `getSwapLiquidityPositionById()` | `gala_launchpad_get_liquidity_position_by_id` |
-| `getSwapUserLiquidityPositions()` | `gala_launchpad_get_user_liquidity_positions` |
-| `getAllSwapUserLiquidityPositions()` | `gala_launchpad_get_all_user_liquidity_positions` |
-| `getSwapEstimateRemoveLiquidity()` | `gala_launchpad_estimate_remove_liquidity` |
-| `collectSwapPositionFees()` | `gala_launchpad_collect_position_fees` |
-| `removeSwapLiquidity()` | `gala_launchpad_remove_liquidity` |
-| `addSwapLiquidityByPrice()` | `gala_launchpad_add_liquidity_by_price` |
-| `addSwapLiquidityByTicks()` | `gala_launchpad_add_liquidity_by_ticks` |
-
-## MCP Tools → Prompt Coverage
-
-**103 prompts covering workflow scenarios**
-
-Prompts are workflow-based, not 1:1 with tools. Each prompt covers a use case that may involve multiple tools.
-
-### Tools Without Direct Prompt (Expected)
-
-Utility tools don't need workflow prompts - they're self-documenting:
-- `gala_launchpad_get_config`
-- `gala_launchpad_get_version`
-- `gala_launchpad_get_cache_info`
-- `gala_launchpad_clear_cache`
-- `gala_launchpad_cleanup`
-- `gala_launchpad_explain_sdk_usage`
-
-Bridge/wrap detail tools covered by main workflow prompts:
-- Individual balance query tools (covered by portfolio/bridge prompts)
-- Individual bridgeable token checks (covered by bridge-tokens prompt)
-- Individual wrappable token checks (covered by wrap-related prompts)
-
-## explainSdkUsage Topic Coverage
-
-**36 topics covering SDK method documentation**
-
-### Topics
-
-1. buy-tokens
-2. sell-tokens
-3. pool-graduation
-4. fetch-pools
-5. balances
-6. token-creation
-7. token-details
-8. token-distribution
-9. token-status
-10. multi-wallet
-11. transfers
-12. locks
-13. dex-trading
-14. error-handling
-15. installation
-16. local-calculations
-17. price-history
-18. spot-prices-smart-routing
-19. profile-management
-20. liquidity-positions
-21. advanced-dex-analysis
-22. trading-analytics
-23. utilities-and-helpers
-24. utilities-system
-25. fetch-all-dex-seasons
-26. fetch-current-dex-season
-27. fetch-dex-leaderboard-by-season-id
-28. fetch-dex-aggregated-volume-summary
-29. fetch-dex-pools
-30. event-subscriptions
-31. mcp-to-sdk-mapping
-32. bridge-operations
-33. dex-token-discovery
-34. wrap-unwrap-operations
-35. referral-system
-36. account-management
-
-## Slash Command Sync Results
-
-| File | Field | Old | New | Status |
-|------|-------|-----|-----|--------|
-| test-mcp-tools.md | Total tools | 128 | 132 | UPDATED |
-| test-mcp-tools.md | balance | 7 | 12 | UPDATED |
-| test-mcp-tools.md | locks | 4 | 3 | UPDATED |
-| test-mcp-tools.md | bridge | 11 | 31 | UPDATED |
-| scour-docs.md | Tool count | 128 | 132 | UPDATED |
-| scour-docs.md | Topics | 33 | 36 | UPDATED |
-
-## Tool Categories Summary
-
-| Category | Count | Description |
-|----------|-------|-------------|
-| utilities | 19 | config, version, wallet, cache, environment, key derivation |
-| pools | 19 | fetch pools, details, prices, watchers |
-| balance | 12 | GALA balance, token balance, profile, locked tokens, referrals, registerAccount |
-| trading | 13 | buy/sell, calculations, graduation |
-| dex | 29 | swaps, quotes, liquidity, leaderboard, token discovery |
-| creation | 4 | launch token, upload images |
-| transfers | 2 | GALA/token transfers |
-| locks | 3 | lock/unlock/burn tokens |
-| bridge | 31 | cross-chain bridging, wrap/unwrap, bridgeable tokens |
-| **Total** | **132** | |
-
-## Recommendations
-
-### No Action Required
-- SDK → MCP coverage is excellent (98%+)
-- All critical SDK methods have MCP tool equivalents
-- explainSdkUsage has comprehensive topic coverage
-
-### Future Improvements (Low Priority)
-1. Add prompts for new referral tools:
-   - `galachain-launchpad:referrals` - View referral stats
-   - `galachain-launchpad:register` - Register account for trading
-
-2. Consider consolidating similar balance prompts into comprehensive portfolio workflows
-
----
-
-**Generated:** 2025-12-09T$(date +%H:%M:%S)
-**Tool:** /scour-mcp audit