MIGRATION.md•5.76 kB
# Migration Guide: Single Canonical Entrypoint
## Overview
This guide helps you migrate from the old multi-entry point architecture to the new consolidated single entry point with feature flags.
## What Changed
### Before (Multiple Entry Points)
- `src/index.ts` - Basic server implementation
- `src/index-registry.ts` - Registry-based implementation
- `src/server/index-enhanced.ts` - Enhanced server with tool discovery
- `src/server/tool-registry.ts` - Base registry
- `src/server/tool-registry-enhanced.ts` - Enhanced registry with discovery
### After (Single Entry Point)
- `src/index.ts` - Single canonical entry point
- `src/server/tool-registry.ts` - Unified registry with all features
- Feature flags control optional functionality
## Migration Steps
### 1. Update Your Imports
#### If you were using index-registry.ts:
**Before:**
```typescript
import { main, validateEnvironment } from './index-registry.js';
import { createAndConfigureToolRegistry } from './index-registry.js';
```
**After:**
```typescript
import { DeepSourceMCPServer } from './index.js';
// Create and configure server
const server = await DeepSourceMCPServer.create({
autoRegisterTools: true,
autoStart: false,
});
```
#### If you were using EnhancedToolRegistry:
**Before:**
```typescript
import { EnhancedToolRegistry } from './server/tool-registry-enhanced.js';
import { createEnhancedToolRegistry } from './server/tool-registry-enhanced.js';
const registry = new EnhancedToolRegistry(server);
await registry.discoverTools(options);
```
**After:**
```typescript
import { ToolRegistry } from './server/tool-registry.js';
// Enable tool discovery via feature flag
process.env.FEATURE_TOOL_DISCOVERY = 'true';
const registry = new ToolRegistry(server);
await registry.discoverTools(options); // Works when feature flag is enabled
```
### 2. Enable Feature Flags
Set environment variables to enable optional features:
```bash
# Enable tool discovery
export FEATURE_TOOL_DISCOVERY=true
# Enable enhanced logging
export FEATURE_ENHANCED_LOGGING=true
# Enable metrics collection
export FEATURE_METRICS=true
# Enable caching (future feature)
export FEATURE_CACHE=true
```
### 3. Update Configuration
#### Tool Discovery Configuration
**Before:**
```typescript
import { getToolDiscoveryConfig } from './config/tool-discovery.config.js';
const config = getToolDiscoveryConfig();
```
**After:**
```typescript
import { getEnvironmentConfig } from './config/default.js';
const config = getEnvironmentConfig();
// Discovery config is at config.discovery
```
### 4. Update Package.json Scripts
No changes needed - the binary field still points to the correct entry:
```json
{
"bin": {
"deepsource-mcp-server": "./dist/index.js"
}
}
```
### 5. Testing Your Migration
1. **Check feature flags are working:**
```bash
FEATURE_TOOL_DISCOVERY=true deepsource-mcp-server --version
# Should show: Enabled features: toolDiscovery
```
2. **Verify tool registration:**
```bash
# Run server and check logs for registered tools
DEEPSOURCE_API_KEY=your-key deepsource-mcp-server
```
3. **Test tool discovery (if used):**
```bash
# Place .tool.js files in ./src/tools directory
FEATURE_TOOL_DISCOVERY=true DEEPSOURCE_API_KEY=your-key deepsource-mcp-server
```
## Deprecated Features
The following will be removed in the next major version:
### Files (Deprecated)
- `src/index-registry.ts` - Use `src/index.ts` instead
- `src/server/index-enhanced.ts` - Features merged into main server
- `src/server/tool-registry-enhanced.ts` - Features merged into ToolRegistry
### Functions (Deprecated)
- `validateEnvironment()` - Use `getConfig()` from `config/index.js`
- `createAndConfigureToolRegistry()` - Use `DeepSourceMCPServer.create()`
- `createEnhancedToolRegistry()` - Use `new ToolRegistry()` with feature flags
## Breaking Changes
None! The migration maintains full backward compatibility:
- Old import paths still work (with deprecation warnings)
- All APIs remain the same
- CLI usage unchanged
- Configuration format unchanged
## Feature Flag Reference
| Flag | Environment Variable | Description | Default |
| ---------------- | -------------------------- | ----------------------------------- | ------- |
| Tool Discovery | `FEATURE_TOOL_DISCOVERY` | Auto-discover tools from filesystem | `false` |
| Enhanced Logging | `FEATURE_ENHANCED_LOGGING` | Additional debug information | `false` |
| Metrics | `FEATURE_METRICS` | Collect and report metrics | `false` |
| Cache | `FEATURE_CACHE` | Cache API responses (future) | `false` |
## Common Issues
### Issue: Tool discovery not working
**Solution:** Ensure `FEATURE_TOOL_DISCOVERY=true` is set:
```bash
export FEATURE_TOOL_DISCOVERY=true
```
### Issue: Import errors after update
**Solution:** Update imports to use the new paths as shown above. The old paths show deprecation warnings but still work.
### Issue: Tests failing after migration
**Solution:** Update test imports and mock the feature flags:
```typescript
// In your tests
vi.mock('./config/features', () => ({
getFeatureFlags: () => ({
toolDiscovery: true,
enhancedLogging: false,
metrics: false,
cache: false,
}),
isFeatureEnabled: (feature: string) => feature === 'toolDiscovery',
}));
```
## Getting Help
- Check the [README](README.md) for general usage
- See [CLAUDE.md](CLAUDE.md) for development guidelines
- Open an issue for migration problems
## Timeline
- **Current Release**: Deprecation warnings added, full backward compatibility
- **Next Minor Release**: Documentation updates, migration tools
- **Next Major Release**: Deprecated files and functions removed