📚 Groq MCP Document Assistant

A high-performance, persistent document management and research assistant powered by Groq and the Model Context Protocol (MCP). This system enables AI-driven document analysis, professional formatting, and long-term memory across sessions.

✨ Key Features

• 💾 Persistent Memory: All documents, edits, and additions are saved to a local db.json file. Your workspace state survives application restarts.

• ⚡ Groq-Powered Intelligence: Utilizes high-speed Llama 3 models for near-instant document summarization and complex formatting.

• 🛡️ Safety Circuit Breaker: Built-in protection against infinite tool-calling loops. The assistant automatically stops and asks for help after 10 autonomous steps.

• 🪄 Smart Formatting: Professional Markdown reformatting with a dedicated /format prompt that preserves original data while elevating readability.

• 🔍 Resource Integration: Mention documents in chat using the @filename syntax to automatically inject their content into the AI's context.

Related MCP server: Aleph

🚀 Getting Started

1. Requirements

• Python 3.11+

• Groq API Key (Get one at console.groq.com)

2. Installation

# Clone or enter the directory
cd MCP

# Setup virtual environment
python -m venv .venv
.venv\Scripts\activate

# Install dependencies
pip install groq mcp python-dotenv prompt-toolkit pydantic anyio

3. Configuration

Create a .env file in the root directory:

GROQ_API_KEY=your_key_here
GROQ_MODEL=llama-3.1-8b-instant

🎮 Usage

Launching the Assistant

python main.py

Common Commands

🛠️ Developer Tools

MCP Inspector

To test the server logic visually and inspect the JSON-RPC traffic:

npx @modelcontextprotocol/inspector .venv\Scripts\python.exe mcp_server.py

🏗️ Architecture

• main.py: The entry point that orchestrates the MCP clients and the Groq service.

• mcp_server.py: The core document server providing tools and prompts. Uses LocalStorage for db.json persistence.

• core/chat.py: Handles the autonomous loop and the 10-step circuit breaker.

• core/groq.py: Manages communication with Groq, including "Tool-Aware Trimming" to prevent history corruption.

🔒 Safety & Stability

This project is optimized for Windows and includes custom handlers for KeyboardInterrupt and asynchronous transport errors, ensuring a clean and silent exit on Ctrl+C.