@jurislm/judicial-mcp 1.3.0 → 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/bin/judicial-mcp.js

@@ -1,18 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * @file judicial-mcp.js
- * @description 司法院 MCP 伺服器的命令列介面 (CLI) 入口點
- * 此檔案作為全域安裝時的可執行檔案，直接啟動伺服器
- */
-
-/**
- * 引入並執行 MCP 伺服器
- * 直接載入 src/index.js 來啟動 MCP 伺服器
- * 
- * 使用方式：
- * - 全域安裝後：judicial-mcp
- * - 或直接執行：node bin/judicial-mcp.js
- * - MCP 客戶端連接：透過 stdio 傳輸協定
- */
-require('../src/index.js');

package/src/index.js

@@ -1,76 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * @file src/index.js
- * @description 司法院 MCP 伺服器 - 遵循 Model Context Protocol 規範
- */
-
-const originalConsole = { ...console };
-console.log = console.info = console.warn = () => {};
-try {
-  require('dotenv').config();
-} finally {
-  Object.assign(console, originalConsole);
-}
-const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const { CallToolRequestSchema, ListToolsRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
-const { TOOLS_CONFIG, TOOL_HANDLERS } = require('./tools.js');
-const { createSuccessResponse, createErrorResponse } = require('./response.js');
-const { version } = require('../package.json');
-
-/**
- * MCP 伺服器實例
- */
-const server = new Server(
-  {
-    name: 'judicial-mcp',
-    version,
-  },
-  {
-    capabilities: {
-      tools: {},
-    },
-  }
-);
-
-/**
- * 列出所有可用的工具
- */
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: Object.values(TOOLS_CONFIG),
-  };
-});
-
-/**
- * 處理工具調用請求
- */
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  try {
-    if (!TOOL_HANDLERS[name]) {
-      throw new Error(`未知的工具: ${name}`);
-    }
-
-    const result = await TOOL_HANDLERS[name](args || {});
-    return createSuccessResponse(result);
-  } catch (error) {
-    console.error(`執行工具 ${name} 時發生錯誤:`, error?.message);
-    return createErrorResponse(error, `執行工具 ${name} 時發生錯誤`);
-  }
-});
-
-/**
- * 啟動 MCP 伺服器
- */
-async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}
-
-main().catch((error) => {
-  console.error('伺服器啟動失敗:', error);
-  process.exit(1);
-});

package/src/response.js

@@ -1,44 +0,0 @@
-/**
- * @file src/response.js
- * @description MCP 規範回應格式工具函數
- *
- * MCP spec: CallToolResult = { content: ContentBlock[], isError?: boolean }
- * - 成功：isError 省略（預設 false）
- * - 失敗：isError: true，讓 client 能分辨工具錯誤與成功回應
- */
-
-/**
- * 建立成功的 MCP 工具回應
- * @param {*} data - 回傳的資料（會序列化為 JSON）
- * @returns {Object} MCP CallToolResult
- */
-const createSuccessResponse = (data) => ({
-  content: [
-    {
-      type: 'text',
-      text: JSON.stringify(data, null, 2),
-    },
-  ],
-});
-
-/**
- * 建立失敗的 MCP 工具回應
- * MCP 規範要求錯誤回應必須包含 isError: true
- * @param {Error|Object} error - 錯誤物件
- * @param {string} message - 錯誤描述
- * @returns {Object} MCP CallToolResult with isError: true
- */
-const createErrorResponse = (error, message) => {
-  const detail = error?.response?.data ?? error?.message ?? String(error);
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({ error: message, detail }, null, 2),
-      },
-    ],
-    isError: true,
-  };
-};
-
-module.exports = { createSuccessResponse, createErrorResponse };