Health Monitor

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

CI codecov Release License: MIT OpenSSF Scorecard Node.js

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:

npx -y health-monitor-mcp --version

Example MCP client configuration:

{
  "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:

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

Legacy SSE:

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

Trusted local stdio:

export HEALTH_MONITOR_ALLOW_STDIO=1
export HEALTH_MONITOR_STDIO_ALLOWLIST=npx,node

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:

export GITHUB_TOKEN=your-runtime-secret

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:

export GITLAB_TOKEN=your-runtime-secret

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:

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

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:

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:

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

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

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 public MCP tool.

Configuration

Variable	Default	Purpose
HEALTH_MONITOR_DB	~/.mcp-health-monitor/health.db	SQLite database path
HEALTH_MONITOR_AUTO_CHECK	0	Enable scheduled checks with 1
HEALTH_MONITOR_RETENTION_DAYS	30	Health-history retention
HEALTH_MONITOR_MAX_CONCURRENCY	5	Scheduled and interactive check concurrency
GITHUB_TOKEN	unset	Optional GitHub Actions read token
GITLAB_TOKEN	unset	Optional GitLab project/pipeline/job read token
HEALTH_MONITOR_GITLAB_BASE_URL_ALLOWLIST	unset	Allowed self-hosted GitLab HTTPS origins
HEALTH_MONITOR_HTTP_TARGET_ALLOWLIST	unset	Private HTTP(S) origins allowed in full profile
HEALTH_MONITOR_ALLOW_STDIO	0	Allow trusted local stdio checks
HEALTH_MONITOR_STDIO_ALLOWLIST	unset	Optional comma-separated executable allowlist
HEALTH_MONITOR_HTTP_TOKEN	unset	Bearer token for POST /mcp
HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST	unset	Allowed remote client origins
HEALTH_MONITOR_HTTP_MAX_BODY_BYTES	1048576	Maximum inbound MCP body
HEALTH_MONITOR_HTTP_BODY_TIMEOUT_MS	15000	Inbound body read timeout
HEALTH_MONITOR_HTTP_STATEFUL_SESSIONS	0	Enable stateful Streamable HTTP sessions
HEALTH_MONITOR_HTTP_SESSION_TTL_MS	1800000	Stateful session TTL
HEALTH_MONITOR_HTTP_MAX_SESSIONS	100	Stateful session cap

HTTP Deployment

The server binds to 127.0.0.1 by default. A non-loopback bind requires a remote-safe profile, bearer token, and Origin allowlist.

HOST=0.0.0.0 \
HEALTH_MONITOR_PROFILE=remote-safe \
HEALTH_MONITOR_HTTP_TOKEN=change-me \
HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST=https://client.example \
npx -y health-monitor-mcp-http

GET /health is unauthenticated and exposes only status and version. POST /mcp requires Authorization: Bearer <token>.

Docker

Persist /data; otherwise the SQLite database disappears with the container.

docker volume create health-monitor-data

docker run --rm \
  -v health-monitor-data:/data \
  -p 127.0.0.1:3000:3000 \
  -e HOST=0.0.0.0 \
  -e HEALTH_MONITOR_PROFILE=remote-safe \
  -e HEALTH_MONITOR_HTTP_TOKEN=change-me \
  -e HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST=https://client.example \
  ghcr.io/oaslananka/health-monitor-mcp:latest

Development

The repository pins Node.js 24.18.0 and pnpm 11.14.0 through .mise.toml.

mise trust
mise install
pnpm install --frozen-lockfile
pnpm run ci

Useful gates:

pnpm run build
pnpm run typecheck
pnpm run lint
pnpm run lint:test
pnpm run test:coverage
pnpm run test:integration
pnpm run docs:api:check
pnpm run security:supply-chain
pnpm run check:metadata
pnpm run check:package

Coverage and Test Analytics

Jest remains the blocking coverage gate with repository-local thresholds. The CI validation job runs all unit and integration tests once, writes coverage/lcov.info and reports/junit/junit.xml, and uploads both reports to Codecov. Codecov project and patch statuses start as informational with target: auto and a 1% tolerance, adding pull-request diff coverage, file-level visibility, and failed-test analytics without duplicating the local merge gate.

Codecov Bundle Analysis is intentionally not enabled. This package ships Node.js entrypoints compiled with tsc; it does not currently produce a Rollup, Vite, or Webpack application bundle whose download size is a product metric.

Architecture and Roadmap

• Architecture
• Operations
• Security
• Usage
• Roadmap
• Release process
• Generated API reference

Agent Runtime Configuration

This repository owns its product-specific MCP configuration, plugin manifest, and skills:

File	Purpose
.claude-plugin/plugin.json	Claude Code plugin manifest
.mcp.json	Project-local MCP configuration
.codex/config.example.toml	Codex CLI example
.vscode/mcp.example.json	VS Code / Copilot example
opencode.example.jsonc	OpenCode example
skills/	Product-specific monitoring workflows
docs/agent-runtime-config.md	Runtime setup and validation

Security and Contributing

Report vulnerabilities through GitHub Private Vulnerability Reporting. See SECURITY.md and docs/security.md.

Contribution setup and standards are documented in docs/contributing.md. Usage questions belong in GitHub Discussions; actionable work belongs in issues.

License

MIT