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

package/docs/CONSTRAINTS-REFERENCE.md

@@ -1,454 +0,0 @@
-# Constraints Reference - SDK to MCP Server Mapping
-
-This document provides a comprehensive reference for all constraint mappings between the Gala Launchpad SDK and the MCP Server tool schemas. It serves as the single source of truth for validation limits and helps maintain consistency across the codebase.
-
-## Overview
-
-The MCP Server tool schemas must match the SDK's internal constraint definitions to prevent validation errors. This document tracks all constraint sources and their proper usage in MCP tool schemas.
-
----
-
-## Constraint Sources in SDK
-
-### 1. Trade Constraints
-
-**Source File:** `packages/sdk/src/types/trade.dto.ts`
-
-**Lines:** 325-355
-
-```typescript
-export const TRADE_CONSTRAINTS = {
-  PAGINATION: {
-    MAX_LIMIT: 20,
-    DEFAULT_LIMIT: 20,
-    MIN_LIMIT: 1,
-    MAX_PAGE: 1000,
-    MIN_PAGE: 1,
-  },
-  // ... other trade constraints
-} as const;
-```
-
-**Affected MCP Tools:**
-- `gala_launchpad_fetch_trades` (packages/mcp-server/src/tools/trading/index.ts:271)
-
-**Usage in MCP Schema:**
-```typescript
-limit: {
-  type: 'number',
-  minimum: 1,
-  maximum: 20,  // TRADE_CONSTRAINTS.PAGINATION.MAX_LIMIT
-  description: 'Results per page (default: 20, maximum: 20)',
-}
-```
-
----
-
-### 2. User Constraints
-
-**Source File:** `packages/sdk/src/types/user.dto.ts`
-
-**Lines:** 291-307
-
-```typescript
-export const USER_CONSTRAINTS = {
-  PAGINATION: {
-    MAX_LIMIT: 20,
-    DEFAULT_LIMIT: 20,
-    MIN_LIMIT: 1,
-    MAX_PAGE: 1000,
-    MIN_PAGE: 1,
-  },
-  // ... other user constraints
-} as const;
-```
-
-**Affected MCP Tools:**
-- `gala_launchpad_fetch_tokens_held` (packages/mcp-server/src/tools/balance/index.ts)
-- `gala_launchpad_fetch_tokens_created` (packages/mcp-server/src/tools/balance/index.ts)
-
-**Usage in MCP Schema:**
-```typescript
-limit: {
-  type: 'number',
-  minimum: 1,
-  maximum: 20,  // USER_CONSTRAINTS.PAGINATION.MAX_LIMIT
-  description: 'Results per page (default: 20, maximum: 20)',
-}
-```
-
----
-
-### 3. General Pagination Constraints
-
-**Source File:** `packages/sdk/src/types/launchpad.dto.ts`
-
-**Lines:** 583-592
-
-```typescript
-export const PAGINATION_CONSTRAINTS = {
-  MAX_LIMIT: 100,
-  DEFAULT_LIMIT: 20,
-  MIN_LIMIT: 1,
-  MAX_PAGE: 1000,
-  MIN_PAGE: 1,
-} as const;
-```
-
-**Affected MCP Tools:**
-- `gala_launchpad_fetch_pools` (packages/mcp-server/src/tools/pools/index.ts:34)
-
-**Usage in MCP Schema:**
-```typescript
-limit: {
-  type: 'number',
-  minimum: 1,
-  maximum: 100,  // PAGINATION_CONSTRAINTS.MAX_LIMIT
-  description: 'Results per page (default: 20, maximum: 100)',
-}
-```
-
----
-
-### 4. Comment Constraints
-
-**Source File:** `packages/sdk/src/types/comment.dto.ts`
-
-**Lines:** 149
-
-```typescript
-export const COMMENT_CONSTRAINTS = {
-  PAGINATION: {
-    MAX_LIMIT: 50,
-    DEFAULT_LIMIT: 20,
-    MIN_LIMIT: 1,
-    MAX_PAGE: 1000,
-    MIN_PAGE: 1,
-  },
-  // ... other comment constraints
-} as const;
-```
-
-**Affected MCP Tools:**
-- `gala_launchpad_fetch_comments` (packages/mcp-server/src/tools/social/index.ts:58)
-
-**Usage in MCP Schema:**
-```typescript
-limit: {
-  type: 'number',
-  minimum: 1,
-  maximum: 50,  // COMMENT_CONSTRAINTS.PAGINATION.MAX_LIMIT
-  description: 'Results per page (default: 20, maximum: 50)',
-}
-```
-
----
-
-## MCP Constraints Utility
-
-**File:** `packages/mcp-server/src/utils/constraints.ts`
-
-This utility file centralizes all constraint constants for use in MCP tool schemas:
-
-```typescript
-export const MCP_CONSTRAINTS = {
-  /**
-   * Trade operations limit (fetchTrades)
-   * Source: TRADE_CONSTRAINTS.PAGINATION.MAX_LIMIT
-   * SDK File: packages/sdk/src/types/trade.dto.ts:331
-   */
-  TRADE_LIMIT: 20,
-
-  /**
-   * User operations limit (fetchTokensHeld, fetchTokensCreated)
-   * Source: USER_CONSTRAINTS.PAGINATION.MAX_LIMIT
-   * SDK File: packages/sdk/src/types/user.dto.ts:297
-   */
-  USER_LIMIT: 20,
-
-  /**
-   * General pool operations limit (fetchPools)
-   * Source: PAGINATION_CONSTRAINTS.MAX_LIMIT
-   * SDK File: packages/sdk/src/types/launchpad.dto.ts:587
-   */
-  POOL_LIMIT: 100,
-
-  /**
-   * Comment operations limit (fetchComments)
-   * Source: COMMENT_CONSTRAINTS.PAGINATION.MAX_LIMIT
-   * SDK File: packages/sdk/src/types/comment.dto.ts:149
-   */
-  COMMENT_LIMIT: 50,
-
-  /**
-   * Minimum limit for all pagination operations
-   */
-  MIN_LIMIT: 1,
-
-  /**
-   * Minimum page number for all pagination operations
-   */
-  MIN_PAGE: 1,
-
-  /**
-   * Maximum page number for all pagination operations
-   */
-  MAX_PAGE: 1000,
-} as const;
-```
-
----
-
-## Complete Mapping Table
-
-| SDK Constraint | Value | MCP Constant | MCP Tools |
-|---------------|-------|--------------|-----------|
-| `TRADE_CONSTRAINTS.PAGINATION.MAX_LIMIT` | 20 | `MCP_CONSTRAINTS.TRADE_LIMIT` | `gala_launchpad_fetch_trades` |
-| `USER_CONSTRAINTS.PAGINATION.MAX_LIMIT` | 20 | `MCP_CONSTRAINTS.USER_LIMIT` | `gala_launchpad_fetch_tokens_held`<br>`gala_launchpad_fetch_tokens_created` |
-| `PAGINATION_CONSTRAINTS.MAX_LIMIT` | 100 | `MCP_CONSTRAINTS.POOL_LIMIT` | `gala_launchpad_fetch_pools` |
-| `COMMENT_CONSTRAINTS.PAGINATION.MAX_LIMIT` | 50 | `MCP_CONSTRAINTS.COMMENT_LIMIT` | `gala_launchpad_fetch_comments` |
-| All constraints `.MIN_LIMIT` | 1 | `MCP_CONSTRAINTS.MIN_LIMIT` | All pagination tools |
-| All constraints `.MIN_PAGE` | 1 | `MCP_CONSTRAINTS.MIN_PAGE` | All pagination tools |
-| All constraints `.MAX_PAGE` | 1000 | `MCP_CONSTRAINTS.MAX_PAGE` | All pagination tools |
-
----
-
-## Validation Pattern Examples
-
-### Trading Tools Example
-
-```typescript
-import { MCP_CONSTRAINTS } from '../../utils/constraints.js';
-
-export const fetchTradesTool: MCPTool = {
-  inputSchema: {
-    properties: {
-      limit: {
-        type: 'number',
-        minimum: MCP_CONSTRAINTS.MIN_LIMIT,
-        maximum: MCP_CONSTRAINTS.TRADE_LIMIT,
-        description: `Results per page (default: 20, maximum: ${MCP_CONSTRAINTS.TRADE_LIMIT})`
-      },
-      page: {
-        type: 'number',
-        minimum: MCP_CONSTRAINTS.MIN_PAGE,
-        maximum: MCP_CONSTRAINTS.MAX_PAGE,
-        description: 'Page number (default: 1)'
-      }
-    }
-  }
-};
-```
-
-### Balance/User Tools Example
-
-```typescript
-export const fetchTokensHeldTool: MCPTool = {
-  inputSchema: {
-    properties: {
-      limit: {
-        type: 'number',
-        minimum: MCP_CONSTRAINTS.MIN_LIMIT,
-        maximum: MCP_CONSTRAINTS.USER_LIMIT,
-        description: `Results per page (default: 20, maximum: ${MCP_CONSTRAINTS.USER_LIMIT})`
-      }
-    }
-  }
-};
-```
-
-### Pool Tools Example
-
-```typescript
-export const fetchPoolsTool: MCPTool = {
-  inputSchema: {
-    properties: {
-      limit: {
-        type: 'number',
-        minimum: MCP_CONSTRAINTS.MIN_LIMIT,
-        maximum: MCP_CONSTRAINTS.POOL_LIMIT,
-        description: `Results per page (default: 20, maximum: ${MCP_CONSTRAINTS.POOL_LIMIT})`
-      }
-    }
-  }
-};
-```
-
-### Social Tools Example
-
-```typescript
-export const fetchCommentsTool: MCPTool = {
-  inputSchema: {
-    properties: {
-      limit: {
-        type: 'number',
-        minimum: MCP_CONSTRAINTS.MIN_LIMIT,
-        maximum: MCP_CONSTRAINTS.COMMENT_LIMIT,
-        description: `Results per page (default: 20, maximum: ${MCP_CONSTRAINTS.COMMENT_LIMIT})`
-      }
-    }
-  }
-};
-```
-
----
-
-## Validation Helpers
-
-The constraints utility provides validation helpers for programmatic checks:
-
-### `isValidLimit(limit: number, operationType: string): boolean`
-
-Validates if a limit value is valid for a specific operation type.
-
-```typescript
-import { isValidLimit } from './utils/constraints.js';
-
-// Returns true if valid, false otherwise
-isValidLimit(20, 'trade')    // true
-isValidLimit(100, 'trade')   // false (max is 20)
-isValidLimit(100, 'pool')    // true
-isValidLimit(50, 'comment')  // true
-```
-
-### `getMaxLimit(operationType: string): number`
-
-Returns the maximum limit for a specific operation type.
-
-```typescript
-import { getMaxLimit } from './utils/constraints.js';
-
-getMaxLimit('trade')    // 20
-getMaxLimit('user')     // 20
-getMaxLimit('pool')     // 100
-getMaxLimit('comment')  // 50
-```
-
----
-
-## Maintenance Guidelines
-
-### When SDK Constraints Change
-
-If the SDK updates any constraint values, follow these steps:
-
-1. **Update `packages/mcp-server/src/utils/constraints.ts`:**
-   - Update the relevant constant value
-   - Update the JSDoc comment with new SDK file line number
-   - Update usage examples if needed
-
-2. **Verify MCP Tool Schemas:**
-   - Search for all usages of the changed constraint
-   - Ensure all tool schemas reference the constant correctly
-   - Update inline comments if needed
-
-3. **Update This Documentation:**
-   - Update the constraint value in all tables
-   - Update the line numbers in "Constraint Sources" section
-   - Add changelog entry if significant change
-
-4. **Test Validation:**
-   - Run MCP server with edge case limit values
-   - Verify validation errors match SDK errors
-   - Test with AI agents to ensure no surprises
-
-### Adding New Constraints
-
-When adding new constraint types:
-
-1. **Add to `constraints.ts`:**
-   - Add constant with descriptive name
-   - Add JSDoc with SDK source reference
-   - Add validation helper if needed
-   - Export constant
-
-2. **Document in This File:**
-   - Add to "Constraint Sources" section
-   - Add to "Complete Mapping Table"
-   - Add usage example
-   - Add to validation helpers if applicable
-
-3. **Update MCP Tools:**
-   - Apply new constraint to relevant tools
-   - Update inline comments
-   - Verify against SDK behavior
-
----
-
-## Testing Constraint Sync
-
-### Manual Testing Checklist
-
-Test each operation type with boundary values:
-
-```typescript
-// Trade Operations (Max: 20)
-gala_launchpad_fetch_trades({ limit: 20 })  // Should succeed
-gala_launchpad_fetch_trades({ limit: 21 })  // Should fail validation
-
-// User Operations (Max: 20)
-gala_launchpad_fetch_tokens_held({ limit: 20 })   // Should succeed
-gala_launchpad_fetch_tokens_held({ limit: 21 })   // Should fail validation
-
-// Pool Operations (Max: 100)
-gala_launchpad_fetch_pools({ limit: 100 })  // Should succeed
-gala_launchpad_fetch_pools({ limit: 101 })  // Should fail validation
-
-// Comment Operations (Max: 50)
-gala_launchpad_fetch_comments({ limit: 50 })  // Should succeed
-gala_launchpad_fetch_comments({ limit: 51 })  // Should fail validation
-```
-
-### Automated Testing
-
-Consider adding constraint validation tests:
-
-```typescript
-describe('MCP Constraint Validation', () => {
-  it('should reject trades with limit > 20', () => {
-    expect(() => fetchTradesValidation({ limit: 21 })).toThrow();
-  });
-
-  it('should accept pools with limit = 100', () => {
-    expect(() => fetchPoolsValidation({ limit: 100 })).not.toThrow();
-  });
-
-  // ... more tests
-});
-```
-
----
-
-## Changelog
-
-### 2025-09-30
-- **BREAKING:** Fixed constraint mismatches across all MCP tools
-  - `fetchTrades`: Reduced limit from 100 → 20 (matches SDK)
-  - `fetchTokensHeld`: Reduced limit from 100 → 20 (matches SDK)
-  - `fetchTokensCreated`: Reduced limit from 100 → 20 (matches SDK)
-  - `fetchComments`: Reduced limit from 100 → 50 (matches SDK)
-  - `fetchPools`: Verified limit 100 is correct (matches SDK)
-- Created `packages/mcp-server/src/utils/constraints.ts` utility
-- Added inline comments linking to SDK constraint sources
-- Created this comprehensive constraints reference document
-
----
-
-## Related Documentation
-
-- [AI Agent Patterns](./AI-AGENT-PATTERNS.md) - Common workflows and gotchas
-- [MCP Server README](../README.md) - Installation and usage guide
-- [SDK Documentation](../../sdk/README.md) - Full SDK reference
-
----
-
-## Quick Reference
-
-| Operation | Max Limit | SDK Source |
-|-----------|-----------|------------|
-| Trade | 20 | `TRADE_CONSTRAINTS.PAGINATION.MAX_LIMIT` |
-| User | 20 | `USER_CONSTRAINTS.PAGINATION.MAX_LIMIT` |
-| Pool | 100 | `PAGINATION_CONSTRAINTS.MAX_LIMIT` |
-| Comment | 50 | `COMMENT_CONSTRAINTS.PAGINATION.MAX_LIMIT` |
-
-**Golden Rule:** When in doubt, check `packages/mcp-server/src/utils/constraints.ts` first!