law-mcp-server 0.1.0

package/.env.example

@@ -0,0 +1,8 @@
+# Base URL for the e-Gov 法令API v2
+LAW_API_BASE=https://laws.e-gov.go.jp/api/2/
+
+# HTTP request timeout in milliseconds
+HTTP_TIMEOUT_MS=15000
+
+# Cache TTL for fetched law responses in seconds
+CACHE_TTL_SECONDS=900

package/.eslintignore

@@ -0,0 +1,2 @@
+dist/
+node_modules/

package/.eslintrc.cjs

@@ -0,0 +1,19 @@
+module.exports = {
+  env: {
+    es2022: true,
+    node: true,
+  },
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    sourceType: "module",
+    ecmaVersion: "latest",
+  },
+  plugins: ["@typescript-eslint"],
+  extends: [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier",
+  ],
+  ignorePatterns: ["dist/**"],
+  rules: {},
+};

package/.prettierignore

@@ -0,0 +1,2 @@
+dist/
+node_modules/

package/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "singleQuote": false,
+  "semi": true,
+  "trailingComma": "es5"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoshihiko Miyaichi
+
+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

@@ -0,0 +1,82 @@
+# Law MCP Server Specification
+
+This repository will host an MCP server that uses **法令API Version 2** (e-Gov) to fetch statute data and help check the consistency between internal documents and the referenced laws. The document below captures the target capabilities and operational expectations before implementation.
+
+## Overview
+
+- Provide MCP tools that surface law data from the official API and perform document-to-law consistency checks.
+- Enable knowledge workers to verify whether policy drafts, contracts, or memos align with authoritative legal text.
+- Favor transparent outputs that include sources (LawID, article numbers, URLs) and the reasoning steps used during checks.
+
+## External Data Source
+
+- Base: `https://laws.e-gov.go.jp/api/2/`
+- Common endpoints (see swagger for full schema):
+  - `GET /lawdata/{LawID}` – fetch law structure and articles.
+  - `GET /lawsearch/{keyword}` – search laws by keyword.
+- Response format: JSON (includes meta, LawName, Articles, etc.). Respect official rate limits; treat 429/503 as retryable with backoff.
+
+## MCP Capabilities (planned tools)
+
+- `fetch_law` – Input: `lawId` (string), optional `revisionDate`. Output: normalized law JSON plus source URL.
+- `search_laws` – Input: `keyword` (string), optional `lawType` filter. Output: list of LawID, title, promulgation date, and API URL.
+- `list_revisions` – Input: `lawId`. Output: known revision dates/IDs when the API supplies them.
+- `check_consistency` – Input: `documentText`, optional `lawIds`, optional `articleHints`, `strictness` (low/medium/high). Output: matched citations, conflicting passages, and a traceable reasoning summary.
+- `summarize_law` – Input: `lawId`, optional `articles` list. Output: concise bullet summary suitable for grounding model responses.
+
+## Consistency Check Workflow
+
+- Normalize the incoming document (segment by sentence/section, detect cited articles like “第○条”).
+- Resolve target laws: use `lawIds` provided or run `search_laws` to suggest candidates.
+- Fetch required law texts via `fetch_law`; cache responses per `LawID` to reduce API load.
+- Align document segments to law articles using string similarity and citation hints; note exact article numbers when present.
+- Produce findings: for each segment, mark status (`aligned`, `potential_mismatch`, `not_found`), include article references, and show snippets from both sides.
+- Provide remediation suggestions (e.g., cite correct article, adjust wording) without altering the source document automatically.
+
+## Server Behavior & Error Handling
+
+- Map API errors to MCP-friendly errors with actionable messages (e.g., missing `LawID`, upstream 429, malformed parameters).
+- Use exponential backoff on 429/503 and surface retry-after hints when present.
+- Validate inputs early: reject empty `documentText`, overly long queries, or unsupported `lawId` formats with clear guidance.
+- Log tool calls and upstream URLs for debugging; avoid storing document contents longer than the session.
+
+## Configuration
+
+- Environment variables (to be wired during implementation):
+  - `LAW_API_BASE` (default `https://laws.e-gov.go.jp/api/2/`)
+  - `HTTP_TIMEOUT_MS` (default 15000)
+  - `CACHE_TTL_SECONDS` (default 900)
+- Add `.env.example` later with the above keys; do not commit secrets.
+
+## Implementation Notes
+
+- Suggested stack: Node.js with a lightweight stdio JSON-RPC bridge for MCP compatibility, `undici`/`node-fetch` for HTTP, and a lightweight in-memory cache (Map/LRU). TypeScript preferred for schema safety using the Swagger spec.
+- Define TypeScript types for API responses (LawData, Article, SearchResult) to enforce strict parsing.
+- Keep business logic pure and testable (e.g., citation extraction, alignment scoring) independent of I/O.
+- Expose a health endpoint or MCP tool (e.g., `ping`) for quick readiness checks.
+
+## Getting Started
+
+- Requirements: Node.js 18+.
+- Install dependencies: `npm install`.
+- Build: `npm run build`.
+- Copy `.env.example` to `.env` and adjust if needed.
+- Run server over stdio (JSON-RPC): `npm start` (or `npm run dev` for ts-node).
+- Configure via environment variables in `.env` (see Configuration section). The server registers tools `fetch_law`, `search_laws`, `list_revisions`, `check_consistency`, and `summarize_law`.
+- Quality: `npm run lint` (ESLint) / `npm run format` (Prettier).
+
+## Usage Examples (conceptual)
+
+- Search and fetch: “Search for 個人情報保護 and show the latest articles.” → calls `search_laws` then `fetch_law`.
+- Consistency check: “Check this draft against 労働基準法 Articles 24 and 37; highlight mismatches.” → calls `check_consistency` with `lawIds=[...]` and article hints.
+
+## Validation Plan (to implement)
+
+- Unit tests for citation parsing, article alignment scoring, and API response normalization.
+- Integration tests mocking the 法令API to cover success, 404, 429/503 retry, and malformed LawID cases.
+- Integration test runner: `npm run test` (uses undici MockAgent; no network).
+- Manual smoke: run MCP client (e.g., Claude Desktop) to issue `search_laws` and `check_consistency` commands.
+
+---
+
+This specification is the starting point; refine it as implementation details solidify while keeping parity with the official 法令API Version 2 documentation.

