customable-mcp/changelog-mcp

Fork 0

⚠️ Add Pagination Support to Prevent Token Overflow #9

New issue

Open

opened 2025-10-10 09:17:50 +02:00 by jack · 0 comments

jack commented

2025-10-10 09:17:50 +02:00

Owner

🚨 Critical Issue

Problem

Currently, tools that return large datasets can cause token overflow in the MCP protocol, leading to:

❌ Truncated responses
❌ Lost data
❌ Poor user experience
❌ Unusable results for large datasets

Affected Tools in This MCP

list_tags - Could return hundreds of tags
get_commits - Could return thousands of commits
generate_changelog - Large changelog content
analyze_commits - Analysis of many commits

Example: Token Overflow Problem

Current Behavior (❌ Bad)

// get_commits - could return 10,000+ commits!
const commits = await getCommits('v1.0.0', 'v2.0.0');
// Response: 8,472 commits = Token overflow!

With Pagination (✅ Good)

// Paginated approach
const commits = await getCommits('v1.0.0', 'v2.0.0', {
  limit: 100,
  offset: 0
});
// Response: { items: [...100 commits], pagination: { total: 8472, hasMore: true } }

💡 Proposed Solution

Standard Pagination Interface

interface PaginationParams {
  limit?: number;      // Max items to return (default: 100, max: 1000)
  offset?: number;     // Number of items to skip (default: 0)
}

interface PaginatedResponse<T> {
  items: T[];
  pagination: {
    total: number;       // Total count of items
    limit: number;       // Applied limit
    offset: number;      // Applied offset
    hasMore: boolean;    // Whether more items exist
    nextOffset?: number; // Offset for next page (null if no more)
  }
}

Implementation Example for `list_tags`, `get_commits`, `generate_changelog`

// Add pagination parameters to tool schema
{
  name: "your_tool",
  inputSchema: {
    type: "object",
    properties: {
      // ... existing parameters
      limit: {
        type: "number",
        description: "Maximum items to return (default: 100, max: 1000)",
        minimum: 1,
        maximum: 1000,
        default: 100
      },
      offset: {
        type: "number",
        description: "Number of items to skip (default: 0)",
        minimum: 0,
        default: 0
      }
    }
  }
}

// In handler
const limit = Math.min(args.limit ?? 100, 1000);
const offset = args.offset ?? 0;

const allItems = await getAllItems();
const total = allItems.length;
const items = allItems.slice(offset, offset + limit);

return {
  items,
  pagination: {
    total,
    limit,
    offset,
    hasMore: offset + limit < total,
    nextOffset: offset + limit < total ? offset + limit : null
  }
};

🎯 Benefits

✅ Prevent token overflow - Never exceed token limits
✅ Faster responses - Smaller payloads = faster responses
✅ Better UX - Users can request more if needed
✅ Scalability - Handles datasets of any size
✅ Efficient - Only process/transfer what's needed
✅ Standard pattern - Familiar to all developers

📋 Implementation Checklist

Add limit and offset parameters to affected tools
Set sensible defaults (limit: 100, max: 1000)
Return pagination metadata in responses
Update tool descriptions to mention pagination
Add examples to README
Update CHANGELOG

🚦 Priority Level

🔴 CRITICAL - This directly affects:

System stability (prevents crashes)
User experience (complete data access)
Data integrity (no truncation)
Resource usage (efficient transfers)

🤖 Generated with Claude Code

## 🚨 Critical Issue ### Problem Currently, tools that return large datasets can cause **token overflow** in the MCP protocol, leading to: - ❌ Truncated responses - ❌ Lost data - ❌ Poor user experience - ❌ Unusable results for large datasets ### Affected Tools in This MCP - **`list_tags`** - Could return hundreds of tags - **`get_commits`** - Could return thousands of commits - **`generate_changelog`** - Large changelog content - **`analyze_commits`** - Analysis of many commits ### Example: Token Overflow Problem #### Current Behavior (❌ Bad) ```typescript // get_commits - could return 10,000+ commits! const commits = await getCommits('v1.0.0', 'v2.0.0'); // Response: 8,472 commits = Token overflow! ``` #### With Pagination (✅ Good) ```typescript // Paginated approach const commits = await getCommits('v1.0.0', 'v2.0.0', { limit: 100, offset: 0 }); // Response: { items: [...100 commits], pagination: { total: 8472, hasMore: true } } ``` ## 💡 Proposed Solution ### Standard Pagination Interface ```typescript interface PaginationParams { limit?: number; // Max items to return (default: 100, max: 1000) offset?: number; // Number of items to skip (default: 0) } interface PaginatedResponse<T> { items: T[]; pagination: { total: number; // Total count of items limit: number; // Applied limit offset: number; // Applied offset hasMore: boolean; // Whether more items exist nextOffset?: number; // Offset for next page (null if no more) } } ``` ### Implementation Example for `list_tags`, `get_commits`, `generate_changelog` ```typescript // Add pagination parameters to tool schema { name: "your_tool", inputSchema: { type: "object", properties: { // ... existing parameters limit: { type: "number", description: "Maximum items to return (default: 100, max: 1000)", minimum: 1, maximum: 1000, default: 100 }, offset: { type: "number", description: "Number of items to skip (default: 0)", minimum: 0, default: 0 } } } } // In handler const limit = Math.min(args.limit ?? 100, 1000); const offset = args.offset ?? 0; const allItems = await getAllItems(); const total = allItems.length; const items = allItems.slice(offset, offset + limit); return { items, pagination: { total, limit, offset, hasMore: offset + limit < total, nextOffset: offset + limit < total ? offset + limit : null } }; ``` ## 🎯 Benefits - ✅ **Prevent token overflow** - Never exceed token limits - ✅ **Faster responses** - Smaller payloads = faster responses - ✅ **Better UX** - Users can request more if needed - ✅ **Scalability** - Handles datasets of any size - ✅ **Efficient** - Only process/transfer what's needed - ✅ **Standard pattern** - Familiar to all developers ## 📋 Implementation Checklist - [ ] Add `limit` and `offset` parameters to affected tools - [ ] Set sensible defaults (limit: 100, max: 1000) - [ ] Return pagination metadata in responses - [ ] Update tool descriptions to mention pagination - [ ] Add examples to README - [ ] Update CHANGELOG ## 🚦 Priority Level **🔴 CRITICAL** - This directly affects: - System stability (prevents crashes) - User experience (complete data access) - Data integrity (no truncation) - Resource usage (efficient transfers) --- 🤖 Generated with [Claude Code](https://claude.com/claude-code)

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

customable-mcp/changelog-mcp#9

No description provided.

Rows
Columns