@pipeworx/mcp-kr-law 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mojibake Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# @pipeworx/kr-law
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+South Korean national statutes: search by title, fetch one article (조문) at
+a time with its own effective date, and a statute's revision history. Bring
+your own OC (Open API user id) — every call runs on your own registration.
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1856+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
+
+## Tools
+
+- `kr_law_search(...)` — find statutes by title keyword. Returns each
+  match's `mst` (the version id every other tool needs), ministry,
+  promulgation/effective dates, and whether it's the current or a superseded
+  version.
+- `kr_law_article(...)` — fetch ONE article by `mst` + `article_no` (e.g.
+  `"5"` or `"4-2"` for 제4조의2). Never the whole law body. Omit
+  `article_no` for a paginated table of contents (numbers + titles) instead.
+  Returns the article's own text, its paragraphs (항) and items (호), and its
+  own effective date — which can differ from the law's own when only that
+  article was later amended.
+- `kr_law_history(...)` — revision history for a statute: every
+  promulgation with its own promulgation date/number and entry-into-force
+  date, each a separate historical `mst` you can pass back to
+  `kr_law_article`.
+
+## Auth
+
+BYO only, and will stay that way. Every tool requires `_apiKey` — your own OC
+from https://open.law.go.kr/LSO/main.do (로그인 → OPEN API → OPEN API 신청).
+With no key, every tool refuses before any network call, naming the argument
+and where to register.
+
+**Registering an OC requires Korean real-name verification** — a Korean
+mobile-carrier identity check or an i-PIN. There is no alien-registration,
+passport, or overseas-signup path on the Ministry's own form. Pipeworx has no
+Korean-resident staff and cannot complete either method, so there is no
+platform key for this pack and none is coming (ruled, fleet #3128,
+2026-10-15).
+
+For a quick smoke test only (never use this as a real credential, and never
+rely on it being stable), the Ministry's own public demo id `"test"` works
+for `kr_law_search` and `kr_law_article`.
+
+**`kr_law_history` needs a service your OC may not have by default.** Even a
+real, verified OC must separately enable 법령연혁 (law history) under
+*My Applications* on the open.law.go.kr dashboard (OPEN API → 신청내역 →
+check the 법령종류 box). An OC without it gets a specific, named error from
+this tool rather than a generic failure — follow the steps the error gives.
+The public demo id does not have this entitlement at all.
+
+## Data sources
+
+- Ministry of Government Legislation (법제처), National Law Information
+  Center Open API — South Korea's official statute database (law, cabinet
+  order, and ministerial-ordinance text, with promulgation and
+  entry-into-force dates and revision history).
+
+## Known gaps and gotchas
+
+- **Korean-language text only.** No translation is attempted or labelled
+  official. The Ministry does not publish an official English statute text
+  through this API.
+- **`kr_law_history`'s success shape is unproven against a live call** — no
+  OC entitled to the history service was available while building this pack.
+  The error path (an OC *without* that entitlement) is proven live and is
+  what most callers without a premium/full registration will actually see.
+  Flag this if it ever drifts from the documented row shape.
+- **`article_no` branch numbering**: Korean statutes insert new articles
+  between existing ones as "제4조의2" rather than renumbering everything —
+  pass that as `"4-2"`. `kr_law_article` with no `article_no` lists every
+  valid value for a given `mst`.
+- A law's own `시행일자` (effective date) and one specific article's
+  `조문시행일자` can differ — an amendment sometimes only moves one article's
+  effective date forward. Both are returned, kept separate.
+- **www.law.go.kr is itself Cloudflare-fronted and blocks a Cloudflare
+  Worker's own egress specifically** (measured live, 2026-10-16: through the
+  gateway only 2 of 10 calls succeeded, while a non-CF vantage got 10 of 10).
+  Every call is routed through the Pipeworx egress relay, the same
+  mechanism as `mcps/oklahoma-code`/`mcps/utah-code` — with a direct-call
+  fallback if the relay itself is misconfigured, since direct egress does
+  sometimes succeed here. Every tool also retries up to 3 times with
+  backoff on a 522/524/503 before giving up; if nothing responds after
+  that, the error says plainly that Korea's law service did not respond and
+  to try again — never a bare Cloudflare status code or its
+  "error code: 5xx" body text.
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "kr-law": {
+      "url": "https://gateway.pipeworx.io/kr-law/mcp"
+    }
+  }
+}
+```
+
+### What this endpoint actually serves
+
+`tools/list` at `https://gateway.pipeworx.io/kr-law/mcp` returns the tools in the table
+above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
+`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
+gateway-wide set. So the tool count you see is larger than this table: a
+single-pack endpoint currently lists roughly 30 shared tools alongside the
+pack's own. The connection's `initialize` response states its exact scope, and
+is the authoritative answer for a given day.
+
+This is deliberate, not multiplexing by accident. The meta-tools are what let a
+scoped connection answer a question this pack does not cover — via
+`ask_pipeworx`, which routes across the whole catalog — without you adding a
+second MCP server. There is currently no way to mount a pack endpoint without
+them; if the extra schemas cost you more context than the routing is worth,
+connect to the full gateway once rather than to several pack endpoints.
+
+Or connect to the full Pipeworx gateway to get every pack's tools listed
+directly, instead of just this one's:
+
+```json
+{
+  "mcpServers": {
+    "pipeworx": {
+      "url": "https://gateway.pipeworx.io/mcp"
+    }
+  }
+}
+```
+
+Both URLs reach the same gateway and the same 1856+ data sources. The
+only difference is which pack's tools are listed **directly**; `ask_pipeworx`
+reaches all of them from either one.
+
+## No MCP client? Call it over HTTP
+
+This pack takes your own API key (`_apiKey`) — we don't front one for it, so there's no curl here that would run without it. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/kr_law_search`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
+
+## Run it from npm
+
+`@pipeworx/mcp-kr-law` is a local stdio bridge to the Pipeworx gateway: your MCP client
+starts it with `npx`, and it forwards every call to the same
+`https://gateway.pipeworx.io/kr-law/mcp` endpoint shown above. It needs network access;
+there is no offline mode.
+
+```json
+{
+  "mcpServers": {
+    "kr-law": {
+      "command": "npx",
+      "args": ["-y", "@pipeworx/mcp-kr-law"]
+    }
+  }
+}
+```
+
+Without a key it calls anonymously, capped at 50 calls a day. A free account
+raises that to 200 a day: get a key at https://pipeworx.io/signup and add
+`"env": { "PIPEWORX_API_KEY": "<your key>" }` to the server entry.
+The key is sent as a Bearer token, the same way a hosted connection sends it,
+so calls are metered and billed exactly as they are there.
+
+It lists **only** this pack's tools by default. Set `PIPEWORX_META_TOOLS=1` to
+also list `ask_pipeworx` and the other gateway-wide tools.
+
+Behind an HTTPS proxy: Node's built-in `fetch` does not read `HTTPS_PROXY` by
+default. Newer Node releases honour it when `NODE_USE_ENV_PROXY=1` is set; check
+your Node version's documentation.
+
+## Using with ask_pipeworx
+
+Instead of calling tools directly, you can ask questions in plain English —
+this works on the pack endpoint above as well as on the full gateway:
+
+```
+ask_pipeworx({ question: "your question about Kr Law data" })
+```
+
+The gateway picks the right tool and fills the arguments automatically.
+
+## More
+
+- [Docs and guides](https://pipeworx.io/docs)
+- [pipeworx.io](https://pipeworx.io)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Entry point for `npx @pipeworx/mcp-<slug>` in gateway mode (bin/cli.js).
+//
+// A stdio MCP server that relays every message to the Pipeworx gateway's
+// /<slug>/mcp endpoint -- fleet #3759, docs/standalone-via-gateway-plan.md.
+// It carries no pack code and has no local mode. The relay itself lives in
+// ../lib/index.js (copied from scripts/templates/standalone-gateway-lib.js);
+// this file only owns stdin/stdout.
+//
+// Copied VERBATIM into every gateway-mode package by scripts/publish-pack.sh.
+// Edit scripts/templates/standalone-gateway-cli.js in the monorepo, never a
+// per-pack copy. Zero dependencies, Node 18+.
+//
+// stdout carries newline-delimited JSON-RPC and nothing else; every diagnostic
+// goes to stderr, because a single stray line on stdout breaks the host's
+// parser.
+import { createInterface } from 'node:readline';
+import { relay, bridgeConfig } from '../lib/index.js';
+
+const cfg = bridgeConfig();
+const warn = (line) => process.stderr.write(`${line}\n`);
+const write = (msg) => { if (msg) process.stdout.write(`${JSON.stringify(msg)}\n`); };
+
+const pending = new Set();
+function track(p) {
+  pending.add(p);
+  p.finally(() => pending.delete(p));
+}
+
+async function handleLine(line) {
+  const text = line.trim();
+  if (!text) return;
+  let message;
+  try {
+    message = JSON.parse(text);
+  } catch {
+    write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    return;
+  }
+  // A JSON-RPC batch: relay each member, answer with the non-notification replies.
+  if (Array.isArray(message)) {
+    const replies = (await Promise.all(message.map((m) => relay(m, { cfg, warn })))).filter(Boolean);
+    if (replies.length) write(replies);
+    return;
+  }
+  write(await relay(message, { cfg, warn }));
+}
+
+// Requests are handled concurrently and answered as they finish: JSON-RPC ids
+// let the host match them, and a slow tool call must not hold up a ping.
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', (line) => {
+  track(handleLine(line).catch((err) => warn(`pipeworx-standalone: ${err && err.stack ? err.stack : err}`)));
+});
+rl.on('close', async () => {
+  // stdin closed: finish what is in flight, then exit.
+  while (pending.size) await Promise.allSettled([...pending]);
+  // Exit only once stdout has flushed: on a pipe that is not synchronous
+  // everywhere, and a bare exit can drop the last reply.
+  process.stdout.write('', () => process.exit(0));
+});

