feat: Implement NUT client library and initial project scaffolding for UPS communication.
This commit is contained in:
200
README.md
Normal file
200
README.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# NUT UPS MCP Server
|
||||
|
||||
An MCP (Model Context Protocol) server that enables LLMs to interact with UPS (Uninterruptible Power Supply) devices through Network UPS Tools (NUT).
|
||||
|
||||
## Features
|
||||
|
||||
- **list_ups** - List all available UPS devices
|
||||
- **get_ups_status** - Get comprehensive status of a UPS (battery, load, runtime, voltage, etc.)
|
||||
- **get_ups_var** - Get specific variable from UPS
|
||||
- **list_ups_commands** - List available instant commands
|
||||
- **execute_ups_command** - Execute instant commands (battery test, beeper control, etc.)
|
||||
- **get_ups_description** - Get UPS model and manufacturer information
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### 1. Install Network UPS Tools (NUT)
|
||||
|
||||
**On Debian/Ubuntu:**
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install nut nut-client
|
||||
```
|
||||
|
||||
**On RHEL/CentOS:**
|
||||
```bash
|
||||
sudo yum install nut nut-client
|
||||
```
|
||||
|
||||
### 2. Configure NUT Server
|
||||
|
||||
Edit `/etc/nut/ups.conf` to add your UPS:
|
||||
```ini
|
||||
[myups]
|
||||
driver = usbhid-ups
|
||||
port = auto
|
||||
desc = "Main UPS"
|
||||
```
|
||||
|
||||
Edit `/etc/nut/upsd.conf`:
|
||||
```ini
|
||||
LISTEN 127.0.0.1 3493
|
||||
```
|
||||
|
||||
Edit `/etc/nut/upsd.users` (if authentication is needed):
|
||||
```ini
|
||||
[admin]
|
||||
password = yourpassword
|
||||
actions = SET
|
||||
instcmds = ALL
|
||||
```
|
||||
|
||||
Start NUT services:
|
||||
```bash
|
||||
sudo systemctl start nut-server
|
||||
sudo systemctl enable nut-server
|
||||
```
|
||||
|
||||
Verify UPS is detected:
|
||||
```bash
|
||||
upsc myups
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` with your NUT server details:
|
||||
|
||||
```env
|
||||
NUT_HOST=localhost
|
||||
NUT_PORT=3493
|
||||
NUT_USERNAME=admin
|
||||
NUT_PASSWORD=yourpassword
|
||||
```
|
||||
|
||||
> **Note:** Username and password are optional. Leave empty if your NUT server doesn't require authentication.
|
||||
|
||||
### 3. Build the Project
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### With Claude Desktop
|
||||
|
||||
Add to your Claude Desktop configuration (`~/.config/Claude/claude_desktop_config.json` on Linux):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"nut-ups": {
|
||||
"command": "node",
|
||||
"args": ["/home/wartana/myApp/nut-ups-mcp/dist/index.js"],
|
||||
"env": {
|
||||
"NUT_HOST": "localhost",
|
||||
"NUT_PORT": "3493",
|
||||
"NUT_USERNAME": "admin",
|
||||
"NUT_PASSWORD": "yourpassword"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### With Other MCP Clients
|
||||
|
||||
Run the server directly:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
Or use the helper script:
|
||||
|
||||
```bash
|
||||
chmod +x run_server.sh
|
||||
./run_server.sh
|
||||
```
|
||||
|
||||
The server communicates via stdio using the MCP protocol.
|
||||
|
||||
## Example Commands
|
||||
|
||||
Once connected, you can ask the LLM things like:
|
||||
|
||||
- "List all UPS devices"
|
||||
- "What's the battery charge level of myups?"
|
||||
- "Show me the complete status of the UPS"
|
||||
- "What's the current load on the UPS?"
|
||||
- "How much runtime is remaining?"
|
||||
- "What commands are available for this UPS?"
|
||||
- "Mute the UPS beeper"
|
||||
- "Start a battery test"
|
||||
- "What's the input voltage?"
|
||||
- "Show me the UPS model and manufacturer"
|
||||
|
||||
## Common UPS Variables
|
||||
|
||||
- `battery.charge` - Battery charge level (%)
|
||||
- `battery.runtime` - Estimated runtime remaining (seconds)
|
||||
- `battery.voltage` - Battery voltage
|
||||
- `input.voltage` - Input line voltage
|
||||
- `output.voltage` - Output voltage
|
||||
- `ups.load` - UPS load (%)
|
||||
- `ups.status` - UPS status (OL=Online, OB=On Battery, LB=Low Battery)
|
||||
- `ups.temperature` - UPS temperature
|
||||
|
||||
## Common UPS Commands
|
||||
|
||||
- `test.battery.start` - Start battery test
|
||||
- `test.battery.stop` - Stop battery test
|
||||
- `beeper.mute` - Mute the beeper
|
||||
- `beeper.enable` - Enable the beeper
|
||||
- `load.off` - Turn off the load
|
||||
- `load.on` - Turn on the load
|
||||
|
||||
> **Warning:** Use instant commands with caution! Commands like `load.off` will power down connected devices.
|
||||
|
||||
## Development
|
||||
|
||||
Watch mode for TypeScript (auto-recompile on changes):
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Error: connect ECONNREFUSED"
|
||||
- Make sure NUT server (upsd) is running: `sudo systemctl status nut-server`
|
||||
- Check that NUT is listening on the correct port: `netstat -tlnp | grep 3493`
|
||||
|
||||
### "Error: Not connected to NUT server"
|
||||
- Verify NUT_HOST and NUT_PORT are correctly set
|
||||
- Test connection manually: `upsc -l localhost`
|
||||
|
||||
### "Access Denied" errors
|
||||
- Check NUT_USERNAME and NUT_PASSWORD are correct
|
||||
- Verify user permissions in `/etc/nut/upsd.users`
|
||||
|
||||
### No UPS devices listed
|
||||
- Check UPS is detected by NUT: `upsc -l`
|
||||
- Verify UPS configuration in `/etc/nut/ups.conf`
|
||||
- Check NUT driver is running: `sudo systemctl status nut-driver`
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user