Skip to main content
Glama
WeDaka MCP Server

WeDaka MCP Server

by keith-hung

WeDaka MCP Server - TypeScript Implementation

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

功能特色

  • 免登入設計: 使用環境變數直接認證,無需登入流程

  • 上班打卡: 記錄員工上班時間,支援備註功能和指定日期時間

  • 下班打卡: 記錄員工下班時間,支援備註功能和指定日期時間

  • 工時查詢: 查詢指定月份的所有打卡記錄

  • 補打卡功能: 支援往回補打過去日期的打卡記錄

  • 工作日檢查: 自動檢查日期是否為工作日,防止在假日或非工作日打卡(DateType "1": 工作日、"2": 休假日、"3": 例假日)

  • 未來日期保護: 禁止為未來日期打卡,只能為今天或過去的日期打卡

Related MCP server: Timesheet MCP Server

安裝方式

方式一:從 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"
      }
    }
  }
}

注意事項:

  1. 將上述設定中的環境變數替換為實際值

  2. 重新啟動 Claude Desktop 或 VSCode 以載入設定

  3. 首次執行時 npx 會自動從 GitHub 下載並安裝專案

  4. 確保使用 Node.js 20.0.0 或更高版本

可用的 MCP Tools

本系統提供以下 MCP tools:

  • wedaka_clock_in - 上班打卡

  • wedaka_clock_out - 下班打卡

  • wedaka_get_timelog - 查詢工時記錄

  • wedaka_check_work_day - 檢查工作日

Time Log 資料結構

wedaka_get_timelog 回傳的每筆記錄包含以下重要欄位:

WorkItem (記錄類型)

數值

意義

說明

'1'

上班打卡

員工開始工作的時間記錄

'2'

請假

員工全天請假

'4'

下班打卡

員工結束工作的時間記錄

重要:當 WorkItem = '2' 時,表示員工當天全天請假(不會有打卡時間記錄)。

DateType (日期類型)

數值

意義

'1'

工作日

'2'

休假日

'3'

例假日

其他欄位

  • WorkTime: 打卡時間 (格式: YYYY/MM/DD HH:MM:SS,請假記錄時為 null)

  • WorkDate: 打卡日期

  • Memo: 備註

  • LeaveHours: 請假時數 (此欄位可能為 0 或 null,不代表實際請假時數)

更多詳細資料結構說明請參考 DEVELOPMENT.md。

專案結構

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

Available Tools

4 tools
wedaka_check_work_dayA

Check if a specific date is a work day. Returns the date type: 1=work day, 2=holiday, 3=weekend.

Inputs: date (required).

wedaka_clock_inA

Clock in (上班打卡). Records the start of work for an employee. Supports custom date/time for retroactive entries.

Inputs: note, clock_date, clock_time.

wedaka_clock_outA

Clock out (下班打卡). Records the end of work for an employee. Supports custom date/time for retroactive entries.

Inputs: note, clock_date, clock_time.

wedaka_get_timelogA

Get employee time log records for a specific month. Returns clock-in/out times, leave records, and work day information.

Inputs: year (required), month (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct action (clock in, clock out, view logs, check work day) with no overlapping purposes. Descriptions clearly differentiate the functions.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with the wedaka_ prefix, making the API predictable and easy to navigate.

    Tool Count5/5

    4 tools is well-scoped for a time-tracking server, covering essential operations without unnecessary bloat or missing core actions.

    Completeness5/5

    The set covers the full clocking lifecycle: clock in, clock out, log retrieval, and work-day checking. While leave management appears in timelog data, it may be outside the server's intended scope.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers