Itsmistahji Leave Management MCP

休假管理MCP服务器

此存储库包含一个模型上下文协议（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

1. 使用UV设置Python环境：

pip install uv
uv init .

1. 安装依赖项：

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

1. 确保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代码集成

将此配置添加到您的VS代码设置中：

"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 根据您的实际项目路径。

故障排除

“没有名为'src'的模块”错误

当Python在其模块搜索路径中找不到“src”包时，会发生此错误。

解决：

1. 添加 __init__.py 使src成为一个合适的包的文件：

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

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

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

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

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

“没有名为'pandas'的模块”错误

当运行服务器的环境没有安装pandas时，就会发生这种情况。

解决：

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

uv add pandas openpyxl python-dotenv PyPDF2

1. 使用 --with 运行服务器时标记：

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

Excel数据加载问题

如果遇到Excel数据的验证错误：

1. 审查和修改 load_data 功能在 data_manager.py 以匹配您的Excel结构
2. 确保工作表名称与Excel文件匹配
3. 检查列名并正确处理NaN值

查询示例

一旦你的服务器开始运行，你可以问克劳德：

• “今天谁休假？”
• “显示员工12345的假期余额”
• “列出4月份休假的所有员工”
• “获取阿伦S的休假详细信息”
• “杰娃·拉奥三月份什么时候休假的？”

查找调试日志

• 克劳德桌面日志：

- macOS： ~/Library/Logs/Claude/mcp.log - 窗户： %APPDATA%\Claude\logs\mcp.log

• 打印报表： 任何 print() 服务器代码中的语句将出现在日志中。

⁂