### Create a New Workload

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Create and start a new MCP server workload with specified configurations including container details, environment variables, and resource limits.

```APIDOC
## POST /api/v1beta/workloads

### Description
Creates and starts a new MCP server workload. You can define the server type, transport, environment variables, secrets, arguments, and resource constraints.

### Method
POST

### Endpoint
`/api/v1beta/workloads`

### Request Body
- **name** (string) - Required - The name for the new workload.
- **group** (string) - Optional - The group to which the workload belongs.
- **registry** (string) - Required - The container registry to use (e.g., 'official').
- **server** (string) - Required - The type of MCP server to run (e.g., 'filesystem').
- **transport** (string) - Required - The transport protocol for client connections (e.g., 'sse').
- **env** (object) - Optional - Environment variables to set for the container.
  - **field** (string) - The environment variable name.
  - **value** (string) - The environment variable value.
- **secrets** (object) - Optional - References to secrets to be injected into the container.
  - **field** (string) - The secret name.
  - **value** (string) - A reference to the secret (e.g., 'secret-key-reference').
- **args** (array of strings) - Optional - Command-line arguments to pass to the server process.
- **resources** (object) - Optional - Resource limits for the container.
  - **cpu_limit** (string) - CPU limit (e.g., '1.0').
  - **memory_limit** (string) - Memory limit (e.g., '512M').

### Request Example
```json
{
  "name": "my-filesystem-server",
  "group": "development",
  "registry": "official",
  "server": "filesystem",
  "transport": "sse",
  "env": {
    "ALLOWED_PATHS": "/home/user/projects"
  },
  "secrets": {
    "API_KEY": "secret-key-reference"
  },
  "args": ["--verbose"],
  "resources": {
    "cpu_limit": "1.0",
    "memory_limit": "512M"
  }
}
```

### Response
#### Success Response (200)
- **name** (string) - The name of the created workload.
- **proxy_url** (string) - The URL to access the workload's proxy endpoint.
- **status** (string) - The initial status of the workload.

#### Response Example
```json
{
  "name": "my-filesystem-server",
  "proxy_url": "http://localhost:8080/proxy/my-filesystem-server",
  "status": "running"
}
```
```

--------------------------------

### Conventional Commits Specification - Examples

Source: https://github.com/stacklok/toolhive-studio/blob/main/CONTRIBUTING.md

Illustrative examples of commit messages adhering to the Conventional Commits specification, demonstrating various types and scopes for different kinds of changes.

```text
Examples:

- `feat: add new MCP server registry endpoint`
- `fix(ui): resolve button alignment issue in dark mode`
- `docs: update installation instructions`
- `test: add unit tests for secret validation`
```

--------------------------------

### Get Application Version with Curl

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Retrieves the current ToolHive backend version, commit hash, build date, and Go version. This is helpful for monitoring and debugging.

```bash
# Get version information
curl -X GET "http://localhost:8080/api/v1beta/version"

# Expected response
{
  "version": "0.1.0",
  "commit": "abc123def",
  "build_date": "2025-11-05T00:00:00Z",
  "go_version": "go1.21.0"
}
```

--------------------------------

### Create New Workload (TypeScript)

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Creates and starts a new MCP server workload using the ToolHive API client. Allows configuration of container details, environment variables, secrets, arguments, and resource limits. Handles potential errors during creation and logs the response data.

```typescript
import { client } from './api/generated/client.gen'

// Create a filesystem MCP server workload
const response = await client.POST('/api/v1beta/workloads', {
  body: {
    name: 'my-filesystem-server',
    group: 'development',
    registry: 'official',
    server: 'filesystem',
    transport: 'sse',
    env: {
      ALLOWED_PATHS: '/home/user/projects'
    },
    secrets: {
      API_KEY: 'secret-key-reference'
    },
    args: ['--verbose'],
    resources: {
      cpu_limit: '1.0',
      memory_limit: '512M'
    }
  }
})

if (response.error) {
  console.error('Failed to create workload:', response.error)
} else {
  console.log('Workload created:', response.data)
  // Response includes name, proxy_url, status
}
```

--------------------------------

### Get Application Version

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Retrieves the current version and build information of the ToolHive backend. This endpoint is useful for monitoring and debugging.

```APIDOC
## GET /api/v1beta/version

### Description
Retrieve the current ToolHive backend version and build information.

### Method
GET

### Endpoint
`/api/v1beta/version`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1beta/version"
```

### Response
#### Success Response (200)
- **version** (string) - The application version.
- **commit** (string) - The Git commit hash of the build.
- **build_date** (string) - The date and time when the application was built (ISO 8601 format).
- **go_version** (string) - The version of Go used to build the application.

#### Response Example
```json
{
  "version": "0.1.0",
  "commit": "abc123def",
  "build_date": "2025-11-05T00:00:00Z",
  "go_version": "go1.21.0"
}
```
```

--------------------------------

### TypeScript: Configure Electron Auto-Updater

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Configures the electron-updater for automatic application updates. It sets download behavior and installation on quit, and includes functions to check for updates and handle download completion events. Requires 'electron-updater' and access to Electron's 'mainWindow' and 'ipcMain'.

```typescript
// main/src/auto-update.ts
import { autoUpdater } from 'electron-updater'

// Configure auto-updater
autoUpdater.autoDownload = false
autoUpdater.autoInstallOnAppQuit = true

// Check for updates
const checkForUpdates = async () => {
  try {
    const result = await autoUpdater.checkForUpdates()
    if (result?.updateInfo) {
      console.log('Update available:', result.updateInfo.version)

      // Notify renderer
      mainWindow.webContents.send('update-available', {
        version: result.updateInfo.version,
        releaseDate: result.updateInfo.releaseDate
      })
    }
  } catch (error) {
    console.error('Update check failed:', error)
  }
}

// Download update
autoUpdater.on('update-downloaded', (info) => {
  mainWindow.webContents.send('update-downloaded', info)
})

// Install update on quit ipcMain.handle('install-update-and-restart', () => {
  autoUpdater.quitAndInstall(false, true)
})
```

--------------------------------

### Get Registry Servers with Curl

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Fetches a list of all available MCP servers from a specific registry, including their metadata. This is useful for exploring the services offered by a particular registry.

```bash
# Get all servers from the official registry
curl -X GET "http://localhost:8080/api/v1beta/registry/official/servers"

# Expected response
{
  "servers": [
    {
      "name": "filesystem",
      "description": "Access local filesystem with MCP",
      "version": "1.0.0",
      "transport": "sse",
      "image": "ghcr.io/stacklok/mcp-filesystem:latest",
      "tier": "Official",
      "tools": ["read_file", "write_file", "list_directory"],
      "metadata": {
        "stars": 1250,
        "pulls": 50000,
        "last_updated": "2025-11-01T00:00:00Z"
      }
    }
  ]
}
```

--------------------------------

### Get Registry Servers

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Fetches a list of all available MCP servers from a specified registry, including detailed metadata for each server. This allows clients to discover specific servers within a registry.

```APIDOC
## GET /api/v1beta/registry/{registry_name}/servers

### Description
List all available MCP servers from a specific registry with metadata.

### Method
GET

### Endpoint
`/api/v1beta/registry/{registry_name}/servers`

### Parameters
#### Path Parameters
- **registry_name** (string) - Required - The name of the registry to query.

#### Query Parameters
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1beta/registry/official/servers"
```

### Response
#### Success Response (200)
- **servers** (array) - A list of server objects available in the specified registry.
  - **name** (string) - The name of the server.
  - **description** (string) - A brief description of the server's functionality.
  - **version** (string) - The version of the server.
  - **transport** (string) - The transport protocol used by the server (e.g., 'sse').
  - **image** (string) - The container image for the server.
  - **tier** (string) - The tier of the server (e.g., 'Official').
  - **tools** (array of strings) - A list of tools or capabilities provided by the server.
  - **metadata** (object) - Additional metadata about the server.
    - **stars** (integer) - Number of stars (e.g., on a repository).
    - **pulls** (integer) - Number of pulls (e.g., for a container image).
    - **last_updated** (string) - The last updated timestamp in ISO 8601 format.

#### Response Example
```json
{
  "servers": [
    {
      "name": "filesystem",
      "description": "Access local filesystem with MCP",
      "version": "1.0.0",
      "transport": "sse",
      "image": "ghcr.io/stacklok/mcp-filesystem:latest",
      "tier": "Official",
      "tools": ["read_file", "write_file", "list_directory"],
      "metadata": {
        "stars": 1250,
        "pulls": 50000,
        "last_updated": "2025-11-01T00:00:00Z"
      }
    }
  ]
}
```
```

