Gemini MCP Server Architecture Plan

Overview

An MCP server that enables Claude to orchestrate multiple Gemini AI agents dynamically, with each agent maintaining its own conversational context through persistent sessions.

✅ Implementation Status

COMPLETED - The Gemini MCP server is now fully implemented and ready for use!

What's Implemented:

• ✅ Complete MCP server with all 6 tool functions
• ✅ Dynamic agent creation and management
• ✅ Gemini API integration with session management
• ✅ Both in-memory and SQLite storage options
• ✅ Context handoff between agents
• ✅ Automatic session cleanup
• ✅ Comprehensive error handling
• ✅ Background cleanup tasks
• ✅ Full conversation history tracking

Quick Start

1. Installation

# Clone or navigate to the project directory
cd gemini_mcp

# Install dependencies
pip install -r requirements.txt

2. Configuration

Create a .env file with your Gemini API key:

# Copy the example environment file
cp .env.example .env

# Edit .env and add your Gemini API key
GEMINI_API_KEY=your-actual-api-key-here

3. Configure Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "gemini-orchestrator": {
      "command": "python",
      "args": ["-m", "gemini_mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here",
        "STORAGE_TYPE": "memory"
      }
    }
  }
}

4. Run the Server

# Run directly
python -m gemini_mcp

# Or run the main module
python __main__.py

5. Test Basic Functionality

# Run basic tests
python tests/test_basic.py

Usage Examples

Creating and Using Agents

Claude: "I need to set up a development team for a new project."

# Create a business analyst
ai_agents_create(
    role="business_analyst",
    system_prompt="You are an experienced business analyst specialising in requirements gathering and stakeholder management. Focus on understanding business needs and translating them into clear, actionable requirements."
)

# Create a software architect  
ai_agents_create(
    role="architect",
    system_prompt="You are a senior software architect with expertise in scalable system design, microservices, and cloud architecture. Provide technical solutions that are robust, maintainable, and future-proof."
)

# Get requirements from business analyst
ai_agents_send_message(
    role="business_analyst",
    message="What are the key considerations for building a task management system for a remote team of 50 people?"
)

# Hand off context to architect
ai_agents_handoff(
    from_role="business_analyst",
    to_role="architect", 
    context_summary="Requirements gathered for a task management system: 50 remote users, needs real-time collaboration, mobile support, integration with existing tools, and strong security.",
    include_full_history=true
)

# Get architectural recommendations
ai_agents_send_message(
    role="architect",
    message="Based on these requirements, what architecture would you recommend and what are the key technical decisions we need to make?"
)

Managing Agents

# List all active agents
ai_agents_list()

# Get conversation history
ai_agents_get_conversation(
    role="architect",
    last_n_messages=10
)

# Delete an agent when done
ai_agents_delete(role="business_analyst")

Core Architecture

1. Dynamic Agent Management

Key Principle: Agents are created on-demand during conversations, not pre-configured.

Claude → MCP Server → Gemini API
         ↓
    Session Store
    (Memory/SQLite)

2. Storage Options

In-Memory Storage (RAM)

• Pros: Lightning fast, no I/O overhead
• Cons: Data lost on server restart
• Use Case: Development, testing, short-lived sessions

SQLite Storage

• Pros: Persistent, lightweight, no external dependencies
• Cons: Slightly slower than memory
• Implementation: Auto-initialised database file in project directory

# Auto-initialisation example
db_path = Path(__file__).parent / "sessions.db"
if not db_path.exists():
    initialise_database(db_path)

MCP Tool Functions

1. ai_agents_create

{
    "name": "ai_agents_create",
    "description": "Create a new Gemini agent with a specific role",
    "parameters": {
        "role": "string (e.g., 'architect', 'tester')",
        "system_prompt": "string (defines agent behaviour)",
        "session_id": "optional string (auto-generated if not provided)"
    }
}

2. ai_agents_send_message

{
    "name": "ai_agents_send_message",
    "description": "Send a message to a specific agent",
    "parameters": {
        "role": "string (agent role)",
        "message": "string (prompt to send)",
        "include_context": "boolean (whether to include previous context)"
    }
}

3. ai_agents_list

{
    "name": "ai_agents_list",
    "description": "List all active agents and their sessions",
    "returns": [
        {
            "role": "string",
            "session_id": "string",
            "created_at": "timestamp",
            "last_interaction": "timestamp",
            "message_count": "integer"
        }
    ]
}

4. ai_agents_get_conversation

{
    "name": "ai_agents_get_conversation",
    "description": "Retrieve conversation history for an agent",
    "parameters": {
        "role": "string",
        "last_n_messages": "integer (optional, default all)"
    }
}

5. ai_agents_handoff

