legal-rag-toolkit

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

# 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:

{
  "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

# 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