@jurislm/judicial-mcp 1.2.6 → 1.6.2

package/types/tools.d.ts

@@ -0,0 +1,236 @@
+export interface TokenArgs {
+    token: string;
+}
+export interface GetJudgmentArgs {
+    token: string;
+    jid: string;
+}
+export interface ListResourcesArgs {
+    categoryNo: string;
+    token: string;
+}
+export interface DownloadFileArgs {
+    fileSetId: string;
+    token: string;
+    top?: number;
+    skip?: number;
+}
+export interface SearchJudgmentsArgs extends Record<string, unknown> {
+    keyword?: string;
+    court?: string;
+    year?: number;
+    caseNumber?: string;
+    limit?: number;
+    page?: number;
+    offset?: number;
+}
+export interface FetchJudgmentTextArgs extends Record<string, unknown> {
+    caseId: string;
+}
+export interface QueryRegulationArgs extends Record<string, unknown> {
+    lawName: string;
+    articleNumber: string;
+    refresh?: boolean;
+}
+export declare const TOOLS_CONFIG: {
+    readonly auth_token: {
+        readonly name: "auth_token";
+        readonly description: "取得司法院裁判書查詢系統的授權 Token。帳密從環境變數 JUDICIAL_USER / JUDICIAL_PASSWORD 讀取。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {};
+            readonly additionalProperties: false;
+        };
+    };
+    readonly list_judgments: {
+        readonly name: "list_judgments";
+        readonly description: "取得裁判書異動清單，包含新增、修改或刪除的裁判書資訊。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly token: {
+                    readonly type: "string";
+                    readonly description: "從 auth_token 工具取得的授權 Token";
+                };
+            };
+            readonly required: readonly ["token"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly get_judgment: {
+        readonly name: "get_judgment";
+        readonly description: "取得特定裁判書的完整內容，包含裁判全文。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly token: {
+                    readonly type: "string";
+                    readonly description: "從 auth_token 工具取得的授權 Token";
+                };
+                readonly jid: {
+                    readonly type: "string";
+                    readonly description: "從 list_judgments 工具取得的裁判書 ID";
+                };
+            };
+            readonly required: readonly ["token", "jid"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly list_categories: {
+        readonly name: "list_categories";
+        readonly description: "取得司法院開放資料平台的所有主題分類清單。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly token: {
+                    readonly type: "string";
+                    readonly description: "從 member_token 工具取得的會員授權 Token";
+                };
+            };
+            readonly required: readonly ["token"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly list_resources: {
+        readonly name: "list_resources";
+        readonly description: "取得指定分類下的所有資料源清單。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly categoryNo: {
+                    readonly type: "string";
+                    readonly description: "從 list_categories 工具取得的分類編號";
+                };
+                readonly token: {
+                    readonly type: "string";
+                    readonly description: "從 member_token 工具取得的會員授權 Token";
+                };
+            };
+            readonly required: readonly ["categoryNo", "token"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly download_file: {
+        readonly name: "download_file";
+        readonly description: "下載指定檔案集的資料檔案，支援分頁參數。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly fileSetId: {
+                    readonly type: "string";
+                    readonly description: "從 list_resources 工具取得的檔案集 ID";
+                };
+                readonly top: {
+                    readonly type: "integer";
+                    readonly description: "限制回傳筆數（可選）";
+                    readonly minimum: 0;
+                };
+                readonly skip: {
+                    readonly type: "integer";
+                    readonly description: "跳過筆數，用於分頁（可選）";
+                    readonly minimum: 0;
+                };
+                readonly token: {
+                    readonly type: "string";
+                    readonly description: "從 member_token 工具取得的會員授權 Token";
+                };
+            };
+            readonly required: readonly ["fileSetId", "token"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly member_token: {
+        readonly name: "member_token";
+        readonly description: "取得司法院開放平台的會員授權 Token，用於存取會員專屬資源。帳密從環境變數 JUDICIAL_USER / JUDICIAL_PASSWORD 讀取。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {};
+            readonly additionalProperties: false;
+        };
+    };
+    readonly search_judgments: {
+        readonly name: "search_judgments";
+        readonly description: "透過司法院公開裁判書查詢頁搜尋裁判，不需要授權 Token。year 可使用西元或民國年；完整案號可同時指定案類。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly keyword: {
+                    readonly type: "string";
+                    readonly description: "裁判全文關鍵字，最多 128 字元";
+                };
+                readonly court: {
+                    readonly type: "string";
+                    readonly description: "司法院法院名稱或官方法院代碼";
+                };
+                readonly year: {
+                    readonly type: "integer";
+                    readonly description: "裁判年度，可使用西元或民國年";
+                    readonly minimum: 1;
+                    readonly maximum: 9999;
+                };
+                readonly caseNumber: {
+                    readonly type: "string";
+                    readonly description: "案號數字，或「年度案類字第號」格式";
+                };
+                readonly limit: {
+                    readonly type: "integer";
+                    readonly description: "每頁最多回傳筆數，預設 5，上限 10";
+                    readonly minimum: 1;
+                    readonly maximum: 10;
+                };
+                readonly page: {
+                    readonly type: "integer";
+                    readonly description: "官方結果頁頁碼，預設 1，上限 50";
+                    readonly minimum: 1;
+                    readonly maximum: 50;
+                };
+                readonly offset: {
+                    readonly type: "integer";
+                    readonly description: "官方結果頁內的起始位置，預設 0，範圍 0–19；依回傳的 next_page 與 next_offset 繼續查詢";
+                    readonly minimum: 0;
+                    readonly maximum: 19;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+    };
+    readonly fetch_judgment_text: {
+        readonly name: "fetch_judgment_text";
+        readonly description: "依 search_judgments 回傳的 case_id 取得司法院公開裁判全文，不需要授權 Token。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly caseId: {
+                    readonly type: "string";
+                    readonly description: "search_judgments 回傳的 case_id";
+                };
+            };
+            readonly required: readonly ["caseId"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly query_regulation: {
+        readonly name: "query_regulation";
+        readonly description: "依官方法規名稱與條號查詢全國法規資料庫現行條文，回傳版本日期與官方來源；不提供歷史版本。";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly lawName: {
+                    readonly type: "string";
+                    readonly description: "法規名稱；若名稱不是唯一精確匹配，會回傳候選清單";
+                };
+                readonly articleNumber: {
+                    readonly type: "string";
+                    readonly description: "條號數字，可含連字號，例如 1 或 1-1";
+                };
+                readonly refresh: {
+                    readonly type: "boolean";
+                    readonly description: "設為 true 時略過快取並重新讀取官方來源";
+                };
+            };
+            readonly required: readonly ["lawName", "articleNumber"];
+            readonly additionalProperties: false;
+        };
+    };
+};
+export declare const TOOL_HANDLERS: Record<string, (_args: Record<string, unknown>) => Promise<unknown>>;