--------------------------------

### Get Workload Logs

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Retrieve recent log lines from a specified workload for debugging purposes.

```APIDOC
## GET /api/v1beta/workloads/{name}/logs

### Description
Fetches up to 100 lines of logs from a specified workload, useful for troubleshooting.

### Method
GET

### Endpoint
`/api/v1beta/workloads/{name}/logs`

### Path Parameters
- **name** (string) - Required - The name of the workload to retrieve logs from.

### Response
#### Success Response (200) (Content-Type: text/plain)
- **logs** (string) - A block of plain text containing the log output.

### Response Example
```text
2025-11-05T10:30:01Z [INFO] MCP server starting
2025-11-05T10:30:02Z [INFO] Listening on stdio
2025-11-05T10:30:03Z [INFO] Ready to accept connections
```
```

--------------------------------

### Get Workload Status

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Check the current status and resource usage of a specific MCP server workload.

```APIDOC
## GET /api/v1beta/workloads/{name}/status

### Description
Retrieves the detailed status of a specific workload, including its container health and resource consumption.

### Method
GET

### Endpoint
`/api/v1beta/workloads/{name}/status`

### Path Parameters
- **name** (string) - Required - The name of the workload to get the status for.

### Response
#### Success Response (200)
- **name** (string) - The name of the workload.
- **status** (string) - The current status of the workload (e.g., 'running', 'stopped').
- **container_id** (string) - The ID of the underlying container.
- **health** (string) - The health status of the container (e.g., 'healthy', 'unhealthy').
- **uptime_seconds** (integer) - The number of seconds the workload has been running.
- **cpu_usage** (string) - The current CPU utilization (e.g., '15.5%').
- **memory_usage** (string) - The current memory utilization (e.g., '256MB').
- **restart_count** (integer) - The number of times the container has restarted.

### Response Example
```json
{
  "name": "my-filesystem-server",
  "status": "running",
  "container_id": "abc123def456",
  "health": "healthy",
  "uptime_seconds": 3600,
  "cpu_usage": "15.5%",
  "memory_usage": "256MB",
  "restart_count": 0
}
```
```

--------------------------------

### Get Workload Logs (Bash)

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Retrieves log output from a specified MCP server workload. It can fetch logs from both running and stopped workloads for debugging purposes. The expected response is plain text containing log entries.

```bash
# Get logs for a workload
curl -X GET "http://localhost:8080/api/v1beta/workloads/my-filesystem-server/logs"

# Expected response (text/plain)
2025-11-05T10:30:01Z [INFO] MCP server starting
2025-11-05T10:30:02Z [INFO] Listening on stdio
2025-11-05T10:30:03Z [INFO] Ready to accept connections
```

--------------------------------

### Get Workload Status (Bash)

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Fetches the current status of a specific MCP server workload from ToolHive, including container health and resource usage. Requires the workload's name and returns detailed information in a JSON format.

```bash
# Get status for a specific workload
curl -X GET "http://localhost:8080/api/v1beta/workloads/my-filesystem-server/status"

# Expected response
{
  "name": "my-filesystem-server",
  "status": "running",
  "container_id": "abc123def456",
  "health": "healthy",
  "uptime_seconds": 3600,
  "cpu_usage": "15.5%",
  "memory_usage": "256MB",
  "restart_count": 0
}
```

--------------------------------

### ToolHive Binary Management with TypeScript

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Ensures the ToolHive backend binary (`thv`) is downloaded and up-to-date for the current platform and architecture. It also demonstrates how to spawn and manage the `thv` process.

