feat: Implement the initial sysmetrics-mcp Go server including configuration, handlers, and project infrastructure.

Author: raythurman2386

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [raythurman2386]

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main", "master" ]
+  pull_request:
+    branches: [ "main", "master" ]
+
+jobs:
+  build:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25.6'
+          check-latest: true
+
+      - name: Format
+        run: go fmt ./...
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Lint
+        uses: golangci/golangci-lint-action@v6
+        with:
+          version: latest
+          install-mode: goinstall
+
+      - name: Test
+        run: go test -v ./...

.gitignore

@@ -0,0 +1,25 @@
+# Binaries for programs and plugins
+bin/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo

.golangci.yml

@@ -0,0 +1,34 @@
+run:
+  timeout: 5m
+  go: '1.25'
+
+linters:
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+    - gocritic
+    - revive
+    - gosec
+    - goconst
+    - bodyclose
+    - nilerr
+    - noctx
+
+linters-settings:
+  revive:
+    rules:
+      - name: exported
+      - name: package-comments
+      - name: argument-limit
+        arguments: [5]
+      - name: function-result-limit
+        arguments: [3]
+
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0

GEMINI.md

@@ -0,0 +1,71 @@
+# SysMetrics MCP Server - Project Context
+
+A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server written in Go that provides comprehensive Linux system metrics to AI models. It is optimized for both generic Linux distributions and Raspberry Pi systems.
+
+## Project Overview
+
+- **Core Functionality**: Exposes system metrics (CPU, Memory, Disk, Network, Processes, Thermal) as MCP tools.
+- **Main Technologies**:
+  - **Language**: Go 1.25.6+
+  - **MCP Framework**: `github.com/mark3labs/mcp-go`
+  - **Metrics Library**: `github.com/shirou/gopsutil/v3`
+- **License**: MIT
+- **Architecture**:
+  - `cmd/sysmetrics-mcp/main.go`: Entry point and server lifecycle management.
+  - `internal/config/config.go`: CLI flag parsing and validation.
+  - `internal/handlers/handlers.go`: Core logic for fetching system metrics.
+  - `bin/sysmetrics-mcp`: The compiled binary (ignored by git).
+
+## Building and Running
+
+The project includes a `Makefile` for common development tasks.
+
+### Key Commands
+
+- **Build**: `make build` (Produces the `sysmetrics-mcp` binary)
+- **Test**: `make test` (Runs all unit tests with verbose output)
+- **Lint**: `make lint` (Runs `go vet` and checks code quality)
+- **Install**: `make install` (Builds and copies the binary to `/usr/local/bin`)
+- **Clean**: `make clean` (Removes compiled binaries and temporary files)
+- **Dependencies**: `make deps` (Downloads and tidies Go modules)
+
+### Development Loop
+
+To run the server locally during development (using stdio transport):
+```bash
+go run . [flags]
+```
+
+## Configuration
+
+The server is configured via CLI flags, which are handled in `config.go`.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--temp-unit` | `celsius` | `celsius`, `fahrenheit`, or `kelvin` |
+| `--max-processes` | `10` | Limit for process list (1-50) |
+| `--mount-points` | `""` | Comma-separated list of mount points to monitor |
+| `--interfaces` | `""` | Comma-separated list of network interfaces to monitor |
+| `--enable-gpu` | `true` | Enable Raspberry Pi GPU metrics via `vcgencmd` |
+
+## Development Conventions
+
+- **Go Standards**: Adheres to standard Go idioms and project structure.
+- **Error Handling**: Handlers return structured error messages via `mcp.NewToolResultError` instead of crashing the server.
+- **Testing**:
+  - Uses table-driven tests for logic (see `config_test.go`).
+  - Handlers are unit tested by mocking/calling them directly with context (see `handlers_test.go`).
+- **Raspberry Pi Specialization**: The code detects Raspberry Pi hardware to provide additional metrics (GPU temp, throttling status) while falling back gracefully on generic Linux systems.
+- **Linting**: Pre-configured for `golangci-lint` (see `.golangci.yml`), including linters like `revive`, `gosec`, and `gocritic`.
+
+## MCP Tools
+
+The following tools are available to the AI:
+
+1.  `get_system_info`: Hostname, OS, kernel, uptime.
+2.  `get_cpu_metrics`: Usage, per-core load, temperature.
+3.  `get_memory_metrics`: Virtual memory and Swap usage.
+4.  `get_disk_metrics`: Disk usage per mount point.
+5.  `get_network_metrics`: Interface statistics and IP addresses.
+6.  `get_process_list`: Top processes by CPU/Memory.
+7.  `get_thermal_status`: Advanced thermal and throttling info (Pi-optimized).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raymond Thurman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,28 @@
+.PHONY: build clean install test
+
+BINARY_NAME=sysmetrics-mcp
+INSTALL_PATH=/usr/local/bin
+
+build:
+	go build -o bin/$(BINARY_NAME) ./cmd/sysmetrics-mcp
+
+clean:
+	rm -f bin/$(BINARY_NAME)
+	go clean
+
+install: build
+	sudo cp bin/$(BINARY_NAME) $(INSTALL_PATH)/
+	sudo chmod +x $(INSTALL_PATH)/$(BINARY_NAME)
+
+uninstall:
+	sudo rm -f $(INSTALL_PATH)/$(BINARY_NAME)
+
+test:
+	go test -v ./...
+
+lint:
+	go vet ./...
+
+deps:
+	go mod download
+	go mod tidy

README.md

@@ -0,0 +1,168 @@
+# SysMetrics MCP Server
+
+A lightweight MCP (Model Context Protocol) server that exposes Linux system metrics through MCP tools. Works on any Linux system including Raspberry Pi.
+
+## Features
+
+- **7 MCP Tools**: System info, CPU, memory, disk, network, processes, and thermal status
+- **Configurable**: CLI arguments for temperature units, process limits, mount points, and interfaces
+- **Cross-Platform**: Works on any Linux system (enhanced metrics for Raspberry Pi)
+- **AI-Ready**: Designed for integration with Claude Desktop, Cursor, or any MCP client
+
+## Installation
+
+### Prerequisites
+
+- Go 1.25.6 or higher
+- Linux system (tested on Ubuntu, Debian, Raspberry Pi OS)
+
+### Build from Source
+
+The project uses a `Makefile` for common tasks.
+
+```bash
+git clone <repository>
+cd sysmetrics-mcp
+make build
+```
+
+The compiled binary will be located in `bin/sysmetrics-mcp`.
+
+### Install to PATH
+
+```bash
+# Option 1: System-wide (installs to /usr/local/bin)
+sudo make install
+
+# Option 2: User-local
+mkdir -p ~/.local/bin
+cp bin/sysmetrics-mcp ~/.local/bin/
+# Add to PATH if not already: export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Verify Installation
+
+```bash
+sysmetrics-mcp --help
+```
+
+## Configuration
+
+### Local AI Agents (Gemini CLI / Personal Agents)
+
+Add to your agent's configuration file:
+
+```json
+{
+  "sysmetrics": {
+    "type": "stdio",
+    "command": "sysmetrics-mcp",
+    "args": [
+      "--temp-unit", "celsius",
+      "--max-processes", "10"
+    ]
+  }
+}
+```
+
+### Available CLI Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--temp-unit` | `celsius` | Temperature unit: `celsius`, `fahrenheit`, or `kelvin` |
+| `--max-processes` | `10` | Default maximum processes to list (1-50) |
+| `--mount-points` | `""` | Comma-separated mount points (empty = all) |
+| `--interfaces` | `""` | Comma-separated interfaces (empty = all, excludes `lo`) |
+| `--enable-gpu` | `true` | Attempt to read GPU metrics (Raspberry Pi only) |
+
+## MCP Tools
+
+### `get_system_info`
+Returns system information including hostname, OS, uptime, and platform details.
+
+### `get_cpu_metrics`
+Returns CPU usage, temperature, core count, and load average.
+
+**Optional Arguments:**
+- `temp_unit`: Override temperature unit
+
+### `get_memory_metrics`
+Returns RAM and swap usage statistics with both bytes and human-readable formats.
+
+### `get_disk_metrics`
+Returns disk usage for all or specified mount points.
+
+**Optional Arguments:**
+- `mount_points`: Comma-separated mount points to check
+- `human_readable`: Include human-readable sizes (default: true)
+
+### `get_network_metrics`
+Returns network interface statistics including bytes sent/received and IP addresses.
+
+**Optional Arguments:**
+- `interfaces`: Comma-separated interface names to check
+
+### `get_process_list`
+Returns list of running processes sorted by resource usage.
+
+**Optional Arguments:**
+- `limit`: Maximum number of processes (1-50)
+- `sort_by`: Sort by `cpu`, `memory`, or `pid` (default: `cpu`)
+
+### `get_thermal_status`
+Returns thermal status including CPU/GPU temperatures and throttling information (Raspberry Pi).
+
+**Optional Arguments:**
+- `temp_unit`: Override temperature unit
+
+## Example Usage
+
+Once configured, you can ask your AI assistant:
+
+- "What's my CPU temperature?"
+- "Show me disk usage for / and /home"
+- "List the top 5 processes by memory usage"
+- "What's my network usage on eth0?"
+- "Check if my Raspberry Pi is throttling"
+
+## Raspberry Pi Enhancements
+
+On Raspberry Pi systems, the server provides additional metrics:
+
+- **CPU Temperature**: Reads from `/sys/class/thermal/thermal_zone0/temp`
+- **GPU Temperature**: Uses `vcgencmd measure_temp`
+- **Throttling Status**: Uses `vcgencmd get_throttled` to detect:
+  - Under-voltage conditions
+  - Frequency capping
+  - Thermal throttling
+  - Soft temperature limits
+
+On non-Pi systems, these metrics return `"not_available"` gracefully.
+
+## Development
+
+Use the included `Makefile` for development tasks:
+
+```bash
+# Run tests
+make test
+
+# Run linter (go vet)
+make lint
+
+# Clean build artifacts
+make clean
+
+# Download and tidy dependencies
+make deps
+```
+
+## Requirements
+
+- Go 1.25.6+
+- Linux system
+- For Pi features: Raspberry Pi OS with `vcgencmd` available
+
+## License
+
+MIT