list_deployments
Read-only
Retrieve deployment records from Octopus Deploy by specifying a space, with optional filters for projects, environments, tenants, channels, and task states to focus on relevant DevOps activities.
Instructions
List deployments in a space
This tool lists deployments in a given space. The space name is required. When requesting latest deployment consider which deployment state the user is interested in (successful or all). Optional filters include: projects (array of project IDs), environments (array of environment IDs), tenants (array of tenant IDs), channels (array of channel IDs), taskState (one of: Canceled, Cancelling, Executing, Failed, Queued, Success, TimedOut), and take (number of results to return).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| spaceName | Yes | ||
| projects | No | ||
| environments | No | ||
| tenants | No | ||
| channels | No | ||
| taskState | No | ||
| skip | No | ||
| take | No |
Implementation Reference
- src/tools/listDeployments.ts:27-79 (handler)The asynchronous handler function that executes the tool logic: connects to Octopus Deploy client, queries deployments with filters, and returns JSON-formatted results.
async ({ spaceName, projects, environments, tenants, channels, taskState, skip, take }) => { const configuration = getClientConfigurationFromEnvironment(); const client = await Client.create(configuration); const deploymentRepository = new DeploymentRepository(client, spaceName); const deploymentsResponse = await deploymentRepository.list({ projects, environments, tenants, channels, taskState: taskState ? TaskState[taskState as keyof typeof TaskState] : undefined, skip, take }); return { content: [ { type: "text", text: JSON.stringify({ totalResults: deploymentsResponse.TotalResults, itemsPerPage: deploymentsResponse.ItemsPerPage, numberOfPages: deploymentsResponse.NumberOfPages, lastPageNumber: deploymentsResponse.LastPageNumber, items: deploymentsResponse.Items.map((deployment: Deployment) => ({ spaceId: deployment.SpaceId, id: deployment.Id, name: deployment.Name, releaseId: deployment.ReleaseId, environmentId: deployment.EnvironmentId, tenantId: deployment.TenantId, projectId: deployment.ProjectId, channelId: deployment.ChannelId, created: deployment.Created, taskId: deployment.TaskId, deploymentProcessId: deployment.DeploymentProcessId, comments: deployment.Comments, formValues: deployment.FormValues, queueTime: deployment.QueueTime, queueTimeExpiry: deployment.QueueTimeExpiry, useGuidedFailure: deployment.UseGuidedFailure, specificMachineIds: deployment.SpecificMachineIds, excludedMachineIds: deployment.ExcludedMachineIds, skipActions: deployment.SkipActions, forcePackageDownload: deployment.ForcePackageDownload, forcePackageRedeployment: deployment.ForcePackageRedeployment, })) }), }, ], }; } ); - src/tools/listDeployments.ts:14-22 (schema)Zod schema defining the input parameters for the list_deployments tool, including required spaceName and optional filters.
spaceName: z.string(), projects: z.array(z.string()).optional(), environments: z.array(z.string()).optional(), tenants: z.array(z.string()).optional(), channels: z.array(z.string()).optional(), taskState: z.enum(["Canceled", "Cancelling", "Executing", "Failed", "Queued", "Success", "TimedOut"]).optional(), skip: z.number().optional(), take: z.number().optional() }, - src/tools/listDeployments.ts:7-80 (registration)The registerListDeploymentsTool function called by the server to register the 'list_deployments' tool with name, description, schema, metadata, and inline handler.
export function registerListDeploymentsTool(server: McpServer) { server.tool( "list_deployments", `List deployments in a space This tool lists deployments in a given space. The space name is required. When requesting latest deployment consider which deployment state the user is interested in (successful or all). Optional filters include: projects (array of project IDs), environments (array of environment IDs), tenants (array of tenant IDs), channels (array of channel IDs), taskState (one of: Canceled, Cancelling, Executing, Failed, Queued, Success, TimedOut), and take (number of results to return).`, { spaceName: z.string(), projects: z.array(z.string()).optional(), environments: z.array(z.string()).optional(), tenants: z.array(z.string()).optional(), channels: z.array(z.string()).optional(), taskState: z.enum(["Canceled", "Cancelling", "Executing", "Failed", "Queued", "Success", "TimedOut"]).optional(), skip: z.number().optional(), take: z.number().optional() }, { title: "List deployments in an Octopus Deploy space", readOnlyHint: true, }, async ({ spaceName, projects, environments, tenants, channels, taskState, skip, take }) => { const configuration = getClientConfigurationFromEnvironment(); const client = await Client.create(configuration); const deploymentRepository = new DeploymentRepository(client, spaceName); const deploymentsResponse = await deploymentRepository.list({ projects, environments, tenants, channels, taskState: taskState ? TaskState[taskState as keyof typeof TaskState] : undefined, skip, take }); return { content: [ { type: "text", text: JSON.stringify({ totalResults: deploymentsResponse.TotalResults, itemsPerPage: deploymentsResponse.ItemsPerPage, numberOfPages: deploymentsResponse.NumberOfPages, lastPageNumber: deploymentsResponse.LastPageNumber, items: deploymentsResponse.Items.map((deployment: Deployment) => ({ spaceId: deployment.SpaceId, id: deployment.Id, name: deployment.Name, releaseId: deployment.ReleaseId, environmentId: deployment.EnvironmentId, tenantId: deployment.TenantId, projectId: deployment.ProjectId, channelId: deployment.ChannelId, created: deployment.Created, taskId: deployment.TaskId, deploymentProcessId: deployment.DeploymentProcessId, comments: deployment.Comments, formValues: deployment.FormValues, queueTime: deployment.QueueTime, queueTimeExpiry: deployment.QueueTimeExpiry, useGuidedFailure: deployment.UseGuidedFailure, specificMachineIds: deployment.SpecificMachineIds, excludedMachineIds: deployment.ExcludedMachineIds, skipActions: deployment.SkipActions, forcePackageDownload: deployment.ForcePackageDownload, forcePackageRedeployment: deployment.ForcePackageRedeployment, })) }), }, ], }; } ); } - src/tools/listDeployments.ts:82-86 (registration)Self-registration of the tool into the TOOL_REGISTRY, specifying toolset and readOnly config, linking to the register function.
registerToolDefinition({ toolName: "list_deployments", config: { toolset: "deployments", readOnly: true }, registerFn: registerListDeploymentsTool, }); - src/tools/index.ts:13-13 (registration)Import statement in tools index that triggers the side-effect registration of listDeployments tool via registerToolDefinition.
import "./listDeployments.js";