vibe-sketcherDocumentation

Source code for vibesketcher.agent.mcp_build_review

"""MCP tools for previewing, applying and undoing periodic builds (#201).

Each tool is a call to the REST routes in :mod:`vibesketcher.server.build_review`;
:func:`tools` is joined to the list in :func:`vibesketcher.agent.mcp.make_tools`.
``build_periodic`` keeps building directly.
"""

from __future__ import annotations

from collections.abc import Callable
from typing import TYPE_CHECKING, Any

from vibesketcher.agent.client import RestClient

if TYPE_CHECKING:
    from vibesketcher.agent.mcp import Tool

_RECIPE_HELP = (
    "recipe = any build_periodic recipe (kind crystal, cell, slab, adsorbate, defect, nanotube, "
    "framework, rolled_nanotube, honeycomb_stack, twisted_bilayer, reticular, interface, "
    "stacking_fault, porous_carbon or cnt_junction)"
)


[docs] def tools(client: RestClient, document_id: Callable[[dict[str, Any]], str]) -> list[Tool]: from vibesketcher.agent.mcp import Tool, _schema, _summary document = {"type": "string", "description": "Document id; the open document when left out."} def base(arguments: dict[str, Any]) -> str: return f"api/documents/{document_id(arguments)}/periodic/build" def preview(arguments: dict[str, Any]) -> Any: return client.call( "POST", f"{base(arguments)}/preview", {"recipe": arguments["recipe"], "structure": bool(arguments.get("structure"))}, ) def revision(arguments: dict[str, Any]) -> int: given = arguments.get("revision") if isinstance(given, int): return given state: dict[str, Any] = client.call("GET", f"api/documents/{document_id(arguments)}") return int(state["revision"]) def apply(arguments: dict[str, Any]) -> Any: body: dict[str, Any] = { "revision": revision(arguments), "actor": "agent", "client": "mcp", "recipe": arguments["recipe"], "recipe_sha256": arguments["recipe_sha256"], } if arguments.get("inputs_sha256"): body["inputs_sha256"] = arguments["inputs_sha256"] return _summary(client.call("POST", f"{base(arguments)}/apply", body)) def undo(arguments: dict[str, Any]) -> Any: body = { "revision": revision(arguments), "actor": "agent", "client": "mcp", "structure": arguments["structure"], } return _summary(client.call("POST", f"{base(arguments)}/undo", body)) return [ Tool( "preview_periodic_build", "Preview a periodic build without changing the document: " + _RECIPE_HELP + ". " "Returns applicable, the would-be structure's summary (formula, sites, bonds, " "charge, multiplicity, cell with lengths, angles, volume, pbc), refusals and " "builder warnings (notices) with stable codes (build.*, or the builder's own such " "as junction.* or porous_carbon.*), the document revision, recipe_sha256, the " "inputs it reads with their digests and inputs_sha256. structure=true adds the " "full derived structure. Add it with apply_periodic_build.", _schema( { "document": document, "recipe": {"type": "object"}, "structure": {"type": "boolean"}, }, ("recipe",), ), # fmt: skip preview, ), Tool( "apply_periodic_build", "Add a previewed periodic build: recipe, recipe_sha256 and optionally " "inputs_sha256 and revision from preview_periodic_build. Refused (build.* code) " "when the document revision, the recipe or the inputs moved since the preview. " "Unlike build_periodic, the structure can be removed with undo_periodic_build.", _schema( { "document": document, "recipe": {"type": "object"}, "recipe_sha256": {"type": "string"}, "inputs_sha256": {"type": "string"}, "revision": {"type": "integer"}, }, ("recipe", "recipe_sha256"), ), # fmt: skip apply, ), Tool( "undo_periodic_build", "Remove a structure added by apply_periodic_build again. Refused with " "build.undo.changed when it was edited since, build.undo.dependents when another " "structure, surface or reaction participant refers to it, and " "build.undo.not_reviewed when it was built directly.", _schema( { "document": document, "structure": {"type": "string"}, "revision": {"type": "integer"}, }, ("structure",), ), # fmt: skip undo, ), ]