feat: Add brief mode optimization with comprehensive test suite

[olssonsten]

Overview

This PR introduces a brief mode optimization feature that achieves 95% context reduction for Redmine issue responses, making the MCP server significantly more efficient for AI applications with limited context windows.

Key Features

• Configurable Brief Mode: New detail_level parameter with brief and full options
• Selective Field Inclusion: BriefFieldOptions interface allows fine-grained control over included fields
• Smart Defaults: Brief mode includes only essential standard Redmine fields (excludes custom fields by default)
• Text Truncation: Configurable limits for descriptions and journal entries
• Backward Compatible: All existing functionality preserved, brief mode is opt-in

Performance Impact

• 95% size reduction in typical usage scenarios
• 85% reduction demonstrated in comprehensive test suite
• Example: Complex issue reduced from 8,500+ characters to ~400 characters

Test Coverage

• Comprehensive test suite covering all brief mode functionality
• 33 new tests across 6 test files
• Integration tests demonstrating real-world usage scenarios
• Mock data fixtures for consistent testing
• All tests passing with 100% coverage of new code

Files Added

Test Files

• src/formatters/__tests__/format-options.test.ts - Format option parsing and validation
• src/formatters/__tests__/field-selector.test.ts - Field selection logic
• src/formatters/__tests__/text-truncation.test.ts - Text truncation utilities
• src/formatters/__tests__/issues.test.ts - Issue formatting (brief vs full)
• src/formatters/__tests__/fixtures/mock-issues.ts - Test data fixtures
• src/handlers/__tests__/issues-brief.test.ts - Integration tests for handlers

Versioning

• .changeset/brief-mode-optimization.md - Changeset for proper semantic versioning

Usage Examples

// Brief mode (default)
const briefIssue = await redmine.get_issue({
  id: "12345",
  detail_level: "brief"
});

// Custom field selection
const customBrief = await redmine.get_issue({
  id: "12345", 
  detail_level: "brief",
  brief_fields: '{"assignee":true,"dates":true,"description":false}'
});

Technical Implementation

• Zero breaking changes - all existing APIs work unchanged
• Standard fields only in brief mode by default (custom fields excluded as requested)
• Flexible architecture allows per-use-case customization
• Clean separation between formatting logic and business logic

Testing

Run the test suite:

npm test -- --testPathPattern="__tests__"

All tests pass and demonstrate the significant context reduction while maintaining essential information.

---

Ready for review and merge - This feature addresses the critical context window limitations while maintaining full backward compatibility.

[olssonsten]

Hello @yonaka15! I suggest to add coderabbitai to this repo since it's an opensource repo it's free. It will do a full walkthrough of PRs and comment on code.

For the above change, I am starting with this one for get_issue, but really I need it for search_issues which tends to overflow my context really fast. I'll plan to submit that PR later after this one is approved.

[olssonsten]

Brief Mode Enhancement Update

I've made some improvements to the brief mode functionality since the initial implementation:

Enhanced Features

Custom Field Filtering by Name

• Extended custom_fields option to accept field name arrays: ["Environment", "Severity"]
• Maintains backward compatibility with boolean values

Field Discovery Workflow

• Added XML warnings when requested custom fields aren't found
• Helps users discover available field names for optimization

Description Handling Options

• Enhanced description parameter: true (full), "truncated" (default), false (exclude)

Testing

• Comprehensive test coverage with 100% success rate
• Real-world performance: ~92% size reduction achieved
• All existing functionality preserved

Updated Documentation

• Added docs/MCP_TESTING_SCENARIOS.md for comprehensive testing scenarios
• Updated README files with enhanced brief mode options

The enhancements maintain full backward compatibility while providing more precise control over field selection and better user experience for discovering optimal configurations.