ayunis-core/ayunis-legal-mcp

A comprehensive system for searching and analyzing German legal texts using vector embeddings and semantic search, consisting of:
Store API: FastAPI backend with PostgreSQL, pgvector, and Ollama embeddings
MCP Server: FastMCP server providing tools for AI assistants to query legal texts
CLI Tool: Command-line interface for importing and querying legal texts
Web Scraper: Automatic extraction of legal texts from gesetze-im-internet.de
XML Parser: Comprehensive parser for German legal XML format (gii-norm.dtd)
## Table of Contents
Features
Architecture
Quick Start
CLI Tool
Environment Configuration
API Documentation
Legal Text Features
XML Parser
Development
Docker Commands
Troubleshooting
Project Structure
Technology Stack
## Features
### Store API Features
🗄️ PostgreSQL + pgvector - Vector database for semantic search
🤖 Ollama Integration - Generate embeddings for legal texts
🌐 Web Scraping - Automatic extraction from gesetze-im-internet.de
📄 XML Parsing - Comprehensive parser for German legal XML format
🔍 Semantic Search - Vector-based similarity search for legal texts
📊 Metadata Tracking - Full document metadata and versioning
📝 RESTful API - FastAPI with automatic documentation
🌍 Multi-jurisdiction model - Source/document identity and jurisdiction-wide search
🐳 Docker Support - Easy deployment with containerization
### MCP Server Features
🔧 FastMCP - Modern MCP server implementation
🤝 AI Assistant Integration - Provides tools for querying legal texts
🔌 HTTP API Client - Connects to Store API for data access
### CLI Tool Features
📋 List Commands - View imported codes and available catalog
📥 Import Commands - Import legal codes with progress indication
🔍 Query Commands - Retrieve texts by code, section, and sub-section
🔎 Search Commands - Semantic search with similarity scoring
📊 Multiple Output Formats - Table view or JSON output
⚙️ Configurable - Custom API URL support via flag or environment variable
## Architecture
┌──────────────────────────────────────────────────┐
│ │
│ Docker Network: legal-mcp-network │
│ │
│ ┌────────────────┐ │
│ │ MCP Server │ :8001 │
│ │ (FastMCP) │ │
│ └───────┬────────┘ │
│ │ │
│ │ LEGAL_API_BASE_URL │
│ │ http://store-api:8000 │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Store API │ :8000 │
│ │ (FastAPI) │ │
│ └───────┬────────┘ │
│ │ │
│ │ DATABASE_URL │
│ │ postgresql://postgres:5432 │
│ │ OLLAMA_BASE_URL │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ PostgreSQL │ :5432 │
│ │ + pgvector │ │
│ └────────────────┘ │
│ │
└──────────────────────────────────────────────────┘
│ External Ollama Service
│ (for embeddings)
┌────────────────┐
│ Ollama API │
│ (Remote/Local)│
└────────────────┘
## Quick Start
### Prerequisites
Docker and Docker Compose
Ollama (local or remote endpoint for embeddings)
Git
> ⚠️ Important: Ollama Embedding Model
> By default, this project uses the embedding model: ryanshillington/Qwen3-Embedding-4B:latest
> You must pull this model (or your configured alternative) before importing legal texts:
> bash
> ollama pull ryanshillington/Qwen3-Embedding-4B:latest
> You can use a different model by setting the OLLAMA_EMBEDDING_MODEL environment variable, but the model must produce 2560-dimensional vectors. Using a model with different dimensions will cause errors, as the database schema is fixed at 2560 dimensions. Changing to a model with different dimensions would require database schema modifications and re-importing all legal texts.