Local MCP Gemini Automation Engine
A highly responsive, production-grade local AI agent workspace built on Anthropics' Model Context Protocol (MCP) and powered by the modern Google GenAI SDK.
This system intercepts custom markdown slash commands (/format) and relative resource targeting context syntax (@) directly from an asynchronous terminal user interface thread to read, reformat, and manipulate local simulated data files autonomously via background tool chains.
🛠️ System Architecture
The application is engineered using a decoupled, four-phase micro-process architecture to maximize scalability and isolate runtime concerns:
[Your Terminal UI Input] ──> Catch / or @ Shortcuts (cli.py)
│
▼
[Orchestration Engine] ──> Intercepts Prompt Template History (cli_chat.py)
│
▼
[Gemini Cloud Engine] ──> Reads context and returns autonomous Tool Action requests (gemini.py)
│
▼
[Tool Schema Router] ──> Maps parameters and selects correct target pipeline (tools.py)
│
▼
[MCP Process Gateway] ──> Streams arguments through background OS text pipes (mcp_client.py)
│
▼
[Local Secure Server] ──> Edits or Reads your local memory data blocks securely (mcp_server.py)
Phase 1: Core Infrastructure (core/gemini.py, mcp_server.py) — Houses the authenticated cloud AI client wrapper and a standalone local micro-server running over system standard input/output (stdio) channels.
• Phase 2: Gateway Clients (mcp_client.py, core/tools.py) — Establishes the background subprocess connection pipelines and translates local tool schema models into JSON configurations the AI natively understands.
• Phase 3: Orchestration Brain (core/chat.py, core/cli_chat.py) — Handles conversational persistence, monitors tool calling queues, pre-seeds custom structural histories, and parses page-relative targets.
• Phase 4: Interface Shell (core/cli.py, main.py) — Drives the asynchronous user interface buffer loops, keybindings, and reactive dropdown autocompletion filters.
🚀 Getting Started
Prerequisites
• Python 3.10+
• uv (Fast Python package installer and resolver)
• A Google AI Studio API Key
Installation & Configuration
1. Clone this repository to your local machine:
git clone [https://github.com/YOUR_USERNAME/local-mcp-gemini-cli.git](https://github.com/YOUR_USERNAME/local-mcp-gemini-cli.git)
cd cli_project
2. Create a local environment configuration file named .env in the root directory:
GEMINI_API_KEY=your_actual_google_ai_studio_key_here
GEMINI_MODEL=gemini-2.5-flash
USE_UV=1
(Note: The .env file is explicitly protected via .gitignore and will never be tracked or exposed via public source control.)
3. Launch the application environment thread using uv:
uv run --active main.py
💻 Usage & Interactivity
Once the active application loop boots up, you can interact with the system via standard messaging or structural shortcuts:
• Standard Context Mentioning (@): Type an @ symbol anywhere in your prompt line to dynamically open an autocompletion menu containing all exposed server documents. Selecting a file injects its text content straight into the background query layout context.
• Slash Automation Command (/format): Type /format (e.g., /format report.pdf) to fetch pre-baked prompt instructions from the server. The client intercepts the turn, spins up a dedicated history thread, reads the file via background tools, converts it to clean markdown layout structures, and saves it directly back to the mock vault without any verbose text filler.
🗂️ Project Directory Structure
cli_project/
├── core/
│ ├── cli.py # Terminal user interface buffer & keybind loops
│ ├── cli_chat.py # Command interceptors & history translation engines
│ ├── chat.py # Core chat loop & automated tool execution wheels
│ ├── tools.py # JSON schema translators and route selectors
│ └── gemini.py # Stateless model wrappers & payload serializers
├── main.py # Master context stack bootloader & orchestrator
├── mcp_client.py # Background stdio process management client
├── mcp_server.py # FastMCP tool, resource, and prompt provider
├── .gitignore # Secret file shield exclusions
├── .env # Private configurations (Local only)
└── README.md # Project blueprint documentation
