List all environments in an Octopus Deploy space

Instructions

Implementation Reference

• src/tools/listEnvironments.ts:29-88 (handler)

  The async handler function that executes the list_environments tool logic: creates an Octopus API client, queries environments via EnvironmentRepository, and returns formatted results.

  async ({ spaceName, partialName, skip, take }) => {
    try {
      const configuration = getClientConfigurationFromEnvironment();
      const client = await Client.create(configuration);
      const environmentRepository = new EnvironmentRepository(
        client,
        spaceName,
      );
  
      const environmentsResponse = await environmentRepository.list({
        partialName,
        skip,
        take,
      });
  
      if (environmentsResponse.Items.length === 0) {
        const message = partialName
          ? `No environments found matching '${partialName}' in space '${spaceName}'. Environment names are case-sensitive.`
          : `No environments found in space '${spaceName}'. This space may not have any environments configured.`;
  
        return {
          content: [
            {
              type: "text",
              text: message,
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              totalResults: environmentsResponse.TotalResults,
              itemsPerPage: environmentsResponse.ItemsPerPage,
              numberOfPages: environmentsResponse.NumberOfPages,
              lastPageNumber: environmentsResponse.LastPageNumber,
              items: environmentsResponse.Items.map(
                (environment: DeploymentEnvironment) => ({
                  spaceId: environment.SpaceId,
                  id: environment.Id,
                  name: environment.Name,
                  description: environment.Description,
                  sortOrder: environment.SortOrder,
                  useGuidedFailure: environment.UseGuidedFailure,
                  allowDynamicInfrastructure:
                    environment.AllowDynamicInfrastructure,
                  extensionSettings: environment.ExtensionSettings,
                }),
              ),
            }),
          },
        ],
      };
    } catch (error) {
      handleOctopusApiError(error, { spaceName });
    }
  },

• src/tools/listEnvironments.ts:16-27 (schema)

  Input schema definition for list_environments tool: validates spaceName (required string), partialName (optional string), skip (optional number), and take (optional number).

    {
      title: "List all environments in an Octopus Deploy space",
      description: `List environments in a space
  
  This tool lists all environments in a given space. The space name is required. Use this tool as early as possible to understand which environments are configured. Optionally filter by partial name match using partialName parameter.`,
      inputSchema: {
        spaceName: z.string(),
        partialName: z.string().optional(),
        skip: z.number().optional(),
        take: z.number().optional(),
      },
      annotations: READ_ONLY_TOOL_ANNOTATIONS,

• src/tools/listEnvironments.ts:92-96 (registration)

  Self-registration call added to the global TOOL_REGISTRY map with toolset 'core' and readOnly: true.

  registerToolDefinition({
    toolName: "list_environments",
    config: { toolset: "core", readOnly: true },
    registerFn: registerListEnvironmentsTool,
  });

• src/tools/listEnvironments.ts:13-90 (handler)

  The public registration function registerListEnvironmentsTool that calls server.registerTool with the name 'list_environments'.

  export function registerListEnvironmentsTool(server: McpServer) {
    server.registerTool(
      "list_environments",
      {
        title: "List all environments in an Octopus Deploy space",
        description: `List environments in a space
  
    This tool lists all environments in a given space. The space name is required. Use this tool as early as possible to understand which environments are configured. Optionally filter by partial name match using partialName parameter.`,
        inputSchema: {
          spaceName: z.string(),
          partialName: z.string().optional(),
          skip: z.number().optional(),
          take: z.number().optional(),
        },
        annotations: READ_ONLY_TOOL_ANNOTATIONS,
      },
      async ({ spaceName, partialName, skip, take }) => {
        try {
          const configuration = getClientConfigurationFromEnvironment();
          const client = await Client.create(configuration);
          const environmentRepository = new EnvironmentRepository(
            client,
            spaceName,
          );
  
          const environmentsResponse = await environmentRepository.list({
            partialName,
            skip,
            take,
          });
  
          if (environmentsResponse.Items.length === 0) {
            const message = partialName
              ? `No environments found matching '${partialName}' in space '${spaceName}'. Environment names are case-sensitive.`
              : `No environments found in space '${spaceName}'. This space may not have any environments configured.`;
  
            return {
              content: [
                {
                  type: "text",
                  text: message,
                },
              ],
            };
          }
  
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({
                  totalResults: environmentsResponse.TotalResults,
                  itemsPerPage: environmentsResponse.ItemsPerPage,
                  numberOfPages: environmentsResponse.NumberOfPages,
                  lastPageNumber: environmentsResponse.LastPageNumber,
                  items: environmentsResponse.Items.map(
                    (environment: DeploymentEnvironment) => ({
                      spaceId: environment.SpaceId,
                      id: environment.Id,
                      name: environment.Name,
                      description: environment.Description,
                      sortOrder: environment.SortOrder,
                      useGuidedFailure: environment.UseGuidedFailure,
                      allowDynamicInfrastructure:
                        environment.AllowDynamicInfrastructure,
                      extensionSettings: environment.ExtensionSettings,
                    }),
                  ),
                }),
              },
            ],
          };
        } catch (error) {
          handleOctopusApiError(error, { spaceName });
        }
      },
    );
  }

• src/helpers/errorHandling.ts:1-36 (helper)

  Error handling utility imported and used in the list_environments handler via handleOctopusApiError.

  /**
   * Enhanced error handling utilities for Octopus Deploy MCP Server tools
   */
  
  /**
   * Checks if the error is an Error instance and has a message containing the specified text
   */
  export function isErrorWithMessage(
    error: unknown,
    messageFragment: string,
  ): error is Error {
    return (
      error instanceof Error && error.message?.includes(messageFragment) === true
    );
  }
  
  /**
   * Common error handler for Octopus Deploy API errors with actionable messages
   */
  export function handleOctopusApiError(
    error: unknown,
    context: {
      entityType?: string;
      entityId?: string;
      spaceName?: string;
      helpText?: string;
    },
  ): never {
    const { entityType, entityId, spaceName, helpText } = context;
  
    // Handle 404/not found errors
    if (
      isErrorWithMessage(error, "not found") ||
      isErrorWithMessage(error, "404")
    ) {
      if (entityType && entityId && spaceName) {