feat(dashboard): add instance health dashboard on GET / endpoint by polaz · Pull Request #286 · structured-world/gitlab-mcp

polaz · 2026-02-04T23:16:42Z

Summary

Add health dashboard endpoint at GET / for server monitoring
Dashboard shows registered GitLab instances, health status, rate limit metrics
Supports content negotiation: HTML for browsers, JSON for API clients
Safe for MCP clients (they use POST /mcp, not GET /)

Changes

New files

src/dashboard/metrics.ts — MetricsCollector aggregating data from InstanceRegistry, SessionManager
src/dashboard/html-template.ts — Responsive HTML template with dark theme
src/dashboard/handler.ts — Express handler with Accept header content negotiation
src/dashboard/index.ts — Barrel exports

Modified files

src/config.ts — Added DASHBOARD_ENABLED env var (default: true)
src/server.ts — Registered GET / route before MCP middleware

Features

Instance health status: healthy/degraded/offline based on latency, queue, rejection rate
Rate limit metrics per instance (active/queued/total requests)
Session count (anonymized)
Server configuration summary
Auto-refresh every 30 seconds
XSS protection via HTML escaping
Disable with DASHBOARD_ENABLED=false

Test plan

44 unit tests added for metrics, handler, and HTML template
All 4548 tests pass
Lint passes
Build succeeds

Closes #275

- Add dashboard module with metrics collector, HTML template, and handler - Dashboard shows server info, registered instances, health status, sessions - Supports content negotiation: HTML for browsers, JSON for API clients - Add DASHBOARD_ENABLED config (default true, disable with =false) - Instances show health status (healthy/degraded/offline) based on metrics - HTML includes auto-refresh every 30 seconds - Safe for MCP clients - they use POST /mcp, not GET / - Add 44 unit tests for metrics, handler, and HTML template Closes #275

github-actions · 2026-02-04T23:18:04Z

Test Coverage Report

Overall Coverage: 95.77%

Metric	Percentage
Statements	95.24%
Branches	86.12%
Functions	94.42%
Lines	95.77%

View detailed coverage report

codecov · 2026-02-04T23:19:35Z

Codecov Report

❌ Patch coverage is 93.46405% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/dashboard/html-template.ts	90.16%	0 Missing and 6 partials ⚠️
src/server.ts	25.00%	2 Missing and 1 partial ⚠️
src/dashboard/metrics.ts	98.36%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This PR implements an instance health dashboard accessible at GET / that provides real-time visibility into the GitLab MCP server's multi-instance federation state, health metrics, and configuration. The dashboard supports content negotiation, serving HTML for browsers and JSON for API clients, while remaining safe for MCP clients that use POST endpoints.

Changes:

Adds a comprehensive health monitoring dashboard with server metrics, instance health status, rate limiting metrics, and session counts
Implements content negotiation to serve HTML dashboards to browsers and JSON to API clients
Provides 44 unit tests ensuring metrics collection, HTML rendering, and HTTP handling work correctly

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/server.ts	Registers GET / route for dashboard when DASHBOARD_ENABLED is true (default)
src/config.ts	Adds DASHBOARD_ENABLED environment variable configuration
src/dashboard/metrics.ts	Implements metrics collection from InstanceRegistry and SessionManager with health status determination
src/dashboard/handler.ts	Handles HTTP requests with Accept header content negotiation between HTML and JSON
src/dashboard/html-template.ts	Generates responsive HTML with dark theme, XSS escaping, and auto-refresh
src/dashboard/index.ts	Barrel exports for dashboard module
tests/unit/dashboard/metrics.test.ts	Tests metrics collection, status determination, and uptime formatting
tests/unit/dashboard/html-template.test.ts	Tests HTML rendering, XSS protection, and content formatting
tests/unit/dashboard/handler.test.ts	Tests content negotiation and response generation

src/dashboard/handler.ts

src/dashboard/html-template.ts

src/dashboard/metrics.ts

…get--endpoint

- Vite/Rollup cannot resolve .d.ts files as runtime imports - Renamed declaration file to regular .ts (content unchanged) - File contains `declare global` + `export {}` which is valid in both formats Fixes #285

- Add try/catch in dashboardHandler for collectMetrics/renderDashboard failures - Add safe URL parsing in renderInstanceCard with fallback to raw URL - Use GITLAB_TOKEN config constant instead of direct process.env access

…get--endpoint

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

src/dashboard/metrics.ts

src/server.ts

src/dashboard/html-template.ts