```typescript
// utils/fetch-thv.ts
import { ensureToolhiveBinary } from './fetch-thv'

// Ensure thv binary is available and up-to-date
try {
  const binaryPath = await ensureToolhiveBinary()
  console.log('ToolHive binary ready at:', binaryPath)

  // Start the ToolHive backend process
  const thvProcess = spawn(binaryPath, ['serve', '--port', '8080'], {
    stdio: 'pipe',
    env: process.env
  })

  thvProcess.stdout.on('data', (data) => {
    console.log(`thv: ${data}`)
  })

  thvProcess.on('error', (error) => {
    console.error('Failed to start ToolHive:', error)
  })
} catch (error) {
  console.error('Failed to download ToolHive binary:', error)
}
```

--------------------------------

### Register an AI Client

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Register AI development tools like Claude Code, Cursor, and GitHub Copilot to enable automatic MCP server connection configuration.

```APIDOC
## POST /api/v1beta/clients

### Description
Registers an AI client application with ToolHive. This allows ToolHive to automatically configure the client with the necessary connection details for MCP servers it manages.

### Method
POST

### Endpoint
`/api/v1beta/clients`

### Request Body
- **name** (string) - Required - The name of the AI client (e.g., 'claude-code', 'cursor').
- **type** (string) - Required - The type identifier for the client (e.g., 'claude-code').
- **config_path** (string) - Required - The file path where the client stores its configuration.
- **groups** (array of strings) - Optional - A list of workload groups this client should connect to.

### Request Example
```json
{
  "name": "claude-code",
  "type": "claude-code",
  "config_path": "/Users/username/Library/Application Support/Claude/claude_desktop_config.json",
  "groups": ["development", "production"]
}
```

### Response
#### Success Response (200)
- **name** (string) - The registered name of the client.
- **config_path** (string) - The configuration file path for the client.

#### Response Example
```json
{
  "name": "claude-code",
  "config_path": "/Users/username/Library/Application Support/Claude/claude_desktop_config.json"
}
```
```

--------------------------------

### Register AI Client (TypeScript)

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Registers AI development tools (e.g., Claude Code, Cursor, GitHub Copilot) with ToolHive to enable automatic MCP server connection configuration. Requires the client's name, type, configuration path, and associated groups. Logs the registered client's name and config path upon successful registration.

```typescript
import { client } from './api/generated/client.gen'

// Register Claude Code client
const response = await client.POST('/api/v1beta/clients', {
  body: {
    name: 'claude-code',
    type: 'claude-code',
    config_path: '/Users/username/Library/Application Support/Claude/claude_desktop_config.json',
    groups: ['development', 'production']
  }
})

if (response.data) {
  console.log('Client registered:', response.data.name)
  console.log('Config file:', response.data.config_path)
}
```

--------------------------------

### Application State Management with TypeScript

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Manages global Electron application state, including handling quit status and interacting with the system tray icon. This is essential for a well-behaved desktop application.

```typescript
// main/src/app-state.ts
import {
  setQuittingState,
  getQuittingState,
  setTray,
  getTray
} from './app-state'

// Handle window close event
mainWindow.on('close', (event) => {
  if (!getQuittingState() && !isMac) {
    event.preventDefault()
    mainWindow.hide()
    return
  }
})

// Handle app quit
app.on('before-quit', () => {
  setQuittingState(true)

  // Clean up tray
  const tray = getTray()
  if (tray) {
    tray.destroy()
    setTray(null)
  }
})
```

--------------------------------

### Manage Secrets with TypeScript

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Provides functionalities to create, list, and delete secrets for secure environment variable injection into workloads using the ToolHive client library. Requires an initialized client instance.

```typescript
import { client } from './api/generated/client.gen'

// Create a new secret
await client.POST('/api/v1beta/secrets/default/keys/API_KEY', {
  body: {
    value: 'my-secret-api-key-value'
  }
})

// List all secrets
const secrets = await client.GET('/api/v1beta/secrets/default/keys')
console.log('Available secrets:', secrets.data?.keys)

// Delete a secret
await client.DELETE('/api/v1beta/secrets/default/keys/API_KEY')
```

--------------------------------