package/dist/cache.js

@@ -0,0 +1,18 @@
+export class MemoryCache {
+    store = new Map();
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlSeconds) {
+        const expiresAt = Date.now() + ttlSeconds * 1000;
+        this.store.set(key, { value, expiresAt });
+    }
+}
+export const cache = new MemoryCache();

package/dist/config.js

@@ -0,0 +1,10 @@
+const toNumber = (value, fallback) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+export const config = {
+    apiBase: process.env.LAW_API_BASE?.trim() || "https://laws.e-gov.go.jp/api/2/",
+    httpTimeoutMs: toNumber(process.env.HTTP_TIMEOUT_MS, 15000),
+    cacheTtlSeconds: toNumber(process.env.CACHE_TTL_SECONDS, 900),
+    userAgent: "law-mcp-server/0.1.0"
+};

package/dist/consistency.js

@@ -0,0 +1,88 @@
+const toArray = (value) => {
+    if (!value)
+        return [];
+    return Array.isArray(value) ? value : [value];
+};
+const paragraphText = (paragraph) => {
+    if (!paragraph || typeof paragraph !== "object")
+        return "";
+    const p = paragraph;
+    const sentences = toArray(p.ParagraphSentence);
+    return sentences.join("\n");
+};
+const articleText = (article) => {
+    const paragraphs = toArray(article.Paragraph);
+    const body = paragraphs.map(paragraphText).filter(Boolean).join("\n");
+    const title = article.ArticleTitle || "";
+    return [title, body].filter(Boolean).join("\n");
+};
+const flattenArticles = (law) => {
+    const articles = toArray(law.LawBody?.MainProvision?.Article);
+    return articles.map((article) => ({
+        lawId: law.LawID,
+        articleNumber: article.ArticleNumber,
+        text: articleText(article)
+    }));
+};
+const similarityScore = (a, b) => {
+    const tokenize = (value) => value
+        .replace(/[\s、。,．\.\n\t]+/g, " ")
+        .split(" ")
+        .map((v) => v.trim())
+        .filter(Boolean);
+    const tokensA = tokenize(a.toLowerCase());
+    const tokensB = tokenize(b.toLowerCase());
+    if (!tokensA.length || !tokensB.length)
+        return 0;
+    const setB = new Set(tokensB);
+    const intersection = tokensA.filter((token) => setB.has(token)).length;
+    const union = new Set([...tokensA, ...tokensB]).size;
+    return intersection / union;
+};
+const extractArticleHint = (segment) => {
+    const match = segment.match(/第\s*([0-9０-９一二三四五六七八九十百千]+)\s*条/);
+    return match ? match[1] : undefined;
+};
+const bestArticleMatch = (segment, articles) => {
+    const hint = extractArticleHint(segment);
+    if (hint) {
+        const exact = articles.find((a) => a.articleNumber && a.articleNumber.includes(hint));
+        if (exact)
+            return exact;
+    }
+    let best;
+    let bestScore = 0;
+    for (const article of articles) {
+        const score = similarityScore(segment, article.text);
+        if (score > bestScore) {
+            best = article;
+            bestScore = score;
+        }
+    }
+    return best;
+};
+export const checkConsistency = (documentText, laws) => {
+    const segments = documentText
+        .split(/\n+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const flattened = laws.flatMap(flattenArticles).filter((a) => a.text.trim().length > 0);
+    const findings = segments.map((segment) => {
+        const match = bestArticleMatch(segment, flattened);
+        if (!match) {
+            return { segment, status: "not_found" };
+        }
+        const score = similarityScore(segment, match.text);
+        const status = score >= 0.6 ? "aligned" : score >= 0.25 ? "potential_mismatch" : "not_found";
+        return {
+            segment,
+            status,
+            lawId: match.lawId,
+            articleNumber: match.articleNumber,
+            lawSnippet: match.text.slice(0, 400),
+            score: Number(score.toFixed(3))
+        };
+    });
+    const matchedLawIds = Array.from(new Set(findings.map((f) => f.lawId).filter(Boolean)));
+    return { findings, matchedLawIds };
+};

package/dist/index.js

@@ -0,0 +1,22 @@
+import { StdioJsonRpcServer } from "./mcp.js";
+import { tools, resolveTool } from "./tools.js";
+const server = new StdioJsonRpcServer();
+server.register("ping", async () => ({ ok: true }));
+server.register("tools/list", async () => ({
+    tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema
+    }))
+}));
+server.register("tools/call", async (params) => {
+    const { name, arguments: args } = params;
+    const tool = resolveTool(name);
+    if (!tool) {
+        throw new Error(`Tool ${name} is not available`);
+    }
+    const result = await tool.handler(args || {});
+    return { content: result };
+});
+server.start();

