taiwan-law-mcp

Local-first MCP server for Taiwan statutes (via MOJ open-data bulk ZIP), local 判決書 storage/search, and firm NAS / vault PDF/DOCX indexing — built around exact span IDs for citations.

Quick start

cd law_mcp
npm install
npm run build

Run as an MCP stdio server (Cursor / Claude Desktop). Use the built dist/index.js from a clone, or after publishing install the CLI globally / via npx:

npx law-mcp

Cursor config examples

Local clone:

{
  "mcpServers": {
    "taiwan-law": {
      "command": "node",
      "args": ["/ABS/PATH/TO/law_mcp/dist/index.js"],
      "env": {
        "LAW_MCP_DATA_DIR": "/ABS/PATH/TO/your/law-mcp-data"
      }
    }
  }
}

After publishing to npm (npx):

{
  "mcpServers": {
    "taiwan-law": {
      "command": "npx",
      "args": ["-y", "law-mcp"],
      "env": {
        "LAW_MCP_DATA_DIR": "/ABS/PATH/TO/your/law-mcp-data"
      }
    }
  }
}

If LAW_MCP_DATA_DIR is omitted, data defaults to ~/.law-mcp/law_mcp.sqlite.

Environment

| Variable | Meaning | |----------|---------| | LAW_MCP_DATA_DIR | Directory for SQLite + indexes | | LAW_MCP_AUTO_INGEST | Set 0 / false to skip automatic first-run MOJ catalog download | | JUDICIAL_OD_TOKEN | Reserved — Judicial Open Data automation still expects out-of-band sync / tokens |

First-run statute catalog

MOJ’s published Open API exposes bulk ChLaw.json.zip (see /api/swagger/docs/v1). On first start, if the catalog is empty and auto-ingest is allowed, the server downloads and indexes it (~6 MB zip → expanded JSON).

Otherwise call tool law_catalog_refresh once.

Firm vault (NAS)

1. vault_register — register a root path (mounted NAS/SMB path as seen by the OS).
2. vault_sync — ingest .pdf / .docx under that root into the local FTS index (pdf-parse text layer + mammoth for DOCX).

Span IDs (audit trail)

| Source | Pattern | Notes | |--------|---------|--------| | Statute article | statute:{pcode}:A{article_row_id} | article_row_id is law_articles.id in SQLite | | Judgment excerpt | judgment:{jid}:C{char_start}:{char_end} | Offsets over normalized judgment text | | Firm document | firm:{doc_id}:C{char_start}:{char_end} | Offsets over extracted vault text |

Use judgment_open / firm_doc_open to compute offsets from paragraph indices or explicit ranges.

Agent harness (recommended policy)

The MCP intentionally stays deterministic (search, fetch, excerpt, structural checks). Host agents should:

1. Search with law_search, judgment_search, firm_vault_search, or unified_search.
2. Open authoritative text with law_fetch, judgment_open, firm_doc_open and record span IDs.
3. Run attach_spans (and optionally detect_crossref_conflicts) before finalizing memos.
4. Treat any claim without at least one resolved span as unsupported.

Tools (summary)

• MOJ / statutes: law_catalog_refresh, law_search, law_fetch, law_resolve_citation
• Judgments: judgment_sync_status, judgment_ingest, judgment_search, judgment_open
• Vault: vault_register, vault_sync, firm_vault_search, firm_doc_open
• Cross-source: unified_search
• Workspace: bundle_save, bundle_load, export_markdown
• Sanity: attach_spans, detect_crossref_conflicts
• Meta: law_mcp_info

Limitations

• Not legal advice; no automated “correctness” of legal reasoning — only retrieval + citation plumbing.
• Judgment bulk APIs from Judicial OD need registration and scheduled sync; this repo ships local ingest (judgment_ingest) as the stable primitive.
• PDFs without a text layer may extract as empty until OCR is added.

Publishing to npm

The tarball includes only dist/, README.md, and LICENSE (see files in package.json). prepublishOnly runs npm run build before each publish.

1. Create an npm account and run npm login.
2. From this directory: npm publish --access public.

If you rename the package to a scoped name (for example @your-org/law-mcp), keep --access public unless you use private npm.

Dry-run the packed files:

npm pack --dry-run