{
    "name": "ai_agents_handoff",
    "description": "Pass context from one agent to another",
    "parameters": {
        "from_role": "string",
        "to_role": "string",
        "context_summary": "string (what to pass along)",
        "include_full_history": "boolean"
    }
}

6. ai_agents_delete

{
    "name": "ai_agents_delete",
    "description": "Remove an agent and its session",
    "parameters": {
        "role": "string"
    }
}

Session Schema

Memory Storage Structure

sessions = {
    "architect_1234": {
        "role": "architect",
        "session_id": "1234",
        "gemini_session": "gemini_session_abc123",
        "system_prompt": "You are a software architect...",
        "created_at": "2024-01-01T10:00:00Z",
        "last_interaction": "2024-01-01T11:30:00Z",
        "messages": [
            {"role": "user", "content": "...", "timestamp": "..."},
            {"role": "assistant", "content": "...", "timestamp": "..."}
        ]
    }
}

SQLite Schema

CREATE TABLE IF NOT EXISTS agents (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    role TEXT UNIQUE NOT NULL,
    session_id TEXT UNIQUE NOT NULL,
    gemini_session TEXT,
    system_prompt TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_interaction TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    agent_id INTEGER,
    role TEXT NOT NULL,
    content TEXT NOT NULL,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (agent_id) REFERENCES agents(id)
);

CREATE TABLE IF NOT EXISTS handoffs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    from_agent_id INTEGER,
    to_agent_id INTEGER,
    context_summary TEXT,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (from_agent_id) REFERENCES agents(id),
    FOREIGN KEY (to_agent_id) REFERENCES agents(id)
);

Configuration

Environment Variables

{
    "mcpServers": {
        "gemini-orchestrator": {
            "command": "python",
            "args": ["-m", "gemini_mcp"],
            "env": {
                "GEMINI_API_KEY": "your-api-key-here",
                "GEMINI_MODEL": "gemini-1.5-pro",
                "STORAGE_TYPE": "memory|sqlite",
                "SQLITE_PATH": "./sessions.db",
                "SESSION_TIMEOUT_HOURS": "24",
                "MAX_AGENTS": "10"
            }
        }
    }
}

Usage Example

Claude's Workflow

1. Initialise Project Team

Claude: "I'll set up a development team for your project."

ai_agents_create(
    role="business_analyst",
    system_prompt="You are a business analyst focusing on requirements gathering..."
)

ai_agents_create(
    role="architect",
    system_prompt="You are a software architect designing scalable systems..."
)

2. Gather Requirements

Claude: "Let me ask our business analyst about the requirements."

ai_agents_send_message(
    role="business_analyst",
    message="What are the key functional requirements for a task management system?"
)

3. Design Architecture

Claude: "Now I'll have our architect design the system based on these requirements."

ai_agents_handoff(
    from_role="business_analyst",
    to_role="architect",
    context_summary="Key requirements: multi-user support, real-time updates, mobile-first..."
)

ai_agents_send_message(
    role="architect",
    message="Based on these requirements, what architecture would you recommend?"
)

Development Roadmap

For detailed development plans, security considerations, and future enhancements, see docs/ROADMAP.md.

Current Status: Version 1.0 is complete and production-ready ✅

Next Steps: Version 1.1 focuses on security, reliability, and observability improvements. All roadmap items are tracked as GitHub Issues.

Package Structure

gemini_mcp/
├── README.md
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
├── __init__.py
├── __main__.py
├── server.py
├── storage/
│   ├── __init__.py
│   ├── memory.py
│   └── sqlite.py
├── agents/
│   ├── __init__.py
│   └── manager.py
├── gemini/
│   ├── __init__.py
│   └── client.py
├── tests/
│   ├── __init__.py
│   └── test_basic.py
└── sessions.db (auto-created)

Troubleshooting

Common Issues

1. "GEMINI_API_KEY not found"

   • Ensure you've set the environment variable
   • Check your .env file exists and has the correct key

2. "Rate limit reached"

   • Gemini API has rate limits
   • Wait 60 seconds and retry
   • Consider upgrading your API quota

3. "Agent not found"

   • Verify the agent role exists with list_agents()
   • Check for typos in the role name

4. SQLite permission errors

   • Ensure the directory is writable
   • Check file permissions on the database

Getting Help

• Check the logs for detailed error messages
• Run the basic tests to verify functionality
• Review the configuration settings
• Ensure all dependencies are installed

Contributing

Contributions are welcome! See docs/ROADMAP.md for development priorities and GitHub Issues for specific tasks.

Development Guidelines

• Follow PEP 8 style guide
• Add tests for new features
• Update documentation
• Use type hints
• Profile before optimising

---

Ready to use! The Gemini MCP server is fully implemented and ready for production use with Claude Desktop.