### React Query Integration for Data Fetching and Mutations

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Integrates TanStack Query hooks (`useQuery`, `useMutation`) for efficient data fetching, caching, and state management in React components. It utilizes the type-safe API client for operations like fetching workloads and creating new ones, with automatic cache invalidation upon successful mutations. Dependencies include '@tanstack/react-query', the generated API client, and React hooks.

```typescript
// renderer/src/hooks/use-workloads.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { client } from '../../api/generated/client.gen'

// Fetch workloads with automatic refetching
export const useWorkloads = (groupFilter?: string) => {
  return useQuery({
    queryKey: ['workloads', groupFilter],
    queryFn: async () => {
      const response = await client.GET('/api/v1beta/workloads', {
        params: { query: { group: groupFilter } }
      })
      if (response.error) throw new Error(response.error)
      return response.data.workloads
    },
    refetchInterval: 5000, // Refresh every 5 seconds
  })
}

// Create workload mutation
export const useCreateWorkload = () => {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: async (config: WorkloadConfig) => {
      const response = await client.POST('/api/v1beta/workloads', {
        body: config
      })
      if (response.error) throw new Error(response.error)
      return response.data
    },
    onSuccess: () => {
      // Invalidate and refetch workloads
      queryClient.invalidateQueries({ queryKey: ['workloads'] })
    }
  })
}
```

--------------------------------

### Type-Safe API Client with Generated TypeScript

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

A generated TypeScript client for type-safe communication with the ToolHive backend API. It configures the base URL dynamically using the backend port exposed via Electron's API and provides typed methods for API calls. Dependencies include the generated client code and Electron's `window.electronAPI`.

```typescript
// renderer/src/api-client.ts
import { client } from '../../api/generated/client.gen'

// Configure base URL from main process
const port = await window.electronAPI.getToolhivePort()
client.setConfig({
  baseUrl: `http://localhost:${port}`
})

// All API calls are fully typed
const listWorkloads = async () => {
  const response = await client.GET('/api/v1beta/workloads', {
    params: {
      query: {
        all: true,
        group: 'development'
      }
    }
  })

  if (response.error) {
    throw new Error(`API error: ${response.error}`)
  }

  // TypeScript knows the exact shape of response.data
  return response.data.workloads
}
```

--------------------------------

### Stop, Restart, and Delete Workloads

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Manage the lifecycle of workloads, including stopping, restarting, and deleting them by name or group.

```APIDOC
## POST /api/v1beta/workloads/stop
## POST /api/v1beta/workloads/restart
## POST /api/v1beta/workloads/delete

### Description
These endpoints allow you to control the execution state of your workloads. You can stop a running workload, restart a stopped or running workload, or permanently delete workloads.

### Method
POST

### Endpoints
- `/api/v1beta/workloads/stop`
- `/api/v1beta/workloads/restart`
- `/api/v1beta/workloads/delete`

### Request Body
- **names** (array of strings) - Optional - A list of workload names to perform the action on.
- **group** (string) - Optional - If `names` is not provided, specifies a group of workloads to perform the action on.

### Request Example (Stop)
```json
{
  "names": ["my-filesystem-server"]
}
```

### Request Example (Restart)
```json
{
  "names": ["my-filesystem-server"]
}
```

### Request Example (Delete by name)
```json
{
  "names": ["my-filesystem-server"]
}
```

### Request Example (Delete by group)
```json
{
  "group": "development"
}
```

### Response
#### Success Response (200)
Typically returns an empty body or a confirmation message upon successful operation.
```

--------------------------------

### List All Workloads (Bash)

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Retrieves all running MCP server workloads from the ToolHive API. Supports filtering by group name or including stopped workloads using the 'all=true' parameter. Returns a JSON object containing a list of workloads with their status, group, creation time, and proxy URL.

```bash
# List only running workloads
curl -X GET "http://localhost:8080/api/v1beta/workloads"

# List all workloads including stopped ones
curl -X GET "http://localhost:8080/api/v1beta/workloads?all=true"

# Filter workloads by group
curl -X GET "http://localhost:8080/api/v1beta/workloads?group=development"

