Kwalee Attendance MCP

Kwalee考勤MCP服务器

A. 模型上下文协议 （MCP）服务器，与SpectraESS考勤系统集成，使克劳德等人工智能助手能够获取考勤记录并管理假期/休假。

特性

• 考勤跟踪：获取考勤记录，包括详细的打卡时间
• 休假管理：添加和管理公司假期、病假和事假
• 日期范围查询：检索特定时期的出勤和休假记录
• 身份验证缓存：具有1小时缓存的自动会话管理
• 结构化存储：用于高效数据组织的月度JSON文件
• 实用工具：获取时间戳操作的当前UTC日期时间

快速开始

先决条件

• Node.js>=24.12.0
• 访问SpectraESS考勤系统
• SpectraESS凭据（主机URL、员工ID、密码）

安装

# Clone the repository
git clone 
cd kwalee-attendance-mcp

# Install dependencies
npm install

# Create environment configuration
cp .env.example .env

配置

编辑 .env 使用您的SpectraESS凭据：

SPECTRA_ESS_HOST=https://your-spectra-server.com
SPECTRA_ESS_USERNAME=your-employee-id
SPECTRA_ESS_PASSWORD=your-password
LOG_LEVEL=info

运行服务器

# Development mode (with auto-reload)
npm run dev

# Production mode
npm run build
npm start

MCP工具

服务器提供6个MCP工具用于考勤管理和实用程序：

1. get_checkins

获取某个日期范围的考勤记录。

参数：

• startDate （字符串）：ISO格式的开始日期（YYYY-MM-DD）
• endDate （字符串）：ISO格式的结束日期（YYYY-MM-DD）
• includeDetails （布尔值，可选）：包括详细的打孔记录

例子：

{
  "startDate": "2025-12-01",
  "endDate": "2025-12-31",
  "includeDetails": true
}

2. add_holiday

添加公司假期或休假记录。

参数：

• date （字符串）：ISO格式的日期（YYYY-MM-DD）
• type （string）：其中之一 company_holiday, sick_leave, casual_leave
• duration （数字）：0.25、0.5、0.75或1.0
• reason （字符串，可选）：描述

例子：

{
  "date": "2025-12-25",
  "type": "company_holiday",
  "duration": 1.0,
  "reason": "Christmas Day"
}

3. add_leave

添加病假或事假记录（别名 add_holiday).

参数：

• date （字符串）：ISO格式的日期（YYYY-MM-DD）
• type （字符串）： sick_leave 或 casual_leave
• duration （数字）：0.25、0.5、0.75或1.0
• reason （字符串，可选）：描述

4. get_holidays_and_leaves

检索日期范围内的所有假期和休假。

参数：

• startDate （字符串）：ISO格式的开始日期（YYYY-MM-DD）
• endDate （字符串）：ISO格式的结束日期（YYYY-MM-DD）

5. delete_holiday_or_leave

按UUID删除假期或休假记录。

参数：

• uuid （string）：要删除的记录的UUID

6. get_current_utc_datetime

以ISO 8601格式的字符串获取UTC中的当前日期和时间。

参数： 无

示例响应：

{
  "success": true,
  "utc_datetime": "2025-12-29T10:30:45.123Z"
}

与Claude Desktop一起使用

将此配置添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kwalee-attendance": {
      "command": "node",
      "args": ["/path/to/kwalee-attendance-mcp/dist/index.js"],
      "env": {
        "SPECTRA_ESS_HOST": "https://your-spectra-server.com",
        "SPECTRA_ESS_USERNAME": "your-employee-id",
        "SPECTRA_ESS_PASSWORD": "your-password"
      }
    }
  }
}

重新启动Claude Desktop，这些工具将在您的对话中可用。

发展

项目结构

kwalee-attendance-mcp/
├── src/
│   ├── index.ts         # MCP server and tool definitions
│   ├── spectra.ts       # SpectraESS API client
│   ├── storage.ts       # File-based storage for holidays/leaves
│   ├── logger.ts        # Winston logger configuration
│   └── utils.ts         # Utility functions
├── test/
│   ├── e2e/             # End-to-end tests (19 tests)
│   ├── integration/     # Integration tests (15 tests)
│   ├── spectra.test.ts  # Unit tests for API client
│   └── storage.test.ts  # Unit tests for storage
├── docs/                # Additional documentation
├── data/                # Runtime data (auth cache, holidays)
└── logs/                # Application logs

脚本

# Development
npm run dev              # Start with auto-reload
npm run logs             # Tail logs with pretty formatting

# Building
npm run build            # Compile TypeScript to dist/
npm run type-check       # Run TypeScript compiler without emitting

# Code Quality
npm run lint             # Run ESLint
npm run test             # Run all tests
npm run test:unit        # Run unit tests only (~40 tests, <1s)
npm run test:integration # Run integration tests (~15 tests, 10-30s)
npm run test:e2e         # Run E2E tests (19 tests, 30-90s)
npm run test:watch       # Watch mode for unit tests

测试

该项目在三个层面上具有全面的测试覆盖率：

• 单元测试（40次测试）：纯函数和数据结构的快速测试
• 集成测试（15项测试）：对SpectraESS的真实API调用
• E2E测试（19项测试）：通过stdio实现MCP服务器的完整生命周期

看 docs/TEST.md 获取详细的测试指南。

日志记录

日志被写入 logs/ 目录：

• combined.log：所有日志消息
• error.log：仅错误级别消息

实时查看日志：

npm run logs

看 docs/LOGGING.md 了解更多详情。

数据存储

身份验证缓存

会话Cookie缓存在 data/auth/{employeeId}.json 使用1小时的TTL来减少登录请求。

假期/休假记录

记录存储在月度文件中： data/holidays/MM-YYYY.json

示例结构：

{
  "month": 12,
  "year": 2025,
  "records": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "date": "2025-12-25",
      "type": "company_holiday",
      "duration": 1.0,
      "reason": "Christmas Day",
      "createdAt": "2025-12-01T10:00:00.000Z"
    }
  ]
}

SpectraESS集成

该服务器使用其web API与SpectraESS考勤系统进行通信：

1. 认证：使用AES-128-CBC加密凭据（与SpectraESS实现匹配）
2. 会话管理：为经过身份验证的请求维护Cookie
3. 数据获取：检索考勤表和打卡详细信息
4. HTML解析：使用JSDOM从响应页面中提取数据

看 docs/spectrum ess/README.md 获取API详细信息。

安全考虑

• 环境变量存储凭据（确保 .env 在...里 .gitignore)
• 身份验证缓存包含会话Cookie（存储在 data/auth/)
• AES加密密钥/IV与SpectraESS实现匹配（记录在代码中）
• 所有API调用都使用HTTPS
• 通过Zod模式进行输入验证

生产建议：

• 使用密钥管理服务获取凭据
• 加密静态身份验证缓存文件
• 为API调用实现速率限制
• 定期安全审计

故障排除

服务器无法启动

• 检查Node.js版本： node --version （应大于等于24.12.0）
• 验证中的环境变量 .env
• 检查语法错误： npm run type-check

身份验证失败

• 验证SpectraESS主机URL是否可访问
• 检查员工ID和密码是否正确
• 清除身份验证缓存： rm -rf data/auth/*

测试失败

• 集成/E2E测试需要环境变量
• 检查与SpectraESS的网络连接
• 如果缺少env变量，则测试自动跳过（预期行为）

贡献

1. 克隆该仓库
2. 创建要素分支
3. 通过测试进行更改
4. 跑 npm run lint 和 npm test
5. 提交拉取请求

许可证

国际学生委员会

致谢

内置：

• @模型上下文协议/sdk -MCP协议实现
• JSDOM -HTML解析
• 温斯顿 -日志记录
• 萨德 -架构验证