Package com.eqixiac.equinix.mcp.server.broker

package com.eqixiac.equinix.mcp.server.broker
The Safe Mutation Broker — the embedded MCP server's only route to a mutation, enforced by the server rather than by prompt discipline: agents propose, dry-run diffs decide, humans confirm.

The broker is a two-phase protocol over two tools in the opt-in mutate toolset (never served unless the operator names it in the toolset selection):

  1. fabric_propose_change — takes a typed create specification (ChangeType: connection, network, or service-token create; there are no update or delete change types) and executes the real, spec-documented dry run through the SDK's fluent creators (dryRun=true on the actual Fabric v4 endpoint). The Equinix API validates the exact payload that a confirm would send, but provisions nothing. The tool returns the validated entity, a rate-card price context where estimable (honest unpriced otherwise), and a single-use confirm token bound to the SHA-256 of the canonicalized spec.
  2. fabric_confirm_change — takes only the confirm token, re-verifies the spec hash, and executes the stored spec via the same creator without dryRun. The agent cannot alter the spec between phases: a different spec is a different proposal with a different token.

Tokens live in the in-memory, single-process ProposalStore for 10 minutes and are consumed on the first confirm attempt, successful or not. Expired, unknown, and replayed tokens each fail with a message telling the agent to re-propose.

Policy, matching the read-only catalog's rules: no delete tools of any kind, and no mutation outside this broker.

  • Class
    Description
    BrokerToolFactory
    The Safe Mutation Broker's two tools — fabric_propose_change and fabric_confirm_change — registered through the exact same ToolRegistration seam as the read-only catalog, in the opt-in Toolset.MUTATE toolset.
    ChangeType
    The mutations the Safe Mutation Broker can carry — deliberately the smallest honest set: three creates, each backed by a spec-documented Fabric v4 dry run the propose phase exercises for real.
    PendingChange
    One dry-run-validated proposal awaiting confirmation: the single-use confirm token, the change type, the exact canonicalized spec the dry run validated (the confirm phase executes this stored spec — never a re-supplied one), the SHA-256 the token is bound to, and the expiry instant.
    ProposalStore
    In-memory, TTL-bounded, single-use store for the Safe Mutation Broker's pending proposals, keyed by confirm token.
    ProposalStore.Consumption
    The result of one consume attempt.
    ProposalStore.Outcome
    How a ProposalStore.consume(String) attempt resolved.