Metadata-Version: 2.4
Name: iflow-mcp_peterkrueck-gemini-assistant
Version: 3.0.0
Summary: A powerful MCP server that allows Claude Code to consult Gemini for complex coding problems with full code context and conversation persistence
Project-URL: Homepage, https://github.com/peterkrueck/mcp-gemini-assistant
Project-URL: Repository, https://github.com/peterkrueck/mcp-gemini-assistant
Project-URL: Issues, https://github.com/peterkrueck/mcp-gemini-assistant/issues
Author-email: Peter Krueck <peterkrueck@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: google-genai>=0.5.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Gemini Coding Assistant MCP Server

A powerful MCP server that allows Claude Code to consult Gemini for complex coding problems with full code context and conversation persistence.

> **Note**: This server works standalone but is highly recommended to use with the [Claude Code Development Kit](https://github.com/peterkrueck/Claude-Code-Development-Kit) for enhanced automation and context management.

## Key Features

- **Session Management**: Maintain conversation context across multiple queries
- **File Attachments**: Read and include actual code files in conversations
- **Hybrid Context**: Combine text-based `code_context` with file attachments
- **Follow-up Questions**: Ask follow-up questions without resending code context
- **Context Caching**: Code context and file content are cached per session
- **Automatic Processing**: Files are processed and formatted automatically
- **Multiple Sessions**: Run multiple parallel conversations for different problems
- **Session Expiry**: Automatic cleanup of inactive sessions after 1 hour
- **Latest Model**: Uses Gemini 2.5 Pro (stable) by default

## Integration with Claude Code Development Kit

While this MCP server works standalone, it is **highly recommended and optimized** to use with the [Claude Code Development Kit](https://github.com/peterkrueck/Claude-Code-Development-Kit).

### Enhanced Features with Development Kit

The Development Kit transforms Claude Code into an orchestrated development environment that seamlessly integrates with this Gemini MCP server:

1. **Automated Context Injection**: The `gemini-context-injector.sh` hook automatically attaches project-specific context files (MCP-ASSISTANT-RULES.md, project-structure.md) to new Gemini sessions
2. **Multi-Agent Orchestration**: Complex commands spawn specialized agents that can consult Gemini for architectural decisions and design patterns
3. **Enhanced System Prompt**: The MCP server's system prompt is designed to work with the Development Kit's context injection system
4. **Security Scanning**: The `mcp-security-scan.sh` hook prevents sensitive data from being sent to external AI services
5. **Seamless Integration**: Commands like `/full-context` automatically leverage Gemini for complex problems

### Quick Setup with Development Kit

1. Install the [Claude Code Development Kit](https://github.com/peterkrueck/Claude-Code-Development-Kit)
2. Configure this MCP server as described in the installation section below
3. The Development Kit's hooks will automatically enhance your Gemini interactions

## Purpose

When Claude Code encounters difficult problems or needs a second opinion, it can:
- Send complete code files by reading them from the local filesystem
- Include text-based code context alongside file attachments
- Have multi-turn conversations about the same problem
- Get different perspectives without repeating context
- Work on multiple problems in parallel sessions
- Process files locally and include content in conversations

## Installation

1. Clone this repository
2. Create a Python virtual environment:
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```
3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
4. Copy `.env.example` to `.env` and add your Gemini API key:
   ```bash
   cp .env.example .env
   # Edit .env file and set your GEMINI_API_KEY
   ```
5. Add to Claude Code:
   ```bash
   claude mcp add gemini-coding -s user -- /path/to/gemini-mcp/start_server.sh
   ```
   Replace `/path/to/gemini-mcp/` with the actual path to this directory.

## Tools Available

### 1. `consult_gemini`
Start or continue a conversation with Gemini about complex coding problems.

**Parameters:**
- `session_id` (optional): Continue a previous conversation
- `problem_description`: Description of the problem (required for new sessions)
- `code_context`: All relevant code (required for new sessions, cached afterward)
- `attached_files` (optional): Array of file paths to read and include in the conversation
- `file_descriptions` (optional): Object mapping file paths to descriptions
- `specific_question`: The question you want answered
- `additional_context` (optional): Updates or changes since last question
- `preferred_approach`: Type of help needed (solution/review/debug/optimize/explain/follow-up)

### 2. `list_sessions`
List all active Gemini consultation sessions.

### 3. `end_session`
End a specific session to free up memory.

## Usage Examples

### Starting a New Conversation (with text code)
```
/consult_gemini 
  problem_description: "I need to implement efficient caching for a React application"
  code_context: "[paste entire relevant codebase]"
  specific_question: "What's the best approach for implementing LRU cache with React Query?"
  preferred_approach: "solution"
```

### Starting a New Conversation (with file attachments)
```
/consult_gemini 
  problem_description: "I need to optimize this React component for performance"
  attached_files: ["/absolute/path/to/src/components/Dashboard.jsx", "/absolute/path/to/src/hooks/useData.js", "/absolute/path/to/package.json"]
  file_descriptions: {
    "/absolute/path/to/src/components/Dashboard.jsx": "Main dashboard component with performance issues",
    "/absolute/path/to/src/hooks/useData.js": "Custom hook for data fetching", 
    "/absolute/path/to/package.json": "Project dependencies"
  }
  specific_question: "How can I improve the rendering performance of this dashboard?"
  preferred_approach: "optimize"
```

### Combining Both Approaches
```
/consult_gemini 
  problem_description: "Complex authentication flow needs debugging"
  code_context: "// Additional context or pseudocode here"
  attached_files: ["/absolute/path/to/auth/login.js", "/absolute/path/to/middleware/auth.js"]
  specific_question: "Why is the token refresh failing?"
  preferred_approach: "debug"
```

Response includes a session ID for follow-ups.

### Follow-up Question
```
/consult_gemini
  session_id: "abc123..."
  specific_question: "I implemented your suggestion but getting stale data issues. How do I handle cache invalidation?"
  additional_context: "Added the LRU cache as suggested, but users see old data after updates"
  preferred_approach: "follow-up"
```

### Managing Sessions
```
/list_sessions
# Shows all active sessions with IDs and summaries

/end_session
  session_id: "abc123..."
# Frees up memory for completed conversations
```

## Best Practices

1. **Initial Context**: Include ALL relevant code via `code_context` or `attached_files`
2. **File Organization**: Use `attached_files` for multiple files, `code_context` for snippets
3. **File Descriptions**: Provide clear descriptions for each attached file
4. **Follow-ups**: Use the session ID to continue conversations
5. **Additional Context**: When asking follow-ups, explain what changed
6. **Session Management**: End sessions when done to free memory and clean up files
7. **Multiple Problems**: Use different sessions for unrelated problems
8. **File Types**: Supports JavaScript, Python, TypeScript, JSON, and other text-based files

## Testing the Server

You can test the server directly before adding it to Claude Code:

```bash
# Make sure your .env file has a valid GEMINI_API_KEY
./start_server.sh
```

The server will start and display:
```
Gemini Coding Assistant MCP Server v3.0 running (Python)
Features: Session management, file attachments, context persistence, follow-up questions
Ready to help with complex coding problems!
```

## Context Limits

- Maximum combined input: ~50,000 characters per message
- Maximum response: 8,192 tokens (~16,000 characters)
- Session timeout: 1 hour of inactivity
- Rate limiting: 1 second between requests

## How It Works

1. **First Message**: Creates a new session, caches code context
2. **Follow-ups**: Reuses cached context, maintains conversation history
3. **Session Storage**: In-memory storage (use Redis for production)
4. **Cleanup**: Automatic expiry after 1 hour of inactivity

## Advantages Over Stateless Design

- **Efficiency**: Code context sent only once per session
- **Context**: Gemini remembers previous questions and answers
- **Natural Flow**: Have real conversations about complex problems
- **Cost Savings**: Reduced token usage for follow-up questions

## Security

- API key is never exposed
- Rate limiting prevents abuse
- Sessions expire automatically
- No persistent storage of code
- When used with Claude Code Development Kit, additional security scanning prevents sensitive data leakage

## Version History

- v3.0.0: Enhanced system prompt for Claude Code Development Kit integration
- v2.1.0: Added file attachment system with automatic cleanup
- v2.0.0: Added session management and follow-up support  
- v1.0.0: Initial stateless implementation

## Connect

Feel free to connect with me on [LinkedIn](https://www.linkedin.com/in/peterkrueck/) if you have questions, need clarification, or wish to provide feedback.