@jurislm/judicial-mcp 1.3.0 → 1.6.3

package/README.md

@@ -1,6 +1,47 @@
 # @jurislm/judicial-mcp
 
-MCP (Model Context Protocol) server for [Taiwan Judicial Yuan](https://www.judicial.gov.tw) — provides 7 tools for accessing open data and judgments via natural language.
+MCP (Model Context Protocol) server for Taiwan's Judicial Yuan public judgments and open data, plus current regulations from the Ministry of Justice National Laws and Regulations Database. It provides 10 tools.
+
+## Public Judgment Search
+
+`search_judgments` searches the Judicial Yuan's public judgment website. `fetch_judgment_text` retrieves the full text for a result. Both tools use the public website and do not require an API token or Judicial Yuan account.
+
+Search accepts any combination of these filters (at least one is required):
+
+| Field | Meaning |
+|-------|---------|
+| `keyword` | Keyword in judgment text, up to 128 characters |
+| `court` | Official court name or code, up to 80 characters |
+| `year` | Decision year as a Gregorian or Minguo integer |
+| `caseNumber` | Case number, either digits or a full form such as `113年度訴字第1234號` |
+| `limit` | Results per page, 1–10; defaults to 5 |
+| `page` | Official result page, 1–50; defaults to 1 |
+| `offset` | Starting row within an official result page, 0–19; defaults to 0 |
+
+Each search result includes `case_id` (pass this as `caseId` to `fetch_judgment_text`), `case_number`, `date` (ISO date or `null`), `court`, `cause`, an optional `summary`, `source_url`, `search_source_url`, `retrieved_at`, `cache`, `truncated`, `partial`, and `source_version`. The search response also includes `count`, `ambiguous`, `results`, `source_url`, `retrieved_at`, `cache`, `truncated`, `partial`, `next_page`, `next_offset`, and `source_version`. Follow both `next_page` and `next_offset` to retrieve every result; `next_offset` may point to another batch on the same official page. An `ambiguous` case-number search returns its candidates for you to choose from rather than selecting one.
+
+The full-text response includes `case_id`, `date`, `full_text`, `source_url`, `retrieved_at`, `cache`, `truncated`, `partial`, and `source_version`. Text is capped at 40,000 characters; when that cap is reached, `truncated` and `partial` are `true`. `cache.status` is `not_cached`; `source_version` is `null` when the official source provides no version identifier.
+
+Only an explicit no-matches response from the official site is returned as an empty result. Upstream denial or failure, an unrecognized page, or a missing judgment is returned as an MCP error (`isError: true`) with `error.code`, `error.message`, `error.source_url`, and `error.retrieved_at`.
+
+## Regulation Lookup
+
+`query_regulation` looks up one article by law name and article number in the Ministry of Justice's [National Laws and Regulations Database](https://law.moj.gov.tw/). The official autocomplete lookup is tokenless. HTML pages are scraped only through a Firecrawl service configured with `FIRECRAWL_API_URL`; set `FIRECRAWL_API_KEY` when that service requires a key. If Firecrawl is unavailable, the tool returns a source error without a direct-HTTP HTML fallback.
+
+```json
+{
+  "lawName": "民法",
+  "articleNumber": "1"
+}
+```
+
+The tool resolves only a unique exact law-name match after normalizing whitespace and the common `台` / `臺` spelling. It returns candidates with `status: "ambiguous"` when the name does not resolve uniquely; it never chooses a fuzzy match. Article numbers use Arabic numerals and may include a hyphen, such as `1` or `1-1`.
+
+Successful results include the regulation name and official identifier, one article's text, the official page URL, the lookup URL, retrieval time, and version metadata. The official page supplies consolidated current text; this tool does not provide historical versions. Amendment, promulgation, and effective dates are returned as ISO dates when the official page states them. Missing dates are `null` and mark the result `partial`; a pending or mixed effective date is identified in `version.effective_status`. `source_version` is the published amendment date, falling back to the promulgation date.
+
+Responses cap article text at 30,000 characters. `truncated` and `partial` are `true` when text is capped or required version details are missing. `cache.status` is `miss`, `hit`, `refreshed`, `revalidated`, or `not_cached`. A process-local least-recently-used cache holds at most 100 exact law/article lookups for 15 minutes. Set `refresh: true` to bypass the cache. Expired entries are looked up and scraped again through Firecrawl; if an upstream refresh fails, the tool returns an error and does not serve stale text as current.
+
+Upstream failures and unrecognized page changes are MCP errors with `error.code`, `error.message`, `error.source_url`, and `error.retrieved_at`. Confirmed no-match, abolished-law, and missing-article responses have distinct codes.
 
 ## Tools
 
@@ -8,8 +49,15 @@ MCP (Model Context Protocol) server for [Taiwan Judicial Yuan](https://www.judic
 - `auth_token` — Get authorization token for judgment API (uses `JUDICIAL_USER` / `JUDICIAL_PASSWORD` env vars by default)
 - `member_token` — Get member token for open data API (uses `JUDICIAL_USER` / `JUDICIAL_PASSWORD` env vars by default)
 
-### Judgments (2 tools)
-- `list_judgments` — Get judgment change list (requires `auth_token`)
+### Public Judgments (2 tools)
+- `search_judgments` — Search public judgments without a token
+- `fetch_judgment_text` — Get a judgment's full text by `case_id`, without a token
+
+### Regulations (1 tool)
+- `query_regulation` — Get one current regulation article and official version metadata, without a token
+
+### Token-based Judgments (2 tools)
+- `list_judgments` — Get the judgment change list (requires `auth_token`)
 - `get_judgment` — Get judgment content by JID (requires `auth_token`)
 
 ### Open Data (3 tools)
@@ -21,14 +69,23 @@ MCP (Model Context Protocol) server for [Taiwan Judicial Yuan](https://www.judic
 
 ### Environment Variables
 
+The public judgment search tools do not require credentials. These variables are used by the existing token-based judgment and open-data tools:
+
 ```bash
 JUDICIAL_USER=your_username
 JUDICIAL_PASSWORD=your_password
 ```
 
+Regulation lookup also needs a Firecrawl service base URL. The server appends `/v1/scrape` and sends raw-HTML scrape requests only for official Ministry of Justice pages. The key is read from the environment and is optional when Firecrawl is configured to allow keyless access. Use HTTPS when the configured service is remote; a key is sent over HTTP only to a loopback address.
+
+```bash
+FIRECRAWL_API_URL=https://your-firecrawl-host
+FIRECRAWL_API_KEY=your_service_key
+```
+
 ### Usage with Claude Code (via bunx)
 
-Add to your MCP configuration (`.mcp.json` or `~/.claude/settings.json`):
+Install Bun first, then add this stdio server to your MCP configuration (`.mcp.json` or `~/.claude/settings.json`). The public judgment tools work without credentials; regulation lookup needs the Firecrawl environment settings above:
 
 ```json
 {
@@ -37,8 +94,8 @@ Add to your MCP configuration (`.mcp.json` or `~/.claude/settings.json`):
       "command": "bunx",
       "args": ["@jurislm/judicial-mcp@latest"],
       "env": {
-        "JUDICIAL_USER": "your_username",
-        "JUDICIAL_PASSWORD": "your_password"
+        "FIRECRAWL_API_URL": "https://your-firecrawl-host",
+        "FIRECRAWL_API_KEY": "your_service_key"
       }
     }
   }
@@ -63,9 +120,11 @@ export JUDICIAL_PASSWORD=your_password
 ## Development
 
 ```bash
-npm install
-npm test           # Run tests
-npm run lint       # oxlint
+bun install --frozen-lockfile
+bun run test
+bun run lint
+bun run typecheck
+bun run build:types
 ```
 
 ## License

package/bin/judicial-mcp.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jurislm/judicial-mcp",
-  "version": "1.3.0",
+  "version": "1.6.3",
   "description": "MCP server for accessing Taiwan Judicial Yuan open data and judgments.",
   "keywords": [
     "mcp",
@@ -22,18 +22,20 @@
     "name": "Terry Chen",
     "email": "zxtw17985321@gmail.com"
   },
-  "type": "commonjs",
-  "main": "src/index.js",
+  "type": "module",
+  "main": "src/index.ts",
   "types": "types/index.d.ts",
   "scripts": {
-    "start": "node src/index.js",
-    "dev": "node src/index.js",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
-    "prepublishOnly": "npm test && npm run lint"
+    "start": "bun src/index.ts",
+    "dev": "bun src/index.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.check.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint --max-warnings=0",
+    "lint:fix": "eslint --fix --max-warnings=0",
+    "build:types": "tsc --emitDeclarationOnly",
+    "prepublishOnly": "bun run typecheck && bun run test && bun run lint && bun run build:types"
   },
   "files": [
     "src",
@@ -42,18 +44,29 @@
     "README.md"
   ],
   "bin": {
-    "judicial-mcp": "bin/judicial-mcp.js"
+    "judicial-mcp": "bin/judicial-mcp.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "axios": "^1.6.0",
+    "cheerio": "^1.2.0",
     "dotenv": "^17.0.0"
   },
-  "devDependencies": {
-    "jest": "^29.7.0",
-    "oxlint": "^0.15.0"
+  "engines": {
+    "bun": ">=1.1.0"
   },
-  "jest": {
-    "testEnvironment": "node"
+  "packageManager": "bun@1.4.3",
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^26.6.5",
+    "@typescript-eslint/eslint-plugin": "^8.62.0",
+    "@typescript-eslint/parser": "^8.62.0",
+    "@vitest/coverage-v8": "3.2.4",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "globals": "^16.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
   }
 }

package/src/index.ts

@@ -0,0 +1,20 @@
+// MCP 使用 stdio transport，stdout 只能輸出 JSON-RPC 訊息。
+// 覆寫必須在所有 import 模組初始化之前生效。
+// ESM static import 會被 hoist 至頂層程式碼之前執行，因此這裡不放任何 static import，
+// 改用 dynamic import 確保覆寫先於所有依賴模組的初始化。
+const safeSerialize = (value: unknown): string => {
+  if (typeof value === 'string') return value
+  try {
+    const s = JSON.stringify(value)
+    return s === undefined ? String(value) : s
+  } catch {
+    return String(value)
+  }
+}
+
+console.log = console.info = console.warn = (...args: unknown[]) =>
+  process.stderr.write(args.map(safeSerialize).join(' ') + '\n')
+
+await import('./server.js')
+
+export {}