SDK_V1_MIGRATION_SUMMARY.md•4.86 kB
# Letta SDK v1.0 Migration Summary
## Overview
This document summarizes the changes made to update the Letta MCP Server for compatibility with Letta SDK v1.0 (Letta server version 0.14.0+).
## Changes Implemented
### 1. Updated API Client Headers (src/core/server.js)
**Purpose**: Identify the MCP server as a v1.0 compatible client to the Letta server.
**Changes**:
- Added `User-Agent: letta-mcp-server/2.0.1 (sdk-v1.0-compatible)` header
- Added `X-Letta-SDK-Version: 1.0` header
**Impact**: The Letta server will now apply v1.0 API behavior when processing requests from this MCP server, ensuring:
- Correct parameter interpretation (e.g., using `include` instead of `include_relationships`)
- Proper handling of new v1.0 features
- Future compatibility with v1.0+ API changes
### 2. Updated list_passages Tool (src/tools/passages/list-passages.js)
**Purpose**: Replace deprecated `ascending` boolean parameter with new `order` string parameter.
**Changes**:
- Added new `order` parameter (accepts "asc" or "desc")
- Maintained backward compatibility for `ascending` parameter (deprecated but still functional)
- Updated tool schema to include both parameters with deprecation notice
**Implementation**:
```javascript
// New v1.0 parameter
if (args.order) {
params.order = args.order; // 'asc' or 'desc'
}
// Backward compatibility
else if (args.ascending !== undefined) {
params.order = args.ascending ? 'asc' : 'desc';
}
```
**Impact**:
- Users can now use `order: "asc"` or `order: "desc"` (recommended)
- Old `ascending: true/false` still works but shows deprecation warning
- Aligns with Letta API v1.0 parameter naming conventions
## What Was NOT Changed (Already Compatible)
### ✅ Property Naming
The codebase already uses snake_case for all API properties:
- `llm_config` ✓
- `embedding_config` ✓
- `agent_id`, `tool_ids`, `block_ids`, etc. ✓
### ✅ Response Parsing
List endpoints still return direct arrays, not paginated objects:
- `response.data` returns array directly
- No need to access `response.data.items`
### ✅ Core Tool Functionality
All tools use correct endpoint structures:
- Agent CRUD operations: `/agents/`, `/agents/{id}`
- Memory operations: `/blocks/`, `/agents/{id}/core-memory/blocks`
- Passage operations: `/agents/{id}/archival-memory`
- Tool operations: `/tools/`, `/agents/{id}/tools/attach/{tool_id}`
## Testing Recommendations
1. **Test with Letta Server 0.14.0+**
- Verify list_passages with both `order` and `ascending` parameters
- Confirm server recognizes v1.0 client headers
- Check that deprecated parameters still work (backward compatibility)
2. **Verify Header Propagation**
- Confirm all API requests include v1.0 headers
- Check that server applies v1.0 API behavior
3. **Test Parallel Tool Calling**
- Verify agent responses with multiple tool calls work correctly
- Ensure tool_call parsing handles array format
## Future Considerations
### Optional Enhancements
1. **Archive Management Tools**: Consider adding new direct archive manipulation tools introduced in v1.0
2. **Additional Parameter Updates**: Monitor for other deprecated parameters in future Letta releases
3. **Pagination**: If Letta adds cursor-based pagination objects in future versions, update response parsing
### Monitoring
- Watch for deprecation warnings from Letta server
- Track Letta releases for additional v1.0 changes
- Monitor MCP server compatibility with different Letta server versions
## Compatibility Matrix
| Component | Pre-v1.0 | v1.0+ | Status |
|-----------|----------|-------|--------|
| API Headers | Generic | v1.0 identified | ✅ Updated |
| Property Naming | snake_case | snake_case | ✅ Compatible |
| List Responses | Arrays | Arrays | ✅ Compatible |
| Pagination Params | `ascending` | `order` | ✅ Updated (backward compatible) |
| Tool Calls | Single object | Array | ✅ Compatible |
| Archive APIs | Agent-bound | Direct access | 📝 Consider adding |
## Migration Checklist
- [x] Update API client headers for v1.0 detection
- [x] Update deprecated query parameters
- [x] Maintain backward compatibility
- [x] Document changes
- [ ] Test with Letta server 0.14.0+
- [ ] Update version in package.json
- [ ] Create release notes
## References
- Letta 0.14.0 Release Notes
- SDK v1.0 Migration Guide: https://docs.letta.com/
- Letta API Reference: https://docs.letta.com/api-reference/
- GitHub Repository: https://github.com/letta-ai/letta
## Files Modified
1. `src/core/server.js` - Updated getApiHeaders() method
2. `src/tools/passages/list-passages.js` - Updated parameter handling and schema
3. `SDK_V1_ASSESSMENT.md` - Initial assessment (new)
4. `SDK_V1_MIGRATION_SUMMARY.md` - This document (new)
---
**Last Updated**: 2025-11-17
**Migration Status**: ✅ Complete
**Tested**: Pending verification with Letta 0.14.0+