[FR] Add timeframe/temporal query parameters to MCP tools for trend analysis

[waynesun09]

Problem Statement

Currently, Sourcebot's MCP tools (search_code, list_repos, get_file_source) only provide access to the current state of the codebase. This limitation prevents AI language models from performing meaningful temporal analysis, trend reporting, or historical insights when using the Sourcebot MCP server.

Use Case

When LLMs attempt to analyze code evolution, track changes over time, or provide trend analysis, they are unable to do so effectively because the MCP tools lack timeframe filtering capabilities. This results in responses like "I cannot analyze trends over time with the available tools" or incomplete analysis based only on current code state.

Real-World Examples:

• Trend Analysis: "Show me how the usage of async/await has evolved in our codebase over the last year"
• Historical Search: "Find all instances where deprecated function X was removed between March and June"
• Evolution Tracking: "Compare the error handling patterns used 6 months ago vs today"
• Regression Analysis: "Identify when specific security patterns were introduced across repositories"

Proposed Solution

Add temporal/timeframe parameters to existing MCP tools to enable time-based querying:

Enhanced search_code Tool

Add optional parameters:

{
 since?: string; // ISO date string (e.g., "2024-01-01")
 until?: string; // ISO date string (e.g., "2024-12-31")
 dateRange?: string; // Relative range (e.g., "last-3-months", "last-year")
 gitRevision?: string; // Specific commit/tag/branch
 compareRevisions?: { // Compare between two points in time
 from: string;
 to: string;
 };
 includeDeletedFiles?: boolean; // Include files that were deleted in timeframe
}

Enhanced list_repos Tool

Add repository filtering by activity timeframe:

{
 activeAfter?: string; // Only repos with commits after this date
 activeBefore?: string; // Only repos with commits before this date
}

New search_commits Tool

{
 query: string; // Search in commit messages, authors, changes
 since?: string;
 until?: string;
 author?: string;
 repository?: string[];
}

Technical Implementation Considerations

1. Git Integration: Leverage git log with --since, --until, --author flags
2. Zoekt Enhancement: Extend Zoekt indexing to include commit metadata and timestamps
3. API Compatibility: Maintain backward compatibility by making all new parameters optional
4. Performance: Consider caching mechanisms for frequently requested time ranges
5. Date Formats: Support both absolute (ISO 8601) and relative dates ("1 week ago", "last month")

Benefits

• Enhanced AI Analysis: Enable LLMs to provide comprehensive temporal insights and trend analysis
• Historical Context: Allow developers to understand code evolution and decision history
• Compliance & Auditing: Support regulatory requirements for tracking code changes over time
• Research Capabilities: Enable academic and organizational research on codebase evolution
• Debugging: Help identify when bugs or issues were introduced

Related Issues

This request complements issue #22 "FR: Ability to query for configuration in repositories over time" but focuses specifically on enhancing the MCP interface for broader temporal querying capabilities.

Community Impact

This feature would make Sourcebot's MCP integration significantly more powerful for AI-assisted development workflows, positioning it as a leader in temporal code analysis capabilities. Many organizations need this functionality for compliance, research, and advanced AI-powered insights.

Alternative Approaches Considered

1. Client-side Git Integration: Less efficient and requires additional tooling
2. Separate Temporal API: Would fragment the interface and require additional complexity
3. External Time-series Database: Overkill for this use case and adds infrastructure complexity

The proposed approach of enhancing existing MCP tools provides the most seamless integration with current workflows while enabling powerful new capabilities.

[brendan-kellam]

Implemented in #625