Get Kubernetes live status from Octopus Deploy

Instructions

Implementation Reference

• src/tools/getKubernetesLiveStatus.ts:9-97 (handler)

  The main handler function that registers the 'get_kubernetes_live_status' tool with the MCP server. Validates entity IDs (project, environment, tenant), creates an Octopus API client, calls observabilityRepository.getLiveStatus() to fetch Kubernetes live status data, formats the response with machine statuses and resources, and handles errors (including a version check for Octopus 2025.3+).

  export function registerGetKubernetesLiveStatusTool(server: McpServer) {
    server.registerTool(
      "get_kubernetes_live_status",
      {
        title: "Get Kubernetes live status from Octopus Deploy",
        description: `Get Kubernetes live status for a project and environment
  
    This tool retrieves the live status of Kubernetes resources for a specific project and environment. Optionally include a tenant ID for multi-tenant deployments.`,
        inputSchema: {
          spaceName: z.string().describe("The space name"),
          projectId: z.string().describe("The ID of the project"),
          environmentId: z.string().describe("The ID of the environment"),
          tenantId: z.string().optional().describe("The ID of the tenant (for multi-tenant deployments)"),
          summaryOnly: z.boolean().optional().describe("Return summary information only")
        },
        annotations: READ_ONLY_TOOL_ANNOTATIONS,
      },
      async ({ spaceName, projectId, environmentId, tenantId, summaryOnly = false }) => {
        validateEntityId(projectId, 'project', ENTITY_PREFIXES.project);
        validateEntityId(environmentId, 'environment', ENTITY_PREFIXES.environment);
        if (tenantId) {
          validateEntityId(tenantId, 'tenant', ENTITY_PREFIXES.tenant);
        }
  
        try {
          const configuration = getClientConfigurationFromEnvironment();
          const client = await Client.create(configuration);
          const observabilityRepository = new ObservabilityRepository(client, spaceName);
  
          const liveStatus = await observabilityRepository.getLiveStatus(
            projectId,
            environmentId,
            tenantId,
            summaryOnly
          );
  
          if (!liveStatus || (!liveStatus.MachineStatuses && !liveStatus.Summary)) {
            throw new Error(
              `No Kubernetes live status found for project '${projectId}' in environment '${environmentId}'${tenantId ? ` for tenant '${tenantId}'` : ''}. ` +
              "This may indicate that the project is not deployed to Kubernetes in this environment, or the resources are not being monitored."
            );
          }
  
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({
                  projectId,
                  environmentId,
                  tenantId,
                  summaryOnly: summaryOnly,
                  liveStatus: {
                    machineStatuses: liveStatus.MachineStatuses?.map((machine: KubernetesMachineLiveStatusResource) => ({
                      machineId: machine.MachineId,
                      status: machine.Status,
                      resources: machine.Resources?.map((resource: KubernetesLiveStatusResource) => ({
                        name: resource.Name,
                        namespace: resource.Namespace,
                        kind: resource.Kind,
                        healthStatus: resource.HealthStatus,
                        syncStatus: resource.SyncStatus,
                        machineId: resource.MachineId,
                        children: resource.Children,
                        desiredResourceId: resource.DesiredResourceId,
                        resourceId: resource.ResourceId
                      }))
                    })),
                    summary: liveStatus.Summary ? {
                      status: liveStatus.Summary.Status,
                      lastUpdated: liveStatus.Summary.LastUpdated
                    } : undefined
                  }
                }),
              },
            ],
          };
        } catch (error) {
          if (isErrorWithMessage(error, 'minimum version')) {
            throw new Error(
              `Kubernetes live status requires Octopus Deploy version 2025.3 or later. ` +
              "This feature is not available in your Octopus Deploy instance version."
            );
          }
          handleOctopusApiError(error, { spaceName });
        }
      }
    );
  }

• src/tools/getKubernetesLiveStatus.ts:17-25 (schema)

  Input schema using Zod validation: requires spaceName (string), projectId (string), environmentId (string), with optional tenantId (string) and summaryOnly (boolean).

    inputSchema: {
      spaceName: z.string().describe("The space name"),
      projectId: z.string().describe("The ID of the project"),
      environmentId: z.string().describe("The ID of the environment"),
      tenantId: z.string().optional().describe("The ID of the tenant (for multi-tenant deployments)"),
      summaryOnly: z.boolean().optional().describe("Return summary information only")
    },
    annotations: READ_ONLY_TOOL_ANNOTATIONS,
  },

• src/tools/getKubernetesLiveStatus.ts:99-104 (registration)

  Registers the tool in the global TOOL_REGISTRY with toolset 'kubernetes', read-only mode, and a minimum Octopus Deploy version requirement of 2025.3.

  registerToolDefinition({
    toolName: "get_kubernetes_live_status",
    config: { toolset: "kubernetes", readOnly: true },
    registerFn: registerGetKubernetesLiveStatusTool,
    minimumOctopusVersion: "2025.3",
  });

• src/tools/index.ts:16-16 (registration)

  Imports the tool module in src/tools/index.ts so that the self-registration call (registerToolDefinition) is executed when tools are loaded.

  import "./getKubernetesLiveStatus.js";

• src/helpers/getClientConfigurationFromEnvironment.ts:61-67 (helper)

  Helper that reads Octopus Deploy server configuration from environment variables (OCTOPUS_SERVER_URL, OCTOPUS_API_KEY, OCTOPUS_ACCESS_TOKEN) to create the API client configuration used by the tool.

  export function getClientConfigurationFromEnvironment(): ClientConfiguration {
    return getClientConfiguration({
      instanceURL: env["CLI_SERVER_URL"] || env["OCTOPUS_SERVER_URL"],
      apiKey: env["OCTOPUS_API_KEY"],
      accessToken: env["OCTOPUS_ACCESS_TOKEN"],
    });
  }