# entscheidsuche/entscheidsuche-mcp architecture

> Architecture diagram of the GitHub repository entscheidsuche/entscheidsuche-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/entscheidsuche/entscheidsuche-mcp
- Repository: https://github.com/entscheidsuche/entscheidsuche-mcp

## Overview

This is an MCP server that exposes Swiss case-law search and retrieval to AI and programmatic clients. The main workflow is a client invoking a registered tool, the server delegating to its search client, and that client querying Elasticsearch before returning typed results. Separate tools expose exact case-number search, document retrieval, hierarchy counts, facets, and server information. Access-log analysis is a distinct operational capability. The graph follows the excerpts and README; links to unsampled tool implementations and statistics routing are omitted where the exact call is not shown.

Main entry points: [`src/entscheidsuche_mcp/server.py`](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/server.py) (MCP tools), [`src/entscheidsuche_mcp/search.py`](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/search.py) (Search client), [`src/entscheidsuche_mcp/__main__.py`](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/__main__.py) (CLI entry), [`src/entscheidsuche_mcp/models.py`](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/models.py) (Request and result models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP interface"]
  node_entry["CLI entry<br/>[__main__.py]"]
  node_server["MCP tools<br/>[server.py]"]
end

subgraph group_search["Search and data"]
  node_models["Request and result models<br/>[models.py]"]
  node_search_client["Search client<br/>[search.py]"]
  node_elasticsearch[("Elasticsearch index")]
  node_facets["Facet hierarchy service"]
end

subgraph group_operations["Usage analytics"]
  node_access_log["Access-log middleware<br/>[access_log.py]"]
  node_statistics["Usage statistics<br/>[statistik.py]"]
end

node_client(("MCP client"))

node_client -->|"starts server"| node_entry
node_entry -->|"builds app"| node_server
node_client -->|"calls tools"| node_server
node_server -->|"delegates search"| node_search_client
node_search_client -->|"builds results"| node_models
node_search_client -->|"queries index"| node_elasticsearch
node_server -->|"validates parameters"| node_models
node_search_client -->|"fetches hierarchy"| node_facets
node_entry -->|"configures logging"| node_access_log
node_server -.->|"wraps requests"| node_access_log
node_server -.->|"routes statistics"| node_statistics

click node_entry "https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/__main__.py"
click node_server "https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/server.py"
click node_models "https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/models.py"
click node_search_client "https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/search.py"
click node_access_log "https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/access_log.py"
click node_statistics "https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/statistik.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_server,node_client toneBlue
class node_models,node_search_client,node_elasticsearch,node_facets toneAmber
class node_access_log,node_statistics toneMint
```

## Components

### MCP interface

- [CLI entry](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/__main__.py): `src/entscheidsuche_mcp/__main__.py`
- [MCP tools](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/server.py): `src/entscheidsuche_mcp/server.py`

### Search and data

- [Request and result models](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/models.py): `src/entscheidsuche_mcp/models.py`
- [Search client](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/search.py): `src/entscheidsuche_mcp/search.py`
- **Elasticsearch index**
- **Facet hierarchy service**

### Usage analytics

- [Access-log middleware](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/access_log.py): `src/entscheidsuche_mcp/access_log.py`
- [Usage statistics](https://github.com/entscheidsuche/entscheidsuche-mcp/blob/main/src/entscheidsuche_mcp/statistik.py): `src/entscheidsuche_mcp/statistik.py`

### Other components

- **MCP client**

## Connections

- MCP client → CLI entry: starts server (evidence: `README.md`)
- CLI entry → MCP tools: builds app (evidence: `src/entscheidsuche_mcp/__main__.py`)
- MCP client → MCP tools: calls tools (evidence: `README.md`)
- MCP tools → Search client: delegates search (evidence: `src/entscheidsuche_mcp/server.py`)
- Search client → Request and result models: builds results (evidence: `src/entscheidsuche_mcp/search.py`)
- Search client → Elasticsearch index: queries index (evidence: `src/entscheidsuche_mcp/search.py`)
- MCP tools → Request and result models: validates parameters (evidence: `src/entscheidsuche_mcp/server.py`)
- Search client → Facet hierarchy service: fetches hierarchy (evidence: `src/entscheidsuche_mcp/search.py`)
- CLI entry → Access-log middleware: configures logging (evidence: `src/entscheidsuche_mcp/__main__.py`)
- MCP tools → Access-log middleware: wraps requests (evidence: `src/entscheidsuche_mcp/server.py`)
- MCP tools → Usage statistics: routes statistics (evidence: `src/entscheidsuche_mcp/server.py`)
