List deployments in an Octopus Deploy space

Instructions

Implementation Reference

• src/tools/listDeployments.ts:9-130 (handler)

  The main handler function that registers the 'list_deployments' tool on the MCP server. It accepts filters (spaceName, projects, environments, tenants, channels, taskState, skip, take), queries the Octopus Deploy API via DeploymentRepository.list(), fetches associated release versions and version control references, and returns a formatted JSON response including deployment details and public URLs.

  export function registerListDeploymentsTool(server: McpServer) {
    server.registerTool(
      "list_deployments",
      {
        title: "List deployments in an Octopus Deploy space",
        description: `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).`,
        inputSchema: {
          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()
        },
        annotations: READ_ONLY_TOOL_ANNOTATIONS,
      },
      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
        });
  
        const deployments = deploymentsResponse.Items as Deployment[];
        const releaseIds = Array.from(
          new Set(
            deployments
              .map((deployment) => deployment.ReleaseId)
              .filter((releaseId): releaseId is string => Boolean(releaseId))
          )
        );
  
        const releaseVersions = new Map<string, string>();
        const releaseVersionControlReferences = new Map<string, { GitRef?: string; GitCommit?: string }>();
  
        if (releaseIds.length > 0) {
          const releaseRepository = new ReleaseRepository(client, spaceName);
          const releaseResults = await Promise.allSettled(releaseIds.map((id) => releaseRepository.get(id)));
  
          releaseResults.forEach((result, index) => {
            if (result.status === "fulfilled") {
              releaseVersions.set(releaseIds[index]!, result.value.Version);
              if (result.value.VersionControlReference) {
                releaseVersionControlReferences.set(releaseIds[index]!, result.value.VersionControlReference);
              }
            }
          });
        }
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                totalResults: deploymentsResponse.TotalResults,
                itemsPerPage: deploymentsResponse.ItemsPerPage,
                numberOfPages: deploymentsResponse.NumberOfPages,
                lastPageNumber: deploymentsResponse.LastPageNumber,
                items: deployments.map((deployment) => {
                  const releaseVersion = deployment.ReleaseId ? releaseVersions.get(deployment.ReleaseId) : undefined;
                  const versionControlReference = deployment.ReleaseId ? releaseVersionControlReferences.get(deployment.ReleaseId) : undefined;
                  const publicUrl = releaseVersion
                    ? getPublicUrl(
                        `${configuration.instanceURL}/app#/{spaceId}/projects/{projectId}/deployments/releases/{releaseVersion}/deployments/{deploymentId}`,
                        {
                          spaceId: deployment.SpaceId,
                          projectId: deployment.ProjectId,
                          releaseVersion,
                          deploymentId: deployment.Id,
                        }
                      )
                    : undefined;
  
                  return {
                    spaceId: deployment.SpaceId,
                    id: deployment.Id,
                    name: deployment.Name,
                    releaseId: deployment.ReleaseId,
                    releaseVersion,
                    versionControlReference,
                    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,
                    publicUrl,
                    publicUrlInstruction: publicUrl
                      ? "You can view more details about this deployment in the Octopus Deploy web portal at the provided publicUrl."
                      : undefined,
                  };
                })
              }),
            },
          ],
        };
      }
    );
  }

• src/tools/listDeployments.ts:132-136 (registration)

  Self-registration of the 'list_deployments' tool via registerToolDefinition(), which adds it to the global TOOL_REGISTRY map with toolset 'deployments' and readOnly: true.

  registerToolDefinition({
    toolName: "list_deployments",
    config: { toolset: "deployments", readOnly: true },
    registerFn: registerListDeploymentsTool,
  });

• src/tools/listDeployments.ts:12-27 (schema)

  Input schema defined using Zod for the list_deployments tool. Parameters: spaceName (required string), projects, environments, tenants, channels (optional arrays of strings), taskState (optional enum), skip and take (optional numbers).

    {
      title: "List deployments in an Octopus Deploy space",
      description: `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).`,
      inputSchema: {
        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()
      },
      annotations: READ_ONLY_TOOL_ANNOTATIONS,

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

  Import of the listDeployments module in the tools index, which triggers its self-registration when the module is loaded.

  import "./listDeployments.js";

• src/types/toolConfig.ts:53-55 (helper)

  The registerToolDefinition() helper function that stores tool registrations in the global TOOL_REGISTRY Map, used by list_deployments for self-registration.

  export function registerToolDefinition(registration: ToolRegistration) {
    TOOL_REGISTRY.set(registration.toolName, registration);
  }