molcompose-mcp 0.1.1__tar.gz

molcompose_mcp-0.1.1/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026, MolCompose contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

molcompose_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: molcompose-mcp
+Version: 0.1.1
+Summary: Agent-safe MCP server exposing MolCompose figure commands in UCSF ChimeraX
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2
+Dynamic: license-file
+
+# molcompose-mcp
+
+An agent-safe [MCP](https://modelcontextprotocol.io) server that exposes the
+MolCompose figure workflow in UCSF ChimeraX as typed tools. Agents call the
+same canonical `molcompose` commands as the GUI panel — versioned presets,
+validated inputs, and a complete provenance record for every exported figure.
+
+## Requirements
+
+1. UCSF ChimeraX 1.12 with the ChimeraX-MolCompose bundle installed.
+2. Start the REST bridge inside ChimeraX:
+
+```
+remotecontrol rest start port 3000 json true
+```
+
+(Image export requires a windowed ChimeraX on macOS; analysis tools also work
+with `--nogui`.)
+
+## Run
+
+```bash
+pip install molcompose-mcp
+molcompose-mcp --chimerax-url http://127.0.0.1:3000
+```
+
+Register the command above as an MCP stdio server in whichever client you use.
+The protocol is open and this server is not written against any one client; a
+command-line client is enough.
+
+Most clients take the same shape of config:
+
+```json
+{
+  "mcpServers": {
+    "molcompose": {
+      "command": "molcompose-mcp",
+      "args": ["--chimerax-url", "http://127.0.0.1:3000"]
+    }
+  }
+}
+```
+
+Check your client's documentation for its configuration-file location rather
+than trusting a path written here, since client conventions change.
+
+## Optional: PythiaStudio ΔΔG
+
+`predict_ddg_pythiastudio` fetches binding/stability ΔΔG from the
+[PythiaStudio](https://pythiastudio.wulab.xyz) REST API and writes a tabular
+file that `load_ddg` then loads into ChimeraX. This is the **only networked
+tool** — the bundle itself never calls out, which keeps its zero-service
+dependency profile intact while the agent acts as the integration layer.
+Set `PYTHIASTUDIO_API_KEY` or pass a key explicitly.
+
+## Safety model
+
+- Figure work goes through the typed `molcompose` tools only.
+- Native passthrough is limited to an enumerated display-only whitelist
+  (`open`, `close`, `view`, `select`, `color`, `show`, `hide`, ...).
+- Coordinate- or file-modifying commands are rejected with a structured error.
+- Every export writes `<figure>.provenance.json` with the client identity,
+  timestamps, and the full command recipe.

molcompose_mcp-0.1.1/README.md

@@ -0,0 +1,63 @@
+# molcompose-mcp
+
+An agent-safe [MCP](https://modelcontextprotocol.io) server that exposes the
+MolCompose figure workflow in UCSF ChimeraX as typed tools. Agents call the
+same canonical `molcompose` commands as the GUI panel — versioned presets,
+validated inputs, and a complete provenance record for every exported figure.
+
+## Requirements
+
+1. UCSF ChimeraX 1.12 with the ChimeraX-MolCompose bundle installed.
+2. Start the REST bridge inside ChimeraX:
+
+```
+remotecontrol rest start port 3000 json true
+```
+
+(Image export requires a windowed ChimeraX on macOS; analysis tools also work
+with `--nogui`.)
+
+## Run
+
+```bash
+pip install molcompose-mcp
+molcompose-mcp --chimerax-url http://127.0.0.1:3000
+```
+
+Register the command above as an MCP stdio server in whichever client you use.
+The protocol is open and this server is not written against any one client; a
+command-line client is enough.
+
+Most clients take the same shape of config:
+
+```json
+{
+  "mcpServers": {
+    "molcompose": {
+      "command": "molcompose-mcp",
+      "args": ["--chimerax-url", "http://127.0.0.1:3000"]
+    }
+  }
+}
+```
+
+Check your client's documentation for its configuration-file location rather
+than trusting a path written here, since client conventions change.
+
+## Optional: PythiaStudio ΔΔG
+
+`predict_ddg_pythiastudio` fetches binding/stability ΔΔG from the
+[PythiaStudio](https://pythiastudio.wulab.xyz) REST API and writes a tabular
+file that `load_ddg` then loads into ChimeraX. This is the **only networked
+tool** — the bundle itself never calls out, which keeps its zero-service
+dependency profile intact while the agent acts as the integration layer.
+Set `PYTHIASTUDIO_API_KEY` or pass a key explicitly.
+
+## Safety model
+
+- Figure work goes through the typed `molcompose` tools only.
+- Native passthrough is limited to an enumerated display-only whitelist
+  (`open`, `close`, `view`, `select`, `color`, `show`, `hide`, ...).
+- Coordinate- or file-modifying commands are rejected with a structured error.
+- Every export writes `<figure>.provenance.json` with the client identity,
+  timestamps, and the full command recipe.

molcompose_mcp-0.1.1/molcompose_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Agent-safe MCP server for MolCompose in UCSF ChimeraX."""
+
+__version__ = "0.1.1"

molcompose_mcp-0.1.1/molcompose_mcp/chimerax.py

@@ -0,0 +1,125 @@
+"""Minimal HTTP client for the ChimeraX ``remotecontrol rest`` bridge."""
+
+import json
+import re
+from urllib.error import URLError
+from urllib.parse import urlencode
+from urllib.request import urlopen
+
+# ChimeraX writes its log for a GUI panel: every command it echoes is wrapped
+# in a clickable link, and the whole command text is repeated inside the href.
+# In a `characterise` on 1BRS that markup is 56% of the reply — 6.2 kB of
+# duplicated pbond syntax an agent must read past to reach the findings.
+_LOG_LINK = re.compile(r"\[(?P<label>[^\]]*)\]\((?:cxcmd|help):[^)]*\)", re.DOTALL)
+
+
+class ChimeraXUnavailable(RuntimeError):
+    """Raised when the ChimeraX REST bridge cannot be reached."""
+
+
+class ChimeraXClient:
+    def __init__(self, base_url: str = "http://127.0.0.1:3000", timeout: float = 120.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def run(self, command: str) -> dict:
+        """Run one ChimeraX command; return parsed JSON or {'raw': text}."""
+        url = f"{self.base_url}/run?{urlencode({'command': command})}"
+        try:
+            with urlopen(url, timeout=self.timeout) as response:  # noqa: S310 - localhost bridge
+                text = response.read().decode("utf-8", errors="replace")
+        except (URLError, OSError) as error:
+            raise ChimeraXUnavailable(
+                "Cannot reach ChimeraX. Start ChimeraX (windowed for image export), "
+                "make sure ChimeraX-MolCompose is installed, and run: "
+                "remotecontrol rest start port 3000 json true "
+                f"(tried {self.base_url}; error: {error})"
+            ) from error
+        try:
+            return json.loads(text)
+        except ValueError:
+            return {"raw": text}
+
+
+#: What `command_value` returns when the bridge cannot supply a return value.
+#: Distinct from ``None``, which is a return value a command may legitimately
+#: have — telling the two apart is the difference between "this command
+#: reported nothing" and "this bridge cannot report anything".
+NO_VALUE = object()
+
+
+def log_text(payload: dict) -> str:
+    """Flatten whatever log structure the REST bridge returned into one string.
+
+    The command's *return value* is deliberately not folded in here. It used to
+    be, as ``str(payload["python values"])``, which put a Python repr of the
+    result on the end of the log — duplicating findings the command had already
+    logged, and leaving the structured value reachable only by parsing it back
+    out again. `command_value` returns it as data instead.
+    """
+    if "raw" in payload:
+        return str(payload["raw"])
+    parts = []
+    messages = payload.get("log messages")
+    if isinstance(messages, dict):
+        for level_messages in messages.values():
+            if isinstance(level_messages, list):
+                parts.extend(str(message) for message in level_messages)
+    elif isinstance(messages, list):
+        parts.extend(str(message) for message in messages)
+    error = payload.get("error")
+    if error:
+        parts.append(str(error))
+    return unlink("\n".join(parts))
+
+
+def command_value(payload: dict):
+    """The command's return value, as data, or `NO_VALUE` if none is available.
+
+    ChimeraX's REST bridge serialises each command's return value when it is
+    started with ``json true`` — ``remotecontrol rest start port 3000 json
+    true``, which is what the docked panel and every documented launch line
+    use. A bridge started without it replies in plain text, there is no return
+    value to be had, and callers get `NO_VALUE` rather than a fabricated one.
+
+    Two keys can carry it. ``json values`` holds the JSON form of commands that
+    opt into ChimeraX's ``JSONResult`` protocol, and is preferred; ``python
+    values`` holds everything else, run through the bridge's own
+    ``make_json_friendly``, which recurses into dicts, lists and tuples. Both
+    are lists, one entry per command in the request, and MolCompose sends one
+    command per request.
+    """
+    if "raw" in payload:
+        return NO_VALUE
+    for key in ("json values", "python values"):
+        values = payload.get(key)
+        if isinstance(values, list) and len(values) == 1 and values[0] is not None:
+            return values[0]
+    return NO_VALUE
+
+
+def unlink(text: str) -> str:
+    """Strip the ChimeraX log's link markup and the repetition it creates.
+
+    Every echoed command appears twice: once as ``[pbond](help:...)`` followed
+    by its arguments, then again whole inside a ``cxcmd:`` href. Unwrapping the
+    links leaves the two forms identical, so the second is dropped. Only exact
+    repeats go — the label is always kept, and text that never had a link is
+    returned unchanged.
+
+    The two copies are wrapped independently to the log panel's width, and
+    ChimeraX breaks an over-long token by inserting a hyphen, so one copy can
+    read ``mc-pi-\\nstacking`` where the other reads ``mc-pi-stacking``.
+    Comparison therefore ignores whitespace entirely; the line breaks
+    themselves are left as ChimeraX made them, since an inserted hyphen cannot
+    be told apart from one belonging to the name.
+    """
+    blocks, previous = [], None
+    for block in _LOG_LINK.sub(r"\g<label>", text).split("\n\n"):
+        if not block.strip():
+            continue
+        collapsed = "".join(block.split())
+        if collapsed != previous:
+            blocks.append(block.strip())
+        previous = collapsed
+    return "\n\n".join(blocks)

molcompose_mcp-0.1.1/molcompose_mcp/console.py

@@ -0,0 +1,206 @@
+"""A styled local web console for ChimeraX, replacing the bare REST test page.
+
+Serves a single-page command console on localhost and proxies commands to the
+ChimeraX ``remotecontrol rest`` bridge (same-origin, so no CORS issues). This
+is the *human* command line — unlike the agent tool surface it applies no
+whitelist, exactly like ChimeraX's own command prompt.
+"""
+
+import argparse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlencode, urlparse
+from urllib.request import urlopen
+
+CONSOLE_HTML = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>MolCompose Console</title>
+<style>
+  :root {
+    --accent: #4F46E5; --accent-dark: #4338CA; --bg: #F1F2F7;
+    --card: #ffffff; --border: #E7E9F0; --ink: #2f323a; --hint: #7c7f88;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--ink);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    display: flex; flex-direction: column; align-items: center;
+    min-height: 100vh; padding: 24px;
+  }
+  .shell { width: min(860px, 100%); display: flex; flex-direction: column; gap: 14px; }
+  header { display: flex; align-items: center; gap: 10px; }
+  .dot { width: 12px; height: 12px; border-radius: 50%; background: var(--accent); }
+  h1 { font-size: 18px; margin: 0; font-weight: 700; }
+  .sub { color: var(--hint); font-size: 12px; margin-left: auto; }
+  #output {
+    background: #1F2430; color: #D9DCE3; border-radius: 12px;
+    padding: 16px; height: 52vh; overflow-y: auto;
+    font-family: Menlo, Consolas, monospace; font-size: 13px; line-height: 1.55;
+    white-space: pre-wrap; word-break: break-word;
+  }
+  #output .cmd { color: #A5B4FC; font-weight: 600; }
+  #output .err { color: #FCA5A5; }
+  #output .hint { color: #8A8D96; }
+  .inputrow {
+    display: flex; gap: 8px; background: var(--card);
+    border: 1px solid var(--border); border-radius: 12px; padding: 10px;
+  }
+  #command {
+    flex: 1; border: none; outline: none; font-family: Menlo, Consolas, monospace;
+    font-size: 14px; color: var(--ink); background: transparent;
+  }
+  button {
+    border: none; border-radius: 9px; padding: 9px 18px; cursor: pointer;
+    background: var(--accent); color: white; font-weight: 600; font-size: 13px;
+  }
+  button:hover { background: var(--accent-dark); }
+  .chips { display: flex; gap: 6px; flex-wrap: wrap; }
+  .chip {
+    background: #EEF2FF; color: var(--accent); border-radius: 14px;
+    padding: 5px 12px; font-size: 12px; font-weight: 600; cursor: pointer;
+  }
+  .chip:hover { background: #E0E7FF; }
+</style>
+</head>
+<body>
+<div class="shell">
+  <header>
+    <div class="dot"></div>
+    <h1>MolCompose Console</h1>
+    <div class="sub">ChimeraX command line · Up/Down for history</div>
+  </header>
+  <div id="output"><span class="hint">Commands run inside ChimeraX.
+Try a chip below, or any ChimeraX / molcompose command.</span>
+</div>
+  <div class="chips" id="chips">
+    <span class="chip">open 1brs</span>
+    <span class="chip">molcompose style complex-by-chain model #1</span>
+    <span class="chip">molcompose interface A D model #1 distance 4.5</span>
+    <span class="chip">molcompose style interface-focus model #1</span>
+    <span class="chip">molcompose confidence model #1</span>
+  </div>
+  <div class="inputrow">
+    <input id="command" placeholder="ChimeraX command…" autocomplete="off" autofocus>
+    <button id="run">Run</button>
+  </div>
+</div>
+<script>
+  const output = document.getElementById("output");
+  const input = document.getElementById("command");
+  const history = [];
+  let cursor = -1;
+
+  function append(text, cls) {
+    const span = document.createElement("span");
+    if (cls) span.className = cls;
+    span.textContent = text + "\\n";
+    output.appendChild(span);
+    output.scrollTop = output.scrollHeight;
+  }
+
+  function flatten(data) {
+    const parts = [];
+    const logs = data["log messages"];
+    if (logs) for (const level of Object.values(logs)) {
+      if (Array.isArray(level)) parts.push(...level.map(String));
+    }
+    if (data["error"]) parts.push("ERROR: " + data["error"]);
+    return parts.join("\\n").replace(/<[^>]*>/g, "").trim();
+  }
+
+  async function run(command) {
+    if (!command.trim()) return;
+    append("❯ " + command, "cmd");
+    history.unshift(command); cursor = -1;
+    try {
+      const response = await fetch("/run?" + new URLSearchParams({command}));
+      const data = await response.json();
+      const text = flatten(data);
+      if (text) append(text, data["error"] ? "err" : "");
+    } catch (error) {
+      append("Cannot reach ChimeraX — is the bridge running? " +
+             "(remotecontrol rest start port 3000 json true)", "err");
+    }
+    input.value = "";
+  }
+
+  document.getElementById("run").onclick = () => run(input.value);
+  input.addEventListener("keydown", (event) => {
+    if (event.key === "Enter") run(input.value);
+    if (event.key === "ArrowUp" && cursor < history.length - 1) {
+      cursor += 1; input.value = history[cursor];
+    }
+    if (event.key === "ArrowDown" && cursor > 0) {
+      cursor -= 1; input.value = history[cursor];
+    }
+  });
+  document.getElementById("chips").addEventListener("click", (event) => {
+    if (event.target.classList.contains("chip")) run(event.target.textContent);
+  });
+</script>
+</body>
+</html>
+"""
+
+
+def build_proxy_url(chimerax_url: str, command: str) -> str:
+    return f"{chimerax_url.rstrip('/')}/run?{urlencode({'command': command})}"
+
+
+class ConsoleHandler(BaseHTTPRequestHandler):
+    chimerax_url = "http://127.0.0.1:3000"
+
+    def _send(self, status: int, content_type: str, body: bytes) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):  # noqa: N802 - http.server API
+        parsed = urlparse(self.path)
+        if parsed.path == "/":
+            self._send(200, "text/html; charset=utf-8", CONSOLE_HTML.encode())
+            return
+        if parsed.path == "/run":
+            command = parse_qs(parsed.query).get("command", [""])[0]
+            try:
+                with urlopen(  # noqa: S310 - localhost bridge
+                    build_proxy_url(self.chimerax_url, command), timeout=300
+                ) as response:
+                    body = response.read()
+                self._send(200, "application/json", body)
+            except OSError as error:
+                self._send(502, "application/json", f'{{"error": "{error}"}}'.encode())
+            return
+        self._send(404, "text/plain", b"not found")
+
+    def log_message(self, *args):  # quiet server
+        return
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="MolCompose web console for ChimeraX")
+    parser.add_argument("--port", type=int, default=8642)
+    parser.add_argument(
+        "--chimerax-url",
+        default="http://127.0.0.1:3000",
+        help="Base URL of the ChimeraX REST bridge (remotecontrol rest)",
+    )
+    parser.add_argument("--no-browser", action="store_true")
+    args = parser.parse_args()
+
+    ConsoleHandler.chimerax_url = args.chimerax_url
+    server = ThreadingHTTPServer(("127.0.0.1", args.port), ConsoleHandler)
+    address = f"http://127.0.0.1:{args.port}/"
+    print(f"MolCompose Console on {address} (bridge: {args.chimerax_url})")
+    if not args.no_browser:
+        webbrowser.open(address)
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

molcompose_mcp-0.1.1/molcompose_mcp/pythiastudio.py

@@ -0,0 +1,141 @@
+"""Optional PythiaStudio REST client, kept out of the ChimeraX bundle.
+
+The bundle itself never touches the network: it consumes ΔΔG *files*. This
+module lets an agent fetch predictions from PythiaStudio and write them to a
+file that `molcompose ddg` can then load — so the agent, not the bundle,
+becomes the integration layer, and the bundle keeps its zero-service
+dependency profile.
+
+API keys are supplied by the user (environment variable `PYTHIASTUDIO_API_KEY`
+or an explicit argument) and are never logged.
+"""
+
+import csv
+import io
+import json
+import os
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+DEFAULT_BASE_URL = "https://pythiastudio.wulab.xyz"
+ENDPOINTS = {
+    "pythia-ppi": "/api/tools/pythia-ppi/predict",
+    "pythia": "/api/tools/pythia/scan",
+}
+
+
+class PythiaStudioError(RuntimeError):
+    pass
+
+
+def api_key(explicit: str | None = None) -> str:
+    key = explicit or os.environ.get("PYTHIASTUDIO_API_KEY", "")
+    if not key:
+        raise PythiaStudioError(
+            "no PythiaStudio API key: set PYTHIASTUDIO_API_KEY or pass one "
+            "explicitly (request a key from the PythiaStudio maintainers)"
+        )
+    return key
+
+
+def request_prediction(
+    structure_path: str,
+    tool: str = "pythia-ppi",
+    base_url: str = DEFAULT_BASE_URL,
+    key: str | None = None,
+    timeout: float = 600.0,
+) -> dict:
+    """POST a structure to PythiaStudio and return the decoded JSON response."""
+    if tool not in ENDPOINTS:
+        raise PythiaStudioError(
+            f"tool must be one of {', '.join(sorted(ENDPOINTS))}: {tool}"
+        )
+    try:
+        structure = open(structure_path, "rb").read()  # noqa: SIM115
+    except OSError as error:
+        raise PythiaStudioError(f"cannot read structure file: {error}") from error
+
+    boundary = "----molcompose-mcp-boundary"
+    name = os.path.basename(structure_path)
+    body = b"".join(
+        [
+            f"--{boundary}\r\n".encode(),
+            f'Content-Disposition: form-data; name="file"; filename="{name}"\r\n'.encode(),
+            b"Content-Type: application/octet-stream\r\n\r\n",
+            structure,
+            f"\r\n--{boundary}--\r\n".encode(),
+        ]
+    )
+    request = Request(  # noqa: S310 - fixed https endpoint
+        f"{base_url.rstrip('/')}{ENDPOINTS[tool]}",
+        data=body,
+        headers={
+            "Content-Type": f"multipart/form-data; boundary={boundary}",
+            "Authorization": f"Bearer {api_key(key)}",
+        },
+        method="POST",
+    )
+    try:
+        with urlopen(request, timeout=timeout) as response:  # noqa: S310
+            return json.loads(response.read().decode("utf-8"))
+    except HTTPError as error:
+        raise PythiaStudioError(
+            f"PythiaStudio returned HTTP {error.code}; check the API key and quota"
+        ) from error
+    except (URLError, OSError, ValueError) as error:
+        raise PythiaStudioError(f"PythiaStudio request failed: {error}") from error
+
+
+def to_tabular(payload: dict) -> str:
+    """Flatten a PythiaStudio mutation map into the tabular ΔΔG format.
+
+    The exact response schema is not published, so several plausible shapes are
+    accepted; anything unrecognised raises with the observed keys so the caller
+    can report the real format.
+    """
+    records = None
+    for key in ("mutations", "results", "predictions", "data"):
+        value = payload.get(key)
+        if isinstance(value, list) and value:
+            records = value
+            break
+    if records is None:
+        raise PythiaStudioError(
+            "could not find a mutation list in the PythiaStudio response; "
+            f"top-level keys were: {', '.join(sorted(payload))}"
+        )
+
+    buffer = io.StringIO()
+    writer = csv.writer(buffer)
+    writer.writerow(["chain", "position", "wt", "mut", "ddG"])
+    written = 0
+    for record in records:
+        if not isinstance(record, dict):
+            continue
+        lowered = {str(k).lower(): v for k, v in record.items()}
+
+        def pick(*names, mapping=lowered):
+            for name in names:
+                if mapping.get(name) not in (None, ""):
+                    return mapping[name]
+            return ""
+
+        position = pick("position", "pos", "resnum", "residue")
+        ddg = pick("ddg", "ddG".lower(), "score", "prediction", "value")
+        if position == "" or ddg == "":
+            continue
+        writer.writerow(
+            [
+                pick("chain", "chain_id"),
+                position,
+                str(pick("wt", "wild_type", "from")).upper(),
+                str(pick("mut", "mutant", "to")).upper(),
+                ddg,
+            ]
+        )
+        written += 1
+    if not written:
+        raise PythiaStudioError(
+            "the PythiaStudio response contained no usable mutation records"
+        )
+    return buffer.getvalue()