aery-geminicli/README.md

Model Context Protocol (MCP) server for Gemini CLI integration with GitHub Copilot - includes advanced file reading, context management, and chat state tools

# 🚀 Aery Gemini CLI MCP Server

**AI-Powered Development Assistant** - Adds advanced Gemini AI capabilities to GitHub Copilot and Cursor through the Model Context Protocol (MCP).

## 🎯 What This Does

Transforms your coding assistant with powerful AI workflows:
- **🏗️ Architecture Analysis** - Deep codebase understanding
- **🔍 Smart Code Review** - Multi-perspective code analysis (security, performance, maintainability)
- **🧠 Project Intelligence** - Comprehensive project comprehension
- **💾 Persistent Memory** - Context that survives across sessions

## ⚡ Quick Setup

### 1. Install & Configure
```bash
# Install Gemini CLI (required dependency)
npm install -g gemini-cli

# Configure your API key
gemini config set-api-key YOUR_GEMINI_API_KEY
```

### 2. Add to MCP Config
Create/edit your MCP configuration file:

**🖥️ Windows:** `%APPDATA%\Code\User\globalStorage\github.copilot-chat\mcp.json`  
**🍎 Mac:** `~/Library/Application Support/Code/User/globalStorage/github.copilot-chat/mcp.json`

```json
{
  "servers": {
    "AeryGemini": {
      "type": "stdio",
      "command": "npx", 
      "args": ["-y", "aery-geminicli"],
      "env": {}
    }
  }
}
```

### 3. Activate
1. **Restart VS Code/Cursor completely**
2. **Test:** Ask Copilot: *"Use Aery to analyze the architecture of this project"*

## 🛠️ Available Tools & Usage Examples

### 🏗️ **Architecture Analysis Workflow**
```
Tool: workflow_analyze_architecture
```
**What to ask Copilot:**
- *"Use Aery to analyze the architecture of this project"*
- *"Run an architectural analysis on /path/to/project and save the results"*

**Parameters:**
- `project_path` (required): Project root directory
- `save_analysis` (optional, default: true): Save to persistent memory

**What it analyzes:**
- Architecture patterns and design decisions
- Directory structure and organization
- Component relationships and dependencies
- Technology stack identification
- Improvement recommendations

---

### 📋 **Smart Code Review Workflow**
```
Tool: workflow_smart_code_review
```
**What to ask Copilot:**
- *"Use Aery to do a complete code review of this function"*
- *"Run a security review on this code using Aery"*
- *"Aery: review this code for performance issues"*

**Parameters:**
- `code` (required): Code to review
- `review_type` (optional): `security`, `performance`, `maintainability`, or `all`
- `language` (optional): Programming language hint

**Review Types:**
- **🔒 Security:** Vulnerabilities, input validation, auth issues
- **⚡ Performance:** Bottlenecks, memory usage, algorithm efficiency  
- **🔧 Maintainability:** Code quality, SOLID principles, patterns

---

### 🧠 **Project Understanding Workflow**
```
Tool: workflow_project_understanding
```
**What to ask Copilot:**
- *"Use Aery to help me understand this entire project"*
- *"Aery: analyze this project focusing on the API and database layers"*

**Parameters:**
- `project_path` (required): Project root directory
- `focus_areas` (optional): Comma-separated areas to focus on

**Analysis Includes:**
- Project purpose and business goals
- Main features and functionality
- Technical architecture deep-dive
- Entry points and data flows
- Setup and configuration requirements

---

### 🗂️ **Context Management Workflow**
```
Tool: workflow_context_manager
```
**What to ask Copilot:**
- *"Use Aery to compress this long conversation"*
- *"Aery: save this analysis to memory with key 'project_overview'"*
- *"Recall what we saved about the user authentication system"*

**Actions:**
- `compress`: Summarize long content
- `save`: Store information in persistent memory
- `recall`: Retrieve saved information
- `clean`: Remove old memories (30+ days)

---

### 🔧 **Basic Tools**

#### Code Explanation
```
Tool: gemini_explain_code
```
**Ask:** *"Use Aery to explain this code in detail"*

#### General AI Queries  
```
Tool: gemini_query
```
**Ask:** *"Ask Aery: How can I optimize this algorithm?"*

#### File Operations
```
Tool: read_file_content
```
**Ask:** *"Use Aery to read and analyze the config file"*

#### Memory Management
```
Tools: save_to_memory, recall_from_memory
```
**Ask:** *"Aery: save this configuration pattern for later"*

## 💡 **Usage Examples & Conversation Starters**

### For AI Tools (Copy-Paste Ready Prompts)
```
"Use the workflow_analyze_architecture tool with project_path='/path/to/project' to analyze this codebase"

"Call workflow_smart_code_review with code='[PASTE_CODE]' and review_type='all' for comprehensive analysis"

"Execute workflow_project_understanding with project_path='/path/to/project' and focus_areas='API,database,authentication'"

"Run workflow_context_manager with action='compress' and content='[LONG_CONTENT]' to summarize"
```

### For Human Developers
```
"Use Aery to analyze the architecture of this project and save the results"
"Aery: do a complete security and performance review of this function"
"Help me understand this codebase using Aery's project analysis workflow"
"Aery: compress our conversation and save the key insights"
```

## 🏃‍♂️ **Real-World Workflow Examples**

### 📊 **New Project Onboarding**
```
1. "Use Aery to analyze the architecture of this project"
2. "Aery: help me understand the main components and data flow"
3. "Save this project analysis to memory for future reference"
```

### 🔍 **Code Review Process**
```
1. "Aery: review this pull request for security issues"
2. "Run a performance analysis on these database queries"
3. "Check this code for maintainability and design patterns"
```

### 🧩 **Debugging Complex Issues**
```
1. "Aery: analyze this error and the surrounding code architecture"
2. "Help me understand how this component fits in the overall system"
3. "Compress our debugging session and save key findings"
```

---

## 🐛 **Troubleshooting**

### ❌ **"gemini command not found"**
```bash
npm install -g gemini-cli
# Verify installation
gemini --version
```

### 🔑 **"API key not configured"**
```bash
# Set your Gemini API key
gemini config set-api-key YOUR_API_KEY

# Verify configuration
gemini config show
```

### 🔌 **"MCP not recognized by Copilot"**
1. **Restart VS Code completely** (not just reload window)
2. **Verify MCP config syntax** - Use a JSON validator
3. **Test manually:** `npx aery-geminicli` should start without errors
4. **Check file location** - Ensure mcp.json is in the correct directory

### 🚫 **"Tool execution failed"**
- **Check API limits** - Gemini has rate limits
- **Verify project path** - Use absolute paths
- **Check file permissions** - Ensure read access to project files

---

## 🏗️ **For AI Tools: Technical Implementation Details**

### **Tool Call Patterns**
```json
{
  "name": "workflow_analyze_architecture",
  "parameters": {
    "project_path": "/absolute/path/to/project",
    "save_analysis": true
  }
}
```

### **Response Structure**
All tools return:
```json
{
  "content": [{
    "type": "text", 
    "text": "Analysis results with emojis and structured format"
  }]
}
```

### **Memory Storage Location**
- **Path:** `~/.gemini-cli-mcp-memory.json`
- **Format:** `{ "key": { "content": "...", "category": "...", "timestamp": "..." } }`
- **Categories:** `general`, `architecture`, `project_analysis`, `context_manager`

### **Error Handling**
- All tools include try-catch with meaningful error messages
- Failed tool calls return error details in response text
- Memory operations are atomic and safe for concurrent access

---

## 🚀 Want More AI-Powered Development Tools?

**Join the QAK Platform Waitlist!** 

QAK is building the future of AI-powered test automation and development tools. Get early access to:

- ✨ **AI Test Generation** - Transform user stories into executable automated tests
- 🚀 **Smart Testing Workflows** - Automated testing pipelines powered by AI

**👉 [Join the Waitlist at qak.app](https://www.qak.app/)**

*Be among the first to experience the next generation of AI-powered development tools!*

---