# chrisryugj/korean-law-mcp architecture

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

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

## Overview

1. **What this repository is**
   - A TypeScript/Node.js **Model Context Protocol (MCP) server plus CLI** for Korean legal data.
   - Its core job is to expose **89 structured tools** that wrap the Korean Ministry of Government Legislation Open API and related document sources, so AI clients and terminal users can query law, cases, rules, treaties, and legal knowledge in a uniform way.

2. **Top-level runtime shape**
   - There are two user-facing entry paths:
     - `src/index.ts` / `src/cli.ts` for the **local CLI**.
     - `src/server/http-server.ts` and `src/server/sse-server.ts` for the **remote MCP endpoint**.
   - The same tool layer is reused by both, so the CLI and the hosted server are just different transport surfaces over the same backend capabilities.

3. **Tool registry as the center of the architecture**
   - `src/tool-registry.ts` is the main composition point where all tool modules under `src/tools/` are registered and exposed.
   - This is the boundary between transport and business logic: the server/CLI invoke registered tools, and tools encapsulate the legal-domain operations.
   - The README’s `lite` vs `full` profiles suggest the registry can be filtered into smaller tool sets for different clients.

4. **Domain tools are organized by legal research task**
   - The `src/tools/` folder is split into clear capability clusters:
     - **Search**: law, precedents, ordinances, treaties, interpretations, search-all.
     - **Retrieval**: law text, article detail/history, annexes, treaty text, ordinance text.
     - **Analysis**: article comparison, precedent summaries, document analysis, law tree/system tree, law statistics.
     - **Chains**: higher-level multi-step workflows like full research, dispute prep, ordinance compare, procedure detail.
     - **Knowledge-base / meta**: legal terms, abbreviations, related laws, discover/execute tool support.
   - This structure is important for architecture diagrams because the system is not a single API wrapper; it is a **domain orchestration layer** with many specialized tool families.

5. **External data sources and integration boundary**
   - The main external dependency is the **법제처 Open API** (`open.law.go.kr`), with the user-supplied `OC` key passed via URL, header, env var, or tool input.
   - Some tools also likely fetch and parse **document files** such as HWP/HWPX/PDF for annexes, special rules, or full-text legal documents.
   - The repository is therefore a **fetch-transform-serve** system: it queries legal sources, normalizes the results, and emits structured tool responses for MCP clients.

6. **Shared service layer under `src/lib/`**
   - Most reusable logic lives in `src/lib/`, which acts as the internal platform for all tools.
   - Key responsibilities include:
     - **API access**: `api-client.ts`, `fetch-with-retry.ts`
     - **Caching/session state**: `cache.ts`, `session-state.ts`
     - **Parsing and normalization**: `law-parser.ts`, `article-parser.ts`, `annex-file-parser.ts`, `xml-parser.ts`, `three-tier-parser.ts`, `date-parser.ts`, `search-normalizer.ts`
     - **Routing and rules**: `query-router.ts`, `risk-rules.ts`, `tool-chain-config.ts`, `tool-profiles.ts`
     - **Shared types/schemas/errors**: `types.ts`, `schemas.ts`, `errors.ts`
   - This layer is where the architectural complexity lives: it converts heterogeneous legal-source payloads into a consistent tool API.

7. **Data flow for a typical legal query**
   - A user asks for something like “근로기준법 제74조”.
   - The CLI or MCP server passes the request to the relevant tool.
   - The tool uses the shared client/router layer to search for the law, normalize the law identifier, and fetch the exact article text.
   - Parsers then convert raw API or document responses into structured, readable output.
   - Results are cached when appropriate, reducing repeated calls and stabilizing latency.

8. **Higher-level chain tools are an orchestration boundary**
   - The `chain_*` tools are not simple lookups; they coordinate multiple lower-level tools to answer compound questions.
   - Examples from the README include legal research, law-system mapping, ordinance comparison, amendment tracking, and dispute preparation.
   - Architecturally, these chain tools are the “application layer” on top of the simpler retrieval tools, and they are likely why the project can offer a much smaller `lite` profile while still covering many use cases.

