# kazakhstan-law/mcp architecture

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

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

## Overview

This is a public MCP server that lets chat clients search Kazakhstan law, read provisions, inspect past text, trace amendment history, and compare changes. The request path enters through the MCP server, passes through rate limiting/logging, then dispatches to tool-specific domain logic backed by the Git-based law corpus. Search includes legal-wording retries; passage reading and change/history tools share corpus and location primitives. The README also documents corpus refresh and usage reporting. Edges reflect visible imports/calls or README statements; unsampled subsystem internals are represented by their exact source paths without speculative connections.

Main entry points: [`src/kzlaw_mcp/server.py`](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/server.py) (MCP server), [`src/kzlaw_mcp/corpus.py`](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/corpus.py) (Act catalog), [`src/kzlaw_mcp/passages.py`](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/passages.py) (Passage reader), [`src/kzlaw_mcp/changes.py`](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/changes.py) (Amendment changes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["MCP Interface"]
  node_mcp["MCP server<br/>[server.py]"]
  node_guard["Request gate<br/>[gate.py]"]
end

subgraph group_tools["Legal Research"]
  node_search["Law search<br/>[search.py]"]
  node_synonyms["Legal wording<br/>[synonyms.py]"]
  node_read["Passage reader<br/>[passages.py]"]
  node_history["Version history<br/>[history.py]"]
  node_changes["Amendment changes<br/>[changes.py]"]
end

subgraph group_core["Corpus Core"]
  node_locate["Article locator<br/>[locate.py]"]
  node_corpus["Act catalog<br/>[corpus.py]"]
  node_gitio["Git access<br/>[gitio.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_ops["Corpus Operations"]
  node_refresh["Corpus refresh<br/>[refresh.py]"]
  node_report["Usage reporting<br/>[report.py]"]
end

node_client(("Chat client"))
node_github(("GitHub corpus"))

node_client -->|"calls tools"| node_mcp
node_mcp -->|"gates calls"| node_guard
node_mcp -->|"dispatches search"| node_search
node_mcp -->|"dispatches read"| node_read
node_mcp -->|"dispatches history"| node_history
node_mcp -->|"dispatches changes"| node_changes
node_search -->|"retries wording"| node_synonyms
node_search -->|"queries acts"| node_corpus
node_read -->|"resolves acts"| node_corpus
node_read -->|"checks pending text"| node_changes
node_read -->|"locates passages"| node_locate
node_history -->|"reads act versions"| node_corpus
node_history -->|"locates articles"| node_locate
node_changes -->|"compares revisions"| node_corpus
node_changes -->|"segments articles"| node_locate
node_corpus -->|"reads repositories"| node_gitio
node_corpus -->|"uses settings"| node_settings
node_refresh -->|"loads settings"| node_settings
node_refresh -->|"updates clones"| node_gitio
node_refresh -->|"clones corpus"| node_github
node_guard -.->|"writes call logs"| node_report
node_report -.->|"summarizes logs"| node_guard

click node_mcp "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/server.py"
click node_guard "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/gate.py"
click node_search "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/search.py"
click node_synonyms "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/synonyms.py"
click node_read "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/passages.py"
click node_history "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/history.py"
click node_changes "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/changes.py"
click node_locate "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/locate.py"
click node_corpus "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/corpus.py"
click node_gitio "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/gitio.py"
click node_settings "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/config.py"
click node_refresh "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/refresh.py"
click node_report "https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/report.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_mcp,node_guard,node_client toneBlue
class node_search,node_synonyms,node_read,node_history,node_changes toneAmber
class node_locate,node_corpus,node_gitio,node_settings toneMint
class node_refresh,node_report toneRose
class node_github toneIndigo
```

## Components

### MCP Interface

- [MCP server](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/server.py): `src/kzlaw_mcp/server.py`
- [Request gate](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/gate.py): `src/kzlaw_mcp/gate.py`

### Legal Research

- [Law search](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/search.py): `src/kzlaw_mcp/search.py`
- [Legal wording](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/synonyms.py): `src/kzlaw_mcp/synonyms.py`
- [Passage reader](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/passages.py): `src/kzlaw_mcp/passages.py`
- [Version history](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/history.py): `src/kzlaw_mcp/history.py`
- [Amendment changes](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/changes.py): `src/kzlaw_mcp/changes.py`

### Corpus Core

- [Article locator](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/locate.py): `src/kzlaw_mcp/locate.py`
- [Act catalog](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/corpus.py): `src/kzlaw_mcp/corpus.py`
- [Git access](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/gitio.py): `src/kzlaw_mcp/gitio.py`
- [Runtime settings](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/config.py): `src/kzlaw_mcp/config.py`

### Corpus Operations

- [Corpus refresh](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/refresh.py): `src/kzlaw_mcp/refresh.py`
- [Usage reporting](https://github.com/kazakhstan-law/mcp/blob/main/src/kzlaw_mcp/report.py): `src/kzlaw_mcp/report.py`

### Other components

- **Chat client**
- **GitHub corpus**

## Connections

- Chat client → MCP server: calls tools (evidence: `README.md`)
- MCP server → Request gate: gates calls (evidence: `src/kzlaw_mcp/server.py`)
- MCP server → Law search: dispatches search (evidence: `src/kzlaw_mcp/server.py`)
- MCP server → Passage reader: dispatches read (evidence: `src/kzlaw_mcp/server.py`)
- MCP server → Version history: dispatches history (evidence: `src/kzlaw_mcp/server.py`)
- MCP server → Amendment changes: dispatches changes (evidence: `src/kzlaw_mcp/server.py`)
- Law search → Legal wording: retries wording (evidence: `src/kzlaw_mcp/search.py`)
- Law search → Act catalog: queries acts (evidence: `src/kzlaw_mcp/search.py`)
- Passage reader → Act catalog: resolves acts (evidence: `src/kzlaw_mcp/passages.py`)
- Passage reader → Amendment changes: checks pending text (evidence: `src/kzlaw_mcp/passages.py`)
- Passage reader → Article locator: locates passages (evidence: `src/kzlaw_mcp/passages.py`)
- Version history → Act catalog: reads act versions (evidence: `src/kzlaw_mcp/history.py`)
- Version history → Article locator: locates articles (evidence: `src/kzlaw_mcp/history.py`)
- Amendment changes → Act catalog: compares revisions (evidence: `src/kzlaw_mcp/changes.py`)
- Amendment changes → Article locator: segments articles (evidence: `src/kzlaw_mcp/changes.py`)
- Act catalog → Git access: reads repositories (evidence: `src/kzlaw_mcp/corpus.py`)
- Act catalog → Runtime settings: uses settings (evidence: `src/kzlaw_mcp/corpus.py`)
- Corpus refresh → Runtime settings: loads settings (evidence: `src/kzlaw_mcp/refresh.py`)
- Corpus refresh → Git access: updates clones (evidence: `src/kzlaw_mcp/refresh.py`)
- Corpus refresh → GitHub corpus: clones corpus (evidence: `README.md`)
- Request gate → Usage reporting: writes call logs
- Usage reporting → Request gate: summarizes logs