package/lib/index.js

@@ -0,0 +1,333 @@
+// @pipeworx/mcp-<slug> -- library half of the gateway bridge (lib/index.js).
+//
+// Copied VERBATIM into every gateway-mode pack package by scripts/publish-pack.sh
+// (fleet #3759, docs/standalone-via-gateway-plan.md section 1). There is no
+// per-pack templating: the slug and version are read from this package's own
+// package.json (`pipeworx.slug`, `version`) at load time, so the same bytes
+// ship in every package and the source hash can cover them once. Edit this
+// file in the monorepo (scripts/templates/standalone-gateway-lib.js), never a
+// per-pack copy.
+//
+// What it is: a relay. Every JSON-RPC message goes to
+// ${PIPEWORX_GATEWAY_URL:-https://gateway.pipeworx.io}/<slug>/mcp, the same
+// endpoint a hosted MCP client uses, so tiers, rate limits and credits apply
+// exactly as they do there. There is no local mode: the pack's code is not in
+// this package.
+//
+// Zero dependencies, plain ESM, Node 18+ (global fetch). Nothing here writes
+// to stdout -- bin/cli.js owns stdout and it carries JSON-RPC only.
+//
+// Environment:
+//   PIPEWORX_API_KEY      sent as `Authorization: Bearer <key>`. Never as
+//                         X-API-Key: the gateway reads a pwx_ key sent that way
+//                         as an unvalidated BYO string with no account.
+//   PIPEWORX_GATEWAY_URL  gateway base URL (no path), default the public gateway.
+//   PIPEWORX_META_TOOLS=1 list the gateway-wide tools (ask_pipeworx, ...) too.
+//   PIPEWORX_TIMEOUT_MS   per-request timeout, default 120000.
+
+import { readFileSync } from 'node:fs';
+
+const readJson = (rel) => JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8'));
+
+const PKG = readJson('../package.json');
+export const SLUG = PKG.pipeworx && PKG.pipeworx.slug;
+if (typeof SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(SLUG)) {
+  throw new Error(`${PKG.name}: package.json carries no valid pipeworx.slug -- this package was built wrong`);
+}
+/**
+ * The pack's slug on the GATEWAY: the /<slug>/mcp route and the `_meta.pack`
+ * every listed tool carries. Usually the same as `slug` (the npm/directory
+ * name), but 14 packs differ -- `hex-pm` is `hex_pm` on the gateway -- and
+ * filtering tools/list on the npm slug would match none of their tools
+ * (fleet #3761). publish-pack.sh stamps it from the gateway manifest.
+ */
+export const GATEWAY_SLUG = (PKG.pipeworx && PKG.pipeworx.gatewaySlug) || SLUG;
+if (typeof GATEWAY_SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(GATEWAY_SLUG)) {
+  throw new Error(`${PKG.name}: package.json carries an invalid pipeworx.gatewaySlug -- this package was built wrong`);
+}
+export const PACKAGE_NAME = PKG.name;
+export const VERSION = PKG.version;
+
+/** The pack's own tool definitions at publish time (the offline tools/list answer). */
+export const tools = readJson('../tools.json');
+
+const DEFAULT_GATEWAY = 'https://gateway.pipeworx.io';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const SIGNUP_URL = 'https://pipeworx.io/signup';
+const VIA = '(via pipeworx-standalone)';
+
+/** Resolve the bridge's settings. Exported for the tests and for callTool. */
+export function bridgeConfig(env = process.env, overrides = {}) {
+  const base = String(overrides.gatewayUrl || env.PIPEWORX_GATEWAY_URL || DEFAULT_GATEWAY).trim().replace(/\/+$/, '');
+  const apiKey = String(overrides.apiKey ?? env.PIPEWORX_API_KEY ?? '').trim();
+  const t = Number(overrides.timeoutMs ?? env.PIPEWORX_TIMEOUT_MS);
+  return {
+    endpoint: `${base}/${GATEWAY_SLUG}/mcp`,
+    apiKey,
+    timeoutMs: Number.isFinite(t) && t > 0 ? t : DEFAULT_TIMEOUT_MS,
+    metaTools: (overrides.metaTools ?? env.PIPEWORX_META_TOOLS) === '1' || overrides.metaTools === true,
+  };
+}
+
+function requestHeaders(cfg) {
+  const h = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    // Stable per package version: the gateway remembers a client's name by
+    // identifier + User-Agent (workers/gateway/src/client-identity.ts).
+    'User-Agent': `pipeworx-standalone/${VERSION} (${PACKAGE_NAME})`,
+    // Analytics label only (blob11 = 'standalone'). It never changes tier,
+    // limits or price -- anyone can send it.
+    'X-Pipeworx-Surface': 'standalone',
+  };
+  if (cfg.apiKey) h.Authorization = `Bearer ${cfg.apiKey}`;
+  return h;
+}
+
+/** Parse a gateway body: JSON, or the last JSON `data:` frame of an SSE stream. */
+function parseBody(text, contentType) {
+  if (/text\/event-stream/i.test(contentType || '')) {
+    let last = null;
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.startsWith('data:')) continue;
+      try { last = JSON.parse(line.slice(5).trim()); } catch { /* keep-alive or partial frame */ }
+    }
+    return last;
+  }
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/**
+ * POST one JSON-RPC message. Never throws: the outcome is one of
+ *   { kind: 'http', status, headers, body, text }   the gateway answered
+ *   { kind: 'network', detail }                      DNS, TLS, refused, reset
+ *   { kind: 'timeout' }                              no answer in cfg.timeoutMs
+ */
+export async function postToGateway(message, cfg) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), cfg.timeoutMs);
+  try {
+    const res = await fetch(cfg.endpoint, {
+      method: 'POST',
+      headers: requestHeaders(cfg),
+      body: JSON.stringify(message),
+      signal: ac.signal,
+    });
+    const text = await res.text();
+    return { kind: 'http', status: res.status, headers: res.headers, body: parseBody(text, res.headers.get('content-type')), text };
+  } catch (err) {
+    if (ac.signal.aborted || (err && (err.name === 'AbortError' || err.name === 'TimeoutError'))) return { kind: 'timeout' };
+    const cause = err && err.cause;
+    const detail = (cause && (cause.code || cause.message)) || (err && err.message) || String(err);
+    return { kind: 'network', detail };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── The key-not-accepted warning (one per process) ──────────────────
+
+let warnedKeyIgnored = false;
+const KEY_IGNORED = 'PIPEWORX_API_KEY was not accepted, calling anonymously.';
+
+/** True when a key was sent but the gateway still served the call as anonymous. */
+function keyIgnored(out, cfg) {
+  return !!cfg.apiKey && out.kind === 'http' && (out.headers.get('x-ratelimit-tier') || '').toLowerCase() === 'anonymous';
+}
+
+function noteTier(out, cfg, warn) {
+  if (!keyIgnored(out, cfg) || warnedKeyIgnored) return;
+  warnedKeyIgnored = true;
+  warn(`${PACKAGE_NAME}: ${KEY_IGNORED} Check the key at ${SIGNUP_URL}.`);
+}
+
+/** Test hook: forget that the warning was printed. */
+export function _resetWarnings() { warnedKeyIgnored = false; }
+
+// ── Results the host shows to the model ─────────────────────────────
+
+function errorResult(text, detail) {
+  const result = { content: [{ type: 'text', text }], isError: true };
+  if (detail) result._meta = { pipeworx_standalone: detail };
+  return result;
+}
+
+const rpcResult = (id, result) => ({ jsonrpc: '2.0', id, result });
+const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+function firstLine(text) {
+  const line = String(text || '').split(/\r?\n/).map((l) => l.trim()).find(Boolean) || '(empty body)';
+  return line.length > 200 ? `${line.slice(0, 200)}...` : line;
+}
+
+function unreachableText(cfg, out) {
+  if (out.kind === 'timeout') {
+    return `The Pipeworx gateway at ${cfg.endpoint} did not answer within ${Math.round(cfg.timeoutMs / 1000)}s, so this call timed out. `
+      + `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode. Try again; a call that keeps timing out is worth reporting.`;
+  }
+  return `Could not reach the Pipeworx gateway at ${cfg.endpoint} (${out.detail}). `
+    + `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode, so it needs network access.`;
+}
+
+function isAuthRequired(body) {
+  return !!body && (body.error_code === 'authentication_required'
+    || (body.error && body.error.data && body.error.data.reason === 'authentication_required'));
+}
+
+/** Map a tools/call outcome to the JSON-RPC response the host gets. */
+function toolsCallResponse(id, out, cfg) {
+  if (out.kind !== 'http') return rpcResult(id, errorResult(unreachableText(cfg, out), { reason: out.kind }));
+  const { status, body } = out;
+
+  // Anonymous daily cap: the gateway answers 401 with a JSON-RPC error whose
+  // message is the offer. Hosts often swallow protocol errors, so hand it over
+  // as a tool result the model actually reads.
+  if (status === 401 && isAuthRequired(body)) {
+    const data = (body.error && body.error.data) || {};
+    const parts = [body.error && body.error.message ? body.error.message : 'The anonymous daily allowance is used up.'];
+    if (data.resets_at) parts.push(`The anonymous allowance resets at ${data.resets_at}.`);
+    parts.push(cfg.apiKey
+      ? `${KEY_IGNORED} Check the key, or get a free one at ${SIGNUP_URL}.`
+      : `To keep going now, set PIPEWORX_API_KEY in this MCP server's environment; a free key is at ${SIGNUP_URL}.`);
+    return rpcResult(id, errorResult(parts.join('\n\n'), { status, reason: 'authentication_required', resets_at: data.resets_at ?? null }));
+  }
+
+  // A keyed tier over its cap: today the gateway answers 429 with a RESULT
+  // that has no isError, which reads as a success (fleet #3760). Mark it.
+  if (status === 429 && body && body.result && typeof body.result === 'object') {
+    const result = { ...body.result, isError: true };
+    if (cfg.apiKey && keyIgnored(out, cfg)) {
+      result.content = [...(Array.isArray(result.content) ? result.content : []), { type: 'text', text: KEY_IGNORED }];
+    }
+    return rpcResult(id, result);
+  }
+  if ((status === 401 || status === 429) && body && body.error) {
+    const extra = keyIgnored(out, cfg) ? ` ${KEY_IGNORED}` : '';
+    return rpcResult(id, errorResult(`${body.error.message || `HTTP ${status}`}${extra}`, { status }));
+  }
+
+  // A real JSON-RPC answer (result or protocol error): relay it verbatim,
+  // structuredContent and _meta (cost, tier, provenance) included.
+  if (body && body.jsonrpc === '2.0' && (body.result !== undefined || body.error !== undefined) && status < 500) {
+    return { ...body, id };
+  }
+
+  // 5xx, an HTML edge page, or anything else that is not JSON-RPC.
+  return rpcResult(id, errorResult(`The Pipeworx gateway returned HTTP ${status}: ${firstLine(out.text)}`, { status }));
+}
+
+function localInitialize(params) {
+  return {
+    protocolVersion: (params && params.protocolVersion) || '2025-06-18',
+    capabilities: { tools: {} },
+    serverInfo: { name: PACKAGE_NAME, version: VERSION },
+  };
+}
+
+const scopedInstructions = () =>
+  `${PACKAGE_NAME} forwards to the Pipeworx gateway and lists only the ${SLUG} pack's tools. `
+  + 'Set PIPEWORX_META_TOOLS=1 to also list ask_pipeworx and the other gateway-wide tools.';
+
+/** `<host name> (via pipeworx-standalone)`. The slug stays OUT of the name: the
+ *  gateway's scanner-name check substring-matches words like poll/watch/index. */
+export function bridgedClientName(name) {
+  const n = typeof name === 'string' && name.trim() ? name.trim() : 'unknown';
+  return n.includes(VIA) ? n : `${n} ${VIA}`;
+}
+
+/**
+ * Relay one JSON-RPC message to the gateway and return the response to write
+ * back, or null for a notification. Never throws.
+ *
+ * @param {object} message  a parsed JSON-RPC request or notification
+ * @param {{cfg?: object, warn?: (line: string) => void}} [opts]
+ */
+export async function relay(message, opts = {}) {
+  const cfg = opts.cfg || bridgeConfig();
+  const warn = opts.warn || ((line) => process.stderr.write(`${line}\n`));
+  if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+    const id = message && typeof message === 'object' && 'id' in message ? message.id : null;
+    return rpcError(id ?? null, -32600, 'Invalid Request');
+  }
+  const isNotification = !('id' in message) || message.id === undefined;
+  const id = message.id;
+
+  if (isNotification) {
+    const out = await postToGateway(message, cfg);
+    if (out.kind !== 'http') warn(`${PACKAGE_NAME}: notification ${message.method} not delivered: ${unreachableText(cfg, out)}`);
+    return null;
+  }
+
+  if (message.method === 'initialize') {
+    const params = { ...(message.params || {}) };
+    params.clientInfo = { ...(params.clientInfo || {}), name: bridgedClientName(params.clientInfo && params.clientInfo.name) };
+    if (!params.clientInfo.version) params.clientInfo.version = '0';
+    const out = await postToGateway({ ...message, params }, cfg);
+    noteTier(out, cfg, warn);
+    if (out.kind === 'http' && out.body && out.body.result && typeof out.body.result === 'object') {
+      const result = { ...out.body.result, serverInfo: { name: PACKAGE_NAME, version: VERSION } };
+      if (!cfg.metaTools) result.instructions = scopedInstructions();
+      return rpcResult(id, result);
+    }
+    // The host must still start: answer locally and let the calls report the
+    // gateway problem when they happen.
+    warn(`${PACKAGE_NAME}: initialize answered locally -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
+    return rpcResult(id, { ...localInitialize(message.params), instructions: scopedInstructions() });
+  }
+
+  if (message.method === 'tools/list') {
+    const out = await postToGateway(message, cfg);
+    noteTier(out, cfg, warn);
+    const listed = out.kind === 'http' && out.body && out.body.result && Array.isArray(out.body.result.tools)
+      ? out.body.result : null;
+    if (listed) {
+      if (cfg.metaTools) return rpcResult(id, listed);
+      const own = listed.tools.filter((t) => t && t._meta && (t._meta.pack === GATEWAY_SLUG || t._meta.pack === SLUG));
+      if (own.length > 0) return rpcResult(id, { ...listed, tools: own });
+      warn(`${PACKAGE_NAME}: the gateway listed no ${SLUG} tools; serving the tool list bundled with this package`);
+    } else {
+      warn(`${PACKAGE_NAME}: tools/list served from the snapshot bundled with this package -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
+    }
+    return rpcResult(id, { tools });
+  }
+
+  if (message.method === 'tools/call') {
+    const out = await postToGateway(message, cfg);
+    noteTier(out, cfg, warn);
+    return toolsCallResponse(id, out, cfg);
+  }
+
+  // Everything else (ping, resources/*, prompts/*, ...): relay as-is.
+  const out = await postToGateway(message, cfg);
+  noteTier(out, cfg, warn);
+  if (out.kind === 'http' && out.body && out.body.jsonrpc === '2.0') return { ...out.body, id };
+  if (message.method === 'ping') return rpcResult(id, {});
+  return rpcError(id, -32603, out.kind === 'http'
+    ? `The Pipeworx gateway returned HTTP ${out.status}: ${firstLine(out.text)}`
+    : unreachableText(cfg, out));
+}
+
+/**
+ * Call one of this pack's tools through the gateway -- the `{tools, callTool}`
+ * shape earlier versions of this package exported. Resolves with the tool's
+ * structured result; rejects with the gateway's message on any error.
+ *
+ * @param {string} name
+ * @param {Record<string, unknown>} [args]
+ * @param {{apiKey?: string, gatewayUrl?: string, timeoutMs?: number}} [opts]
+ *        apiKey defaults to process.env.PIPEWORX_API_KEY.
+ */
+export async function callTool(name, args = {}, opts = {}) {
+  const cfg = bridgeConfig(process.env, opts);
+  const res = await relay({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }, { cfg });
+  if (res.error) throw new Error(res.error.message);
+  const result = res.result || {};
+  const text = Array.isArray(result.content)
+    ? result.content.filter((c) => c && c.type === 'text').map((c) => c.text).join('\n')
+    : '';
+  if (result.isError) throw new Error(text || `${name} failed`);
+  if (result.structuredContent !== undefined) return result.structuredContent;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+export default { tools, callTool };

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@pipeworx/mcp-kr-law",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Korea Law MCP — South Korean national statutes via the Ministry of Government Legislation's (법제처) National Law Information Center Open API (open.law.go.kr).",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./tools.json": "./tools.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "mcp-kr-law": "bin/cli.js"
+  },
+  "files": ["bin/", "lib/", "tools.json", "server.json"],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "kr-law"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pipeworx-io/mcp-kr-law.git"
+  },
+  "mcpName": "io.github.pipeworx-io/kr-law",
+  "pipeworx": {
+    "mode": "gateway",
+    "slug": "kr-law",
+    "gatewaySlug": "kr-law",
+    "sourceHash": "v1-74ca3dd1b43e0a9cd5b5adb81c043cb995f5600074dd95af06c51d9ddcbb87f1",
+    "sourceCommit": "5c89d6abb778d45da5d92002eb251978622bedf9"
+  }
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/kr-law",
+  "title": "Kr Law",
+  "description": "Korea Law MCP — South Korean national statutes via the Ministry of Government Legislation's (법제처)…",
+  "version": "0.2.0",
+  "websiteUrl": "https://pipeworx.io/packs/kr-law",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-kr-law",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/kr-law/mcp"
+    }
+  ]
+}