9. **Specialized legal domains are separated by tool families**
   - The repo contains dedicated modules for:
     - **Administrative appeals and decisions**
     - **Constitutional and tax/customs decisions**
     - **Public institution / school rules**
     - **Treaties**
     - **Law–ordinance linkage**
     - **Legal terminology and precedent lookup**
   - This separation matters because each source family has different query shapes, identifiers, and document formats, so the architecture is intentionally modular rather than one generic “search legal data” path.

10. **Caching, retries, and safety are first-class platform concerns**
   - `cache.ts` and the README’s TTL notes show that the system caches search and article results to cut repeated API traffic.
   - `fetch-with-retry.ts` and the mention of `Retry-After` support indicate it is built to tolerate rate limits and transient API failures.
   - `errors.ts`, `schemas.ts`, and `risk-rules.ts` suggest outputs are standardized and sanitized so AI clients receive predictable, actionable failures rather than raw stack traces.

11. **Transport and deployment**
   - The project supports both **local execution** and a **hosted MCP service** at `fly.toml`, implying deployment on Fly.io.
   - `Dockerfile` and `.dockerignore` indicate container-based deployment is part of the architecture.
   - The HTTP/SSE server split implies compatibility with different MCP client connection patterns, especially remote web clients versus local desktop apps.

12. **Testing and release workflow**
   - The `test/` directory contains end-to-end style checks for individual tools and the whole tool set.
   - `.github/workflows/ci.yml` indicates automated CI validation.
   - `CHANGELOG.md`, `ROADMAP.md`, and versioning support in `src/version.ts` show this is a production-maintained tool platform, not a one-off script.

13. **How to draw the architecture diagram**
   - A good diagram should show:
     - **Clients**: Claude Desktop/Cursor/Windsurf/CLI/web MCP clients
     - **Transport layer**: HTTP/SSE server and CLI entrypoint
     - **Tool registry**: the central dispatcher
     - **Domain tools**: grouped by legal research family
     - **Shared lib layer**: API client, parsers, cache, router, rules
     - **External systems**: 법제처 Open API and document sources
     - **Persistence-ish state**: cache/session state, but no large internal database
   - The key architectural idea is that this repo is a **domain-specific MCP adapter and orchestration layer**, not a traditional CRUD app.