package/dist/lawApi.js

@@ -0,0 +1,45 @@
+import { fetch } from "undici";
+import { cache } from "./cache.js";
+import { config } from "./config.js";
+const withTimeout = async (promise, ms) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), ms);
+    try {
+        return await promise;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const request = async (url) => {
+    const res = await withTimeout(fetch(url, {
+        headers: {
+            "User-Agent": config.userAgent,
+            Accept: "application/json"
+        }
+    }), config.httpTimeoutMs);
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Request failed ${res.status}: ${body}`);
+    }
+    const data = (await res.json());
+    return data;
+};
+export const fetchLawData = async (lawId, revisionDate) => {
+    const cacheKey = `law:${lawId}:${revisionDate || "latest"}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const base = config.apiBase.endsWith("/") ? config.apiBase : `${config.apiBase}/`;
+    const url = new URL(`lawdata/${encodeURIComponent(lawId)}`, base);
+    if (revisionDate)
+        url.searchParams.set("revision", revisionDate);
+    const data = await request(url.toString());
+    cache.set(cacheKey, data, config.cacheTtlSeconds);
+    return data;
+};
+export const searchLaws = async (keyword) => {
+    const base = config.apiBase.endsWith("/") ? config.apiBase : `${config.apiBase}/`;
+    const url = new URL(`lawsearch/${encodeURIComponent(keyword)}`, base);
+    return request(url.toString());
+};

package/dist/mcp.js

@@ -0,0 +1,45 @@
+import readline from "node:readline";
+export class StdioJsonRpcServer {
+    handlers = new Map();
+    register(method, handler) {
+        this.handlers.set(method, handler);
+    }
+    start() {
+        const rl = readline.createInterface({ input: process.stdin });
+        rl.on("line", async (line) => {
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch (error) {
+                return;
+            }
+            if (!message || message.jsonrpc !== "2.0" || message.method === undefined) {
+                return;
+            }
+            const { id, method, params } = message;
+            const handler = this.handlers.get(method);
+            if (!handler) {
+                if (id !== undefined) {
+                    this.send({ jsonrpc: "2.0", id, error: { code: -32601, message: "Method not found" } });
+                }
+                return;
+            }
+            try {
+                const result = await handler(params ?? {});
+                if (id !== undefined) {
+                    this.send({ jsonrpc: "2.0", id, result });
+                }
+            }
+            catch (error) {
+                if (id !== undefined) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.send({ jsonrpc: "2.0", id, error: { code: -32000, message } });
+                }
+            }
+        });
+    }
+    send(payload) {
+        process.stdout.write(JSON.stringify(payload) + "\n");
+    }
+}

