health-monitor-mcp

# health-monitor-mcp

> MCP server, CI workflow, and generic HTTP endpoint monitoring with health history, TLS expiry, assertions, diagnostics, and operational reports.

[![CI](https://github.com/oaslananka/health-monitor-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/oaslananka/health-monitor-mcp/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/oaslananka/health-monitor-mcp/graph/badge.svg)](https://codecov.io/gh/oaslananka/health-monitor-mcp)
[![Release](https://github.com/oaslananka/health-monitor-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/oaslananka/health-monitor-mcp/actions/workflows/release.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/oaslananka/health-monitor-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/oaslananka/health-monitor-mcp)
[![Node.js](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)

## What This Does

`health-monitor-mcp` keeps local registries of MCP servers, GitHub Actions workflows, GitLab pipelines, and generic HTTP endpoints. It performs live checks, records bounded evidence in SQLite, evaluates MCP alert thresholds, and returns JSON or Markdown diagnostics suitable for agents and operators.

Supported target transports:

- **Streamable HTTP** for current remote MCP servers.
- **SSE** for legacy MCP servers.
- **stdio** for trusted local executables after explicit opt-in.
- **GitHub Actions** workflow runs, failed jobs, and failed steps for public or private repositories.
- **GitLab CI/CD** pipelines, failed jobs, stages, refs, commits, URLs, and bounded trace excerpts for GitLab.com or allowlisted self-hosted instances.
- **Generic HTTP/HTTPS** endpoints with status, header, body-substring, JSON-value, redirect, latency, and TLS-expiry checks.

Azure DevOps monitoring was retired in v1.1.0. GitHub Actions shipped in v1.2.0 and GitLab CI/CD in v1.3.0; generic HTTP/TLS monitoring completes the current multi-provider feature line.

## Quick Start

Run the published package noninteractively with Node.js 24:

```bash
npx -y health-monitor-mcp --version
```

Example MCP client configuration:

```json
{
  "mcpServers": {
    "health-monitor": {
      "command": "npx",
      "args": ["-y", "health-monitor-mcp"]
    }
  }
}
```

## Tools

| Tool                         | Purpose                                                 | Typical prompt                          |
| ---------------------------- | ------------------------------------------------------- | --------------------------------------- |
| `register_server`            | Register an MCP target                                  | `Register inventory-prod`               |
| `check_server`               | Run one MCP health check                                | `Check inventory-prod now`              |
| `register_github_actions`    | Register a GitHub workflow                              | `Monitor ci.yml in owner/repo`          |
| `check_github_actions`       | Check latest GitHub run and failed job/step diagnostics | `Check repo-ci now`                     |
| `register_gitlab_pipeline`   | Register a GitLab project pipeline                      | `Monitor group/project on GitLab`       |
| `check_gitlab_pipeline`      | Check latest pipeline and bounded failed-job traces     | `Check gitlab-ci now`                   |
| `register_http_target`       | Register a GET-only HTTP/HTTPS endpoint                 | `Monitor the public health endpoint`    |
| `check_http_target`          | Check response assertions and TLS expiry                | `Check service-health now`              |
| `check_all`                  | Check all target kinds with bounded concurrency         | `Check all production targets`          |
| `get_uptime`                 | Return MCP uptime and latency history                   | `Show 24h uptime for inventory-prod`    |
| `get_dashboard`              | Return a cross-provider JSON dashboard                  | `Give me a 24h dashboard`               |
| `get_report`                 | Return a cross-provider Markdown report                 | `Generate a 24h health report`          |
| `list_servers`               | List registered MCP targets                             | `List monitored MCP servers`            |
| `list_github_actions`        | List registered GitHub workflow targets                 | `List monitored workflows`              |
| `list_gitlab_pipelines`      | List registered GitLab pipeline targets                 | `List monitored GitLab pipelines`       |
| `list_http_targets`          | List registered HTTP targets                            | `List monitored HTTP endpoints`         |
| `unregister_server`          | Remove an MCP target                                    | `Stop monitoring local-debugger`        |
| `unregister_github_actions`  | Remove a GitHub target and its history                  | `Stop monitoring repo-ci`               |
| `unregister_gitlab_pipeline` | Remove a GitLab target and its history                  | `Stop monitoring gitlab-ci`             |
| `unregister_http_target`     | Remove an HTTP target and its history                   | `Stop monitoring service-health`        |
| `set_alert`                  | Configure MCP health thresholds                         | `Alert if inventory-prod exceeds 500ms` |
| `get_monitor_stats`          | Inspect cross-provider monitor activity                 | `How many checks are stored?`           |

Expected configuration mistakes return stable error codes and remediation hints, including `SERVER_NOT_FOUND`, `GITHUB_ACTIONS_TARGET_NOT_FOUND`, `GITLAB_PIPELINE_TARGET_NOT_FOUND`, `GITLAB_BASE_URL_NOT_ALLOWED`, `HTTP_TARGET_NOT_FOUND`, `HTTP_TARGET_URL_NOT_ALLOWED`, `NO_SERVERS_REGISTERED`, `STDIO_DISABLED`, and `STDIO_COMMAND_REJECTED`.

## Register Targets

Streamable HTTP:

```text
register_server name="inventory-prod" type="http" url="https://inventory.example.com/mcp" tags=["production","inventory"]
```

Legacy SSE:

```text
register_server name="legacy-search" type="sse" url="https://search.example.com/sse" tags=["legacy"]
```

Trusted local stdio:

```bash
export HEALTH_MONITOR_ALLOW_STDIO=1
export HEALTH_MONITOR_STDIO_ALLOWLIST=npx,node
```

```text
register_server name="local-debugger" type="stdio" command="npx" args=["-y","mcp-debug-recorder"] tags=["local"]
```

The `command` field must contain one executable only. Put package names and flags in `args`. Remote-safe runtime profiles always disable stdio.

## Register GitHub Actions

Public repositories can be checked without authentication. Private repositories and higher API rate limits require a token with Actions read access:

```bash
export GITHUB_TOKEN=your-runtime-secret
```

```text
register_github_actions name="repo-ci" owner="oaslananka" repository="health-monitor-mcp" workflow="ci.yml" branch="main" token_env="GITHUB_TOKEN" tags=["production","ci"]
check_github_actions name="repo-ci" timeout_ms=5000
```

Only the environment-variable name in `token_env` is stored. The token value is read at check time and is never written to SQLite, logs, reports, or tool responses.

## Register GitLab Pipelines

Public GitLab.com projects can be checked without authentication. Private projects require a token exposed only through the runtime environment:

```bash
export GITLAB_TOKEN=your-runtime-secret
```

```text
register_gitlab_pipeline name="gitlab-ci" project="group/project" ref="main" token_env="GITLAB_TOKEN" tags=["production","ci"]
check_gitlab_pipeline name="gitlab-ci" timeout_ms=5000
```

GitLab.com is allowed by default. A self-hosted instance must use an HTTPS origin and be explicitly allowed:

```bash
export HEALTH_MONITOR_GITLAB_BASE_URL_ALLOWLIST=https://gitlab.internal.example
```

```text
register_gitlab_pipeline name="private-gitlab" base_url="https://gitlab.internal.example" project="platform/service" token_env="GITLAB_TOKEN"
```

Only `token_env` is persisted. Token values, response bodies, and full traces are never stored or returned. Failed-job trace excerpts are range-requested, sanitized, and bounded.

## Register HTTP Targets

Public HTTP and HTTPS endpoints are allowed by default. The provider sends GET requests only and supports bounded status, header, body-substring, JSON scalar, and TLS-expiry assertions:

```text
register_http_target name="service-health" url="https://status.example.com/health" expected_statuses=[200] header_assertions=[{"name":"x-ready","equals":"yes"}] body_contains=["ready"] json_assertions=[{"path":"status","equals":"ready"}] tls_expiry_days=30 tags=["production","http"]
check_http_target name="service-health" timeout_ms=5000
```

Private, loopback, link-local, and other non-public addresses are blocked. A trusted private origin is available only in the `full` runtime profile and must be explicitly listed:

```bash
export HEALTH_MONITOR_HTTP_TARGET_ALLOWLIST=https://status.internal.example:8443
```

Every DNS answer and every redirect destination is revalidated. Responses are capped at 262144 bytes; full response bodies and certificate chains are never stored or returned.

## Health Checks and Reports

```text
check_server name="inventory-prod" timeout_ms=5000
check_all timeout_ms=5000 tags=["production"]
get_uptime name="inventory-prod" hours=24
get_dashboard hours=24 include_tool_stats=true
get_report hours=24
```

`HEALTH_MONITOR_MAX_CONCURRENCY` limits MCP, GitHub Actions, GitLab, and HTTP checks through one shared scheduled and interactive queue. Results preserve MCP-then-GitHub-then-GitLab-then-HTTP registration order even when checks complete out of order.

## Alerts

```text
set_alert name="inventory-prod" max_response_time_ms=500 min_uptime_percent=99 consecutive_failures_before_alert=2
```

Alert findings are evaluated by `check_server`, `check_all`, and `get_dashboard`. Outbound webhook delivery is not yet exposed as a p