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

🚀 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

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