package/dist/src/cache.js

@@ -0,0 +1,18 @@
+export class MemoryCache {
+    store = new Map();
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlSeconds) {
+        const expiresAt = Date.now() + ttlSeconds * 1000;
+        this.store.set(key, { value, expiresAt });
+    }
+}
+export const cache = new MemoryCache();

package/dist/src/config.js

@@ -0,0 +1,10 @@
+const toNumber = (value, fallback) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+export const config = {
+    apiBase: process.env.LAW_API_BASE?.trim() || "https://laws.e-gov.go.jp/api/2/",
+    httpTimeoutMs: toNumber(process.env.HTTP_TIMEOUT_MS, 15000),
+    cacheTtlSeconds: toNumber(process.env.CACHE_TTL_SECONDS, 900),
+    userAgent: "law-mcp-server/0.1.0",
+};

package/dist/src/consistency.js

@@ -0,0 +1,94 @@
+const toArray = (value) => {
+    if (!value)
+        return [];
+    return Array.isArray(value) ? value : [value];
+};
+const paragraphText = (paragraph) => {
+    if (!paragraph || typeof paragraph !== "object")
+        return "";
+    const p = paragraph;
+    const sentences = toArray(p.ParagraphSentence);
+    return sentences.join("\n");
+};
+const articleText = (article) => {
+    const paragraphs = toArray(article.Paragraph);
+    const body = paragraphs.map(paragraphText).filter(Boolean).join("\n");
+    const title = article.ArticleTitle || "";
+    return [title, body].filter(Boolean).join("\n");
+};
+const flattenArticles = (law) => {
+    const articles = toArray(law.LawBody?.MainProvision?.Article);
+    return articles.map((article) => ({
+        lawId: law.LawID,
+        articleNumber: article.ArticleNumber,
+        text: articleText(article),
+    }));
+};
+const similarityScore = (a, b) => {
+    const tokenize = (value) => value
+        .replace(/[\s、。,．.\n\t]+/g, " ")
+        .split(" ")
+        .map((v) => v.trim())
+        .filter(Boolean);
+    const tokensA = tokenize(a.toLowerCase());
+    const tokensB = tokenize(b.toLowerCase());
+    if (!tokensA.length || !tokensB.length)
+        return 0;
+    const setB = new Set(tokensB);
+    const intersection = tokensA.filter((token) => setB.has(token)).length;
+    const union = new Set([...tokensA, ...tokensB]).size;
+    return intersection / union;
+};
+const extractArticleHint = (segment) => {
+    const match = segment.match(/第\s*([0-9０-９一二三四五六七八九十百千]+)\s*条/);
+    return match ? match[1] : undefined;
+};
+const bestArticleMatch = (segment, articles) => {
+    const hint = extractArticleHint(segment);
+    if (hint) {
+        const exact = articles.find((a) => a.articleNumber && a.articleNumber.includes(hint));
+        if (exact)
+            return exact;
+    }
+    let best;
+    let bestScore = 0;
+    for (const article of articles) {
+        const score = similarityScore(segment, article.text);
+        if (score > bestScore) {
+            best = article;
+            bestScore = score;
+        }
+    }
+    return best;
+};
+export const checkConsistency = (documentText, laws) => {
+    const segments = documentText
+        .split(/\n+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const flattened = laws
+        .flatMap(flattenArticles)
+        .filter((a) => a.text.trim().length > 0);
+    const findings = segments.map((segment) => {
+        const match = bestArticleMatch(segment, flattened);
+        if (!match) {
+            return { segment, status: "not_found" };
+        }
+        const score = similarityScore(segment, match.text);
+        const status = score >= 0.6
+            ? "aligned"
+            : score >= 0.25
+                ? "potential_mismatch"
+                : "not_found";
+        return {
+            segment,
+            status,
+            lawId: match.lawId,
+            articleNumber: match.articleNumber,
+            lawSnippet: match.text.slice(0, 400),
+            score: Number(score.toFixed(3)),
+        };
+    });
+    const matchedLawIds = Array.from(new Set(findings.map((f) => f.lawId).filter(Boolean)));
+    return { findings, matchedLawIds };
+};

package/dist/src/index.js

@@ -0,0 +1,26 @@
+import { StdioJsonRpcServer } from "./mcp.js";
+import { tools, resolveTool } from "./tools.js";
+const server = new StdioJsonRpcServer();
+server.register("ping", async () => ({ ok: true }));
+server.register("tools/list", async () => ({
+    tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+    })),
+}));
+server.register("tools/call", async (params) => {
+    const payload = (params ?? {});
+    if (typeof payload.name !== "string") {
+        throw new Error("Tool name is required and must be a string");
+    }
+    const tool = resolveTool(payload.name);
+    if (!tool) {
+        throw new Error(`Tool ${payload.name} is not available`);
+    }
+    const args = payload.arguments && typeof payload.arguments === "object" ? payload.arguments : {};
+    const result = await tool.handler(args);
+    return { content: result };
+});
+server.start();

