Groq 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.

---

🚀 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

Command	Action
/list_docs	Show all documents currently in the persistent database.
/format <doc_id>	Automatically restructure a document into professional Markdown.
/summarize_doc <doc_id>	Generate a concise summary of the specified document.
/add_doc <id> "<content>"	Create a new document in the database.
@doc_id	Mention any document in a normal sentence to use its content as context.

[!TIP] Use Tab for auto-completion of commands and document IDs!

---

🛠️ 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.