list_deployment_targets
Retrieve deployment targets (machines) within a specified Octopus Deploy space. Filter results by name, roles, health status, or other parameters to identify available infrastructure for deployments.
Instructions
List deployment targets (machines) in a space
This tool lists all deployment targets in a given space. The space name is required. You can optionally filter by various parameters like name, roles, health status, etc.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| spaceName | Yes | ||
| skip | No | ||
| take | No | ||
| name | No | ||
| ids | No | ||
| partialName | No | ||
| roles | No | A list of roles / target tags to filter by. | |
| isDisabled | No | ||
| healthStatuses | No | Possible values: Healthy, Unhealthy, Unavailable, Unknown, HasWarnings | |
| commStyles | No | ||
| tenantIds | No | ||
| tenantTags | No | ||
| environmentIds | No | ||
| thumbprint | No | ||
| deploymentId | No | ||
| shellNames | No | ||
| deploymentTargetTypes | No |
Implementation Reference
- The handler function that fetches deployment targets from the Octopus Deploy API using the provided filters, maps the response, and returns a JSON-formatted text content.async ({ spaceName, skip, take, name, ids, partialName, roles, isDisabled, healthStatuses, commStyles, tenantIds, tenantTags, environmentIds, thumbprint, deploymentId, shellNames, deploymentTargetTypes, }) => { const configuration = getClientConfigurationFromEnvironment(); const client = await Client.create(configuration); const spaceId = await resolveSpaceId(client, spaceName); const response = await client.get<ResourceCollection<DeploymentTargetResource>>( "~/api/{spaceId}/machines{?skip,take,name,ids,partialName,roles,isDisabled,healthStatuses,commStyles,tenantIds,tenantTags,environmentIds,thumbprint,deploymentId,shellNames,deploymentTargetTypes}", { spaceId, skip, take, name, ids, partialName, roles, isDisabled, healthStatuses, commStyles, tenantIds, tenantTags, environmentIds, thumbprint, deploymentId, shellNames, deploymentTargetTypes, } ); const deploymentTargets = response.Items.map((target: DeploymentTargetResource) => ({ spaceId: target.SpaceId, id: target.Id, name: target.Name, slug: target.Slug, isDisabled: target.IsDisabled, healthStatus: target.HealthStatus, statusSummary: target.StatusSummary, environmentIds: target.EnvironmentIds, roles: target.Roles, tenantedDeploymentParticipation: target.TenantedDeploymentParticipation, tenantIds: target.TenantIds, tenantTags: target.TenantTags, endpoint: { communicationStyle: target.Endpoint.CommunicationStyle, uri: target.Endpoint.Uri, fingerprint: target.Endpoint.Fingerprint, }, shellName: target.ShellName, machinePolicyId: target.MachinePolicyId, hasLatestCalamari: target.HasLatestCalamari, isInProcess: target.IsInProcess, })); return { content: [ { type: "text", text: JSON.stringify({ totalResults: response.TotalResults, itemsPerPage: response.ItemsPerPage, numberOfPages: response.NumberOfPages, lastPageNumber: response.LastPageNumber, items: deploymentTargets, }), }, ], }; }
- Zod schema defining the input parameters for filtering and paginating the list of deployment targets.spaceName: z.string(), skip: z.number().optional(), take: z.number().optional(), name: z.string().optional(), ids: z.array(z.string()).optional(), partialName: z.string().optional(), roles: z.array(z.string()).optional().describe("A list of roles / target tags to filter by."), isDisabled: z.boolean().optional(), healthStatuses: z.array(z.string()).optional().describe("Possible values: Healthy, Unhealthy, Unavailable, Unknown, HasWarnings"), commStyles: z.array(z.string()).optional(), tenantIds: z.array(z.string()).optional(), tenantTags: z.array(z.string()).optional(), environmentIds: z.array(z.string()).optional(), thumbprint: z.string().optional(), deploymentId: z.string().optional(), shellNames: z.array(z.string()).optional(), deploymentTargetTypes: z.array(z.string()).optional(), },
- src/tools/listDeploymentTargets.ts:8-122 (registration)The registration function that registers the 'list_deployment_targets' tool on the MCP server, including name, description, schema, and handler.export function registerListDeploymentTargetsTool(server: McpServer) { server.tool( "list_deployment_targets", `List deployment targets (machines) in a space This tool lists all deployment targets in a given space. The space name is required. You can optionally filter by various parameters like name, roles, health status, etc.`, { spaceName: z.string(), skip: z.number().optional(), take: z.number().optional(), name: z.string().optional(), ids: z.array(z.string()).optional(), partialName: z.string().optional(), roles: z.array(z.string()).optional().describe("A list of roles / target tags to filter by."), isDisabled: z.boolean().optional(), healthStatuses: z.array(z.string()).optional().describe("Possible values: Healthy, Unhealthy, Unavailable, Unknown, HasWarnings"), commStyles: z.array(z.string()).optional(), tenantIds: z.array(z.string()).optional(), tenantTags: z.array(z.string()).optional(), environmentIds: z.array(z.string()).optional(), thumbprint: z.string().optional(), deploymentId: z.string().optional(), shellNames: z.array(z.string()).optional(), deploymentTargetTypes: z.array(z.string()).optional(), }, { title: "List all deployment targets in an Octopus Deploy space", readOnlyHint: true, }, async ({ spaceName, skip, take, name, ids, partialName, roles, isDisabled, healthStatuses, commStyles, tenantIds, tenantTags, environmentIds, thumbprint, deploymentId, shellNames, deploymentTargetTypes, }) => { const configuration = getClientConfigurationFromEnvironment(); const client = await Client.create(configuration); const spaceId = await resolveSpaceId(client, spaceName); const response = await client.get<ResourceCollection<DeploymentTargetResource>>( "~/api/{spaceId}/machines{?skip,take,name,ids,partialName,roles,isDisabled,healthStatuses,commStyles,tenantIds,tenantTags,environmentIds,thumbprint,deploymentId,shellNames,deploymentTargetTypes}", { spaceId, skip, take, name, ids, partialName, roles, isDisabled, healthStatuses, commStyles, tenantIds, tenantTags, environmentIds, thumbprint, deploymentId, shellNames, deploymentTargetTypes, } ); const deploymentTargets = response.Items.map((target: DeploymentTargetResource) => ({ spaceId: target.SpaceId, id: target.Id, name: target.Name, slug: target.Slug, isDisabled: target.IsDisabled, healthStatus: target.HealthStatus, statusSummary: target.StatusSummary, environmentIds: target.EnvironmentIds, roles: target.Roles, tenantedDeploymentParticipation: target.TenantedDeploymentParticipation, tenantIds: target.TenantIds, tenantTags: target.TenantTags, endpoint: { communicationStyle: target.Endpoint.CommunicationStyle, uri: target.Endpoint.Uri, fingerprint: target.Endpoint.Fingerprint, }, shellName: target.ShellName, machinePolicyId: target.MachinePolicyId, hasLatestCalamari: target.HasLatestCalamari, isInProcess: target.IsInProcess, })); return { content: [ { type: "text", text: JSON.stringify({ totalResults: response.TotalResults, itemsPerPage: response.ItemsPerPage, numberOfPages: response.NumberOfPages, lastPageNumber: response.LastPageNumber, items: deploymentTargets, }), }, ], }; } ); }
- src/tools/listDeploymentTargets.ts:124-128 (registration)Self-registration of the tool into the global TOOL_REGISTRY for conditional enabling.registerToolDefinition({ toolName: "list_deployment_targets", config: { toolset: "machines", readOnly: true }, registerFn: registerListDeploymentTargetsTool, });
- src/tools/index.ts:25-25 (registration)Import that triggers the self-registration of the listDeploymentTargets tool.import "./listDeploymentTargets.js";