package/tools.json

@@ -0,0 +1,91 @@
+[
+  {
+    "name": "kr_law_search",
+    "description": "Search South Korean national statutes by title keyword (국가법령정보, Ministry of Government Legislation). Returns each matching law's id, mst (version id — pass to kr_law_article/kr_law_history), ministry, promulgation/effective dates, and whether it is the current (\"현행\") or a superseded (\"연혁\") version. BYOK: requires your own OC from open.law.go.kr (Korean real-name verification to register); pass it as _apiKey.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Title keyword, Korean or romanized, e.g. \"도로교통법\" (Road Traffic Act) or \"개인정보\"."
+        },
+        "display": {
+          "type": "number",
+          "description": "Results per page, 1-100 (default 20)."
+        },
+        "page": {
+          "type": "number",
+          "description": "1-based page number (default 1)."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "all",
+            "current",
+            "historical"
+          ],
+          "description": "Narrow to currently-in-force laws only (\"current\") or search as-is (\"all\", default). \"historical\" still returns the general list; filter client-side on the returned \"status\" field for superseded versions."
+        },
+        "_apiKey": {
+          "type": "string",
+          "description": "Your own OC (Open API user id) from https://open.law.go.kr/LSO/main.do. The Ministry's public demo id \"test\" works here for smoke-testing."
+        }
+      },
+      "required": [
+        "query"
+      ]
+    }
+  },
+  {
+    "name": "kr_law_article",
+    "description": "Fetch ONE article (조문) of a South Korean statute by mst (from kr_law_search) and article_no (e.g. \"5\" or \"4-2\" for 제4조의2). Never returns the whole law body. Omit article_no to get a paginated table of contents (article numbers + titles) instead. Returns the article's own text, paragraphs (항) and items (호), its own effective date (which can differ from the law's), and law-level metadata (promulgation date, effective date, ministry) kept as separate fields. BYOK: requires your own OC; pass it as _apiKey.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "mst": {
+          "type": "string",
+          "description": "Law version id (법령일련번호) from kr_law_search's \"mst\" field."
+        },
+        "article_no": {
+          "type": "string",
+          "description": "Article number, e.g. \"5\", or \"4-2\" for a branch article (제4조의2). Omit for a table of contents."
+        },
+        "display": {
+          "type": "number",
+          "description": "Table-of-contents mode only: entries per page, 1-200 (default 50)."
+        },
+        "page": {
+          "type": "number",
+          "description": "Table-of-contents mode only: 1-based page number (default 1)."
+        },
+        "_apiKey": {
+          "type": "string",
+          "description": "Your own OC (Open API user id) from https://open.law.go.kr/LSO/main.do. The Ministry's public demo id \"test\" works here for smoke-testing."
+        }
+      },
+      "required": [
+        "mst"
+      ]
+    }
+  },
+  {
+    "name": "kr_law_history",
+    "description": "Revision history for a South Korean statute: every promulgation with its own date, promulgation number, and entry-into-force date, each as a separate historical mst you can pass to kr_law_article. Requires the caller's OC to have the 법령연혁 (law history) service separately enabled under My Applications at open.law.go.kr — if it is not, this throws a specific, actionable upstream error rather than a generic failure. BYOK: pass your OC as _apiKey.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "mst": {
+          "type": "string",
+          "description": "Law version id (법령일련번호) from kr_law_search's \"mst\" field."
+        },
+        "_apiKey": {
+          "type": "string",
+          "description": "Your own OC (Open API user id) from https://open.law.go.kr/LSO/main.do, with 법령연혁 enabled under My Applications."
+        }
+      },
+      "required": [
+        "mst"
+      ]
+    }
+  }
+]