dynamic_grounding_for_github_copilot 0.1.0

# 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


<p align="center">
  <img src="vscode-extension/screenshot1.png" alt="Natural Language Codebase Search" width="800">
  <br>
  <em>Search through your entire codebase using plain English queries</em>
</p>

<p align="center">
  <img src="vscode-extension/screenshot2.png" alt="AI-Powered Project Analysis" width="800">
  <br>
  <em>Get intelligent suggestions for improving your project</em>
</p>

<p align="center">
  <img src="vscode-extension/screenshot3.png" alt="Multi-File Code Understanding" width="800">
  <br>
  <em>Analyze relationships and dependencies across multiple files</em>
</p>

## 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:**

```bash
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:**

```bash
cargo install dynamic_grounding_for_github_copilot
```

## Configuration


### Automated Setup (Recommended)


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

```bash
# 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](https://aistudio.google.com/apikey)
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:

```bash
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


```bash
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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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)


```json
{
  "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


```bash
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](https://docs.rs/mocopr) - Model Context Protocol for Rust
- Powered by [Google Gemini API](https://ai.google.dev/gemini-api/docs)
- Designed for [GitHub Copilot](https://github.com/features/copilot) in VS Code

## Roadmap


- [x] Complete MCP tool handler implementations
- [x] 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)