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:
24
README.md
24
README.md
@@ -1,2 +1,26 @@
|
|||||||
# lzwcai-mcp
|
# lzwcai-mcp
|
||||||
|
|
||||||
|
This repository is a collection of MCP (Machine Control Program) server implementations, designed to act as skill packages for an AI agent. Each server exposes a specific set of capabilities that can be invoked by the agent.
|
||||||
|
|
||||||
|
## Projects
|
||||||
|
|
||||||
|
This collection currently includes the following MCP servers:
|
||||||
|
|
||||||
|
### 1. `terminal-dhr-mcp`
|
||||||
|
|
||||||
|
A skill package for a Visitor Information Query & Registration System and IoT door control.
|
||||||
|
|
||||||
|
- **Features**: Visitor query, visitor registration, and remote door control.
|
||||||
|
- **Details**: See the [`terminal_dhr_mcp/README.md`](./terminal_dhr_mcp/README.md) for more information.
|
||||||
|
|
||||||
|
### 2. `terminal-temi-mcp`
|
||||||
|
|
||||||
|
A skill package to control a Temi robot via the MQTT protocol.
|
||||||
|
|
||||||
|
- **Features**: Robot navigation (`nav_to`), speaking (`speak`), reception tasks, and delivery management.
|
||||||
|
- **Details**: See the [`terminal_temi_mcp/README.md`](./terminal_temi_mcp/README.md) for more information.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Each project is a standalone Python package intended to be run as a separate process and managed by an MCP Agent. They communicate with the agent over `stdio` and are configured via their respective `mcp-server-*.json` files.
|
||||||
|
|
||||||
|
|||||||
@@ -1,96 +1,21 @@
|
|||||||
# Terminal DHR MCP Server
|
# Terminal DHR MCP Server
|
||||||
|
|
||||||
[](https://www.python.org/downloads/)
|
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.
|
||||||
[](https://opensource.org/licenses/MIT)
|
|
||||||
[](https://modelcontextprotocol.io/)
|
|
||||||
[](https://pypi.org/project/terminal-dhr-mcp/)
|
|
||||||
|
|
||||||
一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的智能终端服务器，提供访客管理和门控制功能。支持通过AI助手进行访客信息查询、注册和门禁控制操作。
|
## Features
|
||||||
|
|
||||||
## ✨ 功能特性
|
This server exposes several tools that can be called by an MCP Agent:
|
||||||
|
|
||||||
### 🏢 访客管理系统
|
- **Visitor Management**:
|
||||||
- **访客记录查询**: 根据用户ID查询访客预约记录，支持历史数据检索
|
- `query_visitor`: Queries visitor reservation records using a user ID.
|
||||||
- **访客信息注册**: 在访客系统中注册新的访客信息，包含完整的验证机制
|
- `register_visitor`: Registers new visitor information into the system.
|
||||||
- **数据验证**: 完整的输入参数验证和错误处理，确保数据完整性
|
- **Door Control**:
|
||||||
- **API集成**: 与现有访客管理系统无缝集成
|
- `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).
|
||||||
|
|
||||||
### 🚪 智能门控制
|
## Configuration
|
||||||
- **远程门控制**: 通过Home Assistant API控制门的开关，支持多种门类型
|
|
||||||
- **状态监控**: 实时获取门的当前状态信息，包括开关状态和错误信息
|
|
||||||
- **灵活配置**: 支持自定义实体ID和API端点，适配不同环境
|
|
||||||
- **安全控制**: 内置安全验证机制，防止误操作
|
|
||||||
|
|
||||||
### 🔧 技术特性
|
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:
|
||||||
- **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
|
```json
|
||||||
{
|
{
|
||||||
@@ -100,421 +25,50 @@ LOG_LEVEL=INFO
|
|||||||
"type": "stdio",
|
"type": "stdio",
|
||||||
"timeout": 30,
|
"timeout": 30,
|
||||||
"command": "uvx",
|
"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参考
|
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
|
||||||
##### `query_visitor` - 查询访客记录
|
DHR_API_BASE_URL=http://your-dhr-api-endpoint.com
|
||||||
|
DHR_API_TOKEN=your_api_token
|
||||||
根据用户ID查询访客预约记录。
|
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": "string" // 必需：要查询的用户ID
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**示例:**
|
## Installation and Usage
|
||||||
```json
|
|
||||||
{
|
|
||||||
"user_id": "12345"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**响应:**
|
1. **Install dependencies**:
|
||||||
```json
|
This project uses `setuptools`. Install the package and its dependencies using pip.
|
||||||
{
|
|
||||||
"content": [
|
|
||||||
{
|
|
||||||
"type": "text",
|
|
||||||
"text": "查询结果：找到2条访客记录..."
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**错误处理:**
|
```bash
|
||||||
- 用户ID不存在：返回"未找到该用户的访客记录"
|
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
|
||||||
|
```
|
||||||
|
|
||||||
**参数:**
|
However, it is intended to be launched by an MCP Agent using the JSON configuration file described above.
|
||||||
```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
|
|
||||||
- 支持环境变量配置
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**注意**: 使用本软件前请确保遵守相关法律法规和隐私政策。
|
|
||||||
70
terminal_temi_mcp/README.md
Normal file
70
terminal_temi_mcp/README.md
Normal file
@@ -0,0 +1,70 @@
|
|||||||
|
# Terminal Temi MCP Server
|
||||||
|
|
||||||
|
This project is an MCP (Machine Control Program) skill package designed to control a Temi robot via the MQTT protocol. It exposes robot functionalities like navigation, speaking, and delivery as tools for an MCP Agent.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
This server provides a set of tools to command a Temi robot:
|
||||||
|
|
||||||
|
- `nav_to`: Navigates the robot to a specified location.
|
||||||
|
- `speak`: Makes the robot broadcast a spoken message.
|
||||||
|
- `reception`: Commands the robot to go to a location to welcome and guide a guest.
|
||||||
|
- `notification`: Sends the robot to a location to deliver a notification message.
|
||||||
|
- `repose`: Instructs the robot to perform a repositioning/localization routine.
|
||||||
|
- `delivery`: Manages a delivery task, where the robot moves from a pickup point (`first_location`) to a drop-off point (`next_location`).
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
To be used by an MCP Agent, this server requires a JSON configuration file. Create a file (e.g., `mcp-server-temi.json`) with the following structure:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"terminal-temi-mcp": {
|
||||||
|
"disabled": false,
|
||||||
|
"type": "stdio",
|
||||||
|
"timeout": 30,
|
||||||
|
"command": "uvx",
|
||||||
|
"args": [
|
||||||
|
"terminal_temi_mcp"
|
||||||
|
],
|
||||||
|
"env": {
|
||||||
|
"employeeId": "$employeeId$",
|
||||||
|
"userId": "$employeeId$"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `command`: The command to execute the server, using `uvx` to run the Python package.
|
||||||
|
- `args`: The name of the package to run.
|
||||||
|
- `env`: Environment variables passed to the server. The MCP Agent will replace placeholders like `$employeeId$` with actual values.
|
||||||
|
|
||||||
|
The server also relies on a `.env` file for its own configuration, such as MQTT broker details. Create a `.env` file in the project root:
|
||||||
|
```
|
||||||
|
# .env file
|
||||||
|
LOG_LEVEL=INFO
|
||||||
|
MQTT_BROKER_ADDRESS=your_mqtt_broker_ip
|
||||||
|
MQTT_PORT=1883
|
||||||
|
MQTT_USERNAME=your_username
|
||||||
|
MQTT_PASSWORD=your_password
|
||||||
|
```
|
||||||
|
|
||||||
|
## Installation and Usage
|
||||||
|
|
||||||
|
1. **Install dependencies**:
|
||||||
|
This project uses `hatchling` as its build backend. Install the package and its dependencies using pip.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install .
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Running the server**:
|
||||||
|
The server entry point is defined in `pyproject.toml`. You can run it directly from the command line:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
terminal_temi_mcp
|
||||||
|
```
|
||||||
|
|
||||||
|
Typically, this server is not run manually but is launched by an MCP Agent that uses the `mcp-server-temi.json` configuration file.
|
||||||
Reference in New Issue
Block a user