Skip to content
Back to search

ayunis-legal-mcp

An MCP server for German legal codes

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ayunis-core--ayunis-legal-mcp/badge.svg)](/listings/ayunis-core--ayunis-legal-mcp)

HTML

<a href="/listings/ayunis-core--ayunis-legal-mcp"><img src="/api/listings/ayunis-core--ayunis-legal-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

1. Clone and Setup

# Clone the repository
git clone <repository-url>
cd legal-mcp

# Copy environment file
cp .env.example .env

# Edit .env with your configuration
# Update OLLAMA_BASE_URL and OLLAMA_AUTH_TOKEN if needed

2. Start All Services

# Build and start all services
docker-compose up -d

# Check service status
docker-compose ps

This will start:

- **PostgreSQL** (port 5432) - Database with pgvector extension - **Store API** (port 8000) - FastAPI backend for legal texts - **MCP Server** (port 8001) - FastMCP server for AI assistants

3. Run Database Migrations

# Run Alembic migrations to set up the database
docker-compose exec store-api alembic upgrade head

4. Import Legal Texts

# Import a test legal code (e.g., rag_1)
curl -X POST http://localhost:8000/legal-texts/gesetze-im-internet/rag_1

# Import German Civil Code (BGB)
curl -X POST http://localhost:8000/legal-texts/gesetze-im-internet/bgb

# Import other legal codes
curl -X POST http://localhost:8000/legal-texts/gesetze-im-internet/stgb  # Criminal Code
curl -X POST http://localhost:8000/legal-texts/gesetze-im-internet/gg    # Constitution

5. Test the API

# Check API health
curl http://localhost:8000/health

# Query legal texts by section
curl "http://localhost:8000/legal-texts/gesetze-im-internet/rag_1?section=%C2%A7%201"

# Semantic search (requires embeddings)
curl "http://localhost:8000/legal-texts/gesetze-im-internet/rag_1/search?q=Versicherung&limit=5"

# Search all imported federal codes, or restrict by code/source/document
curl "http://localhost:8000/legal-texts/search?q=Versicherung&jurisdiction=DE"

# Source-independent exact lookup
curl "http://localhost:8000/legal-texts?jurisdiction=DE&code=rag_1&section=%C2%A7%201"

