# Legal RAG Toolkit

Semantic search over Turkish legal contracts and emails, powered by an MCP server that plugs directly into Claude Desktop and Claude Code.

Instead of building a separate web UI, Claude **is** the interface — the toolkit provides the retrieval backend as MCP tools and Claude Code skills.

## What it does

- **Ingest** PDF, DOCX, and `.eml` files — parse, chunk, embed, and store in a local vector database
- **Search** contracts and emails with hybrid dense+sparse retrieval (Turkish and English queries)
- **Retrieve** full documents by filename for deep reading
- **Skills** for Claude Code: `/search-contract`, `/analyze-clause`, `/draft-response`, `/ingest-docs`, `/ingest-emails`

## Architecture

```
Claude Desktop / Claude Code
        |
        | MCP (stdio)
        |
[Legal RAG MCP Server] ── Python, FastMCP
  |
  |── search_contracts     hybrid vector search over contracts
  |── search_emails        hybrid vector search over emails
  |── get_document         retrieve all chunks for a file
  |── ingest_docs          parse + embed PDF/DOCX documents
  |── ingest_email         parse + embed .eml files
  |── list_sources         show indexed files and stats
  |
  |── LanceDB              embedded vector DB (file-based, zero-server)
  |── BAAI/bge-m3          multilingual embeddings (1024d, 8K context)
  |── PyMuPDF + pdfplumber PDF parsing
  |── python-docx          DOCX parsing
  |── imap_tools           email parsing
```

## Setup

```bash
# Clone
git clone https://github.com/avocatt/legal-rag-toolkit.git
cd legal-rag-toolkit

# Create venv and install
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .

# Store HuggingFace token in macOS Keychain (for BGE-M3 model download)
security add-generic-password -a $USER -s HF_TOKEN -w "hf_your_token_here"
```

## Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "legal-rag-toolkit": {
      "command": "/path/to/legal-rag-toolkit/.venv/bin/python",
      "args": ["/path/to/legal-rag-toolkit/src/server/mcp_server.py"]
    }
  }
}
```

Restart Claude Desktop. The tools will appear under the hammer icon.

## Claude Code

```bash
# Add as MCP server
claude mcp add legal-rag-toolkit -- /path/to/legal-rag-toolkit/.venv/bin/python /path/to/legal-rag-toolkit/src/server/mcp_server.py
```

## Usage

Once connected, ask Claude naturally:

- *"Index the contracts in ~/Documents/contracts"*
- *"Search for termination clauses in lease agreements"*
- *"Kira sozlesmelerinde tahliye sartlarini ara"*
- *"Show me all indexed documents"*
- *"Pull up the full text of kira_sozlesmesi_048.pdf"*

## Stack

| Component | Choice | Why |
|-----------|--------|-----|
| MCP Server | Python + FastMCP | Single language, mature SDK |
| Embeddings | BAAI/bge-m3 | 8K context, hybrid retrieval, MIT, Turkish via XLM-RoBERTa |
| Vector DB | LanceDB | Embedded, file-based, hybrid search, zero infrastructure |
| PDF Parsing | PyMuPDF + pdfplumber | Fast, lightweight, good table extraction |
| DOCX Parsing | python-docx | Structural parsing with style detection |
| Email Parsing | imap_tools | Turkish charset support (ISO-8859-9) |

## Roadmap

- [ ] KVKK (Turkish GDPR) PII masking before indexing
- [ ] Structure-aware chunking using heading styles and font sizes
- [ ] Cross-encoder reranking with `BAAI/bge-reranker-v2-m3`
- [ ] Docling integration for OCR and complex PDF layouts
- [ ] Local LLM support via OpenAI-compatible API

## License

MIT