replica-omnisciente/.aurelio/mcp/savearth-mcp/README.md

savearth Unified MCP Server

Single MCP server consolidating device management, telemetry analysis, and infrastructure monitoring for the savearth IoT fleet.

Deployment

Property	Value
Host	Proxmox CT 201
Name	savearth-mcp
Status	✅ Running
IP	192.168.0.212 (CT 201)
Port	8080 (SSE transport)
Endpoint	https://savearth-mcp.portugalfuturista.org/sse (public) / http://192.168.0.212:8080/sse (LAN)
Setup Script	../setup.sh

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  AI CLIENT (Kimi Code, Claude, Antigravity, etc.)               │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  MCP Client                                               │  │
│  └────────────────────┬──────────────────────────────────────┘  │
└───────────────────────┼─────────────────────────────────────────┘
                        │ MCP SSE over HTTP
                        ▼
┌─────────────────────────────────────────────────────────────────┐
│  PROXMOX HOST (ssh.portugalfuturista.org)                        │
│                       │                                         │
│                       ▼                                         │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  CT 201: savearth-mcp                                      │  │
│  │  ┌─────────────────────────────────────────────────────┐   │  │
│  │  │  Python MCP Server (FastMCP)                         │   │  │
│  │  │  Transport: SSE (Server-Sent Events)                 │   │  │
│  │  │  Port: 8080                                          │   │  │
│  │  └────────────────────┬────────────────────────────────┘   │  │
│  │                       │                                     │  │
│  │  ┌────────────────────▼────────────────────────────────┐   │  │
│  │  │  Tool Categories                                     │   │  │
│  │  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │   │  │
│  │  │  │ Device      │ │ Telemetry   │ │ Infrastructure│   │   │  │
│  │  │  │ (ESP32)     │ │ (InfluxDB)  │ │ (AWS)         │   │   │  │
│  │  │  └─────────────┘ └─────────────┘ └─────────────┘    │   │  │
│  │  │  ┌─────────────┐ ┌─────────────┐                     │   │  │
│  │  │  │ CI/CD       │ │             │                     │   │  │
│  │  │  │ (GitHub)    │ │             │                     │   │  │
│  │  │  └─────────────┘ └─────────────┘                     │   │  │
│  │  └────────────────────────────────────────────────────┘   │  │
│  │                                                            │  │
│  │  ┌─────────────────────────────────────────────────────┐   │  │
│  │  │  Data Sources                                        │   │  │
│  │  │  - InfluxDB (telemetry) 172.31.21.178:8086          │   │  │
│  │  │  - DynamoDB (logs) eu-north-1                       │   │  │
│  │  │  - AWS IoT Core (device registry)                   │   │  │
│  │  │  - GitHub API (CI/CD)                               │   │  │
│  │  └─────────────────────────────────────────────────────┘   │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Quick Start

Local Development (stdio)

cd replica-omnisciente/.aurelio/mcp/savearth-mcp
pip install -e .
python3 server.py

Add to MCP config:

{
  "mcpServers": {
    "savearth": {
      "command": "python3",
      "args": ["/path/to/savearth-mcp/server.py"]
    }
  }
}

Production (SSE)

The server is already running on CT 201:

{
  "mcpServers": {
    "savearth": {
      "url": "http://192.168.0.212:8080/sse",
      "transport": "sse"
    }
  }
}

Or via SSH tunnel:

ssh -L 8080:localhost:8080 ssh.portugalfuturista.org -N

Then use http://localhost:8080/sse.

Tools Reference

Device Tools (ESP32 Firmware)

Tool	Description	Example
device_build_firmware	Build ESP32-S3 firmware	target=app or clean
device_flash	Flash firmware to device	Port /dev/ttyACM0
device_monitor	Capture serial output	Duration: 30s
device_list_logs	List available log files	-
device_analyze_log	Run firmware-log-analyzer	Check bug patterns
device_check_ota	Check S3 for OTA versions	-
device_sdkconfig_get	Read sdkconfig values	CONFIG_FREERTOS
device_sdkconfig_set	Set sdkconfig.defaults	Build configuration

Usage:

User: Build the firmware for testing
→ AI: [device_build_firmware] target=app

User: Flash to the device on ttyACM0
→ AI: [device_flash] port=/dev/ttyACM0

User: Monitor serial output for 60 seconds
→ AI: [device_monitor] port=/dev/ttyACM0, duration=60

Telemetry Tools (InfluxDB)

Tool	Description	Use Case
telemetry_query	Execute raw Flux queries	Custom analytics
telemetry_device_status	Latest telemetry snapshot	Real-time status
telemetry_volume_history	Hourly water consumption	Usage analysis
telemetry_connection_health	MQTT connect/disconnect	Reliability check
telemetry_fleet_overview	List all active devices	Fleet monitoring
telemetry_shower_sessions	Daily water usage analysis	Per-session metrics

Usage:

User: Show water consumption for device dc:b4:d9:01:58:38
→ AI: [telemetry_volume_history] device_id=dc:b4:d9:01:58:38, hours=24

User: Check fleet health
→ AI: [telemetry_fleet_overview] hours=24

User: Analyze shower sessions for the past week
→ AI: [telemetry_shower_sessions] device_id=..., days=7

Infrastructure Tools (AWS)

Tool	Description	Data Source
infra_dynamo_logs	Browse device logs	DynamoDB DeviceLogs-v3
infra_fsm_transitions	Parse FSM state transitions	Log analysis
infra_fleet_health	Fleet-wide health check	All 40 devices
infra_iot_things	List IoT things & certificates	AWS IoT Core

Usage:

User: Check logs for device errors in the last hour
→ AI: [infra_dynamo_logs] device_id=..., minutes=60, level_filter=E

User: Analyze FSM transitions for stuck states
→ AI: [infra_fsm_transitions] device_id=..., minutes=60

User: Run a fleet-wide health check
→ AI: [infra_fleet_health] minutes=30

CI Tools (GitHub Actions)

Tool	Description	Capability
ci_list_runs	List recent workflow runs	Status, conclusion
ci_run_status	Detailed job + step breakdown	Per-step logs
ci_job_logs	Fetch full/failed logs	Filtering by job
ci_analyze_failure	Pattern-based error analysis	Fix suggestions

Usage:

User: Check the latest CI run status
→ AI: [ci_list_runs] limit=5

User: Get detailed status for run 123456
→ AI: [ci_run_status] run_id=123456

User: Analyze the failed CI job
→ AI: [ci_analyze_failure] run_id=123456

Configuration

Environment Variables

Variable	Default	Description
INFLUXDB_URL	http://172.31.21.178:8086	InfluxDB endpoint
INFLUXDB_TOKEN	—	Required InfluxDB auth token
INFLUXDB_ORG	Savearth	InfluxDB organization
INFLUXDB_BUCKET	savearth-iot	InfluxDB bucket
AWS_REGION	eu-north-1	AWS region
DYNAMODB_TABLE	DeviceLogs-v3	DynamoDB log table
MCP_PORT	8080	SSE transport port
MCP_HOST	0.0.0.0	SSE bind address
MCP_AUTH_TOKEN	—	Bearer token for SSE auth
SAVEARTH_PROJECT_DIR	auto-detected	Project root override

On CT 201

File: /opt/savearth-mcp/.env

INFLUXDB_URL=http://172.31.21.178:8086
INFLUXDB_TOKEN=your_influxdb_token_here
INFLUXDB_ORG=Savearth
INFLUXDB_BUCKET=savearth-iot
AWS_REGION=eu-north-1
DYNAMODB_TABLE=DeviceLogs-v3
MCP_PORT=8080
MCP_HOST=0.0.0.0

Deployment

Automated (Proxmox LXC)

# From project root
bash replica-omnisciente/.aurelio/mcp/setup.sh [VMID]

# Default VMID is 201

This creates:

• Debian 13 LXC container
• Python 3.11+ with venv
• Systemd service (savearth-mcp)
• AWS SSM registration (optional)

Manual

# SSH to CT 201
pct exec 201 -- bash

# Install dependencies
cd /opt/savearth-mcp/replica-omnisciente/.aurelio/mcp/savearth-mcp
source .venv/bin/activate
pip install -e .

# Configure
cp .env.example .env
nano .env

# Start
python3 server.py --transport sse --port 8080

# Or via systemd
systemctl restart savearth-mcp

Usage Examples

Device Diagnostics

User: Device dc:b4:d9:01:58:38 is not reporting. Check its status.

AI:
1. [telemetry_device_status] → Last seen: 2 hours ago
2. [infra_dynamo_logs] → Last log: "Entering light sleep"
3. [infra_fsm_transitions] → Stuck in SLEEP state
4. Conclusion: Device entered deep sleep, needs physical wake

Fleet Analysis

User: Generate a weekly report on water usage across all devices

AI:
1. [telemetry_fleet_overview] → 38/40 devices active
2. [telemetry_shower_sessions] per device → Daily usage
3. [infra_fleet_health] → 2 devices unhealthy
4. Compile report with trends and anomalies

CI Debugging

User: The HIL tests failed. Investigate.

AI:
1. [ci_list_runs] → Find latest failed run
2. [ci_run_status] → Identify failed job
3. [ci_job_logs] → Get failure logs
4. [ci_analyze_failure] → Pattern analysis
5. Report: "Missing header in new FSM state"

Firmware Release

User: Prepare firmware release v2.8.1

AI:
1. [device_build_firmware] target=app → Build
2. [device_check_ota] → Check version
3. [ci_list_runs] → Verify CI passed
4. [infra_fleet_health] → Check device readiness
5. Recommend: Proceed with OTA rollout

Service Management

Check Status

# Systemd service
ssh ssh.portugalfuturista.org "pct exec 201 -- systemctl status savearth-mcp"

# Direct health check
curl http://192.168.0.212:8080/health

Restart

ssh ssh.portugalfuturista.org "pct exec 201 -- systemctl restart savearth-mcp"

View Logs

# Journal
ssh ssh.portugalfuturista.org "pct exec 201 -- journalctl -u savearth-mcp -f"

# Server logs
ssh ssh.portugalfuturista.org "pct exec 201 -- tail -f /opt/savearth-mcp/logs/mcp.log"

Troubleshooting

Connection Refused

# Check if server is running
ssh ssh.portugalfuturista.org "pct exec 201 -- systemctl status savearth-mcp"

# Check port binding
ssh ssh.portugalfuturista.org "pct exec 201 -- netstat -tlnp | grep 8080"

Authentication Failed

# Check InfluxDB token
ssh ssh.portugalfuturista.org "pct exec 201 -- cat /opt/savearth-mcp/.env | grep INFLUXDB_TOKEN"

# Verify AWS credentials
ssh ssh.portugalfuturista.org "pct exec 201 -- aws sts get-caller-identity"

No Data Returned

# Test InfluxDB connectivity
ssh ssh.portugalfuturista.org "pct exec 201 -- curl -I http://172.31.21.178:8086/ping"

# Check DynamoDB table
ssh ssh.portugalfuturista.org "pct exec 201 -- aws dynamodb describe-table --table-name DeviceLogs-v3 --region eu-north-1"

Development

Local Testing

cd replica-omnisciente/.aurelio/mcp/savearth-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Run with stdio (for testing)
python3 server.py

# Run with SSE
python3 server.py --transport sse --port 8080

Adding New Tools

Edit server.py and add a new @mcp.tool() decorated function:

@mcp.tool()
def my_new_tool(param: str) -> dict:
    """Tool description for AI"""
    # Implementation
    return {"result": "success"}

Security

• Bearer Token: Optional MCP_AUTH_TOKEN for SSE authentication
• Network: Internal Proxmox network (192.168.0.x)
• AWS: Uses IAM roles or instance profiles
• InfluxDB: Token-based authentication
• No External Exposure: Port 8080 only on internal network

References

• MCP Python SDK
• FastMCP Documentation
• InfluxDB Flux Query Language
• Parent MCP README — All MCP servers