Octopus Deploy MCP Server

Instructions

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";