package/.env.example

@@ -1,7 +0,0 @@
-# 司法院裁判書查詢系統帳號設定
-# 請向司法院申請 API 存取權限並填入您的帳號密碼
-JUDICIAL_USER=your_username_here
-JUDICIAL_PASSWORD=your_password_here
-
-# 可選：伺服器端口號設定（僅適用於舊版 Express 伺服器）
-PORT=3000

package/CHANGELOG.md

@@ -1,67 +0,0 @@
-# Changelog
-
-## [1.2.1] - 2025-07-23
-### 改進
-- 達成 100% 測試覆蓋率 (46 tests, 278 lines covered)
-- 移除未使用的 Express 伺服器相關檔案和依賴
-- 修正所有 oxlint 警告，提升程式碼品質
-- 增強 MCP 配置測試，包含所有 7 個工具的完整驗證
-- 新增工具架構安全性驗證 (`additionalProperties: false`)
-
-### 移除
-- 刪除 `server.js`, `start.js` 及相關測試檔案
-- 清理 62 個未使用的 npm 套件依賴
-- 移除 Express.js 和 HTTP API 相關程式碼
-
----
-
-## [1.2.0] - 2025-07-22
-### 新增
-- TypeScript 類型定義檔案 (`types/index.d.ts`)
-- 輸入驗證功能
-- 測試覆蓋率腳本 (`test:coverage`)
-- 環境變數範例檔案 (`.env.example`)
-
-### 改進
-- 強化錯誤處理和日誌記錄
-- 新增 API 參數驗證機制
-
----
-
-## [1.1.1] - 2025-07-10
-### 修復
-- 修正版本號不一致的問題
-- 同步所有文件中的版本資訊
-
-### 改進
-- 優化專案版本管理流程
-
----
-
-## [1.1.0] - 2025-07-02
-### 新增
-- 增加對 `list_resources` 工具的完整支持，允許用戶根據分類編號檢索資料源。
-- 完善 `download_file` 工具，支持分頁參數 `top` 和 `skip`。
-
-### 改進
-- 優化 `auth_token` 工具的錯誤處理，提供更詳細的錯誤信息。
-- 更新測試覆蓋率，新增對 `list_resources` 和 `download_file` 工具的測試用例。
-- 改善 `README.md` 文檔，新增對新功能的使用說明。
-
-### 修復
-- 修正 `get_judgment` 工具在處理無效裁判書 ID 時的錯誤回應。
-- 修復環境變數未正確加載時的潛在問題。
-
----
-
-## [1.0.0] - 2025-06-30
-### ✨ 主要功能
-
-- 🏛️ **司法院裁判書 API** - 取得裁判書授權、清單和內容
-- 📊 **開放資料 API** - 存取司法院開放資料平台
-- 🔍 **分類資料** - 瀏覽主題分類和資料源
-- 📥 **檔案下載** - 下載司法資料檔案
-- 🧪 **完整測試** - Jest 測試覆蓋
-- 🔒 **安全認證** - 支援 Token 基礎認證
-- 📖 **完整文檔** - 詳細的 API 文檔和使用範例
-- ⚡ **高效能** - 基於 Express.js 框架，支援非同步處理

