building-standards-act-mcp 0.3.0 → 0.5.0

package/README.md

@@ -18,9 +18,71 @@ AI の建築法規回答に含まれるハルシネーションを、条文原
 - **主要法令プリセット** — 建築基準法・消防法・都市計画法ほか 115 法令の law_id をプリセット登録済み
 - **プリセット検証** — `validate_presets` ツールでプリセットの有効性をランタイム検証
 - **略称対応** — 「建基法」「都計法」「消防法」等の略称で指定可能
-- **キャッシュ** — 検索 30 分・法令データ 24 時間の TTL キャッシュ
+- **キャッシュ** — 検索 30 分・法令データ 24 時間の TTL キャッシュ（永続化オプションあり）
+- **API 耐障害性** — 自動リトライ（exponential backoff）+ サーキットブレーカー
+- **運用可視化** — 構造化 JSON ログ + 使用量メトリクス（`get_metrics` ツール）
 
-## セットアップ
+## Web で使う（Vercel デプロイ）
+
+Vercel にデプロイすると、ChatGPT・Claude.ai・Gemini CLI からすぐに使えます。環境変数の設定は不要です（e-Gov API は公開 API）。
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FSora-bluesky%2Fbuilding-standards-act-mcp)
+
+### カスタム GPT でのセットアップ（ChatGPT Plus/Pro/Team/Enterprise）
+
+1. 上の「Deploy with Vercel」ボタンでデプロイ（ワンクリック）
+2. [chatgpt.com/create](https://chatgpt.com/create) にアクセス
+3. 「Configure」タブで名前を入力（例: `建築法規アシスタント`）
+4. Instructions に以下を貼り付け:
+   ```
+   建築確認申請の法規に関する質問に回答してください。
+   回答には必ず条文番号を引用し、get_law で原文と照合してください。
+   ```
+5. 「Add Action」→「Import from URL」をクリック
+6. URL に `https://your-app.vercel.app/api/openapi.json`（your-app をデプロイ先に置換）を入力
+7. 「Save」→ 公開設定を選択
+
+> 参考: [Building and publishing a GPT](https://help.openai.com/en/articles/8798878-building-and-publishing-a-gpt)
+
+### Claude.ai でのセットアップ（Free/Pro/Max/Team/Enterprise）
+
+> **注意**: Custom Connectors はベータ版のため、接続が不安定な場合があります。安定してご利用いただくには [npx（ローカル）でのセットアップ](#npx推奨)もご検討ください。
+
+1. 上の「Deploy with Vercel」ボタンでデプロイ（ワンクリック）
+2. [claude.ai](https://claude.ai) → プロフィールアイコン → Settings → Connectors
+3. 「Add custom connector」をクリック
+4. URL に `https://your-app.vercel.app/api/mcp`（your-app をデプロイ先に置換）を入力
+5. チャットで「+」→「Connectors」→ building-law を有効化
+6. 「建築基準法第20条を教えて」と質問
+
+> 参考: [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
+
+### Gemini CLI でのセットアップ（開発者向け）
+
+1. 上の「Deploy with Vercel」ボタンでデプロイ（ワンクリック）
+2. `~/.gemini/settings.json` に以下を追加:
+   ```json
+   {
+     "mcpServers": {
+       "building-law": {
+         "httpUrl": "https://your-app.vercel.app/api/mcp"
+       }
+     }
+   }
+   ```
+3. `gemini` コマンドで「建築基準法第20条を取得して」と質問
+
+> 参考: [MCP servers with the Gemini CLI](https://geminicli.com/docs/tools/mcp-server/)
+
+### Vercel Free tier の制限事項
+
+- 関数の実行時間が **10 秒** に制限されます（Pro プランでは 60 秒）
+- `get_kokuji`（告示取得）は PDF ダウンロード + パースが重いため、タイムアウトする場合があります
+- `BUILDING_LAW_REQUEST_TIMEOUT=8000` を設定してタイムアウトを短縮できます
+
+---
+
+## ローカルで使う（stdio）
 
 ### npx（推奨）
 
@@ -73,18 +135,19 @@ npm run build
 
 ## MCP ツール
 
-| ツール              | 説明                                                                             |
-| ------------------- | -------------------------------------------------------------------------------- |
-| `get_law`           | 条番号を指定して法令の条文を取得する。略称・正式名称のいずれでも指定可能         |
-| `get_full_law`      | 法令の全文を取得する。条番号を指定せず法令全体のテキストを返す                   |
-| `search_law`        | キーワードで建築関連法令を横断検索する。プリセット法令と e-Gov API の両方を検索  |
-| `get_kokuji`        | 建築基準法が技術基準を委任している告示の全文を取得する                           |
-| `validate_presets`  | プリセット法令の law_id が e-Gov API で有効かを一括検証する                      |
-| `check_law_updates` | 法令の改正状況を e-Gov API で確認する（単体/バッチ/改正履歴表示に対応）          |
-| `get_laws_batch`    | 複数の法令・条文を一括取得する（最大20件、同一法令は1回のAPI呼び出しで効率処理） |
-| `verify_citation`   | AIの回答に含まれる法令引用を検証する（条文存在確認・テキスト照合、最大10件）     |
-| `suggest_related`   | 指定した条文の関連法令・委任先・同法令内参照を自動抽出して提案する               |
-| `analyze_article`   | 条文の構造解析メタデータ（項数・号数・参照統計・プレビュー）をJSON形式で返す     |
+| ツール              | 説明                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------- |
+| `get_law`           | 条番号を指定して法令の条文を取得する。略称・正式名称のいずれでも指定可能                    |
+| `get_full_law`      | 法令の全文を取得する。条番号を指定せず法令全体のテキストを返す                              |
+| `search_law`        | キーワードで建築関連法令を横断検索する。プリセット法令と e-Gov API の両方を検索             |
+| `get_kokuji`        | 建築基準法が技術基準を委任している告示の全文を取得する                                      |
+| `validate_presets`  | プリセット法令の law_id が e-Gov API で有効かを一括検証する                                 |
+| `check_law_updates` | 法令の改正状況を e-Gov API で確認する（単体/バッチ/改正履歴表示に対応）                     |
+| `get_laws_batch`    | 複数の法令・条文を一括取得する（最大20件、同一法令は1回のAPI呼び出しで効率処理）            |
+| `verify_citation`   | AIの回答に含まれる法令引用を検証する（条文存在確認・テキスト照合、最大10件）                |
+| `suggest_related`   | 指定した条文の関連法令・委任先・同法令内参照を自動抽出して提案する                          |
+| `analyze_article`   | 条文の構造解析メタデータ（項数・号数・参照統計・プレビュー）をJSON形式で返す                |
+| `get_metrics`       | サーバーの使用量メトリクスを返す（ツール呼び出し回数・APIリクエスト数・キャッシュヒット率） |
 
 ### パラメータ
 
@@ -154,6 +217,10 @@ npm run build
 | `law_name`       | 法令名（正式名称または略称） | `建築基準法` |
 | `article_number` | 条文番号                     | `第20条`     |
 
+#### `get_metrics`
+
+パラメータなし。サーバー起動後の稼働時間・ツール呼び出し回数・API リクエスト数・キャッシュヒット率を返す。
+
 ## 使用例
 
 ### 条文取得
@@ -193,12 +260,48 @@ npm run build
 
 ## ハルシネーション防止ワークフロー
 
-本ツールを使って AI の建築法規回答の正確性を担保するワークフローです。
+AI が建築法規について回答する際、条文の引用ミスや存在しない条文の捏造（ハルシネーション）が発生することがあります。本ツールは **4 段階の防止メカニズム** でこれを解決します。
+
+### 基本ワークフロー（自動実行）
 
-1. Claude が建築法規の質問に仮回答を作成
-2. 引用した条文・告示番号を `get_law` / `get_kokuji` で取得
-3. 実際の原文と仮回答を照合し、誤りがあれば修正
+```
+ユーザーの質問
+  ↓
+1. AI が仮回答を作成
+  ↓
+2. get_law / get_kokuji で引用した条文・告示の原文を取得
+  ↓
+3. 原文と仮回答を照合 → 誤りがあれば修正
+  ↓
 4. 2〜3 を収束するまで繰り返す（最大 4 ラウンド）
+  ↓
+照合済みの条文番号・告示番号を引用元として明示した最終回答
+```
+
+このワークフローは MCP サーバーの [システムプロンプト](src/server.ts) に組み込まれており、AI が自動的に実行します。
+
+### 追加の検証ツール
+
+基本ワークフローに加えて、以下の専用ツールを使用することでさらに精度を高められます。
+
+| ツール            | 用途                                            | 使い方                                                                                                                                           |
+| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `verify_citation` | AI の回答に含まれる **法令引用を自動検証** する | 回答テキストから条文番号・法令名を自動抽出し、e-Gov API から原文を取得して照合。不一致があれば指摘し、正しい条文を提示する（最大 10 件同時検証） |
+| `suggest_related` | 指定条文の **関連法令を自動提案** する          | 条文間の参照（委任先・同法令内参照）を解析し、見落としがちな関連規定を提示。施行令への委任や別の章への参照を漏れなく把握できる                   |
+| `analyze_article` | 条文の **構造を解析** する                      | 項数・号数・参照先の統計情報をメタデータとして返す。複雑な条文の全体像を把握し、読み落としを防ぐ                                                 |
+| `get_laws_batch`  | **複数条文を一括取得** する                     | 関連する複数の条文をまとめて取得し、条文間の整合性を確認する（最大 20 件）                                                                       |
+
+### 使用例：引用検証
+
+```
+「建築基準法第20条で木造建築物の構造計算が必要な条件を教えて」
+
+→ AI が回答を作成
+→ verify_citation で回答内の引用を自動検証
+→ 「第20条第1項第四号の引用が正確であることを確認しました」
+  または
+→ 「第20条第1項第三号の記載に誤りがあります。正しくは…」
+```
 
 ## 対応法令一覧（115 法令）
 
@@ -398,6 +501,31 @@ e-Gov API は告示を収録していないため、`get_kokuji` は国土交通
 - `check_law_updates` ツールで法令の改正状況を確認できます（e-Gov API のリビジョン履歴を参照）
 - 法令改正による `law_id` の無効化リスクは低い（`law_id` は法令番号ベースの固有識別子）
 
+## 環境変数
+
+| 変数                           | 説明                                              | デフォルト                   |
+| ------------------------------ | ------------------------------------------------- | ---------------------------- |
+| `BUILDING_LAW_CACHE`           | キャッシュモード（`memory` / `file`）             | `memory`                     |
+| `BUILDING_LAW_CACHE_DIR`       | ファイルキャッシュの保存先ディレクトリ            | `~/.cache/building-law-mcp/` |
+| `BUILDING_LAW_LOG_LEVEL`       | ログレベル（`debug` / `info` / `warn` / `error`） | `info`                       |
+| `BUILDING_LAW_REQUEST_TIMEOUT` | API リクエストタイムアウト（ミリ秒）              | `30000`                      |
+
+### 永続キャッシュの有効化
+
+```json
+{
+  "mcpServers": {
+    "building-law": {
+      "command": "npx",
+      "args": ["-y", "building-law-mcp"],
+      "env": {
+        "BUILDING_LAW_CACHE": "file"
+      }
+    }
+  }
+}
+```
+
 ## 技術仕様
 
 | 項目                         | 値                               |
@@ -410,7 +538,8 @@ e-Gov API は告示を収録していないため、`get_kokuji` は国土交通
 | 告示 PDF テキストキャッシュ  | 24 時間                          |
 | プリセット検証キャッシュ TTL | 7 日間                           |
 | リビジョン履歴キャッシュ TTL | 1 時間                           |
-| リクエストタイムアウト       | 30 秒                            |
+| リクエストタイムアウト       | 30 秒（環境変数で変更可能）      |
+| Vercel デプロイ              | 対応（MCP-over-HTTP + REST API） |
 | Node.js                      | >= 20.0.0                        |
 
 ## データソース

package/dist/index.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
+import { logger } from "./lib/logger.js";
 const server = createServer();
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("building-law-mcp Server running on stdio");
+    logger.info("server started", { transport: "stdio" });
 }
 main().catch((error) => {
     console.error("Fatal error:", error);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;AAE9B,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;AAC5D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;AAE9B,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;AACxD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lib/cache.d.ts

@@ -1,4 +1,18 @@
-export declare class TTLCache<T> {
+/**
+ * Common cache interface shared by all cache implementations.
+ */
+export interface ICache<T> {
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttl_ms?: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    readonly size: number;
+}
+/**
+ * In-memory TTL cache. Entries expire after a configurable duration.
+ */
+export declare class TTLCache<T> implements ICache<T> {
     private readonly store;
     private readonly default_ttl_ms;
     constructor(default_ttl_ms?: number);
@@ -9,3 +23,28 @@ export declare class TTLCache<T> {
     clear(): void;
     get size(): number;
 }
+/**
+ * File-based TTL cache. Entries persist across server restarts.
+ * Each key is stored as an individual JSON file under
+ * `~/.cache/building-law-mcp/{name}/{hash}.json`.
+ */
+export declare class FileCache<T> implements ICache<T> {
+    private readonly dir;
+    private readonly default_ttl_ms;
+    constructor(name: string, default_ttl_ms?: number);
+    private keyToPath;
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttl_ms?: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Factory function to create a cache instance based on the
+ * `BUILDING_LAW_CACHE` environment variable.
+ *
+ * - `"memory"` (default): in-memory TTLCache
+ * - `"file"`: file-based FileCache that persists across restarts
+ */
+export declare function createCache<T>(name: string, ttl_ms: number): ICache<T>;

package/dist/lib/cache.js

@@ -1,3 +1,10 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+/**
+ * In-memory TTL cache. Entries expire after a configurable duration.
+ */
 export class TTLCache {
     store = new Map();
     default_ttl_ms;
@@ -41,4 +48,124 @@ export class TTLCache {
         return this.store.size;
     }
 }
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), ".cache", "building-law-mcp");
+/**
+ * File-based TTL cache. Entries persist across server restarts.
+ * Each key is stored as an individual JSON file under
+ * `~/.cache/building-law-mcp/{name}/{hash}.json`.
+ */
+export class FileCache {
+    dir;
+    default_ttl_ms;
+    constructor(name, default_ttl_ms = 30 * 60 * 1000) {
+        this.default_ttl_ms = default_ttl_ms;
+        const cacheBase = process.env.BUILDING_LAW_CACHE_DIR ?? DEFAULT_CACHE_DIR;
+        this.dir = path.join(cacheBase, name);
+        fs.mkdirSync(this.dir, { recursive: true });
+    }
+    keyToPath(key) {
+        const hash = crypto.createHash("md5").update(key).digest("hex");
+        return path.join(this.dir, `${hash}.json`);
+    }
+    get(key) {
+        const filePath = this.keyToPath(key);
+        try {
+            const raw = fs.readFileSync(filePath, "utf-8");
+            const entry = JSON.parse(raw);
+            if (Date.now() > entry.expires_at) {
+                try {
+                    fs.unlinkSync(filePath);
+                }
+                catch {
+                    // ignore cleanup failure
+                }
+                return undefined;
+            }
+            return entry.value;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    set(key, value, ttl_ms) {
+        const ttl = ttl_ms ?? this.default_ttl_ms;
+        const entry = { value, expires_at: Date.now() + ttl };
+        fs.writeFileSync(this.keyToPath(key), JSON.stringify(entry), "utf-8");
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    delete(key) {
+        try {
+            fs.unlinkSync(this.keyToPath(key));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    clear() {
+        try {
+            const files = fs.readdirSync(this.dir);
+            for (const file of files) {
+                if (file.endsWith(".json")) {
+                    try {
+                        fs.unlinkSync(path.join(this.dir, file));
+                    }
+                    catch {
+                        // ignore individual file cleanup failure
+                    }
+                }
+            }
+        }
+        catch {
+            // directory might not exist
+        }
+    }
+    get size() {
+        try {
+            const files = fs.readdirSync(this.dir).filter((f) => f.endsWith(".json"));
+            let count = 0;
+            for (const file of files) {
+                const filePath = path.join(this.dir, file);
+                try {
+                    const raw = fs.readFileSync(filePath, "utf-8");
+                    const entry = JSON.parse(raw);
+                    if (Date.now() <= entry.expires_at) {
+                        count++;
+                    }
+                    else {
+                        try {
+                            fs.unlinkSync(filePath);
+                        }
+                        catch {
+                            // ignore cleanup failure
+                        }
+                    }
+                }
+                catch {
+                    // corrupted file, skip
+                }
+            }
+            return count;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+/**
+ * Factory function to create a cache instance based on the
+ * `BUILDING_LAW_CACHE` environment variable.
+ *
+ * - `"memory"` (default): in-memory TTLCache
+ * - `"file"`: file-based FileCache that persists across restarts
+ */
+export function createCache(name, ttl_ms) {
+    const mode = process.env.BUILDING_LAW_CACHE ?? "memory";
+    if (mode === "file") {
+        return new FileCache(name, ttl_ms);
+    }
+    return new TTLCache(ttl_ms);
+}
 //# sourceMappingURL=cache.js.map

package/dist/lib/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/lib/cache.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,QAAQ;IACF,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IACzC,cAAc,CAAS;IAExC,YAAY,iBAAyB,EAAE,GAAG,EAAE,GAAG,IAAI;QACjD,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ,EAAE,MAAe;QACxC,MAAM,GAAG,GAAG,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,KAAK;YACL,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,IAAI,IAAI;QACN,8BAA8B;QAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;gBAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/lib/cache.ts"],"names":[],"mappings":"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"}

package/dist/lib/egov-client.d.ts

@@ -1,4 +1,8 @@
 import type { EgovLawSearchResponse, EgovLawDataResponse, EgovLawRevisionsResponse } from "./types.js";
+/** Configure retry behavior (for testing only). */
+export declare function _setRetryOptions(opts: Partial<import("./resilience.js").RetryOptions>): void;
+/** Reset circuit breaker state (for testing only). */
+export declare function _resetCircuitBreaker(): void;
 /**
  * Search laws by title keyword.
  * Uses GET /api/2/laws?law_title={keyword}

package/dist/lib/egov-client.js

@@ -1,14 +1,28 @@
-import { TTLCache } from "./cache.js";
+import { createCache } from "./cache.js";
 import { EgovApiError } from "./errors.js";
+import { logger } from "./logger.js";
+import { recordApiCall, recordCacheHit } from "./metrics.js";
+import { withRetry, CircuitBreaker } from "./resilience.js";
 const BASE_URL = "https://laws.e-gov.go.jp/api/2";
 const SEARCH_CACHE_TTL = 30 * 60 * 1000; // 30 minutes
 const LAW_DATA_CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours
 const REVISIONS_CACHE_TTL = 60 * 60 * 1000; // 1 hour
-const REQUEST_TIMEOUT = 30_000; // 30 seconds
-const searchCache = new TTLCache(SEARCH_CACHE_TTL);
-const lawDataCache = new TTLCache(LAW_DATA_CACHE_TTL);
-const revisionsCache = new TTLCache(REVISIONS_CACHE_TTL);
-async function fetchJson(url) {
+const REQUEST_TIMEOUT = Number(process.env.BUILDING_LAW_REQUEST_TIMEOUT) || 30_000; // 30 seconds
+const searchCache = createCache("search", SEARCH_CACHE_TTL);
+const lawDataCache = createCache("law-data", LAW_DATA_CACHE_TTL);
+const revisionsCache = createCache("revisions", REVISIONS_CACHE_TTL);
+const circuitBreaker = new CircuitBreaker();
+// Retry options (configurable for testing)
+let retryOptions = {};
+/** Configure retry behavior (for testing only). */
+export function _setRetryOptions(opts) {
+    retryOptions = opts;
+}
+/** Reset circuit breaker state (for testing only). */
+export function _resetCircuitBreaker() {
+    circuitBreaker.reset();
+}
+async function fetchJsonRaw(url) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT);
     try {
@@ -36,6 +50,29 @@ async function fetchJson(url) {
         clearTimeout(timeout);
     }
 }
+/**
+ * Fetch JSON with retry and circuit breaker.
+ */
+async function fetchJson(url) {
+    const endpoint = url.replace(BASE_URL, "").split("?")[0];
+    const start = Date.now();
+    try {
+        const result = await circuitBreaker.execute(() => withRetry(() => fetchJsonRaw(url), retryOptions));
+        recordApiCall(endpoint, Date.now() - start, 200);
+        logger.debug("api call", { endpoint, ms: Date.now() - start });
+        return result;
+    }
+    catch (error) {
+        const status = error instanceof EgovApiError ? error.statusCode : undefined;
+        recordApiCall(endpoint, Date.now() - start, status);
+        logger.warn("api call failed", {
+            endpoint,
+            status,
+            ms: Date.now() - start,
+        });
+        throw error;
+    }
+}
 /**
  * Search laws by title keyword.
  * Uses GET /api/2/laws?law_title={keyword}
@@ -44,8 +81,10 @@ export async function searchLaws(lawTitle) {
     const cacheKey = `search:${lawTitle}`;
     const cached = searchCache.get(cacheKey);
     if (cached) {
+        recordCacheHit("search", true);
         return cached;
     }
+    recordCacheHit("search", false);
     const url = `${BASE_URL}/laws?law_title=${encodeURIComponent(lawTitle)}`;
     const result = await fetchJson(url);
     searchCache.set(cacheKey, result);
@@ -59,8 +98,10 @@ export async function getLawData(lawId) {
     const cacheKey = `law:${lawId}`;
     const cached = lawDataCache.get(cacheKey);
     if (cached) {
+        recordCacheHit("law-data", true);
         return cached;
     }
+    recordCacheHit("law-data", false);
     const url = `${BASE_URL}/law_data/${encodeURIComponent(lawId)}`;
     const result = await fetchJson(url);
     lawDataCache.set(cacheKey, result);
@@ -74,8 +115,10 @@ export async function getLawRevisions(lawId) {
     const cacheKey = `revisions:${lawId}`;
     const cached = revisionsCache.get(cacheKey);
     if (cached) {
+        recordCacheHit("revisions", true);
         return cached;
     }
+    recordCacheHit("revisions", false);
     const url = `${BASE_URL}/law_revisions/${encodeURIComponent(lawId)}`;
     const result = await fetchJson(url);
     revisionsCache.set(cacheKey, result);

package/dist/lib/egov-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"egov-client.js","sourceRoot":"","sources":["../../src/lib/egov-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"egov-client.js","sourceRoot":"","sources":["../../src/lib/egov-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAO5D,MAAM,QAAQ,GAAG,gCAAgC,CAAC;AAClD,MAAM,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,aAAa;AACtD,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW;AAC3D,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AACrD,MAAM,eAAe,GACnB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,IAAI,MAAM,CAAC,CAAC,aAAa;AAE3E,MAAM,WAAW,GAAG,WAAW,CAC7B,QAAQ,EACR,gBAAgB,CACjB,CAAC;AACF,MAAM,YAAY,GAAG,WAAW,CAC9B,UAAU,EACV,kBAAkB,CACnB,CAAC;AACF,MAAM,cAAc,GAAG,WAAW,CAChC,WAAW,EACX,mBAAmB,CACpB,CAAC;AAEF,MAAM,cAAc,GAAG,IAAI,cAAc,EAAE,CAAC;AAE5C,2CAA2C;AAC3C,IAAI,YAAY,GAAoD,EAAE,CAAC;AAEvE,mDAAmD;AACnD,MAAM,UAAU,gBAAgB,CAC9B,IAAqD;IAErD,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,oBAAoB;IAClC,cAAc,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC;AAED,KAAK,UAAU,YAAY,CAAI,GAAW;IACxC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,eAAe,CAAC,CAAC;IAEtE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,OAAO,EAAE;gBACP,MAAM,EAAE,kBAAkB;aAC3B;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,YAAY,CACpB,sBAAsB,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,UAAU,EAAE,EAC/D,QAAQ,CAAC,MAAM,EACf,GAAG,CACJ,CAAC;QACJ,CAAC;QAED,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAM,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;YAClC,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC1D,MAAM,IAAI,YAAY,CAAC,6BAA6B,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QACxE,CAAC;QACD,MAAM,IAAI,YAAY,CACpB,6BAA6B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EACrF,SAAS,EACT,GAAG,CACJ,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,SAAS,CAAI,GAAW;IACrC,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE,CAC/C,SAAS,CAAC,GAAG,EAAE,CAAC,YAAY,CAAI,GAAG,CAAC,EAAE,YAAY,CAAC,CACpD,CAAC;QACF,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,CAAC,CAAC;QACjD,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QAC/D,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5E,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,MAAM,CAAC,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE;YAC7B,QAAQ;YACR,MAAM;YACN,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;SACvB,CAAC,CAAC;QACH,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAgB;IAEhB,MAAM,QAAQ,GAAG,UAAU,QAAQ,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,MAAM,EAAE,CAAC;QACX,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAEhC,MAAM,GAAG,GAAG,GAAG,QAAQ,mBAAmB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAwB,GAAG,CAAC,CAAC;IAE3D,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAa;IAC5C,MAAM,QAAQ,GAAG,OAAO,KAAK,EAAE,CAAC;IAChC,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,MAAM,EAAE,CAAC;QACX,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACjC,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,cAAc,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAElC,MAAM,GAAG,GAAG,GAAG,QAAQ,aAAa,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;IAChE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAsB,GAAG,CAAC,CAAC;IAEzD,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAa;IAEb,MAAM,QAAQ,GAAG,aAAa,KAAK,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,MAAM,EAAE,CAAC;QACX,cAAc,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAClC,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,cAAc,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAEnC,MAAM,GAAG,GAAG,GAAG,QAAQ,kBAAkB,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;IACrE,MAAM,MAAM,GAAG,MAAM,SAAS,CAA2B,GAAG,CAAC,CAAC;IAE9D,cAAc,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACrC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/lib/logger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Structured JSON logger for MCP server.
+ * Outputs to stderr to avoid interfering with stdio MCP transport.
+ */
+export declare const logger: {
+    debug: (msg: string, data?: Record<string, unknown>) => void;
+    info: (msg: string, data?: Record<string, unknown>) => void;
+    warn: (msg: string, data?: Record<string, unknown>) => void;
+    error: (msg: string, data?: Record<string, unknown>) => void;
+};

package/dist/lib/logger.js

@@ -0,0 +1,41 @@
+/**
+ * Structured JSON logger for MCP server.
+ * Outputs to stderr to avoid interfering with stdio MCP transport.
+ */
+const LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function getMinLevel() {
+    const env = process.env.BUILDING_LAW_LOG_LEVEL?.toLowerCase();
+    if (env && env in LEVEL_ORDER) {
+        return env;
+    }
+    return "info";
+}
+function shouldLog(level) {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[getMinLevel()];
+}
+function emit(level, msg, data) {
+    if (!shouldLog(level)) {
+        return;
+    }
+    const entry = {
+        ts: new Date().toISOString(),
+        level,
+        msg,
+    };
+    if (data !== undefined) {
+        entry.data = data;
+    }
+    process.stderr.write(JSON.stringify(entry) + "\n");
+}
+export const logger = {
+    debug: (msg, data) => emit("debug", msg, data),
+    info: (msg, data) => emit("info", msg, data),
+    warn: (msg, data) => emit("warn", msg, data),
+    error: (msg, data) => emit("error", msg, data),
+};
+//# sourceMappingURL=logger.js.map

package/dist/lib/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,GAA6B;IAC5C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,SAAS,WAAW;IAClB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,WAAW,EAAE,CAAC;IAC9D,IAAI,GAAG,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,OAAO,GAAe,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,KAAe;IAChC,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,IAAI,CACX,KAAe,EACf,GAAW,EACX,IAA8B;IAE9B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO;IACT,CAAC;IACD,MAAM,KAAK,GAA4B;QACrC,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,KAAK;QACL,GAAG;KACJ,CAAC;IACF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;IACpB,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CACrD,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;IAC1B,IAAI,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CACpD,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;IACzB,IAAI,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CACpD,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;IACzB,KAAK,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CACrD,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;CAC3B,CAAC"}

package/dist/lib/metrics.d.ts

@@ -0,0 +1,14 @@
+/**
+ * In-memory metrics collector for tool calls, API requests, and cache hits.
+ * Resets on server restart (intentional — lightweight, no external deps).
+ */
+/** Record a tool call (duration in ms, success/failure). */
+export declare function recordToolCall(toolName: string, durationMs: number, success: boolean): void;
+/** Record an API call (duration in ms, HTTP status code). */
+export declare function recordApiCall(endpoint: string, durationMs: number, statusCode?: number): void;
+/** Record a cache hit or miss. */
+export declare function recordCacheHit(cacheName: string, hit: boolean): void;
+/** Return aggregated metrics snapshot. */
+export declare function getMetrics(): Record<string, unknown>;
+/** Reset all metrics (for testing). */
+export declare function _resetMetrics(): void;