How chrisryugj/korean-law-mcp works
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: tool-registry.ts Tool registry · api-client.ts API client · chains.ts Chain tools · query-router.ts Query router
Components 21
Entry points
CLI and MCP server transports
- CLI · Local command-line entry
src/index.ts - HTTP server · Remote MCP HTTP endpoint
src/server/http-server.ts - SSE server · Remote MCP SSE endpoint
src/server/sse-server.ts
Core platform
Registry and shared service layer
- Tool registry · Registers and exposes all tools
src/tool-registry.ts - Tool profiles · Lite/full tool set selection
src/lib/tool-profiles.ts - Chain config · Multi-step tool workflow rules
src/lib/tool-chain-config.ts - Query router · Routes legal queries to the right path
src/lib/query-router.ts - API client · Open API access layer
src/lib/api-client.ts - Cache state · Caching and session state
src/lib/cache.ts - Parsers · Law, article, XML, annex and date parsing
src/lib/law-parser.ts - Schemas · Types, schemas and errors
src/lib/schemas.ts
Domain tools
Legal research capabilities grouped by function
- Search tools · Law, precedent, ordinance and treaty search
src/tools/search.ts - Retrieval tools · Law text, article, annex and history lookup
src/tools/law-text.ts - Analysis tools · Comparisons, summaries, trees and statistics
src/tools/article-compare.ts - Chain tools · Compound multi-step legal workflows
src/tools/chains.ts - Meta tools · Autocomplete, discover and execution helpers
src/tools/meta-tools.ts - Specialized domains · Administrative, tax, constitutional and institutional sources
src/tools/admin-appeals.ts - Knowledge base · Legal terms, linkage and related-law knowledge
src/tools/legal-terms.ts
External systems
Law API and document sources
- Open API · Korean Ministry of Government Legislation API
- Doc sources · HWP, HWPX, PDF and annex documents
Deployment
Container and hosted runtime
- Container deploy · Docker and Fly.io runtime packaging
Dockerfile
Connections 25
- 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