package/dist/src/lawApi.js

@@ -0,0 +1,49 @@
+import { fetch } from "undici";
+import { cache } from "./cache.js";
+import { config } from "./config.js";
+const withTimeout = async (promise, ms) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), ms);
+    try {
+        return await promise;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const request = async (url) => {
+    const res = await withTimeout(fetch(url, {
+        headers: {
+            "User-Agent": config.userAgent,
+            Accept: "application/json",
+        },
+    }), config.httpTimeoutMs);
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Request failed ${res.status}: ${body}`);
+    }
+    const data = (await res.json());
+    return data;
+};
+export const fetchLawData = async (lawId, revisionDate) => {
+    const cacheKey = `law:${lawId}:${revisionDate || "latest"}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const base = config.apiBase.endsWith("/")
+        ? config.apiBase
+        : `${config.apiBase}/`;
+    const url = new URL(`lawdata/${encodeURIComponent(lawId)}`, base);
+    if (revisionDate)
+        url.searchParams.set("revision", revisionDate);
+    const data = await request(url.toString());
+    cache.set(cacheKey, data, config.cacheTtlSeconds);
+    return data;
+};
+export const searchLaws = async (keyword) => {
+    const base = config.apiBase.endsWith("/")
+        ? config.apiBase
+        : `${config.apiBase}/`;
+    const url = new URL(`lawsearch/${encodeURIComponent(keyword)}`, base);
+    return request(url.toString());
+};

package/dist/src/mcp.js

@@ -0,0 +1,60 @@
+import readline from "node:readline";
+export class StdioJsonRpcServer {
+    handlers = new Map();
+    register(method, handler) {
+        this.handlers.set(method, handler);
+    }
+    start() {
+        const rl = readline.createInterface({ input: process.stdin });
+        rl.on("line", async (line) => {
+            const message = this.parseMessage(line);
+            if (!message)
+                return;
+            const { id, method, params } = message;
+            const handler = this.handlers.get(method);
+            if (!handler) {
+                if (id !== undefined) {
+                    this.send({
+                        jsonrpc: "2.0",
+                        id,
+                        error: { code: -32601, message: "Method not found" },
+                    });
+                }
+                return;
+            }
+            try {
+                const result = await handler(params ?? {});
+                if (id !== undefined) {
+                    this.send({ jsonrpc: "2.0", id, result });
+                }
+            }
+            catch (error) {
+                if (id !== undefined) {
+                    const messageText = error instanceof Error ? error.message : String(error);
+                    this.send({
+                        jsonrpc: "2.0",
+                        id,
+                        error: { code: -32000, message: messageText },
+                    });
+                }
+            }
+        });
+    }
+    parseMessage(line) {
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed ||
+                parsed.jsonrpc !== "2.0" ||
+                typeof parsed.method !== "string") {
+                return null;
+            }
+            return parsed;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    send(payload) {
+        process.stdout.write(JSON.stringify(payload) + "\n");
+    }
+}