ZoEasy Product Documents MCP Server

基於 Model Context Protocol (MCP) 的保險產品文件搜尋服務，為 AI 助手提供智慧化的產品文件檢索能力。

快速開始

安裝

yarn install
yarn build

設定環境變數

建立 .env 檔案：

ZOEASY_API_ENDPOINT=http://localhost:8000/api
ZOEASY_API_KEY=your-tools-api-key-here
REQUEST_TIMEOUT=30000

# Optional: Tag filters (server-locked, comma-separated slugs)
# ZOEASY_REQUIRE_TAGS=travel-insurance
# ZOEASY_EXCLUDE_TAGS=annual-plan,group-plan

命令行參數配置

除了環境變數，您也可以通過命令行參數進行配置（優先級高於環境變數）：

# 使用長參數
yarn start -- --api-key your-api-key --api-endpoint http://localhost:8000/api

# 使用短參數
yarn start -- -k your-api-key -e http://localhost:8000/api

# 設置超時時間（毫秒）
yarn start -- -k your-api-key -t 60000

支持的參數：

• --api-endpoint 或 -e：API 端點地址
• --api-key 或 -k：API 密鑰（必需）
• --timeout 或 -t：請求超時時間（毫秒，預設 30000）
• --require-tags：必填標籤過濾（AND，逗號分隔，伺服器端鎖定）
• --exclude-tags：排除標籤過濾（NOT，逗號分隔，伺服器端鎖定）

配置優先級： 命令行參數 > 環境變數 > .env 檔案

V2 API 參數映射

本 MCP Server 使用 V2 API endpoint (/product/tools/v2/product-docs/search)，支援三種標籤過濾：

| MCP Tool 輸入 | V2 API 參數 | 過濾邏輯 | 說明 | |---------------|-------------|----------|------| | slug（每次動態傳入） | include | OR | 轉為單元素陣列，任一符合即納入 | | ZOEASY_REQUIRE_TAGS（env/CLI 鎖定） | require | AND | 伺服器端鎖定，全部符合才納入 | | ZOEASY_EXCLUDE_TAGS（env/CLI 鎖定） | exclude | NOT | 伺服器端鎖定，排除符合項目 |

可用工具 (Available Tools)

本 MCP Server 提供以下 6 個工具：

| 工具名稱 | 說明 | |---------|------| | search_product_documents | 跨類別搜尋產品文件（V2 API，支援標籤過濾） | | list_product_slug | 列出所有產品類別（slug、title、examples） | | quotation_gzgplus | 取得【易起行+】旅遊保險計劃的保費報價 | | quotation_home_choice | 取得家居保險計劃的保費報價 | | quotation_studysmartplus | 取得【StudySmart+】留學保險計劃的保費報價 | | quotation_live2play | 取得【Live2Play】保險計劃的保費報價 |

執行

yarn start

本機測試

yarn test:inspector

AI 客戶端設定

Claude Code

在專案根目錄建立或編輯 .mcp.json：

方式 1：使用環境變數

{
  "mcpServers": {
    "zoeasy-product-documents": {
      "command": "npx",
      "args": ["-y", "@mixmediahk/zoeasy-mcp"],
      "env": {
        "ZOEASY_API_ENDPOINT": "http://localhost:8000/api",
        "ZOEASY_API_KEY": "your-api-key-here"
      }
    }
  }
}

方式 2：使用命令行參數

{
  "mcpServers": {
    "zoeasy-product-documents": {
      "command": "npx",
      "args": [
        "-y",
        "@mixmediahk/zoeasy-mcp",
        "--api-key",
        "your-api-key-here",
        "--api-endpoint",
        "http://localhost:8000/api"
      ]
    }
  }
}

OpenCode

在 OpenCode 設定檔中（如 .opencode/mcp.json），注意欄位有所不同：

方式 1：使用環境變數

{
  "mcp": {
    "zoeasy-product-documents": {
      "type": "local",
      "command": ["npx", "-y", "@mixmediahk/zoeasy-mcp"],
      "enabled": true,
      "environment": {
        "ZOEASY_API_ENDPOINT": "http://localhost:8000/api",
        "ZOEASY_API_KEY": "your-api-key-here"
      }
    }
  }
}

方式 2：使用命令行參數

{
  "mcp": {
    "zoeasy-product-documents": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@mixmediahk/zoeasy-mcp",
        "--api-key",
        "your-api-key-here",
        "--api-endpoint",
        "http://localhost:8000/api"
      ],
      "enabled": true
    }
  }
}

開發

# 開發模式（監聽檔案變化）
yarn dev

# 建構生產版本
yarn build

授權

Apache-2.0