Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,157 @@
+# Remote H2 Database Query via SSH
+
+When an MCP server needs to read from an H2 database on a remote host (e.g., Traccar on app2), use this pattern:
+
+## Architecture
+
+```
+MCP tool call
+  → SSH into remote host (key-based, no password prompt)
+  → scp the .mv.db file to a local temp file
+  → Java H2 Shell query (org.h2.tools.Shell)
+  → Parse pipe-delimited output
+  → Delete temp file
+  → Return structured JSON
+```
+
+## Why this pattern
+
+- **H2 databases lock.** You cannot query a live H2 database from two processes simultaneously. Copying with `scp` creates a read-only snapshot — the copy succeeds even while the DB is in use, and you query the copy.
+- **Java is needed.** H2's file format is proprietary. Python libraries like `jaydebeapi` exist but are brittle; the H2 Shell jar is self-contained and reliable.
+- **30-second cache.** The SCP + Java query takes 3-5 seconds. Caching avoids this overhead on repeated calls.
+
+## Prerequisites
+
+On the local host:
+```bash
+apt-get install -y default-jre-headless
+# Copy H2 jar from the remote host or the container
+scp root@remote:/tmp/h2.jar /tmp/h2.jar
+# Test: java -cp /tmp/h2.jar org.h2.tools.Shell --help
+```
+
+On the remote host (the H2 jar must exist):
+```bash
+# If inside a Docker container:
+docker cp container_name:/opt/app/lib/h2-*.jar /tmp/h2.jar
+```
+
+## Implementation Template
+
+```python
+import subprocess, tempfile, os, time
+
+HOST = "152.53.xxx.xxx"
+DB_PATH = "/root/docker/app/data/database"
+CACHE_TTL = 30
+
+_cache = {"data": None, "ts": 0}
+
+def query_devices():
+    if _cache["data"] and (time.time() - _cache["ts"]) < CACHE_TTL:
+        return _cache["data"]
+
+    tmp_db = tempfile.mktemp(suffix=".mv.db")
+    # 1. Copy DB snapshot from remote
+    subprocess.run(
+        ["scp", "-i", "/root/.ssh/itpp-infra", "-o", "StrictHostKeyChecking=no",
+         f"root@{HOST}:{DB_PATH}.mv.db", tmp_db],
+        capture_output=True, timeout=15, check=True
+    )
+
+    # 2. Query with Java H2 Shell
+    base = tmp_db.replace(".mv.db", "")
+    result = subprocess.run(
+        ["java", "-cp", "/tmp/h2.jar", "org.h2.tools.Shell",
+         "-url", f"jdbc:h2:{base}", "-user", "sa", "-password", "",
+         "-sql", "SELECT id, name, latitude, longitude FROM tc_devices;"],
+        capture_output=True, text=True, timeout=20
+    )
+    os.unlink(tmp_db)
+
+    # 3. Parse pipe-delimited output (H2 Shell format)
+    # Output: "ID | NAME | LATITUDE | LONGITUDE\n1  | foo  | 10.4     | -75.5"
+    rows = []
+    for line in result.stdout.strip().split('\n'):
+        parts = [p.strip() for p in line.split('|')]
+        if len(parts) >= 4 and parts[0].strip().isdigit():
+            rows.append({
+                "id": int(parts[0]),
+                "name": parts[1] if parts[1] != "null" else None,
+            })
+
+    data = {"rows": rows, "count": len(rows)}
+    _cache["data"] = data
+    _cache["ts"] = time.time()
+    return data
+```
+
+## Traccar Schema Reference (GPS Tracking)
+
+These are the live table schemas used by Traccar 6.x. All queries go through the H2 database at `/root/docker/traccar/traccar-data/database.mv.db` on app2 (152.53.39.202).
+
+### tc_devices
+
+| Column | Type | Notes |
+|---|---|---|
+| id | INT | Primary key |
+| name | VARCHAR | User-assigned device name |
+| uniqueid | VARCHAR | Device identifier (IMEI, serial) |
+| lastupdate | TIMESTAMP | Last position received |
+| status | VARCHAR | "online", "offline", or "unknown" |
+
+### tc_positions
+
+| Column | Type | Notes |
+|---|---|---|
+| id | BIGINT | Auto-increment |
+| deviceid | INT | FK → tc_devices.id |
+| latitude | DOUBLE | Decimal degrees |
+| longitude | DOUBLE | Decimal degrees |
+| speed | DOUBLE | Knots (× 1.15078 for mph) |
+| devicetime | TIMESTAMP | Device-reported time |
+
+### Common Queries
+
+```sql
+-- All devices with latest position (one query)
+SELECT d.id, d.name, d.uniqueid, d.lastupdate, d.status,
+       p.latitude, p.longitude, p.speed, p.devicetime
+FROM tc_devices d
+LEFT JOIN tc_positions p ON p.id = (
+    SELECT MAX(id) FROM tc_positions WHERE deviceid = d.id
+)
+ORDER BY d.lastupdate DESC;
+
+-- Position history for one device
+SELECT latitude, longitude, speed, devicetime
+FROM tc_positions WHERE deviceid = 1
+ORDER BY devicetime ASC;
+
+-- Stats: distance (haversine), max speed, active time
+SELECT COUNT(*) as positions,
+       MAX(speed) * 1.15078 as max_speed_mph
+FROM tc_positions
+WHERE deviceid = 1
+  AND devicetime >= NOW() - INTERVAL '24' HOUR;
+```
+
+## FastAPI Proxy Integration
+
+When the MCP server is slow (3-5s per SCP+Java query), serve data through a FastAPI proxy with 30-second caching. The ops portal at `/opt/ops-portal/server.py` uses this pattern:
+
+```python
+# /api/ft360/status endpoint proxies Traccar data
+@app.get("/api/ft360/status")
+async def traccar_status():
+    return _get_traccar_data()  # cached 30s, SCP+Java underneath
+```
+
+The JavaScript dashboard fetches from `/api/ft360/status` every 30 seconds — same TTL as the cache. No authentication needed; the proxy handles the SSH and Java complexity.
+
+- **Java must be on PATH.** Install `default-jre-headless` before using. The `java` binary in Docker containers (e.g., `/opt/traccar/jre/bin/java`) isn't on PATH by default.
+- **H2 jar must be on the same host and compatible.** Copy it from the container or remote host — don't download a different version from Maven Central.
+- **H2 Shell output format.** The first line is column headers (`ID | NAME | ...`), subsequent lines are data. Filter with `.isdigit()` on the first column.
+- **SCP key must work.** The SSH key path must be absolute, and `StrictHostKeyChecking=no` avoids prompt-freezing on first connection.
+- **Temp file cleanup.** Always `os.unlink(tmp_db)` in a `finally` block or immediately after the query. A 176KB file won't cause issues if left, but it's sloppy.
+- **Cache invalidation.** If you stop+start the remote container (restarting the DB), the cache may return stale data until the TTL expires. For write operations, skip the cache.