Update a feature toggle

Instructions

Implementation Reference

• src/tools/updateFeatureToggle.ts:194-390 (handler)

  Main handler that resolves the space, fetches the current toggle, applies environment patches, validates changes, prompts for confirmation, and PUTs the merged toggle resource.

  export async function updateFeatureToggleHandler(
    server: McpServer,
    params: UpdateFeatureToggleParams,
  ) {
    const { spaceName, projectId, slug, environments, confirm } = params;
  
    const noPatches =
      params.defaultIsEnabled === undefined &&
      params.description === undefined &&
      (!environments || environments.length === 0);
    if (noPatches) {
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                success: false,
                reason: "no_patches",
                message:
                  "No fields supplied to update. Pass at least one of defaultIsEnabled, description, or environments[].",
              },
              null,
              2,
            ),
          },
        ],
        isError: true,
      };
    }
  
    const client = await Client.create(getClientConfigurationFromEnvironment());
  
    let spaceId: string;
    try {
      spaceId = await resolveSpaceId(client, spaceName);
    } catch (error) {
      handleOctopusApiError(error, { spaceName });
    }
  
    let current: FeatureToggleResource;
    try {
      current = await client.get<FeatureToggleResource>(
        "~/api/{spaceId}/projects/{projectId}/featuretoggles/{slug}",
        { spaceId, projectId, slug },
      );
    } catch (error) {
      handleOctopusApiError(error, {
        entityType: "feature toggle",
        entityId: slug,
        spaceName,
        helpText:
          "Use find_feature_toggles to list valid slugs. If 404 persists across all toggles in the project, the customer feature toggles capability may be disabled on the Octopus instance.",
      });
    }
  
    // Match patch entries to existing environment configurations. Unknown
    // environments are rejected — the contract is "slight adjustment", not
    // "configure new environments".
    const envPatches: PatchedEnvironment[] = [];
    if (environments) {
      for (const patch of environments) {
        const existing = current.Environments.find(
          (e) => e.DeploymentEnvironmentId === patch.deploymentEnvironmentId,
        );
        if (!existing) {
          const configured = current.Environments.map(
            (e) => e.DeploymentEnvironmentId,
          );
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify(
                  {
                    success: false,
                    reason: "environment_not_configured",
                    message:
                      `Environment '${patch.deploymentEnvironmentId}' is not configured on toggle '${current.Slug}'. ` +
                      "This tool only adjusts existing environment configurations; it does not add new ones. " +
                      "Use the Octopus UI to add an environment to a toggle.",
                    configuredEnvironmentIds: configured,
                  },
                  null,
                  2,
                ),
              },
            ],
            isError: true,
          };
        }
        envPatches.push(applyEnvironmentPatch(existing, patch));
      }
    }
  
    // Detect a no-op call (everything provided already matches current state)
    // before involving the user with a confirmation dialog.
    const toggleLevelChanges =
      (params.defaultIsEnabled !== undefined &&
        params.defaultIsEnabled !== current.DefaultIsEnabled) ||
      (params.description !== undefined &&
        params.description !== (current.Description ?? undefined));
    const envLevelChanges = envPatches.some((p) => p.changedFields.length > 0);
    if (!toggleLevelChanges && !envLevelChanges) {
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                success: true,
                noOp: true,
                message:
                  "All supplied fields already match the current toggle state — nothing to update.",
                slug: current.Slug,
              },
              null,
              2,
            ),
          },
        ],
      };
    }
  
    const merged: FeatureToggleResource = {
      ...current,
      DefaultIsEnabled:
        params.defaultIsEnabled !== undefined
          ? params.defaultIsEnabled
          : current.DefaultIsEnabled,
      Description:
        params.description !== undefined ? params.description : current.Description,
      Environments: current.Environments.map((env) => {
        const patch = envPatches.find(
          (p) => p.current.DeploymentEnvironmentId === env.DeploymentEnvironmentId,
        );
        return patch ? patch.merged : env;
      }),
    };
  
    const confirmation = await requireConfirmation(server, {
      message: `Update feature toggle "${current.Name}" (${current.Slug}) in space ${spaceName}?`,
      fallbackConfirm: confirm,
      change: {
        source: buildDiffSource(current, params, envPatches),
        target: buildDiffTarget(params, envPatches),
      },
    });
    if (!confirmation.confirmed) {
      return unconfirmedResponse(confirmation, {
        action: "feature toggle update",
      });
    }
  
    try {
      await client.doUpdate<FeatureToggleResource>(
        "~/api/{spaceId}/projects/{projectId}/featuretoggles",
        merged,
        { spaceId, projectId },
      );
    } catch (error) {
      handleOctopusApiError(error, {
        entityType: "feature toggle",
        entityId: current.Id,
        spaceName,
        helpText:
          "Verify you have FeatureToggleEdit on the project and every environment referenced. Server-side validation rules (max segments, ephemeral environment clamping, etc.) are documented in the Octopus feature toggles API reference.",
      });
    }
  
    const encodedSpace = encodeURIComponent(spaceName);
    const encodedProjectId = encodeURIComponent(projectId);
    const encodedSlug = encodeURIComponent(current.Slug);
    const resourceUri = `octopus://spaces/${encodedSpace}/projects/${encodedProjectId}/featuretoggles/${encodedSlug}`;
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(
            {
              success: true,
              id: current.Id,
              slug: current.Slug,
              name: current.Name,
              resourceUri,
              message: `Feature toggle '${current.Slug}' updated successfully.`,
              helpText:
                "Dereference resourceUri to read the updated toggle body.",
            },
            null,
            2,
          ),
        },
      ],
    };
  }

• src/tools/updateFeatureToggle.ts:83-106 (schema)

  Input validation schema with superRefine that rejects duplicate deploymentEnvironmentIds in the environments array.

  export const updateFeatureToggleValidationSchema =
    updateFeatureToggleInputSchema.superRefine((args, ctx) => {
      // Reject duplicate deploymentEnvironmentIds up front. Without this,
      // the merge picks the FIRST patch for the env while the confirmation
      // diff overwrites earlier entries with later ones using the same key —
      // the user could see one change in the prompt and a different one
      // actually go through.
      if (!args.environments) return;
      const seen = new Map<string, number>();
      for (let i = 0; i < args.environments.length; i++) {
        const id = args.environments[i].deploymentEnvironmentId;
        const prev = seen.get(id);
        if (prev !== undefined) {
          ctx.addIssue({
            code: z.ZodIssueCode.custom,
            message:
              `Duplicate environment entry for '${id}' at index ${i} (also at index ${prev}). ` +
              "Combine the patches into a single entry per environment.",
            path: ["environments", i, "deploymentEnvironmentId"],
          });
        }
        seen.set(id, i);
      }
    });

• src/tools/updateFeatureToggle.ts:79-81 (schema)

  Raw input schema (published as inputSchema for the MCP tool registration) defining spaceName, projectId, slug, defaultIsEnabled, description, environments (array of patches), and confirm.

  export const updateFeatureToggleInputSchema = z.object(
    updateFeatureToggleRawShape,
  );

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

  Schema for per-environment patches: deploymentEnvironmentId, isEnabled, rolloutPercentage, clientRolloutPercentage.

  const environmentPatchSchema = z.object({

• src/tools/updateFeatureToggle.ts:415-420 (registration)

  Self-registration via registerToolDefinition, called at module import time (side effect when src/tools/index.ts imports the file).

  registerToolDefinition({
    toolName: "update_feature_toggle",
    config: { toolset: "featureToggles", readOnly: false },
    registerFn: registerUpdateFeatureToggleTool,
    minimumOctopusVersion: "2026.1.10655",
  });

• src/tools/updateFeatureToggle.ts:392-413 (registration)

  Registers the tool with the MCP server under the name 'update_feature_toggle', with input schema and a callback that validates and delegates to the handler.

  export function registerUpdateFeatureToggleTool(server: McpServer) {
    server.registerTool(
      "update_feature_toggle",
      {
        title: "Update a feature toggle",
        description: `Adjust an existing customer feature toggle in an Octopus Deploy project.
  
  Narrow surface — flip an environment on/off, change rollout percentages, or update the toggle-level description / default state. Internally fetches the current toggle, applies your patches in memory, and PUTs the merged body, so unmentioned environments and unmentioned fields are preserved.
  
  Deliberately not exposed: name/slug rename, tag changes, rollout group attach/detach, tenant targeting, segments, minimum version, adding or removing environment configurations entirely. For those, use the Octopus UI.
  
  Patches that reference an environment not already configured on the toggle are rejected with reason: environment_not_configured. The tool does not add new environment configurations.`,
        inputSchema: updateFeatureToggleInputSchema,
        annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
      },
      async (args) => {
        const parsed = updateFeatureToggleValidationSchema.safeParse(args);
        if (!parsed.success) return zodErrorResponse(parsed.error);
        return updateFeatureToggleHandler(server, parsed.data);
      },
    );
  }