MIGRATION_GUIDE.md•5.46 kB
# Migration Guide for Deprecated Tools
## Overview
This guide helps you migrate from deprecated tools to the new memory-centric architecture in MCP ADR Analysis Server v2.0+.
## Deprecated Tools and Their Replacements
### 1. `mcp0_manage_todo_json` → `mcp-shrimp-task-manager`
**What Changed:**
- The built-in TODO management has been replaced with an external task manager
- Task data is now stored in the memory system rather than JSON files
**Migration Steps:**
1. Export existing tasks using the old tool (if still available)
2. Install the new task manager: `mcp-shrimp-task-manager`
3. Import tasks into the new system
4. Update any automation scripts to use the new tool names
**New Tool Usage:**
```javascript
// Old way
try {
await mcp0_manage_todo_json({ operation: 'add', task: 'My task' });
} catch (error) {
console.error('Failed to manage todo:', error);
}
// New way (via external task manager)
try {
// Configure mcp-shrimp-task-manager in your MCP settings
// Then use through MCP client
const result = await mcpClient.callTool('manage-task', {
operation: 'add',
task: 'My task'
});
console.log('Task added successfully:', result);
} catch (error) {
console.error('Failed to add task:', error);
}
```
### 2. `mcp0_smart_score` → Memory-Centric Health Scoring
**What Changed:**
- Project health scoring is now integrated into the memory system
- Provides more comprehensive, context-aware scoring
- Historical tracking and pattern recognition
**Migration Steps:**
1. The new system automatically migrates existing score data
2. Access scores through memory entities instead of direct tool calls
**New Usage:**
```javascript
// Old way
try {
const score = await mcp0_smart_score({ projectPath: '/my/project' });
console.log('Project score:', score);
} catch (error) {
console.error('Failed to get project score:', error);
}
// New way (automatic via memory system)
try {
// Scores are calculated automatically and stored as memory entities
const memoryQuery = await mcpClient.callTool('query-memory', {
entityType: 'project-health',
projectPath: '/my/project'
});
console.log('Health data:', memoryQuery.entities);
} catch (error) {
console.error('Failed to query memory system:', error);
}
```
## Cache Directory Changes
### Important: New Cache Location
**Old Location:** `.mcp-adr-cache` (in project directory)
**New Location:** OS temp directory (e.g., `/tmp/[project-name]/cache`)
This change:
- Prevents permission issues
- Provides better cross-platform compatibility
- Keeps project directories clean
**No Action Required:** The system automatically uses the new location.
## Memory System Integration
### New Features
The memory-centric architecture provides:
- **Persistent memory entities** for all tool operations
- **Cross-tool relationships** and pattern detection
- **Historical analysis** and trend identification
- **Intelligent caching** with automatic invalidation
### How to Enable
Memory features are enabled by default. To use advanced features:
```javascript
// Enable memory integration in tools
try {
const result = await deploymentReadiness({
enableMemoryIntegration: true,
migrateExistingHistory: true,
});
console.log('Memory integration enabled:', result);
} catch (error) {
console.error('Failed to enable memory integration:', error);
// Fallback to basic mode
console.log('Continuing with basic deployment readiness...');
}
```
## Troubleshooting
### Common Issues
1. **"Tool not found" errors**
- Solution: Update your MCP client configuration
- Remove references to deprecated tools
- Add new external tools as needed
2. **Cache directory errors**
- Solution: Already fixed! Uses OS temp directory
- Clear old cache: `rm -rf .mcp-adr-cache`
3. **Memory initialization failures**
- Solution: Ensure temp directory has write permissions
- Check disk space in temp directory
### Getting Help
- Report issues: https://github.com/anthropics/claude-code/issues
- Check documentation: `/docs` directory
- Memory system guide: `/./explanation/memory-architecture.md`
## Rollback Instructions
If you need to rollback to previous versions:
1. **Backup current data:**
```bash
cp -r /tmp/[project-name]/cache ./backup-cache
cp -r /tmp/[project-name]/memory ./backup-memory
```
2. **Downgrade package:**
```bash
npm install mcp-adr-analysis-server@1.x
```
3. **Restore old cache location:**
```bash
cp -r ./backup-cache .mcp-adr-cache
```
## Benefits of Migration
### Why Migrate?
1. **Better Performance**
- Memory-centric caching reduces redundant operations
- Pattern recognition improves over time
2. **Enhanced Intelligence**
- Cross-tool learning and relationships
- Historical pattern analysis
- Predictive capabilities
3. **Improved Reliability**
- No more permission issues
- Better error handling and recovery
- Automatic data migration
4. **Future-Proof**
- Active development and support
- New features added regularly
- Community-driven improvements
## Timeline
- **Immediate:** Cache directory fixes are live
- **v2.1:** Full memory system integration
- **v2.2:** Advanced pattern recognition
- **v3.0:** AI-powered workflow automation
## Questions?
For questions about migration, please:
1. Check this guide first
2. Review the changelog in `/CHANGELOG.md`
3. Open an issue if you encounter problems