520 lines
11 KiB
Markdown
520 lines
11 KiB
Markdown
# Terminal DHR MCP Server
|
||
|
||
[](https://www.python.org/downloads/)
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://modelcontextprotocol.io/)
|
||
[](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
|
||
- 支持环境变量配置
|
||
|
||
---
|
||
|
||
**注意**: 使用本软件前请确保遵守相关法律法规和隐私政策。 |