Add endpoints for listing and registering clients

Ref #612

Author: eleftherias

docs/server/docs.go

@@ -1,7 +1,11 @@
 components:
   schemas:
+    client.Client:
+      properties:
+        name:
+          $ref: '#/components/schemas/client.MCPClient'
+      type: object
     client.MCPClient:
-      description: ClientType is the type of MCP client
       type: string
       x-enum-varnames:
       - RooCode
@@ -13,7 +17,15 @@ components:
     client.MCPClientStatus:
       properties:
         client_type:
-          $ref: '#/components/schemas/client.MCPClient'
+          description: ClientType is the type of MCP client
+          type: string
+          x-enum-varnames:
+          - RooCode
+          - Cline
+          - Cursor
+          - VSCodeInsider
+          - VSCode
+          - ClaudeCode
         installed:
           description: Installed indicates whether the client is installed on the
             system
@@ -290,6 +302,32 @@ components:
           type: array
           uniqueItems: false
       type: object
+    v1.createClientRequest:
+      properties:
+        name:
+          description: Name is the type of the client to register.
+          type: string
+          x-enum-varnames:
+          - RooCode
+          - Cline
+          - Cursor
+          - VSCodeInsider
+          - VSCode
+          - ClaudeCode
+      type: object
+    v1.createClientResponse:
+      properties:
+        name:
+          description: Name is the type of the client that was registered.
+          type: string
+          x-enum-varnames:
+          - RooCode
+          - Cline
+          - Cursor
+          - VSCodeInsider
+          - VSCode
+          - ClaudeCode
+      type: object
     v1.createRequest:
       description: Request to create a new server
       properties:
@@ -464,6 +502,46 @@ paths:
       summary: Get OpenAPI specification
       tags:
       - system
+  /api/v1beta/clients:
+    get:
+      description: List all registered clients in ToolHive
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                items:
+                  $ref: '#/components/schemas/client.Client'
+                type: array
+          description: OK
+      summary: List all clients
+      tags:
+      - clients
+    post:
+      description: Register a new client with ToolHive
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/v1.createClientRequest'
+        description: Client to register
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/v1.createClientResponse'
+          description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                type: string
+          description: Invalid request
+      summary: Register a new client
+      tags:
+      - clients
   /api/v1beta/discovery/clients:
     get:
       description: List all clients compatible with ToolHive and their status

docs/server/swagger.json

@@ -27,6 +27,7 @@ import (
 
 	v1 "github.com/stacklok/toolhive/pkg/api/v1"
 	"github.com/stacklok/toolhive/pkg/auth"
+	"github.com/stacklok/toolhive/pkg/client"
 	"github.com/stacklok/toolhive/pkg/container"
 	"github.com/stacklok/toolhive/pkg/lifecycle"
 	"github.com/stacklok/toolhive/pkg/logger"
@@ -113,12 +114,17 @@ func Serve(
 		return fmt.Errorf("failed to create container runtime: %v", err)
 	}
 
+	clientManager, err := client.NewManager(ctx)
+	if err != nil {
+		return fmt.Errorf("failed to create client manager: %v", err)
+	}
 	routers := map[string]http.Handler{
 		"/health":               v1.HealthcheckRouter(),
 		"/api/v1beta/version":   v1.VersionRouter(),
 		"/api/v1beta/servers":   v1.ServerRouter(manager, rt, debugMode),
 		"/api/v1beta/registry":  v1.RegistryRouter(),
 		"/api/v1beta/discovery": v1.DiscoveryRouter(),
+		"/api/v1beta/clients":   v1.ClientRouter(clientManager),
 	}
 
 	// Only mount docs router if enabled

docs/server/swagger.yaml

@@ -0,0 +1,99 @@
+package v1
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/stacklok/toolhive/pkg/client"
+	"github.com/stacklok/toolhive/pkg/logger"
+)
+
+// ClientRoutes defines the routes for the client API.
+type ClientRoutes struct {
+	manager client.Manager
+}
+
+// ClientRouter creates a new router for the client API.
+func ClientRouter(
+	manager client.Manager,
+) http.Handler {
+	routes := ClientRoutes{
+		manager: manager,
+	}
+
+	r := chi.NewRouter()
+	r.Get("/", routes.listClients)
+	r.Post("/", routes.registerClient)
+	return r
+}
+
+// listClients
+//
+//	@Summary		List all clients
+//	@Description	List all registered clients in ToolHive
+//	@Tags			clients
+//	@Produce		json
+//	@Success		200	{array}	client.Client
+//	@Router			/api/v1beta/clients [get]
+func (c *ClientRoutes) listClients(w http.ResponseWriter, _ *http.Request) {
+	clients, err := c.manager.ListClients()
+	if err != nil {
+		logger.Errorf("Failed to list clients: %v", err)
+		http.Error(w, "Failed to list clients", http.StatusInternalServerError)
+		return
+	}
+
+	err = json.NewEncoder(w).Encode(clients)
+	if err != nil {
+		http.Error(w, "Failed to encode client list", http.StatusInternalServerError)
+		return
+	}
+}
+
+// registerClient
+//
+//	@Summary		Register a new client
+//	@Description	Register a new client with ToolHive
+//	@Tags			clients
+//	@Accept			json
+//	@Produce		json
+//	@Param			client	body	createClientRequest	true	"Client to register"
+//	@Success		200	{object}	createClientResponse
+//	@Failure		400	{string}	string	"Invalid request"
+//	@Router			/api/v1beta/clients [post]
+func (c *ClientRoutes) registerClient(w http.ResponseWriter, r *http.Request) {
+	var newClient createClientRequest
+	err := json.NewDecoder(r.Body).Decode(&newClient)
+	if err != nil {
+		logger.Errorf("Failed to decode request body: %v", err)
+		http.Error(w, "Invalid request body", http.StatusBadRequest)
+		return
+	}
+
+	err = c.manager.RegisterClient(r.Context(), client.Client{
+		Name: newClient.Name,
+	})
+	if err != nil {
+		logger.Errorf("Failed to register client: %v", err)
+		http.Error(w, "Failed to register client", http.StatusInternalServerError)
+		return
+	}
+
+	resp := createClientResponse(newClient)
+	if err = json.NewEncoder(w).Encode(resp); err != nil {
+		http.Error(w, "Failed to marshal server details", http.StatusInternalServerError)
+		return
+	}
+}
+
+type createClientRequest struct {
+	// Name is the type of the client to register.
+	Name client.MCPClient `json:"name"`
+}
+
+type createClientResponse struct {
+	// Name is the type of the client that was registered.
+	Name client.MCPClient `json:"name"`
+}

pkg/api/server.go

@@ -149,6 +149,22 @@ type MCPServerConfig struct {
 	URL string `json:"url,omitempty"`
 }
 
+// FindClientConfig returns the client configuration file for a given client type.
+func FindClientConfig(clientType MCPClient) (*ConfigFile, error) {
+	configFiles, err := FindClientConfigs()
+	if err != nil {
+		return nil, fmt.Errorf("failed to fetch client configurations: %w", err)
+	}
+
+	for _, cf := range configFiles {
+		if cf.ClientType == clientType {
+			return &cf, nil
+		}
+	}
+
+	return nil, fmt.Errorf("client configuration for %s not found", clientType)
+}
+
 // FindClientConfigs searches for client configuration files in standard locations
 func FindClientConfigs() ([]ConfigFile, error) {
 	// Start by assuming all clients are enabled