From 5c6a39a7c792a5077ebc6ff45ebb6f9571c1ef55 Mon Sep 17 00:00:00 2001 From: Sucan126 <632190820@qq.com> Date: Fri, 26 Sep 2025 12:19:57 +0800 Subject: [PATCH] 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. --- README.md | 24 ++ terminal_dhr_mcp/README.md | 536 +++--------------------------------- terminal_temi_mcp/README.md | 70 +++++ 3 files changed, 139 insertions(+), 491 deletions(-) create mode 100644 terminal_temi_mcp/README.md diff --git a/README.md b/README.md index 17a8c60..c0db961 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,26 @@ # 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. + diff --git a/terminal_dhr_mcp/README.md b/terminal_dhr_mcp/README.md index e17ad57..3a6c78b 100644 --- a/terminal_dhr_mcp/README.md +++ b/terminal_dhr_mcp/README.md @@ -1,96 +1,21 @@ # 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/) +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 -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 -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 -- 支持环境变量配置 - ---- - -**注意**: 使用本软件前请确保遵守相关法律法规和隐私政策。 \ No newline at end of file + However, it is intended to be launched by an MCP Agent using the JSON configuration file described above. \ No newline at end of file diff --git a/terminal_temi_mcp/README.md b/terminal_temi_mcp/README.md new file mode 100644 index 0000000..ee288bd --- /dev/null +++ b/terminal_temi_mcp/README.md @@ -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.