WeDaka MCP Server - TypeScript Implementation

WeDaka MCP Server 的 TypeScript 實作版本，提供員工打卡系統的 Model Context Protocol (MCP) 伺服器功能。

功能特色

免登入設計: 使用環境變數直接認證，無需登入流程
上班打卡: 記錄員工上班時間，支援備註功能和指定日期時間
下班打卡: 記錄員工下班時間，支援備註功能和指定日期時間
工時查詢: 查詢指定月份的所有打卡記錄
補打卡功能: 支援往回補打過去日期的打卡記錄
工作日檢查: 自動檢查日期是否為工作日，防止在假日或非工作日打卡（DateType "1": 工作日、"2": 休假日、"3": 例假日）
未來日期保護: 禁止為未來日期打卡，只能為今天或過去的日期打卡

安裝方式

方式一：從 GitHub 直接安裝（推薦）

# 複製專案並安裝依賴
git clone git@github.com:keith-hung/WeDaka-MCP.git
cd WeDaka-MCP
npm install
npm run build

方式二：本地開發安裝

如果您已經有專案檔案：

# 安裝依賴
npm install

# 編譯 TypeScript
npm run build

前置需求

Node.js 20.0.0+
Git（用於從 GitHub 安裝）
npm 或 yarn

環境變數設定

使用前需要設定以下環境變數：

export WEDAKA_API_URL="https://your-wedaka-server.com"
export WEDAKA_USERNAME="your-ad-account"
export WEDAKA_DEVICE_ID="your-device-uuid"
export WEDAKA_EMP_NO="your-employee-number"

開發腳本

# 編譯 TypeScript
npx tsc

# 開發模式運行
npx tsx src/server.ts

# 運行編譯後的程式
node dist/server.js

# 執行測試
npx jest

# 程式碼檢查
npx eslint src/**/*.ts

# 程式碼格式化
npx prettier --write src/**/*.ts

MCP 客戶端設定

Claude Desktop

在 claude_desktop_config.json 中加入：

{
  "mcpServers": {
    "wedaka": {
      "command": "npx",
      "args": ["-y", "git+https://github.com/keith-hung/WeDaka-MCP.git"],
      "env": {
        "WEDAKA_API_URL": "https://your-wedaka-server.com",
        "WEDAKA_USERNAME": "your-ad-account",
        "WEDAKA_DEVICE_ID": "your-device-uuid",
        "WEDAKA_EMP_NO": "your-employee-number"
      }
    }
  }
}

VSCode

在 .vscode/settings.json 中加入：

{
  "mcp.servers": {
    "wedaka": {
      "command": "npx",
      "args": ["-y", "git+https://github.com/keith-hung/WeDaka-MCP.git"],
      "env": {
        "WEDAKA_API_URL": "https://your-wedaka-server.com",
        "WEDAKA_USERNAME": "your-ad-account",
        "WEDAKA_DEVICE_ID": "your-device-uuid",
        "WEDAKA_EMP_NO": "your-employee-number"
      }
    }
  }
}

注意事項：

將上述設定中的環境變數替換為實際值
重新啟動 Claude Desktop 或 VSCode 以載入設定
首次執行時 npx 會自動從 GitHub 下載並安裝專案
確保使用 Node.js 20.0.0 或更高版本

可用的 MCP Tools

本系統提供以下 MCP tools：

wedaka_clock_in - 上班打卡
wedaka_clock_out - 下班打卡
wedaka_get_timelog - 查詢工時記錄
wedaka_check_work_day - 檢查工作日

專案結構

typescript/
├── src/
│   ├── types/           # TypeScript 類型定義
│   ├── models/          # Zod 驗證模型
│   ├── client/          # API 客戶端
│   ├── server/          # MCP 伺服器實作
│   ├── __tests__/       # 測試檔案
│   └── server.ts        # 主要入口點
├── dist/                # 編譯輸出目錄
├── jest.config.js       # Jest 測試設定
├── tsconfig.json        # TypeScript 設定
├── .eslintrc.js         # ESLint 設定
├── .prettierrc          # Prettier 設定
└── package.json         # 專案設定

技術棧

TypeScript: 型別安全的 JavaScript
Zod: 執行時型別驗證
Axios: HTTP 客戶端
@modelcontextprotocol/sdk: MCP SDK
Jest: 測試框架
ESLint: 程式碼檢查
Prettier: 程式碼格式化

開發指南

程式碼風格

使用 TypeScript 嚴格模式
遵循 ESLint 和 Prettier 規則
使用 Zod 進行資料驗證
採用 async/await 處理異步操作

測試

# 執行所有測試
npx jest

# 執行特定測試檔案
npx jest src/__tests__/WedakaApiClient.test.ts

# 執行測試並生成覆蓋率報告
npx jest --coverage

程式碼品質

# 檢查程式碼風格
npx eslint src/**/*.ts

# 自動修復可修復的問題
npx eslint src/**/*.ts --fix

# 格式化程式碼
npx prettier --write src/**/*.ts

授權

MIT License

MCP Servers