jprbom/code-time-machine-mcp

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:

# Run the automated setup script
./setup.bat
# OR
./manual-setup.bat

Manual Setup:

1. Install dependencies:

cd C:\Ashlesha\code-time-machine-mcp
npm install

2. Test the setup:

node test-setup.js

3. Make sure Git is installed and accessible:

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

{
  "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:

   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.