Skip to content

Mapicx/MapR1

BranchesTags

Repository files navigation

Unified MCP Client

A modular AI-powered client that combines filesystem and browser automation using the Model Context Protocol (MCP). Supports multiple LLM providers: Ollama (local), Google Gemini, and Groq.

Features

  • 🤖 Multiple LLM Providers: Ollama, Gemini, or Groq
  • 📁 Filesystem Operations: Create, read, update, delete files and directories
  • 🌐 Browser Automation: Web scraping and browser control
  • 📅 Google Calendar Integration: Create, read, update, delete calendar events
  • 🔧 Modular Architecture: Clean, maintainable code structure
  • 🔄 Persistent Connections: Maintains connections to multiple MCP servers
  • 🛡️ Loop Detection: Prevents infinite loops in task execution

Project Structure

.
├── client/                          # Main client code
│   ├── main.py                     # Entry point and CLI
│   ├── mcp_client.py               # Core MCP client logic
│   ├── llm_provider.py             # LLM initialization
│   ├── prompts.py                  # System prompts
│   └── config.py                   # Configuration
├── filesystem-mcp-server/          # Filesystem MCP server (included)
├── mcp-server-browser-use-ollama/  # Browser MCP server (included)
├── gcp-oauth.keys.json             # Google OAuth credentials (create this)
├── Sandbox/                        # Working directory for file operations
├── .env                            # Environment variables (create this)
├── .gitignore                      # Git ignore rules
├── requirements.txt                # Python dependencies
├── setup.sh                        # Setup script for Linux/Mac
├── setup.bat                       # Setup script for Windows
├── README.md                       # This file
└── SETUP.md                        # Detailed setup guide

Prerequisites

  • Python 3.8+
  • Node.js 16+ (for filesystem MCP server)
  • Ollama (optional, for local LLM)
  • API Keys (optional):
    • GEMINI_API_KEY for Google Gemini
    • GROQ_API_KEY for Groq

Quick Start

Automated Setup (Recommended)

For Windows:

setup.bat

For Linux/Mac:

chmod +x setup.sh
./setup.sh

The setup script will:

  • ✅ Check prerequisites (Python, Node.js, npm)
  • ✅ Create Python virtual environment
  • ✅ Install all dependencies
  • ✅ Build MCP servers
  • ✅ Create Sandbox directory

Manual Setup

If you prefer to set up manually or the script fails:

1. Clone the Repository

git clone <your-repo-url>
cd <repo-name>

Note: All MCP servers are included in the repository, no need to clone them separately!

2. Set Up Python Environment

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On Linux/Mac:
source .venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

3. Set Up Filesystem MCP Server

# Navigate to the filesystem server directory
cd filesystem-mcp-server

# Install Node.js dependencies
npm install

# Build the server
npm run build

# Go back to root
cd ..

4. Set Up Browser MCP Server

# Navigate to the browser server directory
cd mcp-server-browser-use-ollama

# Install dependencies (if requirements.txt exists)
pip install -r requirements.txt

# Go back to root
cd ..

5. Configure Environment Variables

Create a .env file in the root directory:

# Optional: Only needed if using Gemini or Groq
GEMINI_API_KEY=your_gemini_api_key_here
GROQ_API_KEY=your_groq_api_key_here

6. Update Configuration Paths (Optional)

The default configuration uses relative paths and should work out of the box.

If you need to customize paths, edit client/config.py:

# The default uses relative paths (recommended):
PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
FILESYSTEM_BASE_DIR = os.path.join(PROJECT_ROOT, "Sandbox")
FILESYSTEM_SERVER_PATH = os.path.join(PROJECT_ROOT, "filesystem-mcp-server", "dist", "index.js")
BROWSER_SERVER_PATH = os.path.join(PROJECT_ROOT, "mcp-server-browser-use-ollama", "src", "server.py")

# Or use absolute paths if needed:
# FILESYSTEM_BASE_DIR = "C:\\Users\\YourName\\unified-mcp-client\\Sandbox"
# FILESYSTEM_SERVER_PATH = "C:\\Users\\YourName\\unified-mcp-client\\filesystem-mcp-server\\dist\\index.js"
# BROWSER_SERVER_PATH = "C:\\Users\\YourName\\unified-mcp-client\\mcp-server-browser-use-ollama\\src\\server.py"

7. Create Sandbox Directory

# Create the working directory for file operations
mkdir Sandbox

8. Set Up Google Calendar (Optional)

