@megamcp/sentinel 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# MegaMCP Sentinel
+
+**Monitoring & reliability for MCP servers.** Sentinel speaks the Model Context Protocol — it runs the real lifecycle (`initialize` handshake → `tools/list` → latency → schema-drift diff) against a target MCP server, keeps history, and flags trouble. A generic HTTP ping can't tell you a server is *up but broken*; Sentinel can.
+
+It ships two ways:
+- a **CLI** (`check` / `watch`) for cron and CI, and
+- an **MCP server** (`list_targets`, `check_target`, `health_summary`) — i.e. an MCP server that monitors MCP servers.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+
+# one-shot check of all targets (exits non-zero if any are DOWN)
+npm run check
+
+# continuous watch
+npm run watch          # every 60s
+node dist/cli.js watch 15
+
+# generate ../web/status.json + ../web/status.html
+npm run report
+```
+
+The repo ships with a bundled **echo-sample** MCP server as a live target, so `npm run check` works with zero external setup.
+
+## What it checks (per target)
+
+| Signal | Meaning |
+|---|---|
+| **reachable / handshake** | Did `initialize` complete? |
+| **tools/list** | Did the server return its tool catalog? |
+| **toolCount** | How many tools — below `minTools` = degraded |
+| **latency** | connect + list timing; over `latencyBudgetMs` = degraded |
+| **schema drift** | Tools added / removed / changed vs. last known-good |
+
+Status is `up` · `degraded` · `down`.
+
+## Configure targets
+
+Edit `sentinel.config.json`. Two transports:
+
+```jsonc
+{ "type": "stdio", "command": "npx", "args": ["-y", "@scope/server"] }
+{ "type": "http",  "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ..." } }
+```
+
+See `_examples` in the config file for full shapes. Point `SENTINEL_CONFIG=/path/to.json` to use a different file.
+
+## Architecture
+
+```
+config.ts ─▶ orchestrate.ts ─▶ monitor.ts ─▶ (MCP client → target)
+                  │                  └─ schema fingerprint + drift
+                  ▼
+              state.ts (history + last-known schema, JSON in ./state)
+                  │
+        ┌─────────┴─────────┐
+     cli.ts              server.ts   (Sentinel as an MCP server)
+```
+
+`monitor.ts` is the engine and is disk-pure; `orchestrate.ts` wires config → check → persist and is shared by both entry points.
+
+## Run Sentinel as an MCP server
+
+```bash
+node dist/server.js
+```
+
+Add to any MCP client config as a stdio server (`command: node`, `args: [".../dist/server.js"]`), then call `check_target` / `health_summary` from your agent.
+
+---
+Part of **[MegaMCP](../CLAUDE.md)** — the reliability layer for the MCP ecosystem.

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { checkTargets } from "./orchestrate.js";
+import { renderResult, renderSummary } from "./format.js";
+const USAGE = "Usage: megamcp-sentinel <check|watch> [targetId] [--json]";
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0] ?? "check";
+    const asJson = argv.includes("--json");
+    const positional = argv.slice(1).filter((a) => !a.startsWith("--"));
+    if (cmd === "check") {
+        const results = await checkTargets(positional[0]);
+        if (asJson) {
+            console.log(JSON.stringify(results, null, 2));
+        }
+        else {
+            for (const r of results)
+                console.log(renderResult(r) + "\n");
+            console.log(renderSummary(results));
+        }
+        process.exit(results.some((r) => r.status === "down") ? 1 : 0);
+    }
+    else if (cmd === "watch") {
+        const intervalSec = Number(positional[0] ?? 60);
+        console.log(`Sentinel watching every ${intervalSec}s. Ctrl+C to stop.\n`);
+        for (;;) {
+            const results = await checkTargets();
+            for (const r of results)
+                console.log(renderResult(r) + "\n");
+            console.log(renderSummary(results) + "\n" + "─".repeat(60) + "\n");
+            await new Promise((r) => setTimeout(r, intervalSec * 1000));
+        }
+    }
+    else {
+        console.error(USAGE);
+        process.exit(2);
+    }
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,26 @@
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Load monitoring targets from a JSON file.
+ * Accepts either a bare array of targets or `{ "targets": [...] }`.
+ * Keys beginning with "_" (e.g. "_examples") are ignored — handy for inline docs.
+ */
+export function loadConfig(path = "sentinel.config.json") {
+    const full = resolve(process.cwd(), path);
+    if (!existsSync(full)) {
+        throw new Error(`Config not found: ${full}`);
+    }
+    const raw = JSON.parse(readFileSync(full, "utf8"));
+    const targets = Array.isArray(raw)
+        ? raw
+        : (raw.targets ?? []);
+    if (!targets.length) {
+        throw new Error(`No targets defined in ${full}`);
+    }
+    for (const t of targets) {
+        if (!t.id || !t.transport) {
+            throw new Error(`Invalid target (needs id + transport): ${JSON.stringify(t)}`);
+        }
+    }
+    return { targets };
+}

package/dist/format.js

@@ -0,0 +1,44 @@
+const C = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+};
+function badge(status) {
+    if (status === "up")
+        return `${C.green}● UP${C.reset}`;
+    if (status === "degraded")
+        return `${C.yellow}● DEGRADED${C.reset}`;
+    return `${C.red}● DOWN${C.reset}`;
+}
+export function renderResult(r) {
+    const lines = [];
+    lines.push(`${badge(r.status)}  ${C.bold}${r.label}${C.reset} ${C.dim}(${r.targetId})${C.reset}`);
+    if (r.serverInfo?.name) {
+        lines.push(`   server: ${r.serverInfo.name}${r.serverInfo.version ? ` v${r.serverInfo.version}` : ""}`);
+    }
+    lines.push(`   tools: ${r.toolCount}   latency: ${r.latencyMs.total}ms ` +
+        `${C.dim}(connect ${r.latencyMs.connect ?? "—"}ms · list ${r.latencyMs.toolsList ?? "—"}ms)${C.reset}`);
+    if (r.schema.drift) {
+        lines.push(`   ${C.yellow}schema drift:${C.reset} +${r.schema.added.length} -${r.schema.removed.length} ~${r.schema.changed.length}`);
+        if (r.schema.added.length)
+            lines.push(`     ${C.green}+ ${r.schema.added.join(", ")}${C.reset}`);
+        if (r.schema.removed.length)
+            lines.push(`     ${C.red}- ${r.schema.removed.join(", ")}${C.reset}`);
+        if (r.schema.changed.length)
+            lines.push(`     ${C.yellow}~ ${r.schema.changed.join(", ")}${C.reset}`);
+    }
+    if (r.error)
+        lines.push(`   ${C.red}error: ${r.error}${C.reset}`);
+    return lines.join("\n");
+}
+export function renderSummary(results) {
+    const up = results.filter((r) => r.status === "up").length;
+    const deg = results.filter((r) => r.status === "degraded").length;
+    const down = results.filter((r) => r.status === "down").length;
+    return (`${C.bold}Summary:${C.reset} ` +
+        `${C.green}${up} up${C.reset}, ${C.yellow}${deg} degraded${C.reset}, ${C.red}${down} down${C.reset} ` +
+        `${C.dim}(${results.length} targets)${C.reset}`);
+}

package/dist/inspect.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// MegaMCP Inspector — devtools for MCP. Connect to any server, browse its
+// tools + schemas, and fire calls. Shares Sentinel's transport layer.
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { loadConfig } from "./config.js";
+const C = { reset: "\x1b[0m", b: "\x1b[1m", dim: "\x1b[2m", o: "\x1b[38;5;208m" };
+function makeTransport(t) {
+    if (t.type === "stdio") {
+        const env = {};
+        for (const [k, v] of Object.entries(process.env))
+            if (typeof v === "string")
+                env[k] = v;
+        return new StdioClientTransport({
+            command: t.command,
+            args: t.args ?? [],
+            env: { ...env, ...(t.env ?? {}) },
+            stderr: "ignore",
+        });
+    }
+    return new StreamableHTTPClientTransport(new URL(t.url), {
+        requestInit: t.headers ? { headers: t.headers } : undefined,
+    });
+}
+function resolveTarget(idOrUrl) {
+    try {
+        const { targets } = loadConfig(process.env.SENTINEL_CONFIG || "sentinel.config.json");
+        const found = targets.find((t) => t.id === idOrUrl);
+        if (found)
+            return found;
+    }
+    catch {
+        /* no config available — fall through to ad-hoc */
+    }
+    if (/^https?:\/\//.test(idOrUrl)) {
+        return { id: idOrUrl, label: idOrUrl, transport: { type: "http", url: idOrUrl } };
+    }
+    throw new Error(`Unknown target "${idOrUrl}". Pass a config target id or an http(s) URL.`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const targetArg = argv[0];
+    if (!targetArg) {
+        console.error("Usage: megamcp-inspect <targetId|url> [--call <tool> --args '<json>']");
+        process.exit(2);
+    }
+    const callIdx = argv.indexOf("--call");
+    const argsIdx = argv.indexOf("--args");
+    const toolName = callIdx >= 0 ? argv[callIdx + 1] : undefined;
+    const toolArgs = argsIdx >= 0 ? JSON.parse(argv[argsIdx + 1]) : {};
+    const target = resolveTarget(targetArg);
+    const client = new Client({ name: "megamcp-inspect", version: "0.1.0" }, { capabilities: {} });
+    await client.connect(makeTransport(target.transport));
+    const v = client
+        .getServerVersion?.();
+    console.log(`${C.b}${target.label}${C.reset} ${C.dim}— ${v?.name ?? "?"} v${v?.version ?? "?"}${C.reset}\n`);
+    if (toolName) {
+        const res = await client.callTool({ name: toolName, arguments: toolArgs });
+        console.log(`${C.o}call ${toolName}(${JSON.stringify(toolArgs)})${C.reset}`);
+        console.log(JSON.stringify(res, null, 2));
+    }
+    else {
+        const { tools } = await client.listTools();
+        console.log(`${C.o}${tools.length} tools${C.reset}`);
+        for (const t of tools) {
+            console.log(`\n  ${C.b}${t.name}${C.reset}${t.description ? ` ${C.dim}— ${t.description}${C.reset}` : ""}`);
+            const schema = (t.inputSchema ?? {});
+            const props = schema.properties ?? {};
+            const required = schema.required ?? [];
+            const keys = Object.keys(props);
+            if (!keys.length) {
+                console.log(`      ${C.dim}(no parameters)${C.reset}`);
+                continue;
+            }
+            for (const k of keys) {
+                const p = props[k];
+                const mark = required.includes(k) ? `${C.o}*${C.reset}` : " ";
+                console.log(`    ${mark} ${k}: ${C.dim}${p.type ?? "any"}${p.description ? " — " + p.description : ""}${C.reset}`);
+            }
+        }
+    }
+    await client.close();
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/dist/monitor.js

@@ -0,0 +1,185 @@
+import { createHash } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+const DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * Run one MCP-native health check against a target:
+ *   reachability -> initialize handshake -> tools/list -> latency -> schema drift.
+ * Pure with respect to disk — persistence is the caller's job.
+ */
+export async function runCheck(target, prior) {
+    const timestamp = new Date().toISOString();
+    const notes = [];
+    const latency = { connect: null, toolsList: null, total: 0 };
+    const t0 = performance.now();
+    const timeoutMs = target.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let client = null;
+    let reachable = false;
+    let handshakeOk = false;
+    let toolsListOk = false;
+    let toolCount = 0;
+    let serverInfo;
+    let newTools = [];
+    let error;
+    try {
+        const transport = makeTransport(target);
+        client = new Client({ name: "megamcp-sentinel", version: "0.1.0" }, { capabilities: {} });
+        const cStart = performance.now();
+        await withTimeout(client.connect(transport), timeoutMs, "connect/initialize");
+        latency.connect = Math.round(performance.now() - cStart);
+        reachable = true;
+        handshakeOk = true;
+        // Server identity (best-effort; method presence varies by SDK version).
+        try {
+            const v = client
+                .getServerVersion?.();
+            if (v)
+                serverInfo = { name: v.name, version: v.version };
+        }
+        catch {
+            /* non-fatal */
+        }
+        const lStart = performance.now();
+        const listed = await withTimeout(client.listTools(), timeoutMs, "tools/list");
+        latency.toolsList = Math.round(performance.now() - lStart);
+        toolsListOk = true;
+        const toolList = listed.tools ?? [];
+        toolCount = toolList.length;
+        newTools = toolList.map((t) => ({ name: t.name, hash: hashTool(t.name, t.inputSchema) }));
+    }
+    catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+        notes.push(`Check failed: ${error}`);
+    }
+    finally {
+        if (client) {
+            try {
+                await client.close();
+            }
+            catch {
+                /* ignore close errors */
+            }
+        }
+    }
+    latency.total = Math.round(performance.now() - t0);
+    // Drift is only meaningful when we actually retrieved the current tool list.
+    const currentTools = toolsListOk ? newTools : prior.tools;
+    const drift = computeDrift(prior.tools, currentTools);
+    const fingerprint = toolsListOk ? fingerprintTools(newTools) : prior.fingerprint ?? "";
+    if (toolsListOk && prior.fingerprint && drift.drift) {
+        notes.push(`Schema drift detected: +${drift.added.length} added, -${drift.removed.length} removed, ~${drift.changed.length} changed`);
+    }
+    const status = determineStatus({ reachable, handshakeOk, toolsListOk, toolCount, latency, target, drift: drift.drift, notes });
+    const result = {
+        targetId: target.id,
+        label: target.label,
+        status,
+        timestamp,
+        reachable,
+        handshakeOk,
+        toolsListOk,
+        toolCount,
+        latencyMs: latency,
+        serverInfo,
+        schema: {
+            fingerprint,
+            drift: drift.drift,
+            added: drift.added,
+            removed: drift.removed,
+            changed: drift.changed,
+        },
+        notes,
+        error,
+    };
+    return { result, tools: currentTools };
+}
+function determineStatus(args) {
+    const { reachable, handshakeOk, toolsListOk, toolCount, latency, target, drift, notes } = args;
+    if (!reachable || !handshakeOk || !toolsListOk)
+        return "down";
+    let status = "up";
+    if (target.minTools !== undefined && toolCount < target.minTools) {
+        status = "degraded";
+        notes.push(`Tool count ${toolCount} below expected minimum ${target.minTools}`);
+    }
+    if (target.latencyBudgetMs !== undefined && latency.total > target.latencyBudgetMs) {
+        status = "degraded";
+        notes.push(`Latency ${latency.total}ms exceeds budget ${target.latencyBudgetMs}ms`);
+    }
+    if (drift)
+        status = "degraded";
+    return status;
+}
+function makeTransport(target) {
+    const tr = target.transport;
+    if (tr.type === "stdio") {
+        return new StdioClientTransport({
+            command: tr.command,
+            args: tr.args ?? [],
+            env: { ...stringEnv(process.env), ...(tr.env ?? {}) },
+            stderr: "ignore",
+        });
+    }
+    return new StreamableHTTPClientTransport(new URL(tr.url), {
+        requestInit: tr.headers ? { headers: tr.headers } : undefined,
+    });
+}
+function stringEnv(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (typeof v === "string")
+            out[k] = v;
+    }
+    return out;
+}
+function hashTool(name, inputSchema) {
+    return createHash("sha256").update(`${name}\n${stableStringify(inputSchema)}`).digest("hex").slice(0, 16);
+}
+function fingerprintTools(tools) {
+    const joined = tools.map((t) => `${t.name}:${t.hash}`).sort().join("|");
+    return createHash("sha256").update(joined).digest("hex").slice(0, 16);
+}
+/** Deterministic JSON so semantically-equal schemas hash identically. */
+function stableStringify(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v) ?? "null";
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(",")}]`;
+    const obj = v;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}
+function computeDrift(prev, next) {
+    const prevMap = new Map(prev.map((t) => [t.name, t.hash]));
+    const nextMap = new Map(next.map((t) => [t.name, t.hash]));
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const [name, hash] of nextMap) {
+        if (!prevMap.has(name))
+            added.push(name);
+        else if (prevMap.get(name) !== hash)
+            changed.push(name);
+    }
+    for (const name of prevMap.keys()) {
+        if (!nextMap.has(name))
+            removed.push(name);
+    }
+    const drift = prev.length > 0 && (added.length > 0 || removed.length > 0 || changed.length > 0);
+    return { drift, added, removed, changed };
+}
+async function withTimeout(p, ms, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`Timed out after ${ms}ms during ${label}`)), ms);
+    });
+    try {
+        return await Promise.race([p, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/orchestrate.js

@@ -0,0 +1,33 @@
+import { loadConfig } from "./config.js";
+import { runCheck } from "./monitor.js";
+import { readState, writeState } from "./state.js";
+export function configPath() {
+    return process.env.SENTINEL_CONFIG || "sentinel.config.json";
+}
+/**
+ * Check one target (by id) or all of them, persisting history + schema baseline.
+ * Returns the results in config order.
+ */
+export async function checkTargets(filterId) {
+    const { targets } = loadConfig(configPath());
+    const selected = filterId ? targets.filter((t) => t.id === filterId) : targets;
+    if (filterId && selected.length === 0) {
+        throw new Error(`No target matched id: ${filterId}`);
+    }
+    const results = [];
+    for (const target of selected) {
+        const prior = readState(target.id);
+        const { result, tools } = await runCheck(target, {
+            fingerprint: prior?.lastFingerprint ?? null,
+            tools: prior?.lastTools ?? [],
+        });
+        writeState({
+            targetId: target.id,
+            lastFingerprint: result.schema.fingerprint || (prior?.lastFingerprint ?? null),
+            lastTools: tools,
+            history: [...(prior?.history ?? []), result],
+        });
+        results.push(result);
+    }
+    return results;
+}

package/dist/report.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { checkTargets } from "./orchestrate.js";
+const DEFAULT_OUT_DIR = "../web";
+async function main() {
+    const outDir = resolve(process.cwd(), process.argv[2] ?? DEFAULT_OUT_DIR);
+    const results = await checkTargets();
+    const report = buildReport(results);
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(resolve(outDir, "status.json"), JSON.stringify(report, null, 2));
+    writeFileSync(resolve(outDir, "status.html"), renderHtml(report));
+    console.log(`Wrote ${resolve(outDir, "status.json")}`);
+    console.log(`Wrote ${resolve(outDir, "status.html")}`);
+}
+function buildReport(targets) {
+    const up = targets.filter((r) => r.status === "up").length;
+    const degraded = targets.filter((r) => r.status === "degraded").length;
+    const down = targets.filter((r) => r.status === "down").length;
+    const latencies = targets.map((r) => r.latencyMs.total).filter((n) => Number.isFinite(n));
+    const averageLatencyMs = latencies.length
+        ? Math.round(latencies.reduce((sum, n) => sum + n, 0) / latencies.length)
+        : null;
+    return {
+        generatedAt: new Date().toISOString(),
+        summary: {
+            total: targets.length,
+            up,
+            degraded,
+            down,
+            availabilityPct: targets.length ? Math.round(((up + degraded) / targets.length) * 1000) / 10 : 0,
+            driftCount: targets.filter((r) => r.schema.drift).length,
+            averageLatencyMs,
+        },
+        targets,
+    };
+}
+function renderHtml(report) {
+    const rows = report.targets.map(renderRow).join("\n");
+    const generated = new Date(report.generatedAt).toLocaleString("en-US", {
+        dateStyle: "medium",
+        timeStyle: "short",
+    });
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>MegaMCP Sentinel Status</title>
+<style>
+  :root{--ink:#13110E;--bone:#EDE8DC;--steel:#6E675C;--molten:#FF4D17;--line:rgba(237,232,220,.16);--panel:#1A1712}
+  *{box-sizing:border-box} body{margin:0;background:var(--ink);color:var(--bone);font-family:Inter,system-ui,sans-serif;line-height:1.45}
+  main{max-width:1120px;margin:0 auto;padding:40px 24px 70px}
+  a{color:inherit}.brand{font-weight:800;letter-spacing:-.04em;font-size:20px}.brand span{background:var(--molten);color:var(--ink);padding:1px 8px;border-radius:5px;margin-left:1px}
+  header{display:flex;justify-content:space-between;gap:24px;align-items:flex-start;border-bottom:1px solid var(--line);padding-bottom:28px;margin-bottom:28px}
+  h1{font-size:clamp(38px,7vw,76px);line-height:.95;letter-spacing:-.06em;margin:28px 0 14px}.sub{color:#A39B8E;max-width:700px;font-size:18px}
+  .stamp{font-family:ui-monospace,Menlo,monospace;color:#A39B8E;font-size:13px;text-align:right}.grid{display:grid;grid-template-columns:repeat(5,1fr);gap:12px;margin:28px 0}
+  .metric{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:18px}.metric b{display:block;font-size:28px;letter-spacing:-.04em}.metric span{font-family:ui-monospace,Menlo,monospace;color:#A39B8E;font-size:12px;text-transform:uppercase}
+  table{width:100%;border-collapse:collapse;background:var(--panel);border:1px solid var(--line);border-radius:12px;overflow:hidden}th,td{text-align:left;padding:15px;border-bottom:1px solid var(--line);vertical-align:top}th{font-family:ui-monospace,Menlo,monospace;color:#A39B8E;font-size:12px;text-transform:uppercase}tr:last-child td{border-bottom:0}
+  .status{font-family:ui-monospace,Menlo,monospace;font-size:12px;font-weight:800;padding:4px 8px;border-radius:5px}.up{background:rgba(70,199,120,.16);color:#7FE0A6}.degraded{background:rgba(255,194,75,.16);color:#FFC24B}.down{background:rgba(255,77,23,.18);color:#FF7A4D}
+  .muted{color:#A39B8E}.mono{font-family:ui-monospace,Menlo,monospace;font-size:13px}@media(max-width:800px){header{display:block}.stamp{text-align:left}.grid{grid-template-columns:1fr 1fr}table{display:block;overflow-x:auto}}
+</style>
+</head>
+<body>
+<main>
+  <header>
+    <div>
+      <div class="brand">MEGA<span>MCP</span></div>
+      <h1>Sentinel status</h1>
+      <p class="sub">Protocol-native health checks for MCP servers: initialize, tools/list, latency, tool inventory, and schema drift.</p>
+    </div>
+    <div class="stamp">Generated<br>${escapeHtml(generated)}</div>
+  </header>
+  <section class="grid" aria-label="Summary metrics">
+    <div class="metric"><b>${report.summary.total}</b><span>targets</span></div>
+    <div class="metric"><b>${report.summary.up}</b><span>up</span></div>
+    <div class="metric"><b>${report.summary.degraded}</b><span>degraded</span></div>
+    <div class="metric"><b>${report.summary.down}</b><span>down</span></div>
+    <div class="metric"><b>${report.summary.averageLatencyMs ?? "-"}${report.summary.averageLatencyMs === null ? "" : "ms"}</b><span>avg latency</span></div>
+  </section>
+  <table>
+    <thead><tr><th>Status</th><th>Target</th><th>Tools</th><th>Latency</th><th>Schema</th><th>Notes</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table>
+</main>
+</body>
+</html>
+`;
+}
+function renderRow(r) {
+    const drift = r.schema.drift
+        ? `+${r.schema.added.length} -${r.schema.removed.length} ~${r.schema.changed.length}`
+        : "no drift";
+    const notes = [...r.notes, r.error ? `Error: ${r.error}` : ""].filter(Boolean).join("; ");
+    return `<tr>
+    <td><span class="status ${r.status}">${r.status.toUpperCase()}</span></td>
+    <td><strong>${escapeHtml(r.label)}</strong><div class="muted mono">${escapeHtml(r.targetId)}</div></td>
+    <td class="mono">${r.toolCount}</td>
+    <td class="mono">${r.latencyMs.total}ms<div class="muted">connect ${r.latencyMs.connect ?? "-"}ms / list ${r.latencyMs.toolsList ?? "-"}ms</div></td>
+    <td class="mono">${escapeHtml(drift)}<div class="muted">${escapeHtml(r.schema.fingerprint || "no fingerprint")}</div></td>
+    <td class="muted">${escapeHtml(notes || "clear")}</td>
+  </tr>`;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/dist/sample-target/echo-server.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// A minimal MCP server used as a local, dependency-free monitoring target
+// so Sentinel's full loop can be demonstrated live.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const server = new Server({ name: "echo-sample", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "echo",
+            description: "Echo back the provided message.",
+            inputSchema: {
+                type: "object",
+                properties: { message: { type: "string" } },
+                required: ["message"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "ping",
+            description: "Health ping.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        },
+        {
+            name: "reverse",
+            description: "Reverse the provided string.",
+            inputSchema: {
+                type: "object",
+                properties: { text: { type: "string" } },
+                required: ["text"],
+                additionalProperties: false,
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const args = (req.params.arguments ?? {});
+    if (name === "echo") {
+        return { content: [{ type: "text", text: String(args.message ?? "") }] };
+    }
+    if (name === "ping") {
+        return { content: [{ type: "text", text: "pong" }] };
+    }
+    if (name === "reverse") {
+        return { content: [{ type: "text", text: String(args.text ?? "").split("").reverse().join("") }] };
+    }
+    return { content: [{ type: "text", text: `unknown tool ${name}` }], isError: true };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("echo-sample MCP server running");

package/dist/server.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// Sentinel exposed AS an MCP server — an MCP server that monitors MCP servers.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig } from "./config.js";
+import { checkTargets, configPath } from "./orchestrate.js";
+import { readState } from "./state.js";
+const server = new Server({ name: "megamcp-sentinel", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "list_targets",
+            description: "List all MCP servers Sentinel is configured to monitor.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        },
+        {
+            name: "check_target",
+            description: "Run a live health check against a monitored MCP server (or all of them). " +
+                "Returns status, latency, tool count, and schema-drift.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    targetId: { type: "string", description: "Target id to check; omit to check all." },
+                },
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "health_summary",
+            description: "Most recent stored status across all monitored MCP servers (no live check).",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const args = (req.params.arguments ?? {});
+    try {
+        if (name === "list_targets") {
+            const { targets } = loadConfig(configPath());
+            return text(JSON.stringify(targets.map((t) => ({ id: t.id, label: t.label, transport: t.transport.type })), null, 2));
+        }
+        if (name === "check_target") {
+            const targetId = typeof args.targetId === "string" ? args.targetId : undefined;
+            const results = await checkTargets(targetId);
+            return text(JSON.stringify(results, null, 2));
+        }
+        if (name === "health_summary") {
+            const { targets } = loadConfig(configPath());
+            const summary = targets.map((t) => {
+                const st = readState(t.id);
+                const last = st?.history?.[st.history.length - 1];
+                return {
+                    id: t.id,
+                    label: t.label,
+                    status: last?.status ?? "unknown",
+                    lastChecked: last?.timestamp ?? null,
+                    tools: last?.toolCount ?? null,
+                };
+            });
+            return text(JSON.stringify(summary, null, 2));
+        }
+        return text(`Unknown tool: ${name}`, true);
+    }
+    catch (e) {
+        return text(`Error: ${e instanceof Error ? e.message : String(e)}`, true);
+    }
+});
+function text(s, isError = false) {
+    return { content: [{ type: "text", text: s }], isError };
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("megamcp-sentinel MCP server running on stdio");
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/state.js

@@ -0,0 +1,26 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+const STATE_DIR = resolve(process.cwd(), "state");
+const HISTORY_CAP = 200;
+function fileFor(id) {
+    // sanitize id for filesystem safety
+    const safe = id.replace(/[^a-z0-9_-]/gi, "_");
+    return join(STATE_DIR, `${safe}.json`);
+}
+export function readState(id) {
+    const f = fileFor(id);
+    if (!existsSync(f))
+        return null;
+    try {
+        return JSON.parse(readFileSync(f, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(state) {
+    if (!existsSync(STATE_DIR))
+        mkdirSync(STATE_DIR, { recursive: true });
+    const capped = { ...state, history: state.history.slice(-HISTORY_CAP) };
+    writeFileSync(fileFor(state.targetId), JSON.stringify(capped, null, 2));
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Core domain types for Sentinel — the MCP-server health monitor.
+export {};

package/docs-run-production.md

@@ -0,0 +1,27 @@
+# Running Sentinel in production (Windows)
+
+`run-check.ps1` runs every configured check once and appends a timestamped JSON record to `logs/runs.jsonl`. Per-target rolling history is also kept in `state/`.
+
+## Enable 24/7 monitoring (every 15 minutes, hidden)
+
+Run this once in PowerShell (it sets up a recurring Scheduled Task — OS-level persistence, so it needs your authorization):
+
+```powershell
+schtasks /Create /TN "MegaMCP Sentinel" `
+  /TR "powershell.exe -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File `"$env:USERPROFILE\Desktop\MegaMCP\sentinel\run-check.ps1`"" `
+  /SC MINUTE /MO 15 /F
+```
+
+## Check / run / disable
+
+```powershell
+schtasks /Query  /TN "MegaMCP Sentinel" /FO LIST   # status + next run
+schtasks /Run    /TN "MegaMCP Sentinel"            # run now
+schtasks /Delete /TN "MegaMCP Sentinel" /F         # remove it
+```
+
+## Where results go
+- `logs/runs.jsonl` — one JSON object per run: `{ at, results: [...] }`
+- `state/<target>.json` — rolling per-target history + last-known tool schema (for drift)
+
+When the hosted version ships, this same wrapper logic moves to a server-side cron / Vercel Cron / GitHub Action feeding the public status board.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@megamcp/sentinel",
+  "version": "0.1.0",
+  "description": "MegaMCP Sentinel — an MCP server that monitors the health of other MCP servers.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "files": [
+    "dist/",
+    "README.md",
+    "docs-run-production.md",
+    "run-check.ps1",
+    "sentinel.config.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "megamcp-sentinel": "dist/cli.js",
+    "megamcp-inspect": "dist/inspect.js",
+    "megamcp-sentinel-report": "dist/report.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "start": "node dist/server.js",
+    "check": "node dist/cli.js check",
+    "watch": "node dist/cli.js watch",
+    "inspect": "node dist/inspect.js",
+    "report": "node dist/report.js",
+    "sample": "node dist/sample-target/echo-server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/server-everything": "^2026.1.26",
+    "@modelcontextprotocol/server-memory": "^2026.1.26",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "typescript": "^5.9.3"
+  }
+}

package/run-check.ps1

@@ -0,0 +1,13 @@
+# MegaMCP Sentinel - production check wrapper (for Windows Task Scheduler).
+# Runs all configured checks and appends one timestamped JSON line to logs\runs.jsonl.
+$ErrorActionPreference = 'Continue'
+$node = Join-Path $env:LOCALAPPDATA 'Programs\nodejs'
+$env:Path = "$node;$env:Path"
+$proj = Split-Path -Parent $MyInvocation.MyCommand.Definition
+Set-Location $proj
+New-Item -ItemType Directory -Force (Join-Path $proj 'logs') | Out-Null
+$stamp = (Get-Date).ToString('o')
+$out = (& node 'dist\cli.js' check --json) -join "`n"
+try { $parsed = $out | ConvertFrom-Json } catch { $parsed = @{ error = 'check failed'; raw = $out } }
+$line = [pscustomobject]@{ at = $stamp; results = $parsed } | ConvertTo-Json -Depth 8 -Compress
+Add-Content -Path (Join-Path $proj 'logs\runs.jsonl') -Value $line

package/sentinel.config.json

@@ -0,0 +1,50 @@
+{
+  "targets": [
+    {
+      "id": "echo-sample",
+      "label": "Echo Sample (bundled demo)",
+      "transport": {
+        "type": "stdio",
+        "command": "node",
+        "args": ["dist/sample-target/echo-server.js"]
+      },
+      "minTools": 2,
+      "latencyBudgetMs": 4000
+    },
+    {
+      "id": "ref-everything",
+      "label": "MCP Reference: everything",
+      "transport": { "type": "stdio", "command": "node", "args": ["node_modules/@modelcontextprotocol/server-everything/dist/index.js"] },
+      "minTools": 1,
+      "latencyBudgetMs": 8000,
+      "timeoutMs": 40000
+    },
+    {
+      "id": "ref-memory",
+      "label": "MCP Reference: memory",
+      "transport": { "type": "stdio", "command": "node", "args": ["node_modules/@modelcontextprotocol/server-memory/dist/index.js"] },
+      "minTools": 1,
+      "latencyBudgetMs": 8000,
+      "timeoutMs": 40000
+    }
+  ],
+  "_examples": {
+    "_comment": "Keys starting with _ are ignored by the loader. Copy these shapes into 'targets'.",
+    "http_target": {
+      "id": "my-remote-mcp",
+      "label": "My Remote MCP (HTTP)",
+      "transport": {
+        "type": "http",
+        "url": "https://example.com/mcp",
+        "headers": { "Authorization": "Bearer ${TOKEN}" }
+      },
+      "minTools": 1,
+      "latencyBudgetMs": 5000
+    },
+    "stdio_target": {
+      "id": "some-local-mcp",
+      "label": "Some Local MCP (stdio)",
+      "transport": { "type": "stdio", "command": "npx", "args": ["-y", "@scope/some-mcp-server"] }
+    }
+  }
+}