aethernet/problems-mcp
Watch
0
0
Fork
You've already forked problems-mcp
 0
Code Issues Pull requests Projects Releases Packages Activity
MCP and CLI to get the list of problems in my homelab
22 commits 1 branch 0 tags 152 KiB
  • Ruby 96.8%
  • Dockerfile 3%
  • Shell 0.2%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Nogweii 9949b7375c gatus: read the newest result, not the oldest 
Gatus returns endpoint results oldest-first, so results.first is the oldest
retained ping rather than the current state. An endpoint that failed once and
then recovered kept being reported as down until the failure aged out of the
results window (~200 samples), which at a 60s interval is over three hours of
false CRITICALs for a service that is perfectly healthy.

Hit this while fixing the AI Conversation Agent check: the watchdog logged 38
consecutive successes after the endpoint moved to /v1/health, but the report
still said "AI Conversation Agent is down (HTTP 415)" because the oldest
retained ping was still the pre-fix 415.

The existing fixture could not catch this: every endpoint in it is uniformly
all-pass or all-fail, where first and last agree by accident. The new fixture
includes a recovered endpoint with old failures followed by recent successes,
and the ordering test pins the oldest-first contract so this cannot silently
come back if Gatus changes it. Verified the new tests fail against the old
.first code and pass against the fix.
2026-10-12 15:34:16 -07:00
bin Initial commit from bundle gem 2026-09-20 16:37:06 -07:00
exe check-problems: exit code 2 if there are any problems 2026-09-27 22:04:46 -07:00
lib/problems gatus: read the newest result, not the oldest 2026-10-12 15:34:16 -07:00
sig/problems Initial commit from bundle gem 2026-09-20 16:37:06 -07:00
test gatus: read the newest result, not the oldest 2026-10-12 15:34:16 -07:00
.dockerignore docker: add 3-stage Dockerfile with Arch Linux and fix IPv6 binding 2026-09-20 17:44:00 -07:00
.gitignore ignore config.yaml 2026-09-20 18:27:07 -07:00
.gitlab-ci.yml Initial commit from bundle gem 2026-09-20 16:37:06 -07:00
.standard.yml Initial commit from bundle gem 2026-09-20 16:37:06 -07:00
CHANGELOG.md Initial commit from bundle gem 2026-09-20 16:37:06 -07:00
config.sample.yml source: add Gatus uptime checks source 2026-09-20 17:53:20 -07:00
Dockerfile docker: use base-devel for build stages and tighten .dockerignore 2026-09-20 17:48:19 -07:00
Gemfile test: add realistic fixtures from real API responses 2026-09-20 18:04:27 -07:00
Gemfile.lock test: add realistic fixtures from real API responses 2026-09-20 18:04:27 -07:00
problems-mcp.gemspec docker: add 3-stage Dockerfile with Arch Linux and fix IPv6 binding 2026-09-20 17:44:00 -07:00
Rakefile some updates to the README and update minitest 2026-09-20 16:51:17 -07:00
README.md drop the push-to-rubygems text 2026-09-20 17:08:50 -07:00

README.md

Problems (MCP)

An MCP server to expose a list of problems in my homelab. That way I can have an interactive conversation about all of the problems my homelab is experiencing.

Supported sources of problems:

  • Prometheus alerts via AlertManager
  • Kubernetes pod status
  • Flux CD Kustomization and HelmRelease
  • Healthchecks.io jobs

Installation

Container

docker build -t problems-mcp .

From source

bundle install
bundle exec rake install

Usage

Run the server with the appropriate configuration:

# Using default settings (no sources configured)
bundle exec problems-mcp

# With a custom config file
bundle exec problems-mcp --config config.yml

# Custom host and port
bundle exec problems-mcp --host 127.0.0.1 --port 8080

Configuration

Create a YAML config file with your sources:

# config.yml

# Alertmanager source
- type: alertmanager
  name: Alertmanager
  api_url: "http://alertmanager:9093/"
  group_by: true  # Group alerts by labels

# Kubernetes source
- type: kubernetes
  name: Kubernetes
  kubeconfig_path: ~/.kube/config  # Optional, defaults to ~/.kube/config
  api_server: https://kubernetes.default.svc  # Optional

# Flux source
- type: flux
  name: Flux
  kubeconfig_path: ~/.kube/config
  api_server: https://kubernetes.default.svc

# Healthchecks.io source
- type: healthchecks
  name: Healthchecks.io
  api_key: "your-api-key-here"
  api_url: https://healthchecks.io/api/v1/checks  # Optional

A sample config is available at config.sample.yml.

Available Tools

The MCP server exposes the following tools:

Tool Description
list_problems List all active problems from all configured sources (optional filters: severity, source)
get_problems_by_source Get problems from a specific source (required: source)
get_critical_problems Get all critical severity problems
refresh_problems Force refresh problems from all sources

Docker

# Build
docker build -t problems-mcp .

# Run with config
docker run -v $(pwd)/config.yml:/app/config.yml -p 3000:3000 problems-mcp --config /app/config.yml

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run:

bundle exec rake release

This will create a git tag for the version, push git commits and the created tag.

Contributing

Bug reports, pull requests, and feedback are welcome. This server is highly personalized, so please don't be surprised if I reject your contribution.