Enhance README documentation for MCP servers, detailing the terminal-dhr-mcp and introducing the new terminal-temi-mcp server. Updated features, configuration instructions, and installation guidelines for both projects.
This commit is contained in:
@@ -1,96 +1,21 @@
|
||||
# Terminal DHR MCP Server
|
||||
|
||||
[](https://www.python.org/downloads/)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://modelcontextprotocol.io/)
|
||||
[](https://pypi.org/project/terminal-dhr-mcp/)
|
||||
This project is an MCP (Machine Control Program) skill package that provides services for a Visitor Information Query and Registration System, as well as IoT-based door control.
|
||||
|
||||
一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的智能终端服务器，提供访客管理和门控制功能。支持通过AI助手进行访客信息查询、注册和门禁控制操作。
|
||||
## Features
|
||||
|
||||
## ✨ 功能特性
|
||||
This server exposes several tools that can be called by an MCP Agent:
|
||||
|
||||
### 🏢 访客管理系统
|
||||
- **访客记录查询**: 根据用户ID查询访客预约记录，支持历史数据检索
|
||||
- **访客信息注册**: 在访客系统中注册新的访客信息，包含完整的验证机制
|
||||
- **数据验证**: 完整的输入参数验证和错误处理，确保数据完整性
|
||||
- **API集成**: 与现有访客管理系统无缝集成
|
||||
- **Visitor Management**:
|
||||
- `query_visitor`: Queries visitor reservation records using a user ID.
|
||||
- `register_visitor`: Registers new visitor information into the system.
|
||||
- **Door Control**:
|
||||
- `control_door`: Opens or closes a door through an IoT API.
|
||||
- `get_door_status`: Retrieves the current status of a door (e.g., open, closed).
|
||||
|
||||
### 🚪 智能门控制
|
||||
- **远程门控制**: 通过Home Assistant API控制门的开关，支持多种门类型
|
||||
- **状态监控**: 实时获取门的当前状态信息，包括开关状态和错误信息
|
||||
- **灵活配置**: 支持自定义实体ID和API端点，适配不同环境
|
||||
- **安全控制**: 内置安全验证机制，防止误操作
|
||||
## Configuration
|
||||
|
||||
### 🔧 技术特性
|
||||
- **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` 配置文件：
|
||||
To be used by an MCP Agent, this server requires a JSON configuration file. Create a file (e.g., `mcp-server-dhr.json`) with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -100,421 +25,50 @@ LOG_LEVEL=INFO
|
||||
"type": "stdio",
|
||||
"timeout": 30,
|
||||
"command": "uvx",
|
||||
"args": ["terminal-dhr-mcp"]
|
||||
"args": [
|
||||
"terminal-dhr-mcp"
|
||||
],
|
||||
"env": {
|
||||
"employeeId": "$employeeId$"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📖 详细文档
|
||||
- `command`: The command to execute the server. `uvx` is used here to run the Python package.
|
||||
- `args`: The name of the package to run.
|
||||
- `env`: Environment variables passed to the server. The `$employeeId$` is a placeholder that will be replaced by the MCP Agent with the actual user's ID.
|
||||
|
||||
### 工具API参考
|
||||
|
||||
#### 访客管理工具
|
||||
|
||||
##### `query_visitor` - 查询访客记录
|
||||
|
||||
根据用户ID查询访客预约记录。
|
||||
|
||||
**参数:**
|
||||
```json
|
||||
{
|
||||
"user_id": "string" // 必需：要查询的用户ID
|
||||
}
|
||||
The server itself is configured via environment variables, as defined in `terminal_dhr_mcp/config.py`. You can create a `.env` file in the project root to manage these settings:
|
||||
```
|
||||
# .env file
|
||||
LOG_LEVEL=INFO
|
||||
DHR_API_BASE_URL=http://your-dhr-api-endpoint.com
|
||||
DHR_API_TOKEN=your_api_token
|
||||
IOT_API_BASE_URL=http://your-iot-api-endpoint.com
|
||||
IOT_API_TOKEN=your_iot_token
|
||||
DOOR_ENTITY_ID=your_default_door_entity_id
|
||||
```
|
||||
|
||||
**示例:**
|
||||
```json
|
||||
{
|
||||
"user_id": "12345"
|
||||
}
|
||||
```
|
||||
## Installation and Usage
|
||||
|
||||
**响应:**
|
||||
```json
|
||||
{
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "查询结果：找到2条访客记录..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
1. **Install dependencies**:
|
||||
This project uses `setuptools`. Install the package and its dependencies using pip.
|
||||
|
||||
**错误处理:**
|
||||
- 用户ID不存在：返回"未找到该用户的访客记录"
|
||||
- 网络错误：返回"网络连接失败，请稍后重试"
|
||||
- 服务器错误：返回"服务器错误，请稍后重试"
|
||||
```bash
|
||||
pip install .
|
||||
```
|
||||
For development, install with the `dev` extras:
|
||||
```bash
|
||||
pip install .[dev]
|
||||
```
|
||||
|
||||
##### `register_visitor` - 注册访客信息
|
||||
2. **Running the server**:
|
||||
The server is defined as a script in `pyproject.toml`. You can run it directly via:
|
||||
|
||||
在访客系统中注册新的访客信息。
|
||||
```bash
|
||||
terminal-dhr-mcp
|
||||
```
|
||||
|
||||
**参数:**
|
||||
```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
|
||||
- 支持环境变量配置
|
||||
|
||||
---
|
||||
|
||||
**注意**: 使用本软件前请确保遵守相关法律法规和隐私政策。
|
||||
However, it is intended to be launched by an MCP Agent using the JSON configuration file described above.
|
||||
Reference in New Issue
Block a user