@jurislm/judicial-mcp 1.2.6

package/.env.example

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

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# 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

@@ -0,0 +1,78 @@
+# 貢獻者行為準則
+
+## 我們的承諾
+
+為了營造一個開放且友善的環境，我們身為貢獻者和維護者承諾，無論年齡、體型、身心障礙、族群、性別認同與表達、經驗程度、教育程度、社會經濟地位、國籍、個人外觀、種族、宗教或性取向，參與我們專案和社群的每個人都能享有無騷擾的體驗。
+
+## 我們的標準
+
+有助於創造正面環境的行為範例包括：
+
+* 使用友善和包容的語言
+* 尊重不同的觀點和經驗
+* 優雅地接受建設性批評
+* 專注於對社群最有益的事情
+* 對其他社群成員展現同理心
+
+不能接受的參與者行為範例包括：
+
+* 使用與性有關的言語或圖像，以及令人不悦的性關注或性騷擾
+* 惡意攻擊、侮辱或貶損的評論，人身攻擊或政治攻擊
+* 公開或私下的騷擾
+* 未經明確許可，發佈他人的個人資料，例如住址或電子信箱
+* 其他可以被合理認定為不恰當或不專業的行為
+
+## 我們的責任
+
+專案維護者有責任為可接受的行為標準做出澄清，並且會對任何不當行為採取適當且公平的糾正措施。
+
+專案維護者有權力及責任去移除、編輯或拒絕與本行為準則不符的評論（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/LICENSE

@@ -0,0 +1,37 @@
+# MIT 授權條款
+
+版權所有 (c) 2025 Terry Chen
+
+特此免費授予任何取得本軟體及相關文件檔案（「軟體」）副本之人員，得不受限制地處置該軟體，包括但不限於使用、複製、修改、合併、發佈、散布、再授權及/或銷售軟體副本之權利；惟須符合以下條件：
+
+上述之版權聲明及本授權聲明應包含在本軟體之所有副本或主要部分中。
+
+本軟體係依「現況」提供，不提供任何形式之明示或暗示擔保，包括但不限於適售性、特定目的適用性及未侵害他人權利之擔保。於任何情況下，無論是契約訴訟、侵權行為或其他訴訟，作者或版權持有人均不承擔因本軟體或本軟體之使用或其他dealings軟體而產生、引起或與其相關之任何索賠、損害或其他責任。
+
+---
+
+## 關於此專案
+
+本專案（judicial-mcp）為開源軟體，專門提供存取台灣司法院開放資料和裁判書的 Model Context Protocol (MCP) 伺服器。
+
+### 使用條款補充說明
+
+1. **資料來源聲明**：本軟體僅提供存取司法院公開資料之介面，所有司法資料之版權歸屬於中華民國司法院。
+
+2. **合法使用**：使用者應遵守相關法律法規，不得將本軟體用於任何非法目的。
+
+3. **資料隱私**：在處理司法資料時，請特別注意個人隱私保護及相關資料保護法規。
+
+4. **免責聲明**：本軟體開發者不對司法院資料之準確性、完整性或時效性負責。
+
+### 貢獻與支援
+
+歡迎社群貢獻程式碼和回報問題。參與本專案前，請先閱讀 [行為準則](CODE_OF_CONDUCT.md)。
+
+如有技術問題或建議，請至 [GitHub Issues](https://github.com/terry90918/judicial-mcp/issues) 頁面回報。
+
+### 聯絡資訊
+
+- 作者：Terry Chen
+- 電子郵件：zxtw17985321@gmail.com
+- GitHub：https://github.com/terry90918/judicial-mcp

package/MCP_TUTORIAL.md

@@ -0,0 +1,83 @@
+# 司法院 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/README.md

@@ -0,0 +1,72 @@
+# @jurislm/judicial-mcp
+
+MCP (Model Context Protocol) server for [Taiwan Judicial Yuan](https://www.judicial.gov.tw) — provides 6 tools for accessing open data and judgments via natural language.
+
+## Tools
+
+### Authentication (1 tool)
+- `auth_token` — Get authorization token (uses `JUDICIAL_USER` / `JUDICIAL_PASSWORD` env vars by default)
+
+### Judgments (2 tools)
+- `list_judgments` — Get judgment change list (requires token)
+- `get_judgment` — Get judgment content by JID (requires token)
+
+### Open Data (3 tools)
+- `list_categories` — List topic categories
+- `list_resources` — List data sources for a category (requires `categoryNo`)
+- `download_file` — Download a data file with pagination support (requires `fileSetId`)
+
+## Setup
+
+### Environment Variables
+
+```bash
+JUDICIAL_USER=your_username
+JUDICIAL_PASSWORD=your_password
+```
+
+### Usage with Claude Code (via bunx)
+
+Add to your MCP configuration (`.mcp.json` or `~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "judicial": {
+      "command": "bunx",
+      "args": ["@jurislm/judicial-mcp@latest"],
+      "env": {
+        "JUDICIAL_USER": "your_username",
+        "JUDICIAL_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+### Usage with Claude Code Plugin (jurislm-tools)
+
+If you use the [jurislm-tools](https://github.com/jurislm/jurislm-tools) Claude Code plugin, `jt:judicial` is included:
+
+```
+/plugin marketplace update jurislm-tools
+```
+
+Then set environment variables in `~/.zshenv`:
+
+```bash
+export JUDICIAL_USER=your_username
+export JUDICIAL_PASSWORD=your_password
+```
+
+## Development
+
+```bash
+npm install
+npm test           # Run tests
+npm run lint       # oxlint
+```
+
+## License
+
+MIT

package/__tests__/mcp.test.js

@@ -0,0 +1,145 @@
+/**
+ * @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);
+    });
+  });
+});