- Remove unused lastSuccessfulRequestMs parameter from determineInstanceStatus - Add .js extension to dashboard import in server.ts - Add safe URL parsing for session hostnames in html-template.ts - Add comprehensive tests for collectMetrics function

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

src/server.ts

- Add tests for error handling in dashboardHandler - Add tests for getMetrics export function - Add tests for OAuth and token auth modes - Add tests for unknown status indicator - Add tests for invalid URL parsing fallbacks - Add tests for queue filling warning - Add tests for formatRelativeTime (hours, days) - Add tests for invalid URL in sessions byInstance Coverage: Lines 100%, Branches 92.85%

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

## [6.56.0](v6.55.1...v6.56.0) (2026-02-04) ### Features * **dashboard:** add instance health dashboard on GET / endpoint ([#286](#286)) ([de47c40](de47c40)), closes [#275](#275) [#287](#287) [#285](#285)

sw-release-bot · 2026-02-04T23:57:09Z

🎉 This PR is included in version 6.56.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Copilot AI review requested due to automatic review settings February 4, 2026 23:16

Copilot started reviewing on behalf of polaz February 4, 2026 23:16 View session

Copilot AI reviewed Feb 4, 2026

View reviewed changes

src/dashboard/handler.ts Outdated Show resolved Hide resolved

src/dashboard/html-template.ts Outdated Show resolved Hide resolved

src/dashboard/metrics.ts Outdated Show resolved Hide resolved

polaz added 4 commits February 5, 2026 01:20

Merge branch 'main' into feat/#275-feat-instance-health-dashboard-on-…

cbb522c

…get--endpoint

fix(docs): rename gtag.d.ts to gtag.ts for Vite compatibility (#287)

39570eb

- Vite/Rollup cannot resolve .d.ts files as runtime imports - Renamed declaration file to regular .ts (content unchanged) - File contains `declare global` + `export {}` which is valid in both formats Fixes #285

fix(dashboard): add error handling and safe URL parsing

b652331

- Add try/catch in dashboardHandler for collectMetrics/renderDashboard failures - Add safe URL parsing in renderInstanceCard with fallback to raw URL - Use GITLAB_TOKEN config constant instead of direct process.env access

Merge branch 'main' into feat/#275-feat-instance-health-dashboard-on-…

8c9aa05

…get--endpoint

polaz requested a review from Copilot February 4, 2026 23:24

Copilot started reviewing on behalf of polaz February 4, 2026 23:25 View session

Copilot AI reviewed Feb 4, 2026

View reviewed changes

src/dashboard/metrics.ts Outdated Show resolved Hide resolved

src/server.ts Outdated Show resolved Hide resolved

src/dashboard/html-template.ts Outdated Show resolved Hide resolved

polaz requested a review from Copilot February 4, 2026 23:37

Copilot started reviewing on behalf of polaz February 4, 2026 23:37 View session

Copilot AI reviewed Feb 4, 2026

View reviewed changes

src/server.ts Show resolved Hide resolved

polaz changed the title ~~feat(dashboard): Instance Health Dashboard on GET / endpoint~~ feat(dashboard): add instance health dashboard on GET / endpoint Feb 4, 2026

polaz requested a review from Copilot February 4, 2026 23:46

Copilot started reviewing on behalf of polaz February 4, 2026 23:46 View session

Copilot AI reviewed Feb 4, 2026

View reviewed changes

polaz merged commit de47c40 into main Feb 4, 2026
28 checks passed

polaz deleted the feat/#275-feat-instance-health-dashboard-on-get--endpoint branch February 4, 2026 23:50

sw-release-bot bot added the released label Feb 4, 2026

sw-release-bot bot mentioned this pull request Mar 29, 2026

chore(main): release gitlab-mcp 7.0.0 #368

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(dashboard): add instance health dashboard on GET / endpoint#286

feat(dashboard): add instance health dashboard on GET / endpoint#286
polaz merged 7 commits intomainfrom
feat/#275-feat-instance-health-dashboard-on-get--endpoint

polaz commented Feb 4, 2026

Uh oh!

github-actions bot commented Feb 4, 2026 •

edited

Loading

Uh oh!

codecov bot commented Feb 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

sw-release-bot bot commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

polaz commented Feb 4, 2026

Summary

Changes

New files

Modified files

Features

Test plan

Uh oh!

github-actions bot commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Coverage Report

Uh oh!

codecov bot commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

sw-release-bot bot commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Feb 4, 2026 •

edited

Loading

codecov bot commented Feb 4, 2026 •

edited

Loading