CONTAM MCP

Instructions

Implementation Reference

• contam-mcp/src/server.js:2405-2726 (handler)

  The "advance_contam_bridge_session" tool is registered here in server.js. It calls `session.advance()` to perform the actual logic of applying adjustments and advancing the simulation.

  server.tool(
    "advance_contam_bridge_session",
    "Use this when you want to send control/weather adjustments to a running bridge session and optionally advance ContamX to a new simulation time.",
    {
      sessionId: z.string(),
      targetTimeSeconds: z.number().int().min(0).optional(),
      advanceBySeconds: z.number().int().min(1).optional(),
      requestConcentrations: z.boolean().optional(),
      requestPathFlows: z.boolean().optional(),
      requestTermFlows: z.boolean().optional(),
      requestAhspFlows: z.boolean().optional(),
      requestDuctFlows: z.boolean().optional(),
      requestLeakFlows: z.boolean().optional(),
      requestOutputControlValues: z.boolean().optional(),
      controlNodeAdjustments: z
        .array(
          z.object({
            nodeId: z.number().int(),
            value: z.number()
          })
        )
        .optional(),
      namedControlNodeAdjustments: z
        .array(
          z.object({
            controlNodeName: z.string(),
            value: z.number()
          })
        )
        .optional(),
      zoneConcentrationAdjustments: z
        .array(
          z.object({
            option: z.union([z.literal(0), z.literal(1)]),
            agentId: z.number().int(),
            zoneIds: z.array(z.number().int()),
            values: z.array(z.number())
          })
        )
        .optional(),
      namedZoneConcentrationAdjustments: z
        .array(
          z.object({
            option: z.union([z.literal(0), z.literal(1)]),
            agentId: z.number().int().optional(),
            agentName: z.string().optional(),
            zoneNames: z.array(z.string()),
            values: z.array(z.number())
          })
        )
        .optional(),
      zoneTemperatureAdjustments: z
        .object({
          zoneIds: z.array(z.number().int()),
          values: z.array(z.number())
        })
        .optional(),
      namedZoneTemperatureAdjustments: z
        .object({
          zoneNames: z.array(z.string()),
          values: z.array(z.number())
        })
        .optional(),
      junctionTemperatureAdjustments: z
        .object({
          junctionIds: z.array(z.number().int()),
          values: z.array(z.number())
        })
        .optional(),
      namedJunctionTemperatureAdjustments: z
        .object({
          junctionNames: z.array(z.string()),
          values: z.array(z.number())
        })
        .optional(),
      zoneHumidityRatioAdjustments: z
        .object({
          zoneIds: z.array(z.number().int()),
          values: z.array(z.number())
        })
        .optional(),
      namedZoneHumidityRatioAdjustments: z
        .object({
          zoneNames: z.array(z.string()),
          values: z.array(z.number())
        })
        .optional(),
      elementAdjustments: z
        .array(
          z.object({
            pathId: z.number().int(),
            elementIndex: z.number().int()
          })
        )
        .optional(),
      namedElementAdjustments: z
        .array(
          z.object({
            pathId: z.number().int().optional(),
            pathSelectorLabel: z.string().optional(),
            fromZoneName: z.string().optional(),
            toZoneName: z.string().optional(),
            elementIndex: z.number().int().optional(),
            elementName: z.string().optional()
          })
        )
        .optional(),
      ahspFlowAdjustments: z
        .object({
          pathIds: z.array(z.number().int()),
          values: z.array(z.number())
        })
        .optional(),
      ahsPoaAdjustments: z
        .object({
          ahsIds: z.array(z.number().int()),
          values: z.array(z.number())
        })
        .optional(),
      namedAhsPoaAdjustments: z
        .object({
          names: z.array(z.string()),
          values: z.array(z.number())
        })
        .optional(),
      weatherAdjustment: z
        .object({
          temperatureK: z.number(),
          pressurePa: z.number(),
          windSpeed: z.number(),
          windDirection: z.number(),
          humidityRatio: z.number().optional()
        })
        .optional(),
      namedAmbientPressureAdjustment: z
        .object({
          timeSeconds: z.number().int().optional(),
          ambientTargetNames: z.array(z.string()),
          values: z.array(z.number()),
          fillValue: z.number().optional()
        })
        .optional(),
      namedAmbientConcentrationAdjustments: z
        .array(
          z.object({
            timeSeconds: z.number().int().optional(),
            agentId: z.number().int().optional(),
            agentName: z.string().optional(),
            ambientTargetNames: z.array(z.string()),
            values: z.array(z.number()),
            fillValue: z.number().optional()
          })
        )
        .optional(),
      wpcAdjustment: z
        .object({
          timeSeconds: z.number().int().optional(),
          agentIds: z.array(z.number().int()).optional(),
          values: z.array(z.number())
        })
        .optional(),
      timeoutSeconds: z.number().int().min(1).max(300).optional()
    },
    async ({
      sessionId,
      targetTimeSeconds,
      advanceBySeconds,
      requestConcentrations,
      requestPathFlows,
      requestTermFlows,
      requestAhspFlows,
      requestDuctFlows,
      requestLeakFlows,
      requestOutputControlValues,
      controlNodeAdjustments,
      namedControlNodeAdjustments,
      zoneConcentrationAdjustments,
      namedZoneConcentrationAdjustments,
      zoneTemperatureAdjustments,
      namedZoneTemperatureAdjustments,
      junctionTemperatureAdjustments,
      namedJunctionTemperatureAdjustments,
      zoneHumidityRatioAdjustments,
      namedZoneHumidityRatioAdjustments,
      elementAdjustments,
      namedElementAdjustments,
      ahspFlowAdjustments,
      ahsPoaAdjustments,
      namedAhsPoaAdjustments,
      weatherAdjustment,
      namedAmbientPressureAdjustment,
      namedAmbientConcentrationAdjustments,
      wpcAdjustment,
      timeoutSeconds
    }) => {
      const session = bridgeSessions.get(sessionId);
      if (!session) {
        throw new Error(`Bridge session not found: ${sessionId}`);
      }
  
      const optionFlags =
        (requestConcentrations ? 2 : 0) +
        (requestPathFlows ? 4 : 0) +
        (requestAhspFlows ? 8 : 0) +
        (requestDuctFlows ? 16 : 0) +
        (requestTermFlows ? 32 : 0) +
        (requestLeakFlows ? 64 : 0) +
        (requestOutputControlValues ? 128 : 0);
  
      let resolvedTargetTime = targetTimeSeconds ?? null;
      if (resolvedTargetTime === null && advanceBySeconds !== undefined) {
        resolvedTargetTime = (session.readyTimeSeconds ?? 0) + advanceBySeconds;
      }
  
      const resolvedControlNodeAdjustments = resolveControlNodeAdjustments(
        session.bridgeMetadata,
        controlNodeAdjustments,
        namedControlNodeAdjustments
      );
      const resolvedZoneConcentrationAdjustments = resolveZoneConcentrationAdjustments(
        session.bridgeMetadata,
        zoneConcentrationAdjustments,
        namedZoneConcentrationAdjustments
      );
      const resolvedZoneTemperatureAdjustments = mergeNamedZoneArrayAdjustment(
        session.bridgeMetadata,
        zoneTemperatureAdjustments,
        namedZoneTemperatureAdjustments
      );
      const resolvedJunctionTemperatureAdjustments = mergeNamedJunctionArrayAdjustment(
        session.bridgeMetadata,
        junctionTemperatureAdjustments,
        namedJunctionTemperatureAdjustments
      );
      const resolvedZoneHumidityRatioAdjustments = mergeNamedZoneArrayAdjustment(
        session.bridgeMetadata,
        zoneHumidityRatioAdjustments,
        namedZoneHumidityRatioAdjustments
      );
      const resolvedElementAdjustments = resolveElementAdjustments(
        session.bridgeMetadata,
        elementAdjustments,
        namedElementAdjustments
      );
      const resolvedAhsPoaAdjustments = mergeNamedIdArrayAdjustment(
        ahsPoaAdjustments,
        namedAhsPoaAdjustments,
        "ahsIds",
        "values",
        (name) =>
          resolveEntityByName(
            session.bridgeMetadata.ahsSystems ?? [],
            name,
            (item) => item.name,
            "AHS",
            (item) => `${item.id}:${item.name}`
          ).id
      );
      if (
        wpcAdjustment &&
        ((namedAmbientConcentrationAdjustments?.length ?? 0) > 0 || namedAmbientPressureAdjustment)
      ) {
        throw new Error(
          "Provide either wpcAdjustment or the named ambient ADJ_WPC helpers, not both."
        );
      }
      if (namedAmbientPressureAdjustment && (namedAmbientConcentrationAdjustments?.length ?? 0) > 0) {
        throw new Error(
          "Provide either namedAmbientPressureAdjustment or namedAmbientConcentrationAdjustments in one call."
        );
      }
      const resolvedWpcAdjustments = wpcAdjustment
        ? [wpcAdjustment]
        : namedAmbientPressureAdjustment
          ? [buildNamedAmbientPressureAdjustment(session.bridgeMetadata, namedAmbientPressureAdjustment)]
          : buildNamedAmbientConcentrationAdjustments(
              session.bridgeMetadata,
              namedAmbientConcentrationAdjustments
            );
  
      if (resolvedTargetTime === null) {
        await session.applyAdjustments({
          controlNodeAdjustments: resolvedControlNodeAdjustments,
          weatherAdjustment,
          zoneConcentrationAdjustments: resolvedZoneConcentrationAdjustments,
          zoneTemperatureAdjustments: resolvedZoneTemperatureAdjustments,
          junctionTemperatureAdjustments: resolvedJunctionTemperatureAdjustments,
          zoneHumidityRatioAdjustments: resolvedZoneHumidityRatioAdjustments,
          elementAdjustments: resolvedElementAdjustments,
          ahspFlowAdjustments,
          ahsPoaAdjustments: resolvedAhsPoaAdjustments,
          wpcAdjustments: resolvedWpcAdjustments
        });
        return toolResponse("Applied bridge adjustments without advancing ContamX.", session.getSummary());
      }
  
      const cycle = await session.advance({
        targetTimeSeconds: resolvedTargetTime,
        optionFlags,
        controlNodeAdjustments: resolvedControlNodeAdjustments,
        weatherAdjustment,
        zoneConcentrationAdjustments: resolvedZoneConcentrationAdjustments,
        zoneTemperatureAdjustments: resolvedZoneTemperatureAdjustments,
        junctionTemperatureAdjustments: resolvedJunctionTemperatureAdjustments,
        zoneHumidityRatioAdjustments: resolvedZoneHumidityRatioAdjustments,
        elementAdjustments: resolvedElementAdjustments,
        ahspFlowAdjustments,
        ahsPoaAdjustments: resolvedAhsPoaAdjustments,
        wpcAdjustments: resolvedWpcAdjustments,
        timeoutSeconds: timeoutSeconds ?? 30
      });
  
      return toolResponse("Advanced the ContamX bridge session.", {
        sessionId,
        targetTimeSeconds: resolvedTargetTime,
        readyTimeSeconds: session.readyTimeSeconds,
        optionFlags,
        updates: cycle.messages.filter((message) => message.type >= bridgeMessageTypes.CONC_UPDATE),
        summary: session.getSummary()
      });
    }
  );