Octopus Deploy MCP Server

Instructions

Implementation Reference

• src/tools/listEnvironments.ts:23-53 (handler)

  The handler function that executes the list_environments tool. It connects to Octopus Deploy using configuration from environment variables, lists environments in the specified space with optional filters (partialName, skip, take), and returns paginated results as JSON in a text content block.

  async ({ spaceName, partialName, skip, take }) => {
    const configuration = getClientConfigurationFromEnvironment();
    const client = await Client.create(configuration);
    const environmentRepository = new EnvironmentRepository(client, spaceName);
  
    const environmentsResponse = await environmentRepository.list({ partialName, skip, take });
  
    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,
            }))
          }),
        },
      ],
    };
  }

• src/tools/listEnvironments.ts:13-18 (schema)

  Input schema defined with Zod: requires spaceName (string), optional partialName (string for filtering), skip and take (numbers for pagination).

  {
    spaceName: z.string(),
    partialName: z.string().optional(),
    skip: z.number().optional(),
    take: z.number().optional()
  },

• src/tools/listEnvironments.ts:58-62 (registration)

  Self-registration of the list_environments tool into the TOOL_REGISTRY, marking it as core toolset and read-only. This is triggered by the import in src/tools/index.ts.

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

• src/tools/listEnvironments.ts:7-55 (registration)

  The registerListEnvironmentsTool function called to register the tool on the MCP server, including name, description, schemas, and handler.

  export function registerListEnvironmentsTool(server: McpServer) {
    server.tool(
      "list_environments",
      `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.`,
      {
        spaceName: z.string(),
        partialName: z.string().optional(),
        skip: z.number().optional(),
        take: z.number().optional()
      },
      {
        title: "List all environments in an Octopus Deploy space",
        readOnlyHint: true,
      },
      async ({ spaceName, partialName, skip, take }) => {
        const configuration = getClientConfigurationFromEnvironment();
        const client = await Client.create(configuration);
        const environmentRepository = new EnvironmentRepository(client, spaceName);
  
        const environmentsResponse = await environmentRepository.list({ partialName, skip, take });
  
        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,
                }))
              }),
            },
          ],
        };
      }
    );
  }