# Code Time Machine MCP Server

A revolutionary MCP (Model Context Protocol) server that allows AI assistants like Claude to navigate through git repository history like a time machine, providing deep insights into code evolution and helping understand legacy systems.

## Features

- **Time Travel Navigation**: Navigate to any point in repository history by date, commit, tag, or relative time
- **Code Evolution Analysis**: Track how files and functions evolved over time with detailed metrics
- **Code Archaeology**: Understand why code was written, who contributed, and how it changed
- **Pattern Detection**: Identify architectural shifts, refactoring patterns, and technical debt
- **AI-Powered Insights**: Get intelligent analysis of code changes and recommendations
- **Visual Timeline**: Generate visual representations of code evolution
- **Ownership Tracking**: See how code ownership evolved over time

## Installation

### Automated Setup (Recommended)

**Windows:**
```bash
# Run the automated setup script
./setup.bat
# OR
./manual-setup.bat
```

**Manual Setup:**

1. Install dependencies:
```bash
cd C:\Ashlesha\code-time-machine-mcp
npm install
```

2. Test the setup:
```bash
node test-setup.js
```

3. Make sure Git is installed and accessible:
```bash
git --version
```

## Configuration

### For Claude Desktop

Add to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "code-time-machine": {
      "command": "node",
      "args": ["C:/path/to/code-time-machine-mcp/src/index.js"],
      "env": {
        "DEFAULT_REPO_PATH": "C:/path/to/your/projects"
      }
    }
  }
}
```

## Usage

Once configured, you can use Claude to explore your code repositories through time:

### Time Travel
- "Show me what this repository looked like 6 months ago"
- "Navigate to the commit where user authentication was added"
- "Take me to January 1st, 2023 in the codebase"
- "Go back 30 days in the repository history"

### Code Evolution
- "How has the authentication module evolved over the past year?"
- "Show me all changes to the payment processing system"
- "Track the evolution of the UserController class"
- "When was error handling added to this function?"

### Code Archaeology
- "Generate an archaeology report for the database layer"
- "Who has contributed most to this file?"
- "Why was this code written this way?"
- "What major architectural decisions were made?"

### Pattern Analysis
- "Detect architectural shifts in the codebase"
- "Find all major refactorings in the last 6 months"
- "Identify technical debt accumulation areas"
- "Show me code ownership patterns"

## Available Tools

1. **time_travel**: Navigate to specific points in repository history
2. **analyze_evolution**: Track how files or functions evolved over time
3. **find_code_introduction**: Find when and why specific code was introduced
4. **compare_implementations**: Compare code implementations across time periods
5. **archaeology_report**: Generate comprehensive code archaeology reports
6. **visualize_code_ownership**: Show code ownership evolution
7. **detect_architectural_shifts**: Identify major architectural changes

## Tool Examples

### Time Travel
```
Input: {
  "repo_path": "/path/to/repo",
  "destination": {
    "type": "date",
    "date": "2023-06-15"
  }
}
```

### Analyze Evolution
```
Input: {
  "repo_path": "/path/to/repo",
  "file_path": "src/auth/UserController.js",
  "time_range": {
    "from": "2023-01-01",
    "to": "2023-12-31"
  }
}
```

### Code Archaeology
```
Input: {
  "repo_path": "/path/to/repo",
  "target_path": "src/database/",
  "depth": "deep",
  "include_contributors": true
}
```

## Advanced Features

### Caching
The server includes intelligent caching to improve performance when analyzing large repositories.

### Pattern Recognition
- Identifies common refactoring patterns
- Detects code smells and technical debt
- Recognizes architectural patterns

### AI Integration
The server prepares data in a format optimized for AI analysis, allowing Claude to:
- Generate insights about code quality
- Suggest refactoring opportunities
- Explain complex code evolution
- Predict future maintenance needs

## Development

### Project Structure
```
code-time-machine-mcp/
├── src/
│   ├── index.js            # Main server file
│   ├── tools/              # Individual tool implementations
│   ├── analyzers/          # Code analysis utilities
│   └── utils/              # Helper functions
├── cache/                  # Analysis cache (gitignored)
├── .env                    # Environment variables (gitignored)
├── .gitignore              # Git ignore file
├── package.json            # Project dependencies
└── README.md               # This file
```

### Extending the Server

To add new analysis capabilities:

1. Create a new tool in the `tools` object
2. Implement the analysis logic
3. Add appropriate caching if needed
4. Update the documentation

## Performance Considerations

- Large repositories may take time to analyze initially
- Caching significantly improves subsequent analyses
- Consider using shallow clones for very large repositories
- The server respects Git's performance optimizations

## Troubleshooting

### Common Issues

1. **"Git not found" error**: Ensure Git is installed and in your PATH
2. **Permission errors**: Make sure you have read access to the repositories
3. **Memory issues**: For large repos, increase Node.js memory limit:
   ```bash
   node --max-old-space-size=4096 src/index.js
   ```

## Roadmap

- [ ] Support for multiple repository comparison
- [ ] Integration with code quality metrics
- [ ] Machine learning models for code prediction
- [ ] Support for other version control systems (SVN, Mercurial)
- [ ] Real-time repository monitoring
- [ ] Advanced visualization exports
- [ ] Integration with CI/CD insights

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- Built with the Model Context Protocol SDK
- Powered by simple-git for Git operations
- Uses diff and parse-diff for code analysis

## Support

For issues, questions, or suggestions, please open an issue on GitHub.