# Expected response
{
  "workloads": [
    {
      "name": "filesystem-server",
      "status": "running",
      "group": "development",
      "created_at": "2025-11-05T10:30:00Z",
      "proxy_url": "http://localhost:8080/proxy/filesystem-server"
    }
  ]
}
```

--------------------------------

### Feature Flags System for Progressive Rollouts

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Implements a feature flagging system to enable or disable features progressively. It includes functions to check feature status in both the main and renderer processes, allowing for dynamic UI changes or behavior adjustments based on configuration. Dependencies include custom feature flag modules and React's `useState` and `useEffect` hooks for renderer-side checks.

```typescript
// main/src/feature-flags/index.ts
import { isFeatureEnabled } from './feature-flags'

// Check if a feature is enabled
if (isFeatureEnabled('chat-interface')) {
  // Show chat UI
  registerChatHandlers()
}

// Feature flags configuration
const flags: FeatureFlagOptions = {
  'chat-interface': true,
  'advanced-networking': false,
  'custom-registries': true
}

// Use in renderer
const ChatFeature = () => {
  const [enabled, setEnabled] = useState(false)

  useEffect(() => {
    window.electronAPI.isFeatureEnabled('chat-interface')
      .then(setEnabled)
  }, [])

  if (!enabled) return null
  return <ChatInterface />
}
```

--------------------------------

### List All Workloads

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Retrieve all running MCP server workloads. Supports filtering by group name and including stopped workloads.

```APIDOC
## GET /api/v1beta/workloads

### Description
Retrieves a list of all MCP server workloads. You can optionally filter by group or include stopped workloads.

### Method
GET

### Endpoint
`/api/v1beta/workloads`

### Query Parameters
- **all** (boolean) - Optional - If true, includes stopped workloads in the list.
- **group** (string) - Optional - Filters workloads by the specified group name.

### Response
#### Success Response (200)
- **workloads** (array) - A list of workload objects.
  - **name** (string) - The name of the workload.
  - **status** (string) - The current status of the workload (e.g., 'running', 'stopped').
  - **group** (string) - The group the workload belongs to.
  - **created_at** (string) - The timestamp when the workload was created.
  - **proxy_url** (string) - The URL to access the workload's proxy endpoint.

### Response Example
```json
{
  "workloads": [
    {
      "name": "filesystem-server",
      "status": "running",
      "group": "development",
      "created_at": "2025-11-05T10:30:00Z",
      "proxy_url": "http://localhost:8080/proxy/filesystem-server"
    }
  ]
}
```
```

--------------------------------

### Export Workload Configuration with Curl

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Exports the complete configuration of a specified workload as a JSON object. This is useful for backing up or sharing workload definitions.

```bash
# Export workload configuration
curl -X GET "http://localhost:8080/api/v1beta/workloads/my-filesystem-server/export"

# Expected response
{
  "name": "my-filesystem-server",
  "registry": "official",
  "server": "filesystem",
  "transport": "sse",
  "env": {
    "ALLOWED_PATHS": "/home/user/projects"
  },
  "args": ["--verbose"],
  "resources": {
    "cpu_limit": "1.0",
    "memory_limit": "512M"
  }
}
```

--------------------------------

### List Registries with Curl

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Retrieves a list of all configured MCP server registries and their available servers using a cURL command. This endpoint is useful for discovering available registry sources.

```bash
# List all registries
curl -X GET "http://localhost:8080/api/v1beta/registry"

# Expected response
{
  "registries": [
    {
      "name": "official",
      "url": "https://registry.toolhive.dev",
      "type": "public",
      "server_count": 25
    },
    {
      "name": "community",
      "url": "https://community.mcp-registry.io",
      "type": "public",
      "server_count": 150
    }
  ]
}
```

--------------------------------

### Export Workload Configuration

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Exports the complete configuration of a specified workload in JSON format. This is useful for backup purposes or for sharing workload configurations.

```APIDOC
## GET /api/v1beta/workloads/{workload_name}/export

### Description
Export a workload's complete configuration as JSON for backup or sharing.

### Method
GET

### Endpoint
`/api/v1beta/workloads/{workload_name}/export`