Main entry points: [`src/tool-registry.ts`](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tool-registry.ts) (Tool registry), [`src/lib/api-client.ts`](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/api-client.ts) (API client), [`src/tools/chains.ts`](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/chains.ts) (Chain tools), [`src/lib/query-router.ts`](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/query-router.ts) (Query router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_entry["Entry points"]
  node_n_cli["CLI<br/>entrypoint<br/>[index.ts]"]
  node_n_http["HTTP server<br/>transport<br/>[http-server.ts]"]
  node_n_sse["SSE server<br/>transport<br/>[sse-server.ts]"]
end

subgraph group_g_core["Core platform"]
  node_n_registry{{"Tool registry<br/>dispatcher<br/>[tool-registry.ts]"}}
  node_n_profiles["Tool profiles<br/>policy<br/>[tool-profiles.ts]"]
  node_n_chaincfg["Chain config<br/>orchestration"]
  node_n_router["Query router<br/>routing<br/>[query-router.ts]"]
  node_n_client["API client<br/>integration<br/>[api-client.ts]"]
  node_n_state[("Cache state<br/>[cache.ts]")]
  node_n_parse["Parsers<br/>normalization<br/>[law-parser.ts]"]
  node_n_schema["Schemas<br/>contracts<br/>[schemas.ts]"]
end

subgraph group_g_tools["Domain tools"]
  node_n_search["Search tools<br/>tool family<br/>[search.ts]"]
  node_n_retrieve["Retrieval tools<br/>tool family<br/>[law-text.ts]"]
  node_n_analysis["Analysis tools<br/>tool family<br/>[article-compare.ts]"]
  node_n_chain{{"Chain tools<br/>orchestration tools<br/>[chains.ts]"}}
  node_n_meta["Meta tools<br/>support tools<br/>[meta-tools.ts]"]
  node_n_special["Specialized domains<br/>tool family<br/>[admin-appeals.ts]"]
  node_n_terms["Knowledge base<br/>reference tools<br/>[legal-terms.ts]"]
end

subgraph group_g_ext["External systems"]
  node_n_api[("Open API<br/>external service")]
  node_n_docs["Doc sources<br/>external documents"]
end

subgraph group_g_deploy["Deployment"]
  node_n_deploy["Container deploy<br/>deployment"]
end

node_n_cli -->|"invoke"| node_n_registry
node_n_http -->|"invoke"| node_n_registry
node_n_sse -->|"invoke"| node_n_registry
node_n_registry -->|"select"| node_n_profiles
node_n_registry -->|"compose"| node_n_chaincfg
node_n_registry -->|"expose"| node_n_search
node_n_registry -->|"expose"| node_n_retrieve
node_n_registry -->|"expose"| node_n_analysis
node_n_registry -->|"expose"| node_n_chain
node_n_registry -->|"expose"| node_n_meta
node_n_registry -->|"expose"| node_n_special
node_n_registry -->|"expose"| node_n_terms
node_n_search -->|"use"| node_n_router
node_n_retrieve -->|"use"| node_n_router
node_n_analysis -->|"use"| node_n_parse
node_n_chain -->|"orchestrate"| node_n_search
node_n_chain -->|"orchestrate"| node_n_retrieve
node_n_meta -->|"use"| node_n_schema
node_n_router -->|"call"| node_n_client
node_n_client -->|"fetch"| node_n_api
node_n_client -->|"fetch"| node_n_docs
node_n_client -->|"cache"| node_n_state
node_n_parse -->|"parse"| node_n_docs
node_n_deploy -->|"hosts"| node_n_http
node_n_deploy -->|"hosts"| node_n_sse

click node_n_cli "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/index.ts"
click node_n_http "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/server/http-server.ts"
click node_n_sse "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/server/sse-server.ts"
click node_n_registry "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tool-registry.ts"
click node_n_profiles "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/tool-profiles.ts"
click node_n_chaincfg "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/tool-chain-config.ts"
click node_n_router "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/query-router.ts"
click node_n_client "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/api-client.ts"
click node_n_state "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/cache.ts"
click node_n_parse "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/law-parser.ts"
click node_n_schema "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/schemas.ts"
click node_n_search "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/search.ts"
click node_n_retrieve "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/law-text.ts"
click node_n_analysis "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/article-compare.ts"
click node_n_chain "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/chains.ts"
click node_n_meta "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/meta-tools.ts"
click node_n_special "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/admin-appeals.ts"
click node_n_terms "https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/legal-terms.ts"
click node_n_deploy "https://github.com/chrisryugj/korean-law-mcp/tree/main/Dockerfile"

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_n_cli,node_n_http,node_n_sse toneBlue
class node_n_registry,node_n_profiles,node_n_chaincfg,node_n_router,node_n_client,node_n_state,node_n_parse,node_n_schema toneAmber
class node_n_search,node_n_retrieve,node_n_analysis,node_n_chain,node_n_meta,node_n_special,node_n_terms toneMint
class node_n_api,node_n_docs toneRose
class node_n_deploy toneIndigo
```

## Components

### Entry points

CLI and MCP server transports

- [CLI](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/index.ts): entrypoint · Local command-line entry · `src/index.ts`
- [HTTP server](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/server/http-server.ts): transport · Remote MCP HTTP endpoint · `src/server/http-server.ts`
- [SSE server](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/server/sse-server.ts): transport · Remote MCP SSE endpoint · `src/server/sse-server.ts`

### Core platform

Registry and shared service layer

- [Tool registry](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tool-registry.ts): dispatcher · Registers and exposes all tools · `src/tool-registry.ts`
- [Tool profiles](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/tool-profiles.ts): policy · Lite/full tool set selection · `src/lib/tool-profiles.ts`
- [Chain config](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/tool-chain-config.ts): orchestration · Multi-step tool workflow rules · `src/lib/tool-chain-config.ts`
- [Query router](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/query-router.ts): routing · Routes legal queries to the right path · `src/lib/query-router.ts`
- [API client](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/api-client.ts): integration · Open API access layer · `src/lib/api-client.ts`
- [Cache state](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/cache.ts): state · Caching and session state · `src/lib/cache.ts`
- [Parsers](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/law-parser.ts): normalization · Law, article, XML, annex and date parsing · `src/lib/law-parser.ts`
- [Schemas](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/lib/schemas.ts): contracts · Types, schemas and errors · `src/lib/schemas.ts`

### Domain tools

Legal research capabilities grouped by function

- [Search tools](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/search.ts): tool family · Law, precedent, ordinance and treaty search · `src/tools/search.ts`
- [Retrieval tools](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/law-text.ts): tool family · Law text, article, annex and history lookup · `src/tools/law-text.ts`
- [Analysis tools](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/article-compare.ts): tool family · Comparisons, summaries, trees and statistics · `src/tools/article-compare.ts`
- [Chain tools](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/chains.ts): orchestration tools · Compound multi-step legal workflows · `src/tools/chains.ts`
- [Meta tools](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/meta-tools.ts): support tools · Autocomplete, discover and execution helpers · `src/tools/meta-tools.ts`
- [Specialized domains](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/admin-appeals.ts): tool family · Administrative, tax, constitutional and institutional sources · `src/tools/admin-appeals.ts`
- [Knowledge base](https://github.com/chrisryugj/korean-law-mcp/blob/main/src/tools/legal-terms.ts): reference tools · Legal terms, linkage and related-law knowledge · `src/tools/legal-terms.ts`

### External systems

Law API and document sources

- **Open API**: external service · Korean Ministry of Government Legislation API
- **Doc sources**: external documents · HWP, HWPX, PDF and annex documents

### Deployment

Container and hosted runtime

- [Container deploy](https://github.com/chrisryugj/korean-law-mcp/tree/main/Dockerfile): deployment · Docker and Fly.io runtime packaging · `Dockerfile`

## Connections

- CLI → Tool registry: invoke · CLI commands dispatch through the shared registry
- HTTP server → Tool registry: invoke · HTTP MCP requests use the same tool registry
- SSE server → Tool registry: invoke · SSE MCP sessions use the same tool registry
- Tool registry → Tool profiles: select · Registry can expose lite or full tool sets
- Tool registry → Chain config: compose · Registers higher-level chain workflows
- Tool registry → Search tools: expose · Search capability family
- Tool registry → Retrieval tools: expose · Retrieval capability family
- Tool registry → Analysis tools: expose · Analysis capability family
- Tool registry → Chain tools: expose · Compound workflow family
- Tool registry → Meta tools: expose · Meta and utility tools
- Tool registry → Specialized domains: expose · Specialized legal-domain tools
- Tool registry → Knowledge base: expose · Knowledge-base and linkage tools
- Search tools → Query router: use · Search tools route queries and identifiers
- Retrieval tools → Query router: use · Retrieval tools resolve exact targets
- Analysis tools → Parsers: use · Analysis depends on normalization and parsing
- Chain tools → Search tools: orchestrate · Chains call lower-level search tools
- Chain tools → Retrieval tools: orchestrate · Chains combine multiple retrieval steps
- Meta tools → Schemas: use · Meta tools rely on shared contracts and errors
- Query router → API client: call · Router-driven tools fetch data through API client
- API client → Open API: fetch · Primary external legal API boundary
- API client → Doc sources: fetch · Document-backed sources are downloaded and parsed
- API client → Cache state: cache · API results are cached with session state
- Parsers → Doc sources: parse · Parsers normalize document payloads
- Container deploy → HTTP server: hosts · Hosted deployment runs the remote server
- Container deploy → SSE server: hosts · Hosted deployment runs the SSE endpoint
