msexchange-mcp/TOKEN_OPTIMIZATION_GUIDE.md

MCP server for Microsoft Exchange/Outlook email operations via Microsoft Graph API

# Token Optimization Guide for Exchange MCP

## Problem Identified

**MCP Response Token Limit**: 25,000 tokens maximum per response
**Actual Usage**: 20 emails with body content = 131,200 tokens (5x over limit!)

## Root Cause Analysis

Email bodies contain massive amounts of text:
- **Average email body**: ~3,000-6,000 tokens
- **20 emails with bodies**: ~60,000-120,000 tokens  
- **Metadata per email**: ~50-100 tokens
- **Response overhead**: ~1,000 tokens

## Implemented Solutions

### 1. Smart Limits Based on Content

#### Original `query_emails` Tool (Enhanced):
- **With body content**: Maximum 5 emails (≈15,000 tokens)
- **Without body content**: Maximum 100 emails (≈10,000 tokens)
- **Automatic capping** with user feedback
- **Intelligent warnings** when limits exceeded

```typescript
const maxLimit = params.include_body ? 5 : 100;
const safeLimit = Math.min(params.limit || 10, maxLimit);
```

### 2. New `query_emails_batch` Tool

**Purpose**: Handle large queries (50-500 emails) intelligently

**Features**:
- **Automatic batch sizing**: 3 emails/batch (with body) or 50 emails/batch (without body)
- **Sequential processing** with rate limiting protection
- **Progress tracking** and partial result handling
- **Token-aware batching** to stay under 25k limit per batch

**Usage Examples**:
```bash
# Get 100 emails without body content (batched automatically)
query_emails_batch --total_emails 100 --include_body false

# Get 20 emails with body content (batched in groups of 3)
query_emails_batch --total_emails 20 --include_body true
```

### 3. New `query_emails_summary` Tool

**Purpose**: Get condensed information about many emails

**Features**:
- **Minimal field selection** (no body content)
- **Truncated previews** (100 characters max)
- **Up to 200 emails** in single response
- **Optimized for token efficiency**

**Perfect for**:
- Email list overviews
- Finding specific emails
- Bulk operations planning

## Performance Comparison

| Scenario | Old Approach | New Approach | Token Usage |
|----------|-------------|--------------|-------------|
| 20 emails + bodies | ❌ 131k tokens (5x limit) | ✅ 4 batches × ~15k = 60k total | ✅ Under limit per batch |
| 100 emails metadata | ❌ ~15k tokens (risky) | ✅ ~10k tokens | ✅ Safe |
| 300 emails summary | ❌ Would fail | ✅ 2 batches × ~12k = 24k total | ✅ Efficient |

## Best Practices by Use Case

### 📧 Reading Recent Emails with Content
```bash
# ✅ GOOD: Small batch with bodies
query_emails --limit 5 --include_body true

# ❌ BAD: Large batch with bodies  
query_emails --limit 20 --include_body true
```

### 📋 Getting Email Overview
```bash
# ✅ GOOD: Summary for quick overview
query_emails_summary --limit 50

# ✅ GOOD: Metadata only for larger sets
query_emails --limit 100 --include_body false
```

### 🔍 Bulk Email Processing
```bash
# ✅ GOOD: Batch processing for large sets
query_emails_batch --total_emails 200 --include_body false

# ✅ GOOD: Incremental processing
query_emails_summary --limit 100 --skip 0
query_emails_summary --limit 100 --skip 100
```

### 📖 Reading Specific Email Content
```bash
# ✅ GOOD: Get summary first, then fetch specific emails
query_emails_summary --limit 20
get_email_by_id --message_id "specific-email-id"
```

## Tool Selection Guide

| Goal | Recommended Tool | Max Emails | Token Efficiency |
|------|-----------------|------------|------------------|
| Read recent emails with content | `query_emails` | 5 | ⭐⭐⭐ |
| Browse email list | `query_emails_summary` | 200 | ⭐⭐⭐⭐⭐ |
| Process many emails | `query_emails_batch` | 500 | ⭐⭐⭐⭐ |
| Get metadata only | `query_emails` | 100 | ⭐⭐⭐⭐ |

## Migration Strategy

### For Existing Users:
1. **Small queries (≤5 emails)**: No change needed
2. **Medium queries (6-20 emails with body)**: Use `query_emails_batch`
3. **Large queries (20+ emails)**: Use `query_emails_summary` first, then targeted queries

### Response Format Changes:
All tools now include helpful metadata:
```json
{
  "summary": {
    "tokenOptimized": true,
    "maxLimitWithBody": 5,
    "maxLimitWithoutBody": 100
  },
  "paginationAdvice": "Use skip parameter for pagination: skip=50"
}
```

## Implementation Details

### Token Estimation Formula:
```typescript
// Rough token estimation
const estimatedTokens = emails.length * (includeBody ? 4000 : 200) + 1000;
const safeForMCP = estimatedTokens < 25000;
```

### Automatic Batching Logic:
```typescript
const batchSize = includeBody ? 3 : 50; // Conservative limits
const numBatches = Math.ceil(totalEmails / batchSize);
```

### Rate Limiting Protection:
- 500ms delay between batches
- Exponential backoff on HTTP 429
- Respect Retry-After headers
- Graceful partial result handling

## Monitoring and Feedback

The server now provides:
- **Real-time token usage warnings**
- **Automatic limit adjustments**
- **Pagination guidance**
- **Performance recommendations**

## Future Enhancements

1. **Dynamic token counting** for more precise limits
2. **Streaming responses** for very large datasets  
3. **Caching strategies** for frequently accessed emails
4. **Compression** for metadata-heavy responses

## Conclusion

The Exchange MCP server now intelligently handles large email queries while respecting MCP token limits. Users get:

✅ **Reliable performance** - No more token limit errors
✅ **Flexible options** - Choose the right tool for each use case  
✅ **Automatic optimization** - Smart defaults that just work
✅ **Clear guidance** - Helpful advice for efficient usage

**Bottom Line**: You can now safely request large amounts of email data through intelligent batching and summarization!