Add automated OpenAPI specification generation for hosted documentation (#208)

* Refactor API routes into single source of truth

Extract route registration logic into internal/api/routes.go with
RegisterRoutes function. This ensures daemon and docs generation
use identical route definitions, maintaining 1:1 mapping between
code and documentation.

Introduces api.APIVersion constant as single source of truth for
API version used in OpenAPI spec and URL paths. The RegisterRoutes
function extracts this version from the router's OpenAPI spec and
returns the path prefix for logging.

All parameters require non-nil values with defensive checks using
reflection to prevent panics from interface nil checks.

Updates internal/daemon/api_server.go to use RegisterRoutes and
api.APIVersion constant, removing duplicate route registration code.

* Add OpenAPI specification generation tool

Introduce tools/docsgen/api/openapi.go for programmatic OpenAPI spec
export. The tool uses api.RegisterRoutes with stub implementations of
contracts to generate the spec without running the daemon.

Output is written to docs/api/openapi.yaml which is excluded from
version control via .gitignore, matching the pattern used for CLI
docs in docs/commands/.

This ensures a 1:1 mapping between the actual API code and the
published OpenAPI specification, automatically generated during
documentation deployment.

* Fix errcheck lint error in nav tool

Add error handling for encoder.Close() call in updateMkDocsNav
function to satisfy errcheck linter.

The encoder must be properly closed to flush any buffered output
before writing the final YAML to the file.

* Update build configuration for reorganized tools

Update Makefile targets to reflect new tools structure where each
standalone tool lives in its own directory (cmds/, nav/, api/)
rather than sharing tools/docsgen/cli/.

Add docs-api target to generate OpenAPI specification.

Configure golangci-lint to include build tags for all docsgen tools
and validate_registry, ensuring proper linting of build-tagged files
that were previously excluded from analysis.

* Integrate OpenAPI docs generation into CI pipeline

Add OpenAPI spec generation step to deploy-docs workflow between
CLI docs generation and navigation updates. This ensures the spec
is generated fresh on every docs deployment.

Update mkdocs.yaml to include API Reference section with link to
the generated OpenAPI specification file.

Update GitHub Actions versions across all workflows to latest
pinned releases for actions/checkout, actions/setup-go, and
astral-sh/setup-uv.

* Drop 'make docs-local' and just use 'make docs'

* make docs includes building OpenAPI too

Author: peteski22

.github/workflows/deploy-docs.yaml

@@ -15,15 +15,15 @@ jobs:
 
     steps:
       - name: Checkout repo
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Set up Go (from go.mod)
-        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version-file: go.mod
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7.1.0
         with:
           python-version: 3.12
           activate-environment: true
@@ -32,6 +32,9 @@ jobs:
       - name: Generate CLI docs
         run: make docs-cli
 
+      - name: Generate OpenAPI docs
+        run: make docs-api
+
       - name: Update MkDocs navigation
         run: make docs-nav
 

.github/workflows/golangci-lint.yaml

@@ -17,10 +17,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Set up Go (from go.mod)
-        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version-file: go.mod
 

.github/workflows/release.yaml

@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
 
@@ -49,7 +49,7 @@ jobs:
           git checkout "$TAG"
 
       - name: Set up Go (from go.mod)
-        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version-file: go.mod
 
@@ -61,13 +61,13 @@ jobs:
         uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
 
       - name: Login to DockerHub
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@9c156ee8a17a598857849441385a2041ef570552 # v6.3.0
+        uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # v6.4.0
         with:
           distribution: goreleaser
           version: latest

.github/workflows/tests.yaml

@@ -12,10 +12,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Set up Go (from go.mod)
-        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version-file: go.mod
 

.github/workflows/validate-registry.yaml

@@ -22,10 +22,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
-      - name: Setup Go (from go.mod)
-        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+      - name: Set up Go (from go.mod)
+        uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version-file: go.mod
 

.gitignore

@@ -46,6 +46,9 @@ secrets.dev.toml
 # Autogenerated docs pages for CLI commands
 docs/commands/
 
+# Autogenerated OpenAPI specification
+docs/api/
+
 # Any Python virtual environments
 .venv/
 # Added by goreleaser init:

.golangci.yaml

@@ -75,4 +75,10 @@ run:
   relative-path-mode: gomod
   modules-download-mode: readonly
   allow-parallel-runners: true
-  allow-serial-runners: true
+  allow-serial-runners: true
+  # Build tags to include files with custom build constraints.
+  build-tags:
+    - docsgen_cli
+    - docsgen_nav
+    - docsgen_api
+    - validate_registry

Makefile

@@ -1,5 +1,3 @@
-.PHONY: build build-dev build-linux build-linux-arm64 clean docs docs-cli docs-local docs-nav install lint local-down local-up test uninstall validate-registry check-licenses check-notice notice
-
 MODULE_PATH := github.com/mozilla-ai/mcpd/v2
 
 # /usr/local/bin is a common default for user-installed binaries
@@ -32,6 +30,7 @@ BUILDFLAGS := -trimpath
 # The license types allowed to be imported by the project
 ALLOWED_LICENSES := Apache-2.0,MIT,BSD-2-Clause,BSD-3-Clause,ZeroBSD,Unlicense
 
+.PHONY: check-licenses
 check-licenses:
 	@echo "Checking licenses..."
 	@go install github.com/google/go-licenses/v2@latest
@@ -43,6 +42,7 @@ check-licenses:
 		exit 1; \
 	fi
 
+.PHONY: check-notice
 check-notice:
 	@echo "Checking NOTICE..."
 	@go install github.com/google/go-licenses/v2@latest
@@ -56,82 +56,100 @@ check-notice:
 		echo "✓ NOTICE is up to date"; \
 	fi
 
+.PHONY: notice
 notice:
 	@echo "Generating NOTICE..."
 	@go install github.com/google/go-licenses/v2@latest
 	@go-licenses report ./... --ignore github.com/mozilla-ai/mcpd/v2 --template build/licenses/notice.tpl > NOTICE
 	@echo "✓ NOTICE generated"
 
+.PHONY: lint
 lint: check-notice
 	golangci-lint run --fix -v
 
+.PHONY: test
 test: lint
 	go test ./...
 
+.PHONY: validate-registry
 validate-registry:
 	@echo "Validating Mozilla AI registry against schema..."
 	@go run -tags=validate_registry ./tools/validate/registry.go \
 		internal/provider/mozilla_ai/data/schema.json \
 		internal/provider/mozilla_ai/data/registry.json
 
+.PHONY: build
 build: lint
 	@echo "building mcpd (version: $(VERSION), commit: $(COMMIT))..."
 	@go build $(BUILDFLAGS) -o mcpd -ldflags="$(LDFLAGS)" .
 
+.PHONY: build-linux
 build-linux:
 	@echo "building mcpd for amd64/linux (version: $(VERSION), commit: $(COMMIT))..."
 	@GOOS=linux GOARCH=amd64 go build $(BUILDFLAGS) -o mcpd -ldflags="$(LDFLAGS)" .
 
+.PHONY: build-linux-arm64
 build-linux-arm64:
 	@echo "building mcpd for arm64/linux (version: $(VERSION), commit: $(COMMIT))..."
 	@GOOS=linux GOARCH=arm64 go build $(BUILDFLAGS) -o mcpd -ldflags="$(LDFLAGS)" .
 
 # For development builds without optimizations (for debugging)
+.PHONY: build-dev
 build-dev:
 	@echo "building mcpd for development (version: $(VERSION), commit: $(COMMIT))..."
 	@go build -o mcpd -ldflags="-X '$(MODULE_PATH)/internal/cmd.version=$(VERSION)' \
 		-X '$(MODULE_PATH)/internal/cmd.commit=$(COMMIT)' \
 		-X '$(MODULE_PATH)/internal/cmd.date=$(DATE)'" .
 
+.PHONY: install
 install: build
 	@# Copy the executable to the install directory
 	@# Requires sudo if INSTALL_DIR is a system path like /usr/local/bin
 	@echo "installing mcpd to $(INSTALL_DIR)..."
 	@cp mcpd $(INSTALL_DIR)/mcpd
 	@chmod +x $(INSTALL_DIR)/mcpd
 
+.PHONY: clean
 clean:
 	@# Remove the built executable and any temporary files
 	@echo "cleaning up local build artifacts..."
 	@rm -f mcpd # The executable itself
 	@rm -rf $(TARGET_PLATFORM) # Remove any orphaned Docker build directories
 
+.PHONY: uninstall
 uninstall:
 	@# Remove the installed executable from the system
 	@# Requires sudo if INSTALL_DIR is a system path
 	@echo "uninstalling mcpd from $(INSTALL_DIR)..."
 	@rm -f $(INSTALL_DIR)/mcpd
 
 # Runs MkDocs locally
-docs: docs-local
-
-# Runs MkDocs locally
-docs-local: docs-nav
+.PHONY: docs
+docs: docs-nav docs-api
 	@uv venv && \
 		source .venv/bin/activate && \
 		uv pip install mkdocs mkdocs-material && \
 		uv run mkdocs serve
 
 # Generates CLI markdown documentation
+.PHONY: docs-cli
 docs-cli:
-	@go run -tags=docsgen_cli ./tools/docsgen/cli/cmds.go
+	@go run -tags=docsgen_cli ./tools/docsgen/cmds/main.go
 	@echo "mcpd CLI command documentation generated"
 
+# Generates OpenAPI specification YAML
+.PHONY: docs-api
+docs-api:
+	@go run -tags=docsgen_api ./tools/docsgen/api/openapi.go
+	@echo "OpenAPI specification generated"
+
 ## Updates mkdocs.yaml nav to match generated CLI docs
+.PHONY: docs-nav
 docs-nav: docs-cli
-	@go run -tags=docsgen_nav ./tools/docsgen/cli/nav.go
+	@go run -tags=docsgen_nav ./tools/docsgen/nav/main.go
 	@echo "navigation updated for MkDocs site"
 
+.PHONY: local-up
 local-up: build-linux
 	@echo "organizing binary for docker build"
 	@mkdir -p $(TARGET_PLATFORM)
@@ -141,6 +159,7 @@ local-up: build-linux
 	@echo "cleaning up temporary platform directory"
 	@rm -rf $(TARGET_PLATFORM)
 
+.PHONY: local-down
 local-down:
 	@echo "stopping mcpd container"
 	@docker compose down

docs/makefile.md

@@ -137,18 +137,13 @@ These commands manage the [MkDocs](https://www.mkdocs.org) developer documentati
     make docs-nav
     ```
 
-- **Serve the docs locally using MkDocs + uv**
-    ```bash
-    make docs-local
-    ```
-
-- **Full pipeline: generate CLI docs, update nav, serve locally**
+- **Serve the docs locally using MkDocs + uv: generate CLI docs, update nav, serve locally**
     ```bash
     make docs
     ```
 
     !!! tip "First time?"
-        The `docs-local` command will create a virtual environment using `uv`, install MkDocs + Material theme, and start the local server at [http://localhost:8000](http://localhost:8000).
+        The `docs` command will create a virtual environment using `uv`, install MkDocs + Material theme, and start the local server at [http://localhost:8000/mcpd/](http://localhost:8000/mcpd/).
 
 ---
 
@@ -165,8 +160,7 @@ Here's a complete list of Makefile targets:
 | `check-licenses`    | Validate all dependency licenses are allowed             |
 | `check-notice`      | Verify NOTICE file is up to date                         |
 | `clean`             | Remove compiled binary from working directory            |
-| `docs`              | Alias for `docs-local` (runs everything)                 |
-| `docs-cli`          | Generate Markdown CLI reference docs                     |
+| `docs`              | Serve docs locally via `mkdocs serve`                    |
 | `docs-local`        | Serve docs locally via `mkdocs serve`                    |
 | `docs-nav`          | Update CLI doc nav in `mkdocs.yaml`                      |
 | `install`           | Install binary to system path                            |

internal/api/routes.go

@@ -0,0 +1,49 @@
+package api
+
+import (
+	"fmt"
+	"net/url"
+	"reflect"
+
+	"github.com/danielgtaylor/huma/v2"
+
+	"github.com/mozilla-ai/mcpd/v2/internal/contracts"
+)
+
+// APIVersion is the version used in the OpenAPI spec and URL paths.
+const APIVersion = "v1"
+
+// RegisterRoutes registers all API routes on the provided Huma router.
+// This is the single source of truth for the API route structure.
+// Returns the API path prefix (e.g., "/api/v1") under which the routes are created.
+func RegisterRoutes(
+	router huma.API,
+	healthTracker contracts.MCPHealthMonitor,
+	clientManager contracts.MCPClientAccessor,
+) (string, error) {
+	if router == nil || reflect.ValueOf(router).IsNil() {
+		return "", fmt.Errorf("router cannot be nil")
+	}
+	if clientManager == nil || reflect.ValueOf(clientManager).IsNil() {
+		return "", fmt.Errorf("client manager cannot be nil")
+	}
+	if healthTracker == nil || reflect.ValueOf(healthTracker).IsNil() {
+		return "", fmt.Errorf("health tracker cannot be nil")
+	}
+
+	// Extract API version from the router's OpenAPI spec.
+	apiVersionID := router.OpenAPI().Info.Version
+
+	// Safe way to ensure /api/{version}.
+	apiPathPrefix, err := url.JoinPath("/api", apiVersionID)
+	if err != nil {
+		return "", fmt.Errorf("failed to construct API path prefix: %w", err)
+	}
+
+	// Group all routes under the /api/{version} prefix.
+	versionedGroup := huma.NewGroup(router, apiPathPrefix)
+	RegisterHealthRoutes(versionedGroup, healthTracker, "/health")
+	RegisterServerRoutes(versionedGroup, clientManager, "/servers")
+
+	return apiPathPrefix, nil
+}