list_deployment_targets
Retrieve deployment targets (machines) from a specified space with optional filtering by name, roles, health status, and 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 |
|---|---|---|---|
| commStyles | No | ||
| deploymentId | No | ||
| deploymentTargetTypes | No | ||
| environmentIds | No | ||
| healthStatuses | No | Possible values: Healthy, Unhealthy, Unavailable, Unknown, HasWarnings | |
| ids | No | ||
| isDisabled | No | ||
| name | No | ||
| partialName | No | ||
| roles | No | A list of roles / target tags to filter by. | |
| shellNames | No | ||
| skip | No | ||
| spaceName | Yes | ||
| take | No | ||
| tenantIds | No | ||
| tenantTags | No | ||
| thumbprint | No |
Implementation Reference
- The core handler function that executes the tool: creates Octopus client, resolves space, queries machines API with filters, maps results, and returns JSON response.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, }), }, ], }; }
- Input schema using Zod validators for parameters: required spaceName and optional filters like pagination, 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(), },
- src/tools/listDeploymentTargets.ts:8-122 (registration)Primary registration function that calls server.tool() to register the tool with MCP server, including name, description, schema, output hint, 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 call that adds the tool to the global TOOL_REGISTRY for conditional enabling via src/tools/index.ts.registerToolDefinition({ toolName: "list_deployment_targets", config: { toolset: "machines", readOnly: true }, registerFn: registerListDeploymentTargetsTool, });