Octopus Deploy MCP Server

Instructions

Implementation Reference

• src/tools/listDeployments.ts:27-78 (handler)

  Handler function that executes the list_deployments tool: connects to Octopus Deploy, 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)

  Input schema using Zod for validating parameters: spaceName (required), optional filters for projects, environments, tenants, channels, taskState, skip, take.
  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)

  Registration function registerListDeploymentsTool that calls server.tool to register the list_deployments tool with name, description, schema, hints, and 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 in the TOOL_REGISTRY via registerToolDefinition for dynamic enabling/disabling.
  registerToolDefinition({ toolName: "list_deployments", config: { toolset: "deployments", readOnly: true }, registerFn: registerListDeploymentsTool, });