Dynamic Grounding for GitHub Copilot

A Model Context Protocol (MCP) server that integrates Google's Gemini AI to provide enhanced codebase search and analysis capabilities for GitHub Copilot in VS Code.

Features

• Natural Language Codebase Search: Search through files using plain English queries
• Multi-File Analysis: Analyze relationships and dependencies across files
• Code Understanding: Ask questions about specific code sections
• Directory Summarization: Get high-level overviews of project structure
• Quota Management: Client-side tracking of Google's free tier limits (15 RPM, 1500 RPD)
• Secure API Key Storage: Integration with VS Code Secret Storage

Screenshots

Search through your entire codebase using plain English queries

Get intelligent suggestions for improving your project

Analyze relationships and dependencies across multiple files

Architecture

Core Components

1. Quota Tracker (src/quota.rs)

   • Rolling window implementation for RPM/RPD/TPM limits
   • Warns at 80% usage, blocks at 95%
   • Provides real-time quota status in tool responses

2. Gemini Client (src/gemini.rs)

   • HTTP client for Gemini API (gemini-2.0-flash model)
   • Automatic token counting and quota recording
   • Error handling and retries
   • Methods: search_codebase, analyze_files, ask_about_code, summarize_directory

3. API Key Manager (src/api_key.rs)

   • SecureString type that zeros memory on drop
   • Never logs or displays API keys
   • Provider trait for flexible key storage

4. MCP Server (src/mcp_server.rs)

   • Built on mocopr crate
   • stdio-based communication
   • Tool registration (implementation pending)

Installation

For End Users (Recommended)

Install from VS Code Marketplace:

1. Open VS Code
2. Press Ctrl+Shift+X (or Cmd+Shift+X on Mac) to open Extensions
3. Search for "Dynamic Grounding for GitHub Copilot"
4. Click Install
5. Run the setup wizard: Ctrl+Shift+P → "Dynamic Grounding: Setup API Key"

The extension automatically downloads the MCP server binary for your platform. No Rust toolchain required!

For Developers

From Source:

git clone https://github.com/ciresnave/dynamic_grounding_for_github_copilot
cd dynamic_grounding_for_github_copilot

# Build the Rust MCP server
cargo build --release

# Build the VS Code extension
cd vscode-extension
npm install
npm run compile
npx vsce package

Via Cargo:

cargo install dynamic_grounding_for_github_copilot

Configuration

Automated Setup (Recommended)

The easiest way to get started is with the interactive setup wizard:

# After installation, run:
dynamic_grounding_for_github_copilot --setup

The wizard will:

1. Open your browser automatically to Google AI Studio's API key page
2. Guide you through the key creation process with clear instructions
3. Validate your API key by testing it against the Gemini API
4. Securely store your key for future use

No need to manually navigate URLs or remember configuration steps - just follow the prompts!

Manual Setup

If you prefer manual configuration:

1. Visit Google AI Studio
2. Sign in and create a new API key
3. Store it securely (the MCP server will prompt for it on first run)

API Key Storage

The MCP server receives the API key through initialization parameters from the VS Code extension (secure VS Code Secret Storage). Never use environment variables for API keys in production.

Usage

First-Time Setup

Run the interactive setup wizard to configure your API key:

dynamic_grounding_for_github_copilot --setup

This will walk you through the entire process with automatic browser opening and key validation.

Running the MCP Server

dynamic_grounding_for_github_copilot

The server communicates via stdio and awaits MCP protocol messages.

Available MCP Tools

The server exposes 4 tools that GitHub Copilot can use:

1. search_codebase

Search through code files using natural language queries.

Parameters:

• query (string): Natural language search query
• files (array): Array of file objects with path and content fields

Example:

{
  "query": "Find all error handling implementations",
  "files": [
    {
      "path": "src/error.rs",
      "content": "..."
    },
    {
      "path": "src/gemini.rs",  
      "content": "..."
    }
  ]
}

Returns: Structured results with relevant file paths, line numbers, explanations, and code snippets.

2. analyze_files

Analyze relationships and dependencies across multiple files.

Parameters:

• question (string): Question about the files
• files (array): Array of file objects with path and content fields

Example:

{
  "question": "How does the quota tracker integrate with the API client?",
  "files": [
    {
      "path": "src/quota.rs",
      "content": "..."
    },
    {
      "path": "src/gemini.rs",
      "content": "..."
    }
  ]
}

Returns: Detailed analysis of relationships, dependencies, and answers to the question.

3. ask_about_code

Ask questions about specific code sections with context.

Parameters:

• context (string): Code context or snippet
• question (string): Question about the code

Example:

{
  "context": "pub struct QuotaTracker { ... }",
  "question": "How does this struct track API rate limits?"
}

Returns: Clear, concise explanation based on the provided context.

4. summarize_directory

Get a high-level overview of a directory's structure and purpose.

Parameters:

• directory_structure (string): Tree-like directory structure
• files (array): Array of key file objects with path and content fields

Example:

{
  "directory_structure": "src/\n  main.rs\n  lib.rs\n  ...",
  "files": [
    {
      "path": "src/lib.rs",
      "content": "..."
    }
  ]
}

Returns: Summary including overall purpose, architecture, key components, and notable patterns.

Example Tool Calls (via MCP)

{
  "method": "tools/call",
  "params": {
    "name": "search_codebase",
    "arguments": {
      "query": "Find all error handling implementations",
      "file_paths": ["src/error.rs", "src/gemini.rs"]
    }
  }
}

Google Gemini Free Tier Limits

• 15 requests per minute (RPM)
• 1,500 requests per day (RPD)
• 1,000,000 tokens per minute (TPM)
• Free input & output tokens
• 2M token context window (gemini-2.0-flash)

The quota tracker monitors all three limits and provides warnings in tool responses.

Security

• API keys stored in VS Code Secret Storage (encrypted)
• SecureString type prevents accidental logging
• Keys zeroed from memory on drop
• Comprehensive .gitignore patterns

Never commit:

• .env files
• Files containing *secret* or *token* in the name
• API keys in any form

Development

Running Tests

cargo test

Test Coverage

• ✅ Quota tracking (rolling windows, limits, warnings)
• ✅ API key management (secure storage, validation)
• ✅ Gemini client initialization
• ✅ Setup wizard (URL validation, wizard creation)
• ⏳ Integration tests (pending)
• ⏳ MCP tool handlers (pending implementation)

Project Status

Completed:

• ✅ Core Rust MCP server with quota tracking
• ✅ Gemini API client (gemini-2.0-flash)
• ✅ Secure API key management with SecureString
• ✅ Complete unit test suite (17/17 passing)
• ✅ MCP tool handlers (all 4 tools implemented)
• ✅ VS Code extension with Secret Storage
• ✅ Setup wizard with browser integration
• ✅ Automatic binary downloads (GitHub releases)
• ✅ Cross-platform support (Windows, macOS, Linux)

Pending:

• ⏳ VS Code Marketplace publication
• ⏳ crates.io publication
• ⏳ Integration tests with live API
• ⏳ Advanced caching strategies

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure cargo test passes
5. Submit a pull request

License

MIT OR Apache-2.0

Acknowledgments

• Built with mocopr - Model Context Protocol for Rust
• Powered by Google Gemini API
• Designed for GitHub Copilot in VS Code

Roadmap

• Complete MCP tool handler implementations
• VS Code extension with Secret Storage integration
• Publish to VS Code Marketplace
• Publish to crates.io
• Advanced caching strategies
• Support for additional Gemini models
• Telemetry and usage analytics (opt-in)