customable-mcp/docu-mcp

Fork 0

⚠️ Add Pagination Support to Prevent Token Overflow #9

New issue

Open

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

jack commented

2025-10-10 09:17:51 +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

analyze_codebase - Analysis of many files
extract_comments - Could extract thousands of comments
generate_docs - Large documentation output

Example: Token Overflow Problem

Current Behavior (❌ Bad)

// extract_comments - could extract thousands of comments!
const comments = await extractComments('/path/to/project');
// Response: 5,000 code comments = Token overflow!

With Pagination (✅ Good)

// Paginated extraction
const comments = await extractComments('/path/to/project', {
  limit: 50,
  offset: 0
});
// Response: { items: [...50 comments], pagination: { total: 5000, 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 `analyze_codebase`, `extract_comments`, `generate_docs`

// 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 - **`analyze_codebase`** - Analysis of many files - **`extract_comments`** - Could extract thousands of comments - **`generate_docs`** - Large documentation output ### Example: Token Overflow Problem #### Current Behavior (❌ Bad) ```typescript // extract_comments - could extract thousands of comments! const comments = await extractComments('/path/to/project'); // Response: 5,000 code comments = Token overflow! ``` #### With Pagination (✅ Good) ```typescript // Paginated extraction const comments = await extractComments('/path/to/project', { limit: 50, offset: 0 }); // Response: { items: [...50 comments], pagination: { total: 5000, 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 `analyze_codebase`, `extract_comments`, `generate_docs` ```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/docu-mcp#9

No description provided.

Rows
Columns