### Parameters
#### Path Parameters
- **workload_name** (string) - Required - The name of the workload to export.

#### Query Parameters
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1beta/workloads/my-filesystem-server/export"
```

### Response
#### Success Response (200)
- **name** (string) - The name of the workload.
- **registry** (string) - The registry where the workload is defined.
- **server** (string) - The specific server or component of the workload.
- **transport** (string) - The transport protocol used.
- **env** (object) - Environment variables for the workload.
- **args** (array of strings) - Command-line arguments for the workload.
- **resources** (object) - Resource configuration for the workload.
  - **cpu_limit** (string) - CPU limit.
  - **memory_limit** (string) - Memory limit.

#### Response Example
```json
{
  "name": "my-filesystem-server",
  "registry": "official",
  "server": "filesystem",
  "transport": "sse",
  "env": {
    "ALLOWED_PATHS": "/home/user/projects"
  },
  "args": ["--verbose"],
  "resources": {
    "cpu_limit": "1.0",
    "memory_limit": "512M"
  }
}
```
```

--------------------------------

### List Available Registries

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Retrieves a list of all configured MCP server registries and their respective server counts. This endpoint is useful for discovering available registry sources.

```APIDOC
## GET /api/v1beta/registry

### Description
Get all configured MCP server registries and their available servers.

### Method
GET

### Endpoint
`/api/v1beta/registry`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1beta/registry"
```

### Response
#### Success Response (200)
- **registries** (array) - A list of registry objects.
  - **name** (string) - The name of the registry.
  - **url** (string) - The URL of the registry.
  - **type** (string) - The type of the registry (e.g., 'public').
  - **server_count** (integer) - The number of servers available in the registry.

#### Response Example
```json
{
  "registries": [
    {
      "name": "official",
      "url": "https://registry.toolhive.dev",
      "type": "public",
      "server_count": 25
    },
    {
      "name": "community",
      "url": "https://community.mcp-registry.io",
      "type": "public",
      "server_count": 150
    }
  ]
}
```
```

--------------------------------

### Container Engine Detection with TypeScript

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Checks for the availability of Docker or Podman on the system, including enhanced path detection. This function is crucial for applications that rely on container runtimes.

```typescript
// main/src/container-engine.ts
import { checkContainerEngine } from './container-engine'

// Check if Docker or Podman is available
const engineStatus = await checkContainerEngine()

console.log('Docker available:', engineStatus.docker)
console.log('Podman available:', engineStatus.podman)
console.log('Any engine available:', engineStatus.available)

// Use in application startup
if (!engineStatus.available) {
  // Show error dialog to user
  dialog.showErrorBox(
    'Container Engine Required',
    'Please install Docker Desktop or Podman to use ToolHive'
  )
  app.quit()
}
```

--------------------------------

### IPC Communication Bridge with Electron ContextBridge

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Exposes a secure communication channel between Electron's renderer and main processes using `contextBridge`. It allows the renderer process to invoke functions in the main process, such as retrieving backend ports or checking application status. Dependencies include 'electron'.

```typescript
// preload/src/preload.ts
import { contextBridge, ipcRenderer } from 'electron'

// Exposed to renderer as window.electronAPI
contextBridge.exposeInMainWorld('electronAPI', {
  // Get ToolHive backend port
  getToolhivePort: () => ipcRenderer.invoke('get-toolhive-port'),

  // Check if ToolHive is running
  isToolhiveRunning: () => ipcRenderer.invoke('is-toolhive-running'),

  // Restart ToolHive backend
  restartToolhive: () => ipcRenderer.invoke('restart-toolhive'),

  // Container engine status
  checkContainerEngine: () => ipcRenderer.invoke('check-container-engine'),

  // Auto-launch management
  getAutoLaunchStatus: () => ipcRenderer.invoke('get-auto-launch-status'),
  setAutoLaunch: (enabled: boolean) =>
    ipcRenderer.invoke('set-auto-launch', enabled),
})