package/CODE_OF_CONDUCT.md

@@ -1,78 +0,0 @@
-# 貢獻者行為準則
-
-## 我們的承諾
-
-為了營造一個開放且友善的環境，我們身為貢獻者和維護者承諾，無論年齡、體型、身心障礙、族群、性別認同與表達、經驗程度、教育程度、社會經濟地位、國籍、個人外觀、種族、宗教或性取向，參與我們專案和社群的每個人都能享有無騷擾的體驗。
-
-## 我們的標準
-
-有助於創造正面環境的行為範例包括：
-
-* 使用友善和包容的語言
-* 尊重不同的觀點和經驗
-* 優雅地接受建設性批評
-* 專注於對社群最有益的事情
-* 對其他社群成員展現同理心
-
-不能接受的參與者行為範例包括：
-
-* 使用與性有關的言語或圖像，以及令人不悦的性關注或性騷擾
-* 惡意攻擊、侮辱或貶損的評論，人身攻擊或政治攻擊
-* 公開或私下的騷擾
-* 未經明確許可，發佈他人的個人資料，例如住址或電子信箱
-* 其他可以被合理認定為不恰當或不專業的行為
-
-## 我們的責任
-
-專案維護者有責任為可接受的行為標準做出澄清，並且會對任何不當行為採取適當且公平的糾正措施。
-
-專案維護者有權力及責任去移除、編輯或拒絕與本行為準則不符的評論（comments）、提交（commits）、程式碼、wiki 編輯、問題（issues）和其他貢獻，或暫時或永久禁止任何他們認為有不適當、威脅、冒犯或有害行為的貢獻者。
-
-## 適用範圍
-
-本行為準則適用於所有專案空間，也適用於個人在公共空間代表該專案或其社群的情況。代表專案或社群的例子包括使用官方專案的電子郵件地址、透過官方社群媒體帳號發文，或在線上或線下活動中擔任指定代表。專案的代表可由專案維護者進一步定義及澄清。
-
-## 執行
-
-若遇到濫用、騷擾或其他不當行為，可以透過 [zxtw17985321@gmail.com] 與專案團隊聯繫。所有投訴都會被審查及調查，並會依情況給予必要且適當的回應。專案團隊有義務為舉報者的隱私保密。具體執行政策的更多細節可能會單獨發佈。
-
-專案維護者若未能以誠信原則遵守或執行本行為準則，可能會面臨專案領導階層其他成員所決定的暫時或永久的影響。
-
-## 特定於司法院 MCP 專案的補充說明
-
-作為一個專注於台灣司法資料存取的開源專案，我們特別重視：
-
-### 法律資料的正確性和倫理使用
-
-* 貢獻者應確保所提供的程式碼和文件準確無誤
-* 尊重司法資料的隱私和敏感性
-* 遵守相關的法律法規和資料使用條款
-* 不得將本專案用於任何非法或不當目的
-
-### 技術討論的專業性
-
-* 在討論技術問題時保持專業和建設性的態度
-* 提供清晰的問題描述和重現步驟
-* 尊重不同的技術觀點和解決方案
-* 鼓勵學習和知識分享
-
-### 社群參與
-
-* 歡迎各種背景的開發者參與貢獻
-* 提供中文和英文的雙語支援
-* 協助新手理解專案架構和貢獻流程
-* 分享使用案例和最佳實踐
-
-## 歸屬
-
-本行為準則改編自 [Contributor Covenant][homepage] 2.1 版，可於 [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1] 取得。
-
-社群影響指引的靈感來自 [Mozilla's code of conduct enforcement ladder][Mozilla CoC]。
-
-關於本行為準則的常見問題，請參閱 [https://www.contributor-covenant.org/faq][FAQ]。翻譯可於 [https://www.contributor-covenant.org/translations][translations] 取得。
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations

package/MCP_TUTORIAL.md

@@ -1,83 +0,0 @@
-# 司法院 MCP 伺服器教學
-
-## 概述
-
-司法院 MCP 伺服器讓 AI 助手透過 Model Context Protocol 存取台灣司法院的開放資料和裁判書。
-
-## 快速開始
-
-### 安裝
-```bash
-npm install judicial-mcp
-```
-
-### 環境設定
-```bash
-cp .env.example .env
-# 編輯 .env 設定司法院帳號密碼
-JUDICIAL_USER=your_username
-JUDICIAL_PASSWORD=your_password
-```
-
-## MCP 客戶端配置
-
-### Claude Desktop
-```json
-{
-  "mcpServers": {
-    "judicial-mcp": {
-      "command": "npx",
-      "args": ["-y", "judicial-mcp@latest"],
-      "env": {
-        "JUDICIAL_USER": "your_username",
-        "JUDICIAL_PASSWORD": "your_password"
-      }
-    }
-  }
-}
-```
-
-## 可用工具
-
-### 裁判書開放
-- `auth_token` - 驗證權限（服務時間：00:00~06:00）
-- `list_judgments` - 取得裁判書異動清單
-- `get_judgment` - 取得裁判書內容
-
-### 開放平台
-- `list_categories` - 取得主題分類清單
-- `list_resources` - 取得資料源清單
-- `download_file` - 下載資料檔案（支援分頁）
-- `member_token` - 取得會員授權 Token
-
-## 使用流程
-
-### 裁判書開放查詢
-1. `auth_token` → 驗證權限
-2. `list_judgments` → 取得異動清單
-3. `get_judgment` → 取得裁判書內容
-
-### 開放平台查詢
-1. `member_token` → 取得會員授權 Token
-2. `list_categories` → 取得主題分類
-3. `list_resources` → 取得資料源
-4. `download_file` → 下載資料檔案
-
-## 常見問題
-
-**Q: 授權失敗**
-A: 確認司法院帳號密碼正確，檢查環境變數設定
-
-**Q: 服務時間限制** 
-A: `auth_token` 僅在 00:00~06:00 提供服務
-
-**Q: 大檔案處理**
-A: `download_file` 工具會將檔案轉為 base64 格式回傳
-
-## 開發命令
-
-```bash
-npm start      # 啟動伺服器
-npm test       # 執行測試
-npm run lint   # 程式碼檢查
-```

package/__tests__/mcp.test.js

@@ -1,145 +0,0 @@
-/**
- * @file __tests__/mcp.test.js
- * @description MCP 伺服器功能測試
- */
-
-const { TOOLS_CONFIG, TOOL_HANDLERS } = require('../src/tools');
-
-describe('MCP 伺服器測試', () => {
-  describe('工具配置', () => {
-    test('所有工具都有必要的屬性', () => {
-      const tools = Object.values(TOOLS_CONFIG);
-      
-      tools.forEach(tool => {
-        expect(tool).toHaveProperty('name');
-        expect(tool).toHaveProperty('description');
-        expect(tool).toHaveProperty('inputSchema');
-        expect(tool.inputSchema).toHaveProperty('type');
-        expect(tool.inputSchema.type).toBe('object');
-      });
-    });
-
-    test('工具名稱唯一性', () => {
-      const tools = Object.values(TOOLS_CONFIG);
-      const names = tools.map(tool => tool.name);
-      const uniqueNames = [...new Set(names)];
-      
-      expect(names.length).toBe(uniqueNames.length);
-    });
-
-    test('所有工具都有對應的處理器', () => {
-      const toolNames = Object.keys(TOOLS_CONFIG);
-      const handlerNames = Object.keys(TOOL_HANDLERS);
-      
-      expect(toolNames.sort()).toEqual(handlerNames.sort());
-    });
-
-    test('所有工具都禁止額外屬性', () => {
-      const tools = Object.values(TOOLS_CONFIG);
-      
-      tools.forEach(tool => {
-        expect(tool.inputSchema.additionalProperties).toBe(false);
-      });
-    });
-  });
-
-  describe('工具處理器', () => {
-    test('list_categories 處理器存在', () => {
-      expect(TOOL_HANDLERS.list_categories).toBeDefined();
-      expect(typeof TOOL_HANDLERS.list_categories).toBe('function');
-    });
-
-    test('auth_token 處理器參數驗證', async () => {
-      // 測試缺少環境變數時的行為
-      const originalUser = process.env.JUDICIAL_USER;
-      const originalPassword = process.env.JUDICIAL_PASSWORD;
-      
-      delete process.env.JUDICIAL_USER;
-      delete process.env.JUDICIAL_PASSWORD;
-      
-      await expect(TOOL_HANDLERS.auth_token({}))
-        .rejects
-        .toThrow('未提供使用者帳號或密碼');
-      
-      // 恢復環境變數
-      if (originalUser) process.env.JUDICIAL_USER = originalUser;
-      if (originalPassword) process.env.JUDICIAL_PASSWORD = originalPassword;
-    });
-  });
-
-  describe('工具配置驗證', () => {
-    test('auth_token 工具配置正確', () => {
-      const tool = TOOLS_CONFIG.auth_token;
-      
-      expect(tool.name).toBe('auth_token');
-      expect(tool.inputSchema.properties).toHaveProperty('user');
-      expect(tool.inputSchema.properties).toHaveProperty('password');
-      expect(tool.inputSchema.required).toBeUndefined(); // 因為有預設值
-    });
-
-    test('list_judgments 工具配置正確', () => {
-      const tool = TOOLS_CONFIG.list_judgments;
-      
-      expect(tool.name).toBe('list_judgments');
-      expect(tool.inputSchema.properties).toHaveProperty('token');
-      expect(tool.inputSchema.required).toContain('token');
-    });
-
-    test('get_judgment 工具配置正確', () => {
-      const tool = TOOLS_CONFIG.get_judgment;
-      
-      expect(tool.name).toBe('get_judgment');
-      expect(tool.inputSchema.properties).toHaveProperty('token');
-      expect(tool.inputSchema.properties).toHaveProperty('jid');
-      expect(tool.inputSchema.required).toContain('token');
-      expect(tool.inputSchema.required).toContain('jid');
-    });
-
-    test('download_file 工具配置正確', () => {
-      const tool = TOOLS_CONFIG.download_file;
-      
-      expect(tool.name).toBe('download_file');
-      expect(tool.inputSchema.properties).toHaveProperty('fileSetId');
-      expect(tool.inputSchema.properties).toHaveProperty('top');
-      expect(tool.inputSchema.properties).toHaveProperty('skip');
-      expect(tool.inputSchema.properties).toHaveProperty('token');
-      expect(tool.inputSchema.required).toEqual(['fileSetId', 'token']);
-      expect(tool.inputSchema.properties.top.pattern).toBe('^[0-9]+$');
-      expect(tool.inputSchema.properties.skip.pattern).toBe('^[0-9]+$');
-    });
-
-    test('list_categories 工具配置正確', () => {
-      const tool = TOOLS_CONFIG.list_categories;
-      
-      expect(tool.name).toBe('list_categories');
-      expect(tool.inputSchema.properties).toEqual({
-        token: {
-          type: 'string',
-          description: '從 member_token 工具取得的會員授權 Token'
-        }
-      });
-      expect(tool.inputSchema.required).toEqual(['token']);
-      expect(tool.inputSchema.additionalProperties).toBe(false);
-    });
-
-    test('list_resources 工具配置正確', () => {
-      const tool = TOOLS_CONFIG.list_resources;
-      
-      expect(tool.name).toBe('list_resources');
-      expect(tool.inputSchema.properties).toHaveProperty('categoryNo');
-      expect(tool.inputSchema.properties).toHaveProperty('token');
-      expect(tool.inputSchema.required).toEqual(['categoryNo', 'token']);
-      expect(tool.inputSchema.additionalProperties).toBe(false);
-    });
-
-    test('member_token 工具配置正確', () => {
-      const tool = TOOLS_CONFIG.member_token;
-      
-      expect(tool.name).toBe('member_token');
-      expect(tool.inputSchema.properties).toHaveProperty('user');
-      expect(tool.inputSchema.properties).toHaveProperty('password');
-      expect(tool.inputSchema.required).toBeUndefined(); // 因為有預設值
-      expect(tool.inputSchema.additionalProperties).toBe(false);
-    });
-  });
-});