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,
),
]