// Usage in renderer process (React component)
const checkStatus = async () => {
  const port = await window.electronAPI.getToolhivePort()
  const isRunning = await window.electronAPI.isToolhiveRunning()
  console.log(`ToolHive running on port ${port}:`, isRunning)
}
```

--------------------------------

### Manage Secrets API

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Provides endpoints for managing secrets, enabling secure storage and retrieval of sensitive information used for environment variable injection into workloads. Supports creation, listing, and deletion of secrets.

```APIDOC
## Secrets Management Endpoints

### Description
Create, list, and manage secrets for secure environment variable injection into workloads.

### Method
POST, GET, DELETE

### Endpoint
- `/api/v1beta/secrets/{namespace}/keys/{key_name}` (for POST and DELETE)
- `/api/v1beta/secrets/{namespace}/keys` (for GET)

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace for the secrets (e.g., 'default').
- **key_name** (string) - Required - The name of the secret key.

#### Query Parameters
None

#### Request Body (for POST)
- **value** (string) - Required - The value of the secret.

### Request Example
```typescript
// Create a new secret
await client.POST('/api/v1beta/secrets/default/keys/API_KEY', {
  body: {
    value: 'my-secret-api-key-value'
  }
})

// List all secrets
const secrets = await client.GET('/api/v1beta/secrets/default/keys')
console.log('Available secrets:', secrets.data?.keys)

// Delete a secret
await client.DELETE('/api/v1beta/secrets/default/keys/API_KEY')
```

### Response
#### Success Response (200)
- **keys** (array of strings) - A list of secret key names (for GET).

#### Response Example (for GET)
```json
{
  "keys": ["API_KEY", "DB_PASSWORD"]
}
```
```

--------------------------------

### Control Workload Lifecycle (TypeScript)

Source: https://context7.com/stacklok/toolhive-studio/llms.txt

Manages the lifecycle of MCP server workloads using the ToolHive API client. Provides functions to stop, restart, and delete workloads by specifying their names or group. Returns a response indicating the success or failure of the operation.

```typescript
import { client } from './api/generated/client.gen'

// Stop a workload
const stopResponse = await client.POST('/api/v1beta/workloads/stop', {
  body: {
    names: ['my-filesystem-server']
  }
})

// Restart a workload
const restartResponse = await client.POST('/api/v1beta/workloads/restart', {
  body: {
    names: ['my-filesystem-server']
  }
})

// Delete workloads by name or group
const deleteResponse = await client.POST('/api/v1beta/workloads/delete', {
  body: {
    names: ['my-filesystem-server'],
    // Or delete by group: group: 'development'
  }
})
```

--------------------------------

### Conventional Commits Specification

Source: https://github.com/stacklok/toolhive-studio/blob/main/CONTRIBUTING.md

The standard format for commit messages used in this project, including types, optional scopes, descriptions, bodies, and footers. This helps maintain a consistent and understandable commit history.

```text
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

--------------------------------

### Add DCO Signed-off-by Trailer to Git Commit

Source: https://github.com/stacklok/toolhive-studio/blob/main/DCO.md

This snippet shows how to include the 'Signed-off-by' trailer in a git commit message, which will be required for DCO compliance. It demonstrates the trailer format and the git command to automatically add it. This is essential for legal compliance in future contributions.

```bash
git commit -s -m "A commit message\n\nCloses gh-345\n\nSigned-off-by: jane marmot <jmarmot@example.org>"
```

```bash
git commit -s -m "A commit message\n\nCloses gh-345\n\nSigned-off-by: jane marmot <462403+jmarmot@users.noreply.github.com>"
```

--------------------------------

### Conventional Commits Specification - Types

Source: https://github.com/stacklok/toolhive-studio/blob/main/CONTRIBUTING.md

Defines the types of changes that can be made to the codebase, such as new features, bug fixes, documentation updates, styling changes, refactoring, performance improvements, tests, and chores.

```text
Types:

- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation only changes
- `style`: Changes that do not affect the meaning of the code (white-space,
  formatting, etc.)
- `refactor`: A code change that neither fixes a bug nor adds a feature
- `perf`: A code change that improves performance
- `test`: Adding missing tests or correcting existing tests
- `chore`: Changes to the build process or auxiliary tools and libraries
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.