🚀 Kyronix Stratus NTP MCP

Kyronix Stratus NTP MCP is a read-only Model Context Protocol server for diagnosing and monitoring a Stratus NTP node backed by Prometheus metrics.

It provides a practical AI interface for:

• Chrony status and timing quality
• PPS stability analysis
• GPS signal quality checks
• Incident and recovery analysis
• Hybrid risk and health diagnostics

Built for operational troubleshooting through MCP-compatible clients such as GitHub Copilot CLI and VS Code.

---

✨ Highlights

• Read-only MCP server
• Prometheus-backed diagnostics
• Visibility into Chrony, PPS, GPS, and risk metrics
• Human-readable health and operator summaries
• Incident-focused troubleshooting workflow
• Portable bundle support for redeployment and restore
• Compatible with SSH + stdio MCP workflows

---

🏗️ Architecture

MCP Client (Copilot CLI / VS Code)
        │
        ▼
SSH + stdio
        │
        ▼
Kyronix Stratus NTP MCP
        │
        ▼
Prometheus (local on Stratus host)
        │
        ├── Chrony metrics
        ├── PPS metrics
        ├── GPS metrics
        └── Stratus health / anomaly / risk metrics

---

🧰 Available Tools

The MCP server currently exposes tools such as:

• query_prometheus_instant
• query_prometheus_range
• get_ntp_health_snapshot
• get_recovery_status
• get_current_status_brief
• get_operator_status
• get_reference_quality
• get_last_incident_summary
• get_stratus_diagnosis_v2
• get_pps_stability_check

These tools allow both raw metric inspection and high-level diagnosis.

---

🎯 Example Use Cases

Quick health check

• Is the node healthy right now?
• Is holdover active?
• Is PPS stable?

Diagnosis

• Why is health score low?
• Is the issue caused by PPS, GPS, Chrony, or hybrid risk?
• What changed before the latest incident?

Incident analysis

• Summarize the latest RMS spike
• Show likely precursor metrics
• Check whether the node is recovering or oscillating

---

⚙️ Installation

Requirements

• Linux-based Stratus or compatible host
• Docker installed
• Prometheus available locally
• SSH access from MCP client host
• MCP-compatible client such as:
  • GitHub Copilot CLI
  • VS Code MCP

Typical install path

/opt/stratus-mcp

Typical wrapper entrypoint

/opt/stratus-mcp/run-stdio.sh

---

🤖 Copilot CLI Configuration

Example ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "kyronix-stratus-ntp": {
      "type": "stdio",
      "command": "ssh",
      "args": [
        "-T",
        "-q",
        "-o", "BatchMode=yes",
        "-o", "LogLevel=ERROR",
        "YOUR_SSH_USER@YOUR_HOST_OR_IP",
        "exec /opt/stratus-mcp/run-stdio.sh"
      ],
      "tools": ["*"]
    }
  }
}

---

🧑‍💻 VS Code Configuration

Example .vscode/mcp.json:

{
  "servers": {
    "kyronix-stratus-ntp": {
      "command": "ssh",
      "args": [
        "-T",
        "-q",
        "-o", "BatchMode=yes",
        "-o", "LogLevel=ERROR",
        "YOUR_SSH_USER@YOUR_HOST_OR_IP",
        "exec /opt/stratus-mcp/run-stdio.sh"
      ]
    }
  }
}

---

📦 Portable Bundle

The project supports a portable distribution bundle for reuse on other compatible hosts.

Portable bundle includes:

• MCP source archive
• Docker image archive
• install script
• restore script
• client config templates
• README
• tool list

Build portable bundle

/opt/stratus-mcp-backup/build_portable_bundle_v2.sh

Install from portable bundle

sudo sh install_stratus_mcp_portable.sh

---

🔄 Typical Workflow

1. Quick summary

Ask the client for a one-line health summary.

2. Operator view

Use the operator-oriented tool for current state, indicators, and next step.

3. Deep diagnosis

Run the full diagnosis tool when health is degraded or warning persists.

4. Incident analysis

Check the latest incident window and correlate RMS, holdover, PPS, GPS, and risk.

5. PPS validation

Run PPS stability check to identify signal irregularity or guard failure.

---

📝 Operational Notes

• This MCP server is intentionally read-only.
• It is designed for diagnostics, not direct control or remediation.
• Tool quality depends on Prometheus metric availability and consistent metric naming.
• SSH access should be key-based and non-interactive for stdio mode.

---

📁 Directory Layout

/opt/stratus-mcp/
├── stratus_ntp_mcp_server_stdio.py
├── Dockerfile.stdio
├── run-stdio.sh
└── assets/

Backup / bundle area

/opt/stratus-mcp-backup/
├── backup_stratus_mcp.sh
├── build_portable_bundle.sh
├── build_portable_bundle_v2.sh
├── install_or_restore_stratus_mcp.sh
├── latest
└── portable_latest_v2

---

📊 Status Model

The server commonly classifies node state into:

• healthy
• warning
• degraded

Typical drivers include:

• holdover
• PPS guard failure
• elevated RMS offset
• elevated hybrid risk
• anomaly persistence
• elevated stratum

---

🛣️ Roadmap

Planned or possible future improvements:

• GPS stability focused tool
• incident export to JSON
• richer operator summary formatting
• templated config generation
• checksum and release metadata in portable bundle
• optional visual and icon branding across clients

---

📄 License

Licensed under the MIT License.

---

🤝 Contributing

This project follows a controlled appliance model.
Suggestions, issues, and discussions are welcome via GitHub Issues.

---