lzwcai-mcp/terminal_dhr_mcp/README.md

Terminal DHR MCP Server

一个基于 Model Context Protocol (MCP) 的智能终端服务器，提供访客管理和门控制功能。支持通过AI助手进行访客信息查询、注册和门禁控制操作。

✨ 功能特性

🏢 访客管理系统

• 访客记录查询: 根据用户ID查询访客预约记录，支持历史数据检索
• 访客信息注册: 在访客系统中注册新的访客信息，包含完整的验证机制
• 数据验证: 完整的输入参数验证和错误处理，确保数据完整性
• API集成: 与现有访客管理系统无缝集成

🚪 智能门控制

• 远程门控制: 通过Home Assistant API控制门的开关，支持多种门类型
• 状态监控: 实时获取门的当前状态信息，包括开关状态和错误信息
• 灵活配置: 支持自定义实体ID和API端点，适配不同环境
• 安全控制: 内置安全验证机制，防止误操作

🔧 技术特性

• MCP协议: 完全兼容Model Context Protocol标准，支持最新版本
• 异步处理: 基于asyncio的高性能异步架构，支持并发操作
• 配置管理: 支持环境变量和配置文件，灵活的环境适配
• 日志系统: 完整的操作日志和错误追踪，便于调试和监控
• 错误处理: 完善的异常处理和重试机制，提高系统稳定性
• 类型安全: 基于Pydantic的强类型验证，确保数据安全

🚀 快速开始

环境要求

• Python 3.8 - 3.12
• Home Assistant服务器（用于门控制功能）
• 访客管理系统API（可选）

安装方式

方式一：使用pip安装

pip install terminal-dhr-mcp

方式二：从源码安装

git clone <repository-url>
cd terminal_dhr_mcp
pip install -e .

方式三：使用uv安装（推荐）

# 使用uvx直接运行
uvx terminal-dhr-mcp

# 或安装到环境
uv add terminal-dhr-mcp

基础配置

1. 创建配置文件

# 创建环境变量文件
cp .env.example .env

2. 配置环境变量

# 访客系统配置
BASE_URL=http://192.168.2.236:8088
VISITOR_API_TIMEOUT=30

# Home Assistant配置
HA_URL=http://192.168.1.100:8123
HA_TOKEN=your_long_lived_access_token
DOOR_ENTITY_ID=switch.door_switch

# 日志配置
LOG_LEVEL=INFO

3. 配置MCP客户端

创建 mcp-server-dhr.json 配置文件：

{
  "mcpServers": {
    "terminal-dhr-mcp": {
      "disabled": false,
      "type": "stdio",
      "timeout": 30,
      "command": "uvx",
      "args": ["terminal-dhr-mcp"]
    }
  }
}

📖 详细文档

工具API参考

访客管理工具

query_visitor - 查询访客记录

根据用户ID查询访客预约记录。

参数:

{
  "user_id": "string"  // 必需：要查询的用户ID
}

示例:

{
  "user_id": "12345"
}

响应:

{
  "content": [
    {
      "type": "text",
      "text": "查询结果：找到2条访客记录..."
    }
  ]
}

错误处理:

• 用户ID不存在：返回"未找到该用户的访客记录"
• 网络错误：返回"网络连接失败，请稍后重试"
• 服务器错误：返回"服务器错误，请稍后重试"

register_visitor - 注册访客信息

在访客系统中注册新的访客信息。

参数:

{
  "employeeId": "string",    // 必需：员工ID，最大50字符
  "visitorName": "string",   // 必需：访客姓名，最大50字符
  "reason": "string",        // 必需：访问原因，最大200字符
  "userId": "string"         // 必需：用户ID，最大50字符
}

示例:

{
  "employeeId": "EMP001",
  "visitorName": "张三",
  "reason": "业务洽谈",
  "userId": "12345"
}

验证规则:

• 所有字段不能为空
• 字段长度限制：employeeId(50)、visitorName(50)、reason(200)、userId(50)
• 特殊字符过滤和转义

门控制工具

control_door - 控制门开关

通过Home Assistant API控制门的开关。

参数:

{
  "action": "string",        // 必需：门操作，"open" 或 "close"
  "entity_id": "string"      // 可选：Home Assistant实体ID，默认使用配置中的DOOR_ENTITY_ID
}

示例:

{
  "action": "open"
}

响应:

{
  "content": [
    {
      "type": "text",
      "text": "门已成功打开"
    }
  ]
}

错误处理:

• 无效操作：返回"无效的门操作，请使用 'open' 或 'close'"
• 连接失败：返回"无法连接到Home Assistant"
• 权限错误：返回"权限不足，请检查访问令牌"

get_door_status - 获取门状态

获取门的当前状态信息。

参数:

{
  "entity_id": "string"      // 可选：Home Assistant实体ID，默认使用配置中的DOOR_ENTITY_ID
}

示例:

{}

响应:

{
  "content": [
    {
      "type": "text",
      "text": "门当前状态：关闭"
    }
  ]
}

配置详解

Home Assistant配置

1. 获取长期访问令牌

   • 登录Home Assistant
   • 进入"配置" > "用户" > "长期访问令牌"
   • 创建新令牌并复制到环境变量HA_TOKEN

2. 配置门开关实体

   • 确保门开关在Home Assistant中正确配置
   • 记录实体ID（如：switch.door_switch）
   • 在环境变量中设置DOOR_ENTITY_ID

3. 网络访问

   • 确保MCP服务器能够访问Home Assistant
   • 检查防火墙和网络配置
   • 验证HA_URL配置正确

访客系统配置

1. API端点配置

   • 配置访客系统的API基础地址（BASE_URL）
   • 确保API端点可访问
   • 验证API响应格式

2. 超时设置

   • 根据网络情况调整API超时时间（VISITOR_API_TIMEOUT）
   • 建议设置为30秒或更长
   • 考虑网络延迟和服务器响应时间

🔧 故障排除

常见问题

1. 模块导入错误

错误信息:

ModuleNotFoundError: No module named 'tools'

解决方案:

• 确保使用相对导入（已在最新版本中修复）
• 重新安装包：pip install --force-reinstall terminal-dhr-mcp
• 检查Python环境：python --version
• 验证安装：pip list | grep terminal-dhr-mcp

2. Home Assistant连接失败

错误信息:

HTTP 401 Unauthorized

解决方案:

• 检查HA_TOKEN是否正确设置
• 确认令牌未过期
• 验证Home Assistant服务器可访问
• 检查HA_URL配置格式

3. 访客API连接失败

错误信息:

Connection timeout

解决方案:

• 检查BASE_URL是否正确
• 确认网络连接正常
• 调整VISITOR_API_TIMEOUT值
• 验证访客系统服务状态

4. MCP服务器启动失败

错误信息:

Connection closed

解决方案:

• 检查Python版本（需要3.8+）
• 确认所有依赖已正确安装
• 验证配置文件格式
• 检查权限设置

5. 门控制操作失败

错误信息:

Entity not found

解决方案:

• 检查DOOR_ENTITY_ID配置
• 确认实体在Home Assistant中存在
• 验证实体类型是否为switch或cover
• 检查实体权限设置

日志调试

启用详细日志：

LOG_LEVEL=DEBUG

查看日志输出以获取详细的错误信息：

# 查看实时日志
tail -f logs/terminal_dhr_mcp.log

# 查看错误日志
grep ERROR logs/terminal_dhr_mcp.log

性能优化

1. 连接池配置

   • 调整HTTP连接池大小
   • 优化超时设置

2. 缓存策略

   • 实现状态缓存机制
   • 减少重复API调用

3. 并发控制

   • 限制并发请求数量
   • 实现请求队列管理

🛠️ 开发指南

项目结构

terminal_dhr_mcp/
├── terminal_dhr_mcp/
│   ├── __init__.py          # 包初始化
│   ├── main.py              # 主程序入口
│   ├── tools.py             # 工具定义和处理
│   ├── config.py            # 配置管理
│   ├── visitor_service.py   # 访客服务
│   └── door_control.py      # 门控制服务
├── pyproject.toml           # 项目配置
├── requirements.txt         # 依赖列表
├── mcp-server-dhr.json     # MCP服务器配置
└── README.md               # 项目文档

开发环境设置

1. 克隆项目

git clone <repository-url>
cd terminal_dhr_mcp

2. 创建虚拟环境

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

3. 安装开发依赖

pip install -e ".[dev,test]"

添加新工具

1. 定义工具 在 tools.py 中添加新工具定义：

Tool(
    name="new_tool",
    description="新工具描述",
    inputSchema={
        "type": "object",
        "properties": {
            "param": {"type": "string"}
        },
        "required": ["param"]
    }
)

2. 实现处理函数 添加对应的处理函数：

async def handle_new_tool(arguments: Dict[str, Any]) -> CallToolResult:
    # 实现工具逻辑
    return CallToolResult(content=[TextContent(text="结果")])

3. 注册工具 在工具列表中添加新工具。

测试

运行测试套件：

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_visitor_service.py

# 运行代码检查
black .
isort .
flake8 .
mypy .

# 运行覆盖率测试
pytest --cov=terminal_dhr_mcp

代码质量

项目使用以下工具确保代码质量：

• Black: 代码格式化
• isort: 导入排序
• flake8: 代码检查
• mypy: 类型检查
• pytest: 单元测试

📄 许可证

本项目采用 MIT License 许可证。

🤝 贡献

欢迎提交Issue和Pull Request！

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

贡献指南

• 遵循现有代码风格
• 添加适当的测试
• 更新相关文档
• 确保所有测试通过

📞 支持

• 作者: Sucan126
• 邮箱: 632190820@qq.com

🔄 更新日志

v0.1.7

• 修复模块导入问题
• 优化错误处理机制
• 完善API文档
• 增强配置管理

v0.1.6

• 添加门控制功能
• 实现访客查询API
• 支持环境变量配置

---

注意: 使用本软件前请确保遵守相关法律法规和隐私政策。