# 📚 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](https://console.groq.com))

### 2. Installation
```powershell
# 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:
```env
GROQ_API_KEY=your_key_here
GROQ_MODEL=llama-3.1-8b-instant
```

---

## 🎮 Usage

### Launching the Assistant
```powershell
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:
```powershell
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`.