# Access interactive API documentation
open http://localhost:8000/docs

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 601 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Legal MCP - German Legal Texts Search System
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  4. [![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com/)
  5. [![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
  6. A comprehensive system for searching and analyzing German legal texts using vector embeddings and semantic search, consisting of:
  7. - **Store API**: FastAPI backend with PostgreSQL, pgvector, and Ollama embeddings
  8. - **MCP Server**: FastMCP server providing tools for AI assistants to query legal texts
  9. - **CLI Tool**: Command-line interface for importing and querying legal texts
  10. - **Web Scraper**: Automatic extraction of legal texts from gesetze-im-internet.de
  11. - **XML Parser**: Comprehensive parser for German legal XML format (gii-norm.dtd)
  12. ## Table of Contents
  13. - [Features](#features)
  14. - [Architecture](#architecture)
  15. - [Quick Start](#quick-start)
  16. - [CLI Tool](#cli-tool)
  17. - [Environment Configuration](#environment-configuration)
  18. - [API Documentation](#api-documentation)
  19. - [Legal Text Features](#legal-text-features)
  20. - [XML Parser](#xml-parser)
  21. - [Development](#development)
  22. - [Docker Commands](#docker-commands)
  23. - [Troubleshooting](#troubleshooting)
  24. - [Project Structure](#project-structure)
  25. - [Technology Stack](#technology-stack)
  26. ## Features
  27. ### Store API Features
  28. - 🗄️ **PostgreSQL + pgvector** - Vector database for semantic search
  29. - 🤖 **Ollama Integration** - Generate embeddings for legal texts
  30. - 🌐 **Web Scraping** - Automatic extraction from gesetze-im-internet.de
  31. - 📄 **XML Parsing** - Comprehensive parser for German legal XML format
  32. - 🔍 **Semantic Search** - Vector-based similarity search for legal texts
  33. - 📊 **Metadata Tracking** - Full document metadata and versioning
  34. - 📝 **RESTful API** - FastAPI with automatic documentation
  35. - 🌍 **Multi-jurisdiction model** - Source/document identity and jurisdiction-wide search
  36. - 🐳 **Docker Support** - Easy deployment with containerization
  37. ### MCP Server Features
  38. - 🔧 **FastMCP** - Modern MCP server implementation
  39. - 🤝 **AI Assistant Integration** - Provides tools for querying legal texts
  40. - 🔌 **HTTP API Client** - Connects to Store API for data access
  41. ### CLI Tool Features
  42. - 📋 **List Commands** - View imported codes and available catalog
  43. - 📥 **Import Commands** - Import legal codes with progress indication
  44. - 🔍 **Query Commands** - Retrieve texts by code, section, and sub-section
  45. - 🔎 **Search Commands** - Semantic search with similarity scoring
  46. - 📊 **Multiple Output Formats** - Table view or JSON output
  47. - ⚙️ **Configurable** - Custom API URL support via flag or environment variable
  48. ## Architecture
  49. ```
  50. ┌──────────────────────────────────────────────────┐
  51. │ │
  52. │ Docker Network: legal-mcp-network │
  53. │ │
  54. │ ┌────────────────┐ │
  55. │ │ MCP Server │ :8001 │
  56. │ │ (FastMCP) │ │
  57. │ └───────┬────────┘ │
  58. │ │ │
  59. │ │ LEGAL_API_BASE_URL │
  60. │ │ http://store-api:8000 │
  61. │ │ │
  62. │ ▼ │
  63. │ ┌────────────────┐ │
  64. │ │ Store API │ :8000 │
  65. │ │ (FastAPI) │ │
  66. │ └───────┬────────┘ │
  67. │ │ │
  68. │ │ DATABASE_URL │
  69. │ │ postgresql://postgres:5432 │
  70. │ │ OLLAMA_BASE_URL │
  71. │ │ │
  72. │ ▼ │
  73. │ ┌────────────────┐ │
  74. │ │ PostgreSQL │ :5432 │
  75. │ │ + pgvector │ │
  76. │ └────────────────┘ │
  77. │ │
  78. └──────────────────────────────────────────────────┘
  79. │
  80. │ External Ollama Service
  81. │ (for embeddings)
  82. ▼
  83. ┌────────────────┐
  84. │ Ollama API │
  85. │ (Remote/Local)│
  86. └────────────────┘
  87. ```
  88. ## Quick Start
  89. ### Prerequisites
  90. - Docker and Docker Compose
  91. - Ollama (local or remote endpoint for embeddings)
  92. - Git
  93. > ⚠️ **Important: Ollama Embedding Model**
  94. >
  95. > By default, this project uses the embedding model: `ryanshillington/Qwen3-Embedding-4B:latest`
  96. >
  97. > You must pull this model (or your configured alternative) before importing legal texts:
  98. > ```bash
  99. > ollama pull ryanshillington/Qwen3-Embedding-4B:latest
  100. > ```
  101. >
  102. > 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.
  103. ### 1. Clone and Setup
  104. ```bash
  105. # Clone the repository
  106. git clone <repository-url>
  107. cd legal-mcp
  108. # Copy environment file
  109. cp .env.example .env
  110. # Edit .env with your configuration
  111. # Update OLLAMA_BASE_URL and OLLAMA_AUTH_TOKEN if needed
  112. ```
  113. ### 2. Start All Services
  114. ```bash
  115. # Build and start all services
  116. docker-compose up -d
  117. # Check service status
  118. docker-compose ps
  119. ```
  120. This will start:
  121. - **PostgreSQL** (port 5432) - Database with pgvector extension
  122. - **Store API** (port 8000) - FastAPI backend for legal texts
  123. - **MCP Server** (port 8001) - FastMCP server for AI assistants
  124. ### 3. Run Database Migrations
  125. ```bash
  126. # Run Alembic migrations to set up the database
  127. docker-compose exec store-api alembic upgrade head
  128. ```
  129. ### 4. Import Legal Texts
  130. ```bash
  131. # Import a test legal code (e.g., rag_1)
  132. curl -X POST http://localhost:8000/legal-texts/gesetze-im-internet/rag_1
  133. # Import German Civil Code (BGB)
  134. curl -X POST http://localhost:8000/legal-texts/gesetze-im-internet/bgb
  135. # Import other legal codes
  136. curl -X POST http://localhost:8000/legal-texts/gesetze-im-internet/stgb # Criminal Code
  137. curl -X POST http://localhost:8000/legal-texts/gesetze-im-internet/gg # Constitution
  138. ```
  139. ### 5. Test the API
  140. ```bash
  141. # Check API health
  142. curl http://localhost:8000/health
  143. # Query legal texts by section
  144. curl "http://localhost:8000/legal-texts/gesetze-im-internet/rag_1?section=%C2%A7%201"
  145. # Semantic search (requires embeddings)
  146. curl "http://localhost:8000/legal-texts/gesetze-im-internet/rag_1/search?q=Versicherung&limit=5"
  147. # Search all imported federal codes, or restrict by code/source/document
  148. curl "http://localhost:8000/legal-texts/search?q=Versicherung&jurisdiction=DE"
  149. # Source-independent exact lookup
  150. curl "http://localhost:8000/legal-texts?jurisdiction=DE&code=rag_1&section=%C2%A7%201"
  151. # Access interactive API documentation
  152. open http://localhost:8000/docs
  153. ```
  154. ## CLI Tool
  155. The CLI provides a convenient command-line interface for managing legal texts without writing code.
  156. ### Installation
  157. ```bash
  158. # Install in development mode (from project root)
  159. pip install -e .
  160. # Verify installation
  161. legal-mcp --help
  162. ```
  163. ### Prerequisites
  164. The CLI requires the Store API to be running:
  165. ```bash
  166. # Start all services
  167. docker-compose up -d
  168. # Verify Store API is running
  169. curl http://localhost:8000/health
  170. ```
  171. ### Available Commands
  172. #### List Commands
  173. **List Imported Codes**
  174. ```bash
  175. # Show all imported legal codes in table format
  176. legal-mcp list codes
  177. # Output as JSON
  178. legal-mcp list codes --json
  179. ```
  180. **List Available Catalog**
  181. ```bash
  182. # Show all available legal codes that can be imported
  183. legal-mcp list catalog
  184. # Output as JSON
  185. legal-mcp list catalog --json
  186. ```
  187. #### Import Command
  188. ```bash
  189. # Import a single legal code
  190. legal-mcp import --code bgb
  191. # Import multiple legal codes
  192. legal-mcp import --code bgb --code stgb --code gg
  193. # Import with JSON output
  194. legal-mcp import --code bgb --json
  195. ```
  196. The import command displays a spinner while processing and shows progress for each code.
  197. #### Query Command
  198. ```bash
  199. # Query all texts for a legal code
  200. legal-mcp query bgb
  201. # Query specific section
  202. legal-mcp query bgb --section "§ 1"
  203. # Query specific sub-section
  204. legal-mcp query bgb --section "§ 1" --sub-section "1"
  205. # Output as JSON
  206. legal-mcp query bgb --section "§ 1" --json
  207. ```
  208. #### Search Command
  209. ```bash
  210. # Semantic search in a legal code
  211. legal-mcp search bgb "Kaufvertrag"
  212. # Limit number of results
  213. legal-mcp search bgb "Kaufvertrag" --limit 5
  214. # Set similarity cutoff threshold (0-2, lower = stricter)
  215. legal-mcp search bgb "Kaufvertrag" --cutoff 0.5
  216. # Output as JSON
  217. legal-mcp search bgb "Kaufvertrag" --json
  218. ```
  219. ### Configuration
  220. **Default API URL**: `http://localhost:8000`
  221. **Override with environment variable:**
  222. ```bash
  223. export LEGAL_API_BASE_URL=http://custom-host:8000
  224. legal-mcp list codes
  225. ```
  226. **Override with command flag:**
  227. ```bash
  228. legal-mcp list codes --api-url http://custom-host:8000
  229. ```
  230. ### Output Formats
  231. **Table Format (default):**
  232. - Clean, formatted tables with Rich library
  233. - Text truncation for readability
  234. - Color-coded output
  235. **JSON Format:**
  236. - Complete data with full text content
  237. - Machine-readable for scripting
  238. - Use `--json` flag with any command
  239. ### Example Workflow
  240. ```bash
  241. # 1. Check available legal codes
  242. legal-mcp list catalog
  243. # 2. Import desired codes
  244. legal-mcp import --code bgb --code stgb
  245. # 3. Verify imports
  246. legal-mcp list codes
  247. # 4. Query specific sections
  248. legal-mcp query bgb --section "§ 433"
  249. # 5. Perform semantic search
  250. legal-mcp search bgb "Kaufvertrag" --limit 10
  251. ```
  252. ## Environment Configuration
  253. The application uses a `.env` file for configuration. See `.env.example` for a template.
  254. ### Required Environment Variables
  255. ```bash
  256. # Ollama Configuration
  257. OLLAMA_BASE_URL=https://your-ollama-endpoint.com
  258. OLLAMA_AUTH_TOKEN=your-auth-token-here
  259. OLLAMA_EMBEDDING_MODEL=ryanshillington/Qwen3-Embedding-4B:latest # Optional, this is the default
  260. # PostgreSQL Configuration
  261. POSTGRES_HOST=postgres # Use 'postgres' in Docker, 'localhost' for local dev
  262. ```
  263. > **Note:** The `OLLAMA_EMBEDDING_MODEL` variable allows you to use a different embedding model. However, **any alternative model must produce 2560-dimensional vectors** to be compatible with the database schema. The default model (`ryanshillington/Qwen3-Embedding-4B:latest`) is recommended.
  264. ### Additional Configuration (set in docker-compose.yml)
  265. ```bash
  266. # Database URL (automatically constructed)
  267. DATABASE_URL=postgresql+asyncpg://legal_mcp:legal_mcp_password@postgres:5432/legal_mcp_db
  268. # MCP Server Configuration
  269. LEGAL_API_BASE_URL=http://store-api:8000
  270. ```
  271. ## API Documentation
  272. Once running, access the interactive API documentation:
  273. - **Swagger UI**: http://localhost:8000/docs
  274. - **ReDoc**: http://localhost:8000/redoc
  275. ### Main Endpoints
  276. #### Legal Texts
  277. - `POST /legal-texts/gesetze-im-internet/{book}` - Import legal text with embeddings
  278. - `GET /legal-texts` - Source-independent exact lookup with jurisdiction/source/document filters
  279. - `GET /legal-texts/search` - Jurisdiction search with an optional code filter
  280. - `GET /legal-texts/codes` - List imported codes by jurisdiction and optional source
  281. - `GET /legal-texts/gesetze-im-internet/{code}` - Query legal texts by code/section
  282. - `GET /legal-texts/gesetze-im-internet/{code}/search` - Compatible federal semantic search
  283. #### System
  284. - `GET /health` - Health check endpoint
  285. - `GET /` - API information
  286. ## MCP Server
  287. The MCP Server provides tools for AI assistants to interact with the legal text database through the Model Context Protocol.
  288. ### Available Tools
  289. The MCP Server exposes the following tools:
  290. - **`search_legal_texts`** - Perform semantic search on legal texts
  291. - Parameters: `query`, `jurisdiction`, optional `code`/`source`/`document_id`, `limit`, `cutoff`
  292. - Returns: List of matching legal text sections with similarity scores
  293. - **`get_legal_section`** - Retrieve specific legal text sections
  294. - Parameters: `code`, `section`, `jurisdiction`, optional `source`/`document_id`/`sub_section`
  295. - Returns: List of legal text sections matching the criteria
  296. - **`get_available_codes`** - Get all available legal codes in the database
  297. - Parameters: `jurisdiction`, optional `source`
  298. - Returns: List of matching legal code identifiers
  299. ### Using the MCP Server
  300. The MCP Server runs on port 8001 and can be accessed by MCP-compatible clients:
  301. ```bash
  302. # Check MCP server is running
  303. curl http://localhost:8001/health
  304. # The MCP server automatically connects to the Store API
  305. # using LEGAL_API_BASE_URL environment variable
  306. ```
  307. For AI assistants, configure the MCP client to connect to `http://localhost:8001` (or the appropriate host/port for your deployment).
  308. ## Legal Text Features
  309. ### Importing Legal Texts
  310. The system automatically:
  311. 1. Scrapes legal text XML from gesetze-im-internet.de
  312. 2. Parses the XML into structured legal text sections
  313. 3. Generates embeddings for each text section using Ollama
  314. 4. Stores the texts with their embeddings in PostgreSQL with pgvector
  315. ### Querying Legal Texts
  316. Query by section identifier:
  317. ```bash
  318. curl "http://localhost:8000/legal-texts/gesetze-im-internet/bgb?section=%C2%A7%201"
  319. ```
  320. ### Semantic Search
  321. Search using natural language with vector similarity:
  322. ```bash
  323. curl "http://localhost:8000/legal-texts/gesetze-im-internet/bgb/search?q=Kaufvertrag&limit=5&cutoff=0.7"
  324. ```
  325. Parameters:
  326. - `q` - Search query (required)
  327. - `limit` - Maximum results (1-100, default: 10)
  328. - `cutoff` - Similarity threshold (0-2, default: 0.5)
  329. - Lower values = stricter matching
  330. - 0.3-0.5: Very strict
  331. - 0.6-0.7: Good balance
  332. - 0.8-1.0: More permissive
  333. ## XML Parser
  334. The system includes a comprehensive parser for the gii-norm.dtd format used by gesetze-im-internet.de.
  335. ### Parser Features
  336. - **Complete DTD Coverage** - All major elements from gii-norm.dtd
  337. - **Structured Data** - Type-safe dataclasses for all structures
  338. - **Text Extraction** - Handles complex nested text with formatting
  339. - **Table Support** - Captures table structures
  340. - **Footnote Handling** - Extracts footnotes with references
  341. - **Metadata Parsing** - Complete metadata extraction
  342. ### Using the Parser
  343. ```python
  344. from app.scrapers import GesetzteImInternetScraper
  345. # The scraper automatically uses the XML parser
  346. scraper = GesetzteImInternetScraper()
  347. legal_texts = scraper.scrape('bgb')
  348. for text in legal_texts:
  349. print(f"Section: {text.section}")
  350. print(f"Text: {text.text}")
  351. ```
  352. ### Parsed Metadata
  353. The parser extracts:
  354. - Legal abbreviations (jurabk, amtabk)
  355. - Dates (ausfertigung-datum)
  356. - Citations (fundstelle)
  357. - Titles (kurzue, langue, titel)
  358. - Structural classification (gliederungseinheit)
  359. - Section designations (enbez)
  360. - Version information (standangabe)
  361. ## Development
  362. ### Local Development (without Docker)
  363. 1. **Install dependencies:**
  364. ```bash
  365. python -m venv .venv
  366. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  367. pip install -r requirements.txt
  368. # Install CLI tool in development mode
  369. pip install -e .
  370. ```
  371. 2. **Set up local database:**
  372. ```bash
  373. # Start only PostgreSQL
  374. docker-compose up postgres -d
  375. # Update .env to use localhost
  376. # POSTGRES_HOST=localhost
  377. ```
  378. 3. **Run migrations:**
  379. ```bash
  380. cd store
  381. alembic upgrade head
  382. ```
  383. 4. **Start Store API:**
  384. ```bash
  385. cd store
  386. uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
  387. ```
  388. 5. **Start MCP Server:**
  389. ```bash
  390. cd mcp
  391. export LEGAL_API_BASE_URL=http://localhost:8000
  392. python -m server.main
  393. ```
  394. ### Running Tests
  395. ```bash
  396. # Run all tests
  397. pytest
  398. # Run with coverage
  399. pytest --cov=app tests/
  400. # Run specific test file
  401. pytest tests/test_main.py -v
  402. # Run CLI tests specifically
  403. pytest tests/cli/ -v
  404. ```
  405. ## Contributing
  406. We welcome contributions from the community! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on:
  407. - How to report bugs
  408. - How to suggest features
  409. - How to submit pull requests
  410. - Development setup instructions
  411. - Code style guidelines
  412. ## Code of Conduct
  413. This project adheres to the Contributor Covenant [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior through the project's reporting mechanisms.
  414. ## Security
  415. Security is important to us. If you discover a security vulnerability, please follow our [Security Policy](SECURITY.md) for responsible disclosure. Do not open public issues for security vulnerabilities.
  416. ## License
  417. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  418. ## Acknowledgments
  419. - Legal texts sourced from [Gesetze im Internet](https://www.gesetze-im-internet.de/)
  420. - Built with [FastAPI](https://fastapi.tiangolo.com/), [FastMCP](https://github.com/jlowin/fastmcp), and [Ollama](https://ollama.ai/)
  421. - Vector similarity search powered by [pgvector](https://github.com/pgvector/pgvector)
  422. ## Support
  423. - **Issues**: Open an issue on GitHub for bugs or feature requests
  424. - **Discussions**: Use GitHub Discussions for questions and community chat
  425. ---
  426. Made with ❤️ for the gov tech community

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.