pac-vector 0.1.0__py3-none-any.whl

pac_vector/server.py

@@ -0,0 +1,320 @@
+"""MCP tool surface: 17 tools over the document store."""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated, Literal
+
+from mcp.server.fastmcp import FastMCP, Image
+from mcp.types import ToolAnnotations
+from pydantic import BaseModel, Field
+
+from .document import Document, Store
+from .preview import Preview
+
+INSTRUCTIONS = """\
+SVG editor over in-memory virtual documents (one per "window", like Inkscape).
+
+Workflow: doc_create → add / update / arrange / group / mask … → render to look at the
+result → doc_export to save. A live browser preview runs at the URL doc_create and
+doc_list return; every edit appears there immediately with the touched elements outlined.
+
+Model:
+- Every element has an id; when markup omits one, an id like rect-3 is assigned and
+  returned. Tools address elements by id; layers may also be addressed by label.
+- Layers are Inkscape layers (<g inkscape:groupmode="layer">). New elements go to the
+  current layer (the last one created or added to) unless parent= is given.
+- Coordinates are user units of the document's viewBox.
+- Content goes in as SVG markup. Gradients, patterns, filters, markers, symbols and
+  <defs> in markup are moved into <defs> automatically; reference them with url(#id).
+- Every successful edit is one undo step. A failed edit changes nothing.
+
+Granularity: put several elements in one add call; give update several ids at once;
+use replace only when an element's structure changes (e.g. rewriting a path or a group).
+inspect (outline) is the cheap way to see structure; render shows pixels.
+"""
+
+mcp = FastMCP("pac-vector", instructions=INSTRUCTIONS)
+store = Store()
+preview = Preview(store, port=int(os.environ.get("PAC_VECTOR_PORT", "0") or 0))
+store.on_change = lambda doc, summary: preview.publish(doc.payload(summary))
+store.on_close = lambda doc_id: preview.publish({"type": "closed", "id": doc_id})
+
+RO = ToolAnnotations(readOnlyHint=True, idempotentHint=True, openWorldHint=False)
+EDIT = ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False)
+DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=False)
+
+DocId = Annotated[str, Field(description="Document id from doc_create / doc_list, e.g. 'badge__3fa9c1'.")]
+Ids = Annotated[list[str], Field(description="Element ids (layers may also be given by label).")]
+Position = Annotated[
+    str | None,
+    Field(description="'top' (default, frontmost) | 'bottom' | 'before:<id>' | 'after:<id>' (z-order inside the parent)."),
+]
+
+
+def _foot(doc: Document) -> str:
+    return f"[{doc.id} v{doc.version}]"
+
+
+def _done(doc: Document, summary: str) -> str:
+    return f"{summary}\n{_foot(doc)}"
+
+
+# ── documents ────────────────────────────────────────────────────────────────
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def doc_create(
+    name: Annotated[str | None, Field(description="Window name; defaults to the file name or 'untitled'.")] = None,
+    width: Annotated[float | None, Field(description="Page width in `units` (blank default 800).")] = None,
+    height: Annotated[float | None, Field(description="Page height in `units` (blank default 600).")] = None,
+    units: Literal["px", "mm", "cm", "in", "pt", "pc"] = "px",
+    view_box: Annotated[str | None, Field(description="'minx miny w h'; default '0 0 width height'.")] = None,
+    background: Annotated[str | None, Field(description="Page colour, e.g. '#ffffff'. Omit for transparent.")] = None,
+    layers: Annotated[list[str] | None, Field(description="Layer labels to create, bottom to top. Default ['Layer 1'].")] = None,
+    source: Annotated[
+        str | None,
+        Field(description="Import instead of starting blank: a path to .svg/.svgz, or full <svg> markup."),
+    ] = None,
+) -> str:
+    """Open a new document window, blank or imported. Returns its id, structure and the live preview URL."""
+    url = preview.start()
+    doc, notes = store.create(name, width, height, units, view_box, background, layers, source)
+    return "\n".join([f"created {doc.id}", doc.info(), *notes, f"preview: {url}#{doc.id}"])
+
+
+@mcp.tool(annotations=RO, structured_output=False)
+def doc_list() -> str:
+    """List open document windows: id, name, size, layers, version, unsaved flag, file path, preview URL."""
+    if not store.docs:
+        return "no documents open (doc_create)"
+    url = preview.start()
+    return "\n".join([d.info() for d in store.docs.values()] + [f"preview: {url}"])
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def doc_set(
+    doc: DocId,
+    name: str | None = None,
+    width: Annotated[float | None, Field(description="New page width; the viewBox scales with it so content keeps its size.")] = None,
+    height: Annotated[float | None, Field(description="New page height (viewBox scales with it).")] = None,
+    units: Literal["px", "mm", "cm", "in", "pt", "pc"] | None = None,
+    view_box: Annotated[str | None, Field(description="'minx miny w h' — sets the coordinate system explicitly.")] = None,
+    background: Annotated[str | None, Field(description="Page colour; 'none' for transparent.")] = None,
+    fit: Annotated[Literal["content"] | None, Field(description="'content' shrinks/grows the page to the drawing's visual bounds.")] = None,
+) -> str:
+    """Change window properties: name, page size, units, viewBox, background, or fit the page to the content."""
+    d = store.get(doc)
+    return _done(d, d.set_props(name, width, height, units, view_box, background, fit))
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def doc_export(
+    doc: DocId,
+    path: Annotated[str | None, Field(description="Output file (.svg or .png). Relative paths resolve against PAC_VECTOR_ROOT or the server's cwd. Omit to re-save to the file it was opened from / last saved to.")] = None,
+    format: Annotated[Literal["svg", "png"] | None, Field(description="Defaults to the path's extension.")] = None,
+    scale: Annotated[float, Field(description="PNG only: pixels per CSS px (2 = retina). Capped at 2048px per side.")] = 1.0,
+    area: Annotated[
+        str | list[str],
+        Field(description="'page' (default), 'drawing' (crop to visible content), or a list of element ids (export only those, cropped)."),
+    ] = "page",
+    plain: Annotated[bool, Field(description="SVG only: strip Inkscape/sodipodi metadata (layers become plain <g>).")] = False,
+    background: Annotated[bool, Field(description="Paint the page background into the output.")] = True,
+) -> str:
+    """Write the document to disk as SVG (Inkscape-compatible, layers kept) or PNG."""
+    d = store.get(doc)
+    return d.export(path, format, scale, area, plain, background)
+
+
+@mcp.tool(annotations=DESTRUCTIVE, structured_output=False)
+def doc_close(
+    doc: DocId,
+    discard: Annotated[bool, Field(description="Close even with unsaved changes (they are lost).")] = False,
+) -> str:
+    """Close a document window. Refuses if it has unsaved changes unless discard=true."""
+    return store.close(doc, discard)
+
+
+# ── reading ──────────────────────────────────────────────────────────────────
+
+
+@mcp.tool(annotations=RO, structured_output=False)
+def inspect(
+    doc: DocId,
+    root: Annotated[str | None, Field(description="Id of the subtree to show; omit for the whole document.")] = None,
+    depth: Annotated[int, Field(ge=1, le=20, description="Outline levels to expand (layers are level 1).")] = 3,
+    format: Annotated[
+        Literal["outline", "xml"],
+        Field(description="'outline': one compact line per element (id, geometry, paint, transform). 'xml': the subtree's markup (big data: URIs are elided)."),
+    ] = "outline",
+) -> str:
+    """Show document structure: defs, layers, groups and elements with their ids and key attributes."""
+    d = store.get(doc)
+    out = d.inspect(root, depth, format)
+    if root is None and format == "outline":
+        out += f"\npreview: {preview.start()}#{d.id}"
+    return out
+
+
+@mcp.tool(annotations=RO, structured_output=False)
+def render(
+    doc: DocId,
+    ids: Annotated[list[str] | None, Field(description="Crop to these elements (with surrounding context); omit for the whole page.")] = None,
+    scale: Annotated[float, Field(gt=0, le=8, description="Zoom factor; output is capped at 2048px per side.")] = 1.0,
+    padding: Annotated[int, Field(ge=0, le=512, description="Pixels of margin around a crop.")] = 16,
+    isolate: Annotated[bool, Field(description="With ids: draw only those elements.")] = False,
+    background: Annotated[bool, Field(description="Paint the page background.")] = True,
+) -> list:
+    """Rasterise the page (or a crop around elements) to a PNG you can look at. With ids it also reports their visual bounding box in user units."""
+    d = store.get(doc)
+    text, png = d.render(ids, scale, padding, background, isolate)
+    return [f"{text}\n{_foot(d)}", Image(data=png, format="png")]
+
+
+# ── editing ──────────────────────────────────────────────────────────────────
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def add(
+    doc: DocId,
+    markup: Annotated[
+        str,
+        Field(description="One or more SVG elements, e.g. '<rect x=\"10\" y=\"10\" width=\"80\" height=\"40\" fill=\"url(#g)\"/><linearGradient id=\"g\">…</linearGradient>'. Gradients/patterns/filters/markers/symbols go to <defs> automatically. Prefixes xlink:, inkscape:, sodipodi: are pre-declared."),
+    ],
+    parent: Annotated[str | None, Field(description="Layer or group id/label to add into; default: the current layer.")] = None,
+    position: Position = None,
+) -> str:
+    """Add SVG elements to a layer or group. Returns the ids assigned to every new element."""
+    d = store.get(doc)
+    return _done(d, d.add(markup, parent, position))
+
+
+class TransformSpec(BaseModel):
+    translate: list[float] | None = Field(None, description="[dx, dy]")
+    rotate: float | None = Field(None, description="Degrees, clockwise.")
+    scale: float | list[float] | None = Field(None, description="s or [sx, sy].")
+    origin: Literal["center"] | list[float] = Field(
+        "center", description="Pivot for rotate/scale in parent coordinates: 'center' (each element's own visual center) or [x, y]."
+    )
+    mode: Literal["append", "set"] = Field(
+        "append", description="'append' applies on top of the existing transform; 'set' replaces it."
+    )
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def update(
+    doc: DocId,
+    ids: Ids,
+    attrs: Annotated[
+        dict[str, str | float | None] | None,
+        Field(description="Attributes to set; null removes. Geometry, paint, href, 'xlink:href', 'inkscape:label'… 'id' renames (one element; references follow)."),
+    ] = None,
+    style: Annotated[
+        dict[str, str | float | None] | None,
+        Field(description="CSS properties merged into style=\"\" (they override attributes); null removes the property from both."),
+    ] = None,
+    text: Annotated[str | None, Field(description="Replace the text content of a <text>/<tspan>.")] = None,
+    transform: Annotated[
+        str | TransformSpec | None,
+        Field(description="Raw transform string (replaces; '' removes), or {translate, rotate, scale, origin, mode}. Applied as translate · rotate · scale on top of the current transform."),
+    ] = None,
+    label: Annotated[str | None, Field(description="Inkscape label ('' removes).")] = None,
+    hidden: Annotated[bool | None, Field(description="Hide (display:none) or show.")] = None,
+    locked: Annotated[bool | None, Field(description="Lock against edits by these tools, or unlock.")] = None,
+) -> str:
+    """Change attributes, style, text, transform, label, visibility or lock of one or many elements at once."""
+    d = store.get(doc)
+    tf = transform.model_dump() if isinstance(transform, TransformSpec) else transform
+    return _done(d, d.update(ids, attrs, style, text, tf, label, hidden, locked))
+
+
+@mcp.tool(annotations=DESTRUCTIVE, structured_output=False)
+def replace(
+    doc: DocId,
+    markup: Annotated[str, Field(description="New SVG for the element (keeps its id if the markup has none), or a whole <svg> / element list for the whole drawing.")],
+    id: Annotated[str | None, Field(description="Element to replace. Omit to replace the entire drawing (document properties and the preview stay).")] = None,
+) -> str:
+    """Swap one element's markup for new markup, or set the whole drawing's content."""
+    d = store.get(doc)
+    return _done(d, d.replace(markup, id))
+
+
+@mcp.tool(annotations=DESTRUCTIVE, structured_output=False)
+def remove(doc: DocId, ids: Ids) -> str:
+    """Delete elements (with their children). Warns about anything still referencing them."""
+    d = store.get(doc)
+    return _done(d, d.remove(ids))
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def arrange(
+    doc: DocId,
+    ids: Ids,
+    to: Annotated[str | None, Field(description="Layer or group to move/copy into (on-canvas position is preserved).")] = None,
+    position: Annotated[
+        str | None,
+        Field(description="'top' | 'bottom' | 'up' | 'down' (one step, no `to`) | 'before:<id>' | 'after:<id>'."),
+    ] = None,
+    copy: Annotated[bool, Field(description="Duplicate instead of move (copies get new ids; placed just above the originals unless to/position say otherwise).")] = False,
+    offset: Annotated[list[float] | None, Field(description="[dx, dy] translation applied to the moved/copied elements.")] = None,
+) -> str:
+    """Z-order, move between layers/groups, reorder layers, or duplicate elements."""
+    d = store.get(doc)
+    return _done(d, d.arrange(ids, to, position, copy, offset))
+
+
+# ── structure ────────────────────────────────────────────────────────────────
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def group(
+    doc: DocId,
+    ids: Annotated[list[str] | None, Field(description="Elements to wrap; omit to create an empty group/layer.")] = None,
+    label: Annotated[str | None, Field(description="Label (layer name when layer=true).")] = None,
+    layer: Annotated[bool, Field(description="Make it an Inkscape layer. layer=true without ids creates a new empty layer and makes it current.")] = False,
+    parent: Annotated[str | None, Field(description="Where the new group goes; default: the topmost element's parent (or the root for a new layer).")] = None,
+    position: Position = None,
+) -> str:
+    """Group elements (or create a new empty group/layer). Elements keep their on-canvas position."""
+    d = store.get(doc)
+    return _done(d, d.group(ids, label, layer, parent, position))
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def ungroup(doc: DocId, ids: Ids) -> str:
+    """Dissolve groups or layers: children move up one level; the group's transform and inherited styles are pushed onto them."""
+    d = store.get(doc)
+    return _done(d, d.ungroup(ids))
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def mask(
+    doc: DocId,
+    targets: Ids,
+    source: Annotated[
+        str,
+        Field(description="Id of an existing element to turn into the mask/clip (it is moved out of the drawing), or SVG markup drawn in the targets' own canvas coordinates."),
+    ],
+    kind: Annotated[Literal["mask", "clip"], Field(description="'clip': hard edge, only the source's shape matters. 'mask': soft, uses the source's colours.")] = "mask",
+    mode: Annotated[
+        Literal["luminance", "alpha"],
+        Field(description="mask only — 'luminance': white shows, black hides; 'alpha': source opacity decides."),
+    ] = "luminance",
+) -> str:
+    """Apply a mask or clip path to elements; the <mask>/<clipPath> is created in <defs> and wired up."""
+    d = store.get(doc)
+    return _done(d, d.mask(targets, source, kind, mode))
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def unmask(doc: DocId, targets: Ids) -> str:
+    """Release masks/clip paths: their content returns to the drawing just above each target."""
+    d = store.get(doc)
+    return _done(d, d.unmask(targets))
+
+
+@mcp.tool(annotations=EDIT, structured_output=False)
+def undo(doc: DocId, steps: Annotated[int, Field(ge=1, le=100)] = 1) -> str:
+    """Undo the last edit(s) of a document."""
+    d = store.get(doc)
+    return _done(d, d.undo(steps))