If you want calendar integration:

  1. Create Google Cloud Project:

    • Go to Google Cloud Console
    • Create a new project or select existing one
    • Enable the Google Calendar API

  2. Create OAuth Credentials:

    • Go to "APIs & Services" > "Credentials"
    • Click "Create Credentials" > "OAuth client ID"
    • Choose "Desktop app" as application type
    • Download the JSON file and rename it to gcp-oauth.keys.json
    • Place it in the project root directory

  3. Install the Calendar MCP Server:

    npm install -g @gongrzhe/server-calendar-autoauth-mcp

  4. Authenticate (first time only):

    npx @gongrzhe/server-calendar-autoauth-mcp auth

    This will open your browser for Google authentication.

9. Install Ollama (Optional)

If you want to use local LLMs:

  1. Download Ollama from ollama.ai
  2. Install and start Ollama
  3. Pull the required model:
ollama pull qwen2.5-coder:14b

Usage

Basic Usage

# With Ollama (local) - uses qwen2.5-coder:14b
python client/main.py "Create a folder called 'projects'"

# With Gemini - uses gemini-2.0-flash-exp
python client/main.py "Your task" --gemini

# With Groq - uses llama-3.1-70b-versatile
python client/main.py "Your task" --groq

Advanced Options

# Filesystem operations only (faster)
python client/main.py "Create a file notes.txt" --filesystem-only

# Browser operations only
python client/main.py "Open GitHub trending" --browser-only

# Calendar operations only
python client/main.py "What's on my calendar today?" --calendar-only

# Skip calendar (if not set up)
python client/main.py "Create notes.txt" --no-calendar

# Debug mode
python client/main.py "Your task" --debug

# Custom max iterations
python client/main.py "Your task" --max-iterations 30

Example Tasks

# File operations
python client/main.py "Create a file hello.txt with 'Hello World'"

# Web scraping
python client/main.py "Open GitHub trending, get top 5 Python repos, save to file"

# Calendar management
python client/main.py "Schedule a team meeting tomorrow at 2pm"
python client/main.py "What meetings do I have this week?"
python client/main.py "Cancel my 3pm meeting today"

# Combined operations
python client/main.py "Check my calendar, then create a summary file of today's meetings"

Configuration

Changing LLM Models

Edit client/llm_provider.py to change the hardcoded models:

# Groq
model_name = "llama-3.1-70b-versatile"

# Gemini
model_name = "gemini-2.0-flash-exp"

# Ollama
model_name = "qwen2.5-coder:14b"

Adjusting LLM Settings

Edit client/config.py:

LLM_TEMPERATURE = 0.7          # Creativity (0.0 - 1.0)
OLLAMA_CONTEXT_SIZE = 32000    # Context window size
MAX_ITERATIONS = 20            # Max task iterations

Modifying System Prompts

Edit client/prompts.py to customize the AI assistant's behavior.

Troubleshooting

"No such file or directory" Errors

Update the paths in client/config.py to use absolute paths for your system:

import os

# Get the project root directory
PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# Use relative paths from project root
FILESYSTEM_BASE_DIR = os.path.join(PROJECT_ROOT, "Sandbox")
FILESYSTEM_SERVER_PATH = os.path.join(PROJECT_ROOT, "filesystem-mcp-server", "dist", "index.js")
BROWSER_SERVER_PATH = os.path.join(PROJECT_ROOT, "mcp-server-browser-use-ollama", "src", "server.py")

Filesystem Server Won't Start

# Make sure Node.js is installed
node --version

# Rebuild the server
cd filesystem-mcp-server
npm install
npm run build
cd ..

Python Dependencies Issues

# Upgrade pip
python -m pip install --upgrade pip

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

Ollama Connection Failed

# Check if Ollama is running
curl http://localhost:11434

# Start Ollama service
ollama serve

API Key Errors

Make sure your .env file is in the root directory and contains valid API keys:

# Check if .env exists
cat .env  # Linux/Mac
type .env  # Windows

# Verify environment variables are loaded
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.getenv('GEMINI_API_KEY'))"

Browser Server Issues

# Make sure browser dependencies are installed
cd mcp-server-browser-use-ollama
pip install -r requirements.txt
cd ..

Development

Project Structure Details

  • client/main.py: CLI entry point, argument parsing, server initialization
  • client/mcp_client.py: Core logic for MCP connections, tool execution, conversation management
  • client/llm_provider.py: LLM initialization for different providers
  • client/prompts.py: System prompts and instructions for the AI
  • client/config.py: Centralized configuration and environment setup

Adding New Features

  1. New LLM Provider: Add to llm_provider.py
  2. New MCP Server: Update main.py connection logic
  3. Custom Prompts: Modify prompts.py
  4. Configuration: Add to config.py

Requirements

Create a requirements.txt file:

mcp
langchain-ollama
langchain-google-genai
langchain-groq
langchain-core
python-dotenv
pydantic

License

[Your License Here]

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

Support

For issues and questions:

  • Open an issue on GitHub
  • Check existing documentation
  • Review troubleshooting section

Acknowledgments

About

Hmmm

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages