lzwcai-mcp/terminal_dhr_mcp/README.md

# Terminal DHR MCP Server

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-green.svg)](https://modelcontextprotocol.io/)
[![Version](https://img.shields.io/badge/version-0.1.7-blue.svg)](https://pypi.org/project/terminal-dhr-mcp/)

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

## ✨ 功能特性

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

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

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

## 🚀 快速开始

### 环境要求

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

### 安装方式

#### 方式一：使用pip安装

```bash
pip install terminal-dhr-mcp
```

#### 方式二：从源码安装

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

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

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

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

### 基础配置

1. **创建配置文件**

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

2. **配置环境变量**

```env
# 访客系统配置
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` 配置文件：

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

## 📖 详细文档

### 工具API参考

#### 访客管理工具

##### `query_visitor` - 查询访客记录

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

**参数:**
```json
{
  "user_id": "string"  // 必需：要查询的用户ID
}
```

**示例:**
```json
{
  "user_id": "12345"
}
```

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

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

##### `register_visitor` - 注册访客信息

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

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

**示例:**
```json
{
  "employeeId": "EMP001",
  "visitorName": "张三",
  "reason": "业务洽谈",
  "userId": "12345"
}
```

**验证规则:**
- 所有字段不能为空
- 字段长度限制：employeeId(50)、visitorName(50)、reason(200)、userId(50)
- 特殊字符过滤和转义

#### 门控制工具

##### `control_door` - 控制门开关

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

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

**示例:**
```json
{
  "action": "open"
}
```

**响应:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "门已成功打开"
    }
  ]
}
```

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

##### `get_door_status` - 获取门状态

获取门的当前状态信息。

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

**示例:**
```json
{}
```

**响应:**
```json
{
  "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
- 检查实体权限设置

### 日志调试

启用详细日志：

```env
LOG_LEVEL=DEBUG
```

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

```bash
# 查看实时日志
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. **克隆项目**
```bash
git clone <repository-url>
cd terminal_dhr_mcp
```

2. **创建虚拟环境**
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows
```

3. **安装开发依赖**
```bash
pip install -e ".[dev,test]"
```

### 添加新工具

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

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

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

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

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

### 测试

运行测试套件：

```bash
# 运行所有测试
pytest

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

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

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

### 代码质量

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

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

## 📄 许可证

本项目采用 [MIT License](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
- 支持环境变量配置

---

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