pac_vector-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: pac-vector
+Version: 0.1.0
+Summary: Local stdio MCP server for SVG editing via in-memory virtual documents, with a live browser preview
+Requires-Python: >=3.11
+Requires-Dist: lxml>=5.0
+Requires-Dist: mcp[cli]<2.0.0,>=1.10.0
+Requires-Dist: pillow>=10.0
+Requires-Dist: resvg-py>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pac-vector
+
+Local stdio MCP server: an SVG editor over in-memory **virtual documents** (one per
+"window", like Inkscape), with a **live browser preview** of every edit.
+
+- Content goes in as SVG markup; structure (layers, groups, masks, z-order) has typed tools.
+- Layers are real Inkscape layers, so exported files open in Inkscape with layers intact.
+- Every edit is atomic (a failed call changes nothing) and one undo step.
+- `render` returns a PNG the agent can look at; rendering is resvg (no browser, no Cairo).
+
+## Install
+
+Same shape as pac-pincers: a pip package, run as a module by whatever Python it
+was installed into.
+
+```powershell
+python -m pip install --upgrade pac-vector
+claude mcp add pac-vector --scope user -- python -m pac_vector
+```
+
+As a plugin `.mcp.json` entry (mirrors the datatopia plugin's pac-pincers entry):
+
+```json
+"pac-vector": {
+  "type": "stdio",
+  "command": "${PAC_VECTOR_PYTHON:-python}",
+  "args": ["-m", "pac_vector"],
+  "env": {}
+}
+```
+
+Development:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+.\.venv\Scripts\python.exe run_tests.py -q
+.\.venv\Scripts\python.exe -m build          # dist/pac_vector-<ver>.tar.gz + .whl
+```
+
+## Tools (17)
+
+| Group | Tools |
+|---|---|
+| Documents | `doc_create` (blank or import), `doc_list`, `doc_set` (size, units, viewBox, background, fit), `doc_export` (svg/png, page/drawing/ids, plain), `doc_close` |
+| Reading | `inspect` (outline or xml), `render` (PNG, optional crop to ids + bbox) |
+| Editing | `add` (markup → layer/group, defs auto-routed), `update` (attrs/style/text/transform/label/hidden/locked on many ids), `replace` (one element or the whole drawing), `remove`, `arrange` (z-order, move between layers, duplicate, offset) |
+| Structure | `group` (also new layers), `ungroup`, `mask` (mask or clip from id or markup), `unmask` |
+| History | `undo` |
+
+## Preview
+
+`doc_create` / `doc_list` / `inspect` print `preview: http://127.0.0.1:<port>/#<doc>`.
+The page has a tab per document, outlines the elements each edit touched, and
+shows (and copies) the id of anything you click. The server lives inside the MCP
+process: it starts on the first `doc_create` and dies with the session.
+
+## Environment
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `PAC_VECTOR_PORT` | `0` (random) | Pin the preview port (falls back to random if busy) |
+| `PAC_VECTOR_OPEN_BROWSER` | off | `1` opens the preview in the default browser on first start |
+| `PAC_VECTOR_ROOT` | server cwd | Base directory for relative export/import paths |
+| `PAC_VECTOR_LOG` | `WARNING` | Log level (stderr only) |
+
+## Notes
+
+- stdout is the JSON-RPC pipe: nothing may print to it. `tests/test_stdout_safety.py`
+  scans the package for `print()` / `sys.stdout`, and `tests/test_stdio.py` runs a real session.
+- Native modules are loaded before the stdio loop starts (`render.warm`): on Windows a
+  first native load from inside the FastMCP loop can hang (see pac-pincers' `_excel.py`).
+- Bounding boxes are measured from pixels (two-pass render), so they include strokes and
+  filters and work for text and curves; content further than two page-widths off-canvas isn't found.
+- Version lives only in `pyproject.toml`; a release is a commit named after the version.

pac_vector-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pac_vector/__init__.py,sha256=dcq66GafZ0X2Fk2h6bI7gjBtzlGpzN9xjCT0yhmVMOU,90
+pac_vector/__main__.py,sha256=xivJhtEKPNXdY9Ihl8AvE8h4RT7ZrTdx6Y2NPrGu7O8,564
+pac_vector/_xml.py,sha256=7yj-ni6Eq3LSrKzbfZWsjblYYahd3A39uqBdFT9LiNg,11253
+pac_vector/document.py,sha256=8Zg6ND1I6IwtRfptYW5ukhuPJ54mfBT4Hovb1GGdD4o,57615
+pac_vector/preview.py,sha256=kxjsf9i_nnqY0fXVJuW7Zbt2pUTE939z0N4jaObWID4,12145
+pac_vector/render.py,sha256=WwXPX8a79REyHJQ-Hfush-4SUvmhd6LN-3Q5brVw4Rw,5850
+pac_vector/server.py,sha256=lBNi42PMigL9mOywV0dqrguPnr4_FgLKESYuSuQcee8,16743
+pac_vector-0.1.0.dist-info/METADATA,sha256=GjGhQiC8y-eNlNTc9Q_GAn9babRvlK5eRv-EJak5CHs,3684
+pac_vector-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pac_vector-0.1.0.dist-info/entry_points.txt,sha256=uMldFTCt33_kG6GG8hLz7ZXhcxY18s3GfVO3Iok6JgA,56
+pac_vector-0.1.0.dist-info/RECORD,,

pac_vector-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pac_vector-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pac-vector = pac_vector.__main__:main