Leave Management MCP Server

请假管理 MCP 服务

此代码仓库包含一个用于管理组织员工请假的 Model Context Protocol（MCP）服务。该服务与包含员工请假数据的 Excel 工作簿集成，并提供用于查询和分析请假记录的工具。

目录

• 前置条件
• 项目结构
• 安装
• 配置
• 运行服务
• 故障排除
• 示例查询

前置条件

• Python 3.9+
• UV 包管理器
• Claude Desktop（或其他 MCP 客户端）
• 包含请假数据的 Excel 工作簿

项目结构

leave-management-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py                # Configuration settings
│   ├── leave_server.py          # Main MCP server
│   ├── data_manager.py          # Data processing module
│   └── models/
│       ├── __init__.py
│       └── employee.py          # Employee data models
├── data/
│   └── leave_tracker.xlsx       # Excel workbook with leave data
├── main.py                      # Entry point wrapper
├── __init__.py                  # Root package marker
├── requirements.txt             # Dependencies
└── README.md                    # Project documentation

安装

1. 克隆此代码仓库：

git clone https://github.com/ItsMistahJi/itsmistahji-leave-management-mcp.git
cd leave-management-mcp

2. 使用 UV 设置 Python 环境：

pip install uv
uv init .

3. 安装依赖项：

uv add "mcp[cli]" pandas openpyxl python-dotenv PyPDF2

配置

1. 在项目根目录中创建 .env 文件：

DATA_DIR=/path/to/your/data/directory
EXCEL_FILE=/path/to/your/data/directory/leave_tracker.xlsx
SERVER_NAME=LeaveManagement
DEBUG_MODE=True

2. 确保 Excel 工作簿具有正确的结构：
   • 名为 "Leaves-2025" 的工作表（或修改 data_manager.py 以使用你的工作表名称）
   • 包含 "Sl No"、"Name"、"EMP ID"、"Location" 和月份名称（"Jan"、"Feb" 等）的列

运行服务

本地开发测试

# Test the server locally
uv run python -m src.leave_server

# Install in Claude Desktop for testing
uv run mcp install src/leave_server.py --name "Leave Management"

VS Code 集成

将此配置添加到 VS Code 设置中：

"mcpServers": {
  "LeaveManagement": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "--with",
      "mcp[cli],pandas,openpyxl,python-dotenv,PyPDF2",
      "mcp",
      "run",
      "/path/to/leave-management-mcp/src/leave_server.py"
    ]
  }
}

[

注意： 将 /path/to/leave-management-mcp 替换为你的实际项目路径。

故障排除

“No module named 'src'”错误

当 Python 无法在其模块搜索路径中找到 'src' 包时，会出现此错误。

解决方案：

1. 添加 __init__.py 文件，使 src 成为一个规范的包：

touch __init__.py
touch src/__init__.py
touch src/models/__init__.py

2. 修改服务器脚本（leave_server.py）以包含路径：

import sys
import os
sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))

3. 使用根目录中的 main.py 包装器：

import sys
import os
sys.path.insert(0, os.path.abspath('.'))
from src.leave_server import mcp
if __name__ == "__main__":
    mcp.run()

“No module named 'pandas'”错误

当运行服务的环境中未安装 pandas 时，会出现此错误。

解决方案：

1. 确保在同一环境中安装了所有依赖项：

uv add pandas openpyxl python-dotenv PyPDF2

2. 运行服务时使用 --with 标志：

uv run --with "mcp[cli],pandas,openpyxl,python-dotenv,PyPDF2" mcp run src/leave_server.py

Excel 数据加载问题

如果 Excel 数据出现验证错误：

1. 检查并修改 data_manager.py 中的 load_data 函数，使其符合你的 Excel 结构
2. 确保工作表名称与 Excel 文件中的名称一致
3. 检查列名，并妥善处理 NaN 值

示例查询

服务运行后，你可以向 Claude 提问：

• “今天谁在休假？”
• “显示员工 12345 的假期余额”
• “列出 4 月份所有休假的员工”
• “获取 Arun S 的请假详情”
• “Jeeva Rao 3 月份什么时候休假？”

查找调试日志

• Claude Desktop 日志：
  • macOS：~/Library/Logs/Claude/mcp.log
  • Windows：%APPDATA%\Claude\logs\mcp.log
• 打印语句： 服务器代码中的任何 print() 语句都会显示在日志中。