Mercury

12.01.26·Jordan Prescott
Mercury

The Brief

BroadWorks is one of the most widely deployed telephony platforms in the world. It is also, by most accounts, a nightmare to build on top of.
The platform has interfaces — OCIP being the primary one — but working with them directly means wrestling with raw XML schemas, manual connection orchestration, and a development experience that feels designed to discourage automation rather than enable it. Mercury was built to change that: a Python SDK that wraps the BroadWorks OCIP interface in a clean abstraction layer, making the platform programmable in the way it always should have been.
The result is not a single tool but an ecosystem — three components targeting three distinct personas, from the developer who wants raw async speed to the engineer who just wants to stop doing things manually.

The Problem

Before Mercury, automating anything in BroadWorks was either painful, slow, or simply not done.
The OCIP interface exists, but working with it directly requires the correct schemas, careful connection handling, significant orchestration, and a tolerance for raw XML that most modern engineers don't have and shouldn't need. Anything in bulk had to be done manually — hours of repetitive configuration that couldn't be scripted. Orchestration around the platform was effectively impossible.
Existing open-source solutions existed but were narrow — limited to either SOAP or TCP, limited in feature set, and not built with production engineering teams in mind. The gap was real, and the cost of it was measured in engineer-hours spent on work that should never have required a human.

The Approach

The solution started as a single SDK and grew into a three-tier ecosystem shaped by a lesson learned early: handing an SDK to a non-developer and expecting them to run with it doesn't work. You end up trying to turn engineers into developers, and engineers don't want to learn to code — they want their problems solved.
That insight drove the architecture. Rather than a single monolithic tool, Mercury became a layered ecosystem built around personas:
  • The SDK for developers who want to build with BroadWorks programmatically
  • The CLI for engineers and administrators who want automation without writing code
  • The async engine for developers building enterprise-scale applications on top of BroadWorks
Each layer uses the one beneath it. Each serves a distinct audience. Together they cover the full spectrum of who actually works with BroadWorks.

The Work

Mercury OCIP — The SDK

The core SDK, written in Python 3.12, managed with uv. Published on PyPI as mercury-ocip.
Supports both BroadWorks connection types — SOAP and TCP — simultaneously. BroadWorks XML schemas are run through a custom-built parser that generates Pydantic classes. Pydantic was the deliberate choice — the type safety, validation speed, and memory efficiency it provides is material when running bulk operations against a live telephony platform.
On top of the raw command layer sits the Agent — alias lookup, bulk user creation from CSV, automated configuration workflows. 67 commits. 13 releases. MIT licensed.

Mercury CLI — The Terminal Interface

When the SDK reached non-developer engineers, the feedback was consistent: they didn't want to write Python. They wanted the features.
The CLI is a terminal wrapper around Mercury OCIP, exposing core automation and bulk operation features through a command-line interface. It targets the engineer persona precisely: comfortable in a terminal, not interested in a Python REPL.

Mercury OCIP Fast — The Async Engine

A stripped-down async version of the SDK for developers building production applications on top of BroadWorks at scale. Asynchronous, deliberately lean, opens multiple connections to BroadWorks and load-balances across them per client instance. Designed for speed and throughput.

Documentation

Three separate MkDocs documentation sites — one per component — covering the full surface area of each.

The Outcome

An open-source ecosystem that genuinely extends what BroadWorks can do. The SDK is on PyPI, actively maintained, and in use. Engineers who previously spent hours on manual configuration tasks now run a CLI command. The things that weren't possible before Mercury are now table stakes.

Stack & Tools

  • Python 3.12 — primary language
  • uv — package management (Astral)
  • Pydantic — schema validation and type safety
  • SOAP + TCP — dual BroadWorks connection support
  • MkDocs — documentation
  • PyPI — package distribution
  • Docker — containerisation
  • GitHub Actions — CI/CD and release automation
Next Entry
L'Antidote

L'Antidote