/docs renders OpenAPI docs (#61)

* /docs renders OpenAPI docs

* e.g. http://localhost:8090/docs
* BREAKING: API: changed route for listing tools schemas for a server to: /servers/{server_name}/tools
* BREAKING API: changed routes for tools to: /servers/{server_name}/tools/{tool_name}
* Docs updates
* Refactored code, introduced huma.
* Register routes and use Operations to define the routes better for OpenAPI docs

Author: peteski22

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build clean docs docs-cli docs-nav docs-local install test uninstall
+.PHONY: build clean docs docs-cli docs-local docs-nav install test uninstall
 
 MODULE_PATH := github.com/mozilla-ai/mcpd/v2
 
@@ -34,25 +34,25 @@ clean:
 	@# Remove the built executable and any temporary files
 	@rm -f mcpd # The executable itself
 	@# Add any other build artifacts here if they accumulate (e.g., cache files)
-	@echo "Build artifacts cleaned"
+	@echo "build artifacts cleaned"
 
 uninstall:
 	@# Remove the installed executable from the system
 	@# Requires sudo if INSTALL_DIR is a system path
 	@rm -f $(INSTALL_DIR)/mcpd
 	@echo "mcpd uninstalled from $(INSTALL_DIR)/mcpd"
 
-## Runs MkDocs locally
+# Runs MkDocs locally
 docs: docs-local
 
-## Runs MkDocs locally
+# Runs MkDocs locally
 docs-local: docs-nav
 	@uv venv && \
 		source .venv/bin/activate && \
 		uv pip install mkdocs mkdocs-material && \
 		uv run mkdocs serve
 
-## Generates CLI markdown documentation
+# Generates CLI markdown documentation
 docs-cli:
 	@go run -tags=docsgen_cli ./tools/docsgen/cli/cmds.go
 	@echo "mcpd CLI command documentation generated"

README.md

@@ -27,8 +27,8 @@ Covers setup, CLI usage, configuration, secrets, the daemon, Makefile commands,
 Install dependencies:
 
 - [Go](https://go.dev/doc/install)
-- [uvx](https://docs.astral.sh/uv/getting-started/installation/)
 - [npx](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+- [uvx](https://docs.astral.sh/uv/getting-started/installation/)
 
 Clone the repo:
 ```bash
@@ -63,6 +63,8 @@ Start the daemon:
 mcpd daemon
 ```
 
+API docs will be available at `/docs`, e.g. `http://localhost:8090/docs` 
+
 ## 🧰 Development
 
 Run tests:

docs/requirements.md

@@ -2,9 +2,11 @@
 
 To use `mcpd`, ensure the following tools are installed:
 
-- [`uv` / `uvx`](https://docs.astral.sh/uv/getting-started/installation/) - for running `uvx` Python packages
-- [`npx` / `npm` / `NodeJS`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) - for running JavaScript/TypeScript packages
-- [Go](https://go.dev/doc/install) - only required for building and developing `mcpd`
+| Tool           | Purpose                                        | Notes                                                             | 
+|----------------|------------------------------------------------|-------------------------------------------------------------------| 
+| `Go >= 1.24.4` | Required for building `mcpd` and running tests | https://go.dev/doc/install                                        | 
+| `uv`           | for running `uvx` Python packages              | https://docs.astral.sh/uv/getting-started/installation/           |
+| `npx`          | for running JavaScript/TypeScript packages     | https://docs.npmjs.com/downloading-and-installing-node-js-and-npm |
 
 !!! note "Internet Connectivity"
     `mcpd` requires internet access to contact package registries and to allow MCP servers access to the internet if required when running.

docs/tutorial.md

@@ -54,7 +54,7 @@ mcpd daemon
 ```
 
 !!! note "API Endpoint"
-    The API will be available at `http://localhost:8090/api/v1/servers`
+    The API docs will be available at `http://localhost:8090/docs`
 
 ---
 
@@ -73,5 +73,5 @@ Make a request to a tool on a specific MCP server:
 ```bash
 curl -s -X POST -H "Content-Type: application/json" \\
   -d '{"timezone": "America/New_York"}' \\
-  http://localhost:8090/api/v1/servers/time/get_current_time | jq
+  http://localhost:8090/api/v1/servers/time/tools/get_current_time | jq
 ```

go.mod

@@ -4,28 +4,29 @@ go 1.24.4
 
 require (
 	github.com/BurntSushi/toml v1.5.0
+	github.com/danielgtaylor/huma/v2 v2.34.1
 	github.com/go-chi/chi/v5 v5.2.2
 	github.com/hashicorp/go-hclog v1.6.3
-	github.com/mark3labs/mcp-go v0.31.0
+	github.com/mark3labs/mcp-go v0.32.0
 	github.com/spf13/cobra v1.9.1
 	github.com/spf13/pflag v1.0.6
-	github.com/stretchr/testify v1.9.0
+	github.com/stretchr/testify v1.10.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
-	github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/fatih/color v1.13.0 // indirect
+	github.com/fatih/color v1.18.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/mattn/go-colorable v0.1.12 // indirect
-	github.com/mattn/go-isatty v0.0.14 // indirect
-	github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/rogpeppe/go-internal v1.11.0 // indirect
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
-	github.com/spf13/cast v1.7.1 // indirect
+	github.com/spf13/cast v1.9.2 // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
-	golang.org/x/sys v0.18.0 // indirect
-	gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f // indirect
+	golang.org/x/sys v0.33.0 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
 )

go.sum

@@ -1,67 +1,73 @@
 github.com/BurntSushi/toml v1.5.0 h1:W5quZX/G/csjUnuI8SUYlsHs9M38FC7znL0lIO+DvMg=
 github.com/BurntSushi/toml v1.5.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
-github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/cpuguy83/go-md2man/v2 v2.0.7 h1:zbFlGlXEAKlwXpmvle3d8Oe3YnkKIK4xSRTd3sHPnBo=
+github.com/cpuguy83/go-md2man/v2 v2.0.7/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/danielgtaylor/huma/v2 v2.34.1 h1:EmOJAbzEGfy0wAq/QMQ1YKfEMBEfE94xdBRLPBP0gwQ=
+github.com/danielgtaylor/huma/v2 v2.34.1/go.mod h1:ynwJgLk8iGVgoaipi5tgwIQ5yoFNmiu+QdhU7CEEmhk=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/fatih/color v1.13.0 h1:8LOYc1KYPPmyKMuN8QV2DNRWNbLo6LZ0iLs8+mlH53w=
 github.com/fatih/color v1.13.0/go.mod h1:kLAiJbzzSOZDVNGyDpeOxJ47H46qBXwg5ILebYFFOfk=
+github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
+github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/go-chi/chi/v5 v5.2.2 h1:CMwsvRVTbXVytCk1Wd72Zy1LAsAh9GxMmSNWLHCG618=
 github.com/go-chi/chi/v5 v5.2.2/go.mod h1:L2yAIGWB3H+phAw1NxKwWM+7eUH/lU8pOMm5hHcoops=
-github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
-github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/hashicorp/go-hclog v1.6.3 h1:Qr2kF+eVWjTiYmU7Y31tYlP1h0q/X3Nl3tPGdaB11/k=
 github.com/hashicorp/go-hclog v1.6.3/go.mod h1:W4Qnvbt70Wk/zYJryRzDRU/4r0kIg0PVHBcfoyhpF5M=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/mark3labs/mcp-go v0.31.0 h1:4UxSV8aM770OPmTvaVe/b1rA2oZAjBMhGBfUgOGut+4=
-github.com/mark3labs/mcp-go v0.31.0/go.mod h1:rXqOudj/djTORU/ThxYx8fqEVj/5pvTuuebQ2RC7uk4=
+github.com/mark3labs/mcp-go v0.32.0 h1:fgwmbfL2gbd67obg57OfV2Dnrhs1HtSdlY/i5fn7MU8=
+github.com/mark3labs/mcp-go v0.32.0/go.mod h1:rXqOudj/djTORU/ThxYx8fqEVj/5pvTuuebQ2RC7uk4=
 github.com/mattn/go-colorable v0.1.9/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
-github.com/mattn/go-colorable v0.1.12 h1:jF+Du6AlPIjs2BiUiQlKOX0rt3SujHxPnksPKZbaA40=
 github.com/mattn/go-colorable v0.1.12/go.mod h1:u5H1YNBxpqRaxsYJYSkiCWKzEfiAb1Gb520KVy5xxl4=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
 github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
-github.com/mattn/go-isatty v0.0.14 h1:yVuAays6BHfxijgZPzw+3Zlu5yQgKGP2/hcQbHb7S9Y=
 github.com/mattn/go-isatty v0.0.14/go.mod h1:7GGIvUiUoEMVVmxf/4nioHXj79iQHKdU27kJ6hsGG94=
-github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e h1:fD57ERR4JtEqsWbfPhv4DMiApHyliiK5xCTNVSPiaAs=
-github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
-github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/rogpeppe/go-internal v1.11.0 h1:cWPaGQEPrBb5/AsnsZesgZZ9yb1OQ+GOISoDNXVBh4M=
+github.com/rogpeppe/go-internal v1.11.0/go.mod h1:ddIwULY96R17DhadqLgMfk9H9tvdUzkipdSkR5nkCZA=
 github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/spf13/cast v1.7.1 h1:cuNEagBQEHWN1FnbGEjCXL2szYEXqfJPbP2HNUaca9Y=
-github.com/spf13/cast v1.7.1/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
+github.com/spf13/cast v1.9.2 h1:SsGfm7M8QOFtEzumm7UZrZdLLquNdzFYfIbEXntcFbE=
+github.com/spf13/cast v1.9.2/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo=
 github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
 github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
 github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
 github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.7.2/go.mod h1:R6va5+xMeoiuVRoj+gSkQ7d3FALtqAAGI1FQKckRals=
-github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
-github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210927094055-39ccf1dd6fa6/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220503163025-988cb79eb6c6/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.18.0 h1:DBdB3niSjOA/O0blCZBqDefyWNYveAYMNF1Wum0DYQ4=
-golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw=
+golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f h1:BLraFXnmrev5lT+xlilqcH8XK9/i0At2xKjWk4p6zsU=
-gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/api/convert.go

@@ -0,0 +1,5 @@
+package api
+
+type Convertible[T any] interface {
+	ToAPIType() T
+}

internal/api/health.go

@@ -0,0 +1,140 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/danielgtaylor/huma/v2"
+
+	"github.com/mozilla-ai/mcpd/v2/internal/contracts"
+	"github.com/mozilla-ai/mcpd/v2/internal/domain"
+)
+
+const (
+	HealthStatusOK          HealthStatus = "ok"
+	HealthStatusTimeout     HealthStatus = "timeout"
+	HealthStatusUnreachable HealthStatus = "unreachable"
+	HealthStatusUnknown     HealthStatus = "unknown"
+)
+
+// DomainServerHealth is a wrapper that allows receivers to be declared in the API package that deal with domain types.
+type DomainServerHealth domain.ServerHealth
+
+// HealthStatus represents the current status of a particular MCP server when establishing its health.
+type HealthStatus string
+
+// ServerHealth is used to provide information about ongoing health checks that are performed on running MCP servers.
+type ServerHealth struct {
+	Name           string       `json:"name"`
+	Status         HealthStatus `json:"status"`
+	Latency        *string      `json:"latency,omitempty"`
+	LastChecked    *time.Time   `json:"last_checked,omitempty"`
+	LastSuccessful *time.Time   `json:"last_successful,omitempty"`
+}
+
+// ServersHealth represents a collection of ServerHealth.
+type ServersHealth struct {
+	Servers []ServerHealth `json:"servers"`
+}
+
+// ServersHealthResponse is the response for GET /health
+type ServersHealthResponse struct {
+	Body struct {
+		Servers []ServerHealth `json:"servers" doc:"Tracked MCP server health statuses"`
+	}
+}
+
+// ServerHealthRequest represents the incoming request for obtaining ServerHealth.
+type ServerHealthRequest struct {
+	Name string `path:"name" example:"time" doc:"Name of the server to check"`
+}
+
+// ServerHealthResponse represents the wrapped API response for a ServerHealth.
+type ServerHealthResponse struct {
+	Body ServerHealth
+}
+
+// ToAPIType can be used to convert a wrapped domain type to an API-safe type.
+func (d DomainServerHealth) ToAPIType() ServerHealth {
+	var latency *string
+	if d.Latency != nil {
+		s := d.Latency.String()
+		latency = &s
+	}
+	return ServerHealth{
+		Name:           d.Name,
+		Status:         HealthStatus(d.Status), // TODO: Validation?
+		Latency:        latency,
+		LastChecked:    d.LastChecked,
+		LastSuccessful: d.LastSuccessful,
+	}
+}
+
+// RegisterHealthRoutes sets up health-related API endpoint routes.
+func RegisterHealthRoutes(routerAPI huma.API, monitor contracts.MCPHealthMonitor, apiPathPrefix string) {
+	healthAPI := huma.NewGroup(routerAPI, apiPathPrefix)
+	tags := []string{"Health"}
+
+	huma.Register(
+		healthAPI,
+		huma.Operation{
+			OperationID: "listServersHealth",
+			Method:      http.MethodGet,
+			Path:        "/",
+			Summary:     "List the health statuses for all servers",
+			Tags:        tags,
+		},
+		func(ctx context.Context, _ *struct{}) (*ServersHealthResponse, error) {
+			return handleHealthServers(monitor)
+		},
+	)
+
+	huma.Register(
+		healthAPI,
+		huma.Operation{
+			OperationID: "getServerHealth",
+			Method:      http.MethodGet,
+			Path:        "/servers/{name}",
+			Summary:     "Get the health status of a server",
+			Tags:        tags,
+		},
+		func(ctx context.Context, input *ServerHealthRequest) (*ServerHealthResponse, error) {
+			return handleHealthServer(monitor, input.Name)
+		},
+	)
+}
+
+// handleHealthServers is the handler for retrieving the current health for all registered MCP servers.
+func handleHealthServers(monitor contracts.MCPHealthMonitor) (*ServersHealthResponse, error) {
+	servers := monitor.List()
+
+	slices.SortFunc(servers, func(a, b domain.ServerHealth) int {
+		return strings.Compare(a.Name, b.Name)
+	})
+
+	apiServers := make([]ServerHealth, 0, len(servers))
+	for _, s := range servers {
+		apiServers = append(apiServers, DomainServerHealth(s).ToAPIType())
+	}
+
+	resp := &ServersHealthResponse{}
+	resp.Body.Servers = apiServers
+
+	return resp, nil
+}
+
+// handleHealthServer is the handler for retrieving the current health the specified registered MCP server.
+func handleHealthServer(monitor contracts.MCPHealthMonitor, name string) (*ServerHealthResponse, error) {
+	health, err := monitor.Status(name)
+	if err != nil {
+		return nil, err
+	}
+
+	response := ServerHealthResponse{}
+	response.Body = DomainServerHealth(health).ToAPIType()
+
+	return &response, nil
+}