pac-vector 0.1.0__tar.gz

pac_vector-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# OS files
+.DS_Store
+Thumbs.db
+
+# Visual Studio Code
+.vscode/
+
+# Logs
+logs/
+*.log
+
+# Claude Code agent worktrees — checkouts of this same repo nested inside it
+.claude/
+
+# Virtual environment
+.venv/
+
+# Build output
+dist/
+build/
+*.egg-info/
+/__pycache__/
+*.pyc
+.*_cache
+__pycache__
+
+# Local exports while testing
+out/

pac_vector-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,75 @@
+# 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/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pac-vector"
+version = "0.1.0"
+description = "Local stdio MCP server for SVG editing via in-memory virtual documents, with a live browser preview"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    # mcp 2.0 removed the vendored FastMCP (mcp.server.fastmcp) that this server is
+    # built on — pin to the 1.x line, same as pac-pincers.
+    "mcp[cli]>=1.10.0,<2.0.0",
+    # Namespace-correct XML (Inkscape layers live in the inkscape:/sodipodi: namespaces).
+    "lxml>=5.0",
+    # Rust SVG renderer for render / PNG export / bounding boxes. Ships wheels for
+    # Windows, so no Cairo DLLs and no browser.
+    "resvg-py>=0.5.0",
+    # PNG decode for pixel bounding boxes and crops.
+    "pillow>=10.0",
+]
+
+[project.scripts]
+pac-vector = "pac_vector.__main__:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pac_vector"]
+
+[tool.hatch.build.targets.sdist]
+# Claude Code puts agent worktrees under .claude/worktrees/ — full checkouts of
+# this same repo nested inside it — and hatchling would sweep them into the
+# sdist (pac-pincers 1.3.7 shipped three copies of itself that way). Keep the
+# exclusion explicit rather than relying on .gitignore.
+exclude = [
+    "/.claude",
+    "/.venv",
+    "/out",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pac_vector-0.1.0/run_tests.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python
+"""Stable test-runner entry point for pac-vector.
+
+Always invoke the suite the same way — `python run_tests.py` — so the command
+shape never changes (easy to allowlist). Any extra arguments are forwarded
+straight to pytest, e.g.:
+
+    python run_tests.py                         # full suite
+    python run_tests.py -q                      # quiet
+    python run_tests.py tests/test_stdio.py     # a single file
+    python run_tests.py -k mask                 # filter by keyword
+"""
+import subprocess
+import sys
+
+if __name__ == "__main__":
+    sys.exit(subprocess.call([sys.executable, "-m", "pytest", *sys.argv[1:]]))

pac_vector-0.1.0/src/pac_vector/__init__.py

@@ -0,0 +1 @@
+"""pac-vector: Local stdio MCP server for SVG editing via in-memory virtual documents."""

pac_vector-0.1.0/src/pac_vector/__main__.py

@@ -0,0 +1,20 @@
+import logging
+import os
+import sys
+
+
+def main() -> None:
+    # stdout is the JSON-RPC pipe: logs go to stderr only.
+    logging.basicConfig(stream=sys.stderr, level=os.environ.get("PAC_VECTOR_LOG", "WARNING").upper())
+    # Load every native module (lxml, resvg, PIL codecs, font DB) BEFORE the
+    # stdio loop starts — on Windows a first native load from inside the
+    # FastMCP loop can hang the process (see pac-pincers' _excel.py).
+    from .render import warm
+    from .server import mcp
+
+    warm()
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

pac_vector-0.1.0/src/pac_vector/_xml.py

@@ -0,0 +1,348 @@
+"""XML/SVG helpers: namespaces, safe parsing, sanitising, styles, number
+formatting and 2D affine transforms. No document state lives here."""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Iterable, Iterator
+
+from lxml import etree
+
+SVG_NS = "http://www.w3.org/2000/svg"
+XLINK_NS = "http://www.w3.org/1999/xlink"
+INK_NS = "http://www.inkscape.org/namespaces/inkscape"
+SODI_NS = "http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+XML_NS = "http://www.w3.org/XML/1998/namespace"
+
+NSMAP = {None: SVG_NS, "xlink": XLINK_NS, "inkscape": INK_NS, "sodipodi": SODI_NS}
+PREFIXES = {"xlink": XLINK_NS, "inkscape": INK_NS, "sodipodi": SODI_NS, "xml": XML_NS}
+
+INK_LABEL = f"{{{INK_NS}}}label"
+INK_GROUPMODE = f"{{{INK_NS}}}groupmode"
+SODI_INSENSITIVE = f"{{{SODI_NS}}}insensitive"
+XLINK_HREF = f"{{{XLINK_NS}}}href"
+
+ELIDED_MARK = "⟪elided"
+
+
+class EditError(Exception):
+    """A user-facing error: the message tells the agent what to fix."""
+
+
+def q(tag: str) -> str:
+    return f"{{{SVG_NS}}}{tag}"
+
+
+def is_el(node) -> bool:
+    return isinstance(node.tag, str)
+
+
+def local(el) -> str:
+    return etree.QName(el).localname if is_el(el) else ""
+
+
+def is_svg(el) -> bool:
+    return is_el(el) and etree.QName(el).namespace == SVG_NS
+
+
+def children(el) -> list:
+    return [c for c in el if is_el(c)]
+
+
+def iter_els(el) -> Iterator:
+    for e in el.iter():
+        if is_el(e):
+            yield e
+
+
+# ── parsing ──────────────────────────────────────────────────────────────────
+
+# resolve_entities=False + no_network: no XXE, no billion laughs.
+# huge_tree: embedded base64 images easily exceed libxml2's 10 MB text limit.
+PARSER = etree.XMLParser(resolve_entities=False, no_network=True, huge_tree=True)
+
+_PROLOG = re.compile(r"^\s*(<\?xml[^>]*\?>)?\s*(<!DOCTYPE[^>\[]*(\[[^\]]*\])?\s*>)?", re.S)
+
+
+def parse_fragment(markup: str) -> list:
+    """Parse one or more SVG elements. Unprefixed elements land in the SVG
+    namespace; the xlink/inkscape/sodipodi prefixes are pre-declared."""
+    if not markup or not markup.strip():
+        raise EditError("markup is empty")
+    if ELIDED_MARK in markup:
+        raise EditError(
+            "markup contains data elided by inspect (⟪elided …⟫). Reference the existing "
+            "element by id (arrange copy=true duplicates it) or pass the full data."
+        )
+    body = _PROLOG.sub("", markup, count=1)
+    decl = " ".join(f'xmlns:{p}="{ns}"' for p, ns in PREFIXES.items() if p != "xml")
+    wrapped = f'<svg xmlns="{SVG_NS}" {decl}>{body}</svg>'
+    try:
+        root = etree.fromstring(wrapped.encode("utf-8"), PARSER)
+    except etree.XMLSyntaxError as e:
+        raise EditError(f"invalid SVG markup: {e.msg} (line {e.lineno})") from None
+    els = children(root)
+    if not els:
+        raise EditError("markup has no elements")
+    for el in els:
+        root.remove(el)
+        el.tail = None
+    return els
+
+
+def parse_document(text: str):
+    """Parse a whole <svg> document into a root normalised to NSMAP."""
+    els = parse_fragment(text)
+    if len(els) != 1 or local(els[0]) != "svg":
+        raise EditError("expected a single <svg> root element")
+    return normalise_root(els[0])
+
+
+def normalise_root(src):
+    root = etree.Element(q("svg"), nsmap=NSMAP)
+    for k, v in src.attrib.items():
+        root.set(k, v)
+    root.text = src.text
+    for c in list(src):
+        root.append(c)
+    return root
+
+
+def new_root():
+    return etree.Element(q("svg"), nsmap=NSMAP)
+
+
+def from_bytes(data: bytes):
+    return etree.fromstring(data, PARSER)
+
+
+def sanitize(els: Iterable) -> list[str]:
+    """Remove scripts, event handlers and javascript: links. Returns notes."""
+    notes = []
+    for top in els:
+        for e in list(iter_els(top)):
+            if local(e) == "script":
+                parent = e.getparent()
+                if parent is not None:
+                    parent.remove(e)
+                notes.append("removed <script>")
+                continue
+            for k in list(e.attrib):
+                name = etree.QName(k).localname.lower()
+                v = e.attrib[k]
+                if name.startswith("on"):
+                    del e.attrib[k]
+                    notes.append(f"removed {name} handler")
+                elif name == "href" and v.strip().lower().startswith("javascript:"):
+                    del e.attrib[k]
+                    notes.append("removed javascript: href")
+    return sorted(set(notes))
+
+
+def attr_name(name: str) -> str:
+    """'xlink:href' → '{ns}href'. Plain names pass through."""
+    if ":" in name and not name.startswith("{"):
+        prefix, loc = name.split(":", 1)
+        if prefix not in PREFIXES:
+            raise EditError(f"unknown attribute prefix '{prefix}:' (known: {', '.join(PREFIXES)})")
+        return f"{{{PREFIXES[prefix]}}}{loc}"
+    return name
+
+
+def short_attr(k: str) -> str:
+    qn = etree.QName(k)
+    if qn.namespace is None:
+        return qn.localname
+    for p, ns in PREFIXES.items():
+        if ns == qn.namespace:
+            return f"{p}:{qn.localname}"
+    return qn.localname
+
+
+def href(el) -> str | None:
+    return el.get("href") or el.get(XLINK_HREF)
+
+
+# ── numbers & styles ─────────────────────────────────────────────────────────
+
+
+def fmt(v) -> str:
+    if isinstance(v, str):
+        return v
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    x = float(v)
+    if not math.isfinite(x):
+        raise EditError(f"non-finite number {v!r}")
+    s = f"{x:.4f}".rstrip("0").rstrip(".")
+    return "0" if s in ("-0", "") else s
+
+
+def parse_style(s: str | None) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for part in (s or "").split(";"):
+        if ":" in part:
+            k, v = part.split(":", 1)
+            if k.strip():
+                out[k.strip()] = v.strip()
+    return out
+
+
+def style_str(d: dict[str, str]) -> str:
+    return ";".join(f"{k}:{v}" for k, v in d.items())
+
+
+def get_prop(el, name: str) -> str | None:
+    """Effective own value of a presentation property (style beats attribute)."""
+    st = parse_style(el.get("style"))
+    if name in st:
+        return st[name]
+    return el.get(name)
+
+
+_NUM = re.compile(r"^\s*([-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?)\s*([a-z%]*)\s*$")
+
+
+def parse_length(s: str | None) -> tuple[float, str] | None:
+    if s is None:
+        return None
+    m = _NUM.match(s)
+    if not m:
+        return None
+    return float(m.group(1)), m.group(2)
+
+
+def numbers(s: str) -> list[float]:
+    return [float(x) for x in re.findall(r"[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?", s or "")]
+
+
+# ── references ───────────────────────────────────────────────────────────────
+
+URL_REF = re.compile(r"url\(\s*['\"]?#([^)'\"\s]+)['\"]?\s*\)")
+
+
+def refs_of(el) -> set[str]:
+    """Ids this element references (url(#x) anywhere, href="#x")."""
+    out = set()
+    for k, v in el.attrib.items():
+        out.update(URL_REF.findall(v))
+        if etree.QName(k).localname == "href" and v.startswith("#"):
+            out.add(v[1:])
+    return out
+
+
+def rewrite_refs(tops: Iterable, mapping: dict[str, str]) -> None:
+    if not mapping:
+        return
+    sub = lambda m: f"url(#{mapping.get(m.group(1), m.group(1))})"  # noqa: E731
+    for top in tops:
+        for e in iter_els(top):
+            for k, v in list(e.attrib.items()):
+                nv = URL_REF.sub(sub, v)
+                if etree.QName(k).localname == "href" and nv.startswith("#") and nv[1:] in mapping:
+                    nv = "#" + mapping[nv[1:]]
+                if nv != v:
+                    e.set(k, nv)
+
+
+# ── affine transforms (a, b, c, d, e, f) as in SVG matrix() ──────────────────
+
+Matrix = tuple[float, float, float, float, float, float]
+IDENT: Matrix = (1.0, 0.0, 0.0, 1.0, 0.0, 0.0)
+
+
+def mul(m1: Matrix, m2: Matrix) -> Matrix:
+    """m1 · m2 — apply m2 first, then m1."""
+    a1, b1, c1, d1, e1, f1 = m1
+    a2, b2, c2, d2, e2, f2 = m2
+    return (
+        a1 * a2 + c1 * b2,
+        b1 * a2 + d1 * b2,
+        a1 * c2 + c1 * d2,
+        b1 * c2 + d1 * d2,
+        a1 * e2 + c1 * f2 + e1,
+        b1 * e2 + d1 * f2 + f1,
+    )
+
+
+def inv(m: Matrix) -> Matrix:
+    a, b, c, d, e, f = m
+    det = a * d - b * c
+    if abs(det) < 1e-12:
+        raise EditError("transform is not invertible (zero scale?)")
+    return (d / det, -b / det, -c / det, a / det, (c * f - d * e) / det, (b * e - a * f) / det)
+
+
+def apply(m: Matrix, x: float, y: float) -> tuple[float, float]:
+    a, b, c, d, e, f = m
+    return a * x + c * y + e, b * x + d * y + f
+
+
+def is_ident(m: Matrix, eps: float = 1e-9) -> bool:
+    return all(abs(x - y) < eps for x, y in zip(m, IDENT))
+
+
+def same(m1: Matrix, m2: Matrix, eps: float = 1e-9) -> bool:
+    return all(abs(x - y) < eps for x, y in zip(m1, m2))
+
+
+_TF = re.compile(r"(matrix|translate|scale|rotate|skewX|skewY)\s*\(([^)]*)\)")
+
+
+def parse_transform(s: str | None) -> Matrix:
+    m = IDENT
+    for name, args in _TF.findall(s or ""):
+        n = numbers(args)
+        if name == "matrix" and len(n) == 6:
+            t = tuple(n)
+        elif name == "translate":
+            t = (1, 0, 0, 1, n[0] if n else 0, n[1] if len(n) > 1 else 0)
+        elif name == "scale":
+            sx = n[0] if n else 1
+            t = (sx, 0, 0, n[1] if len(n) > 1 else sx, 0, 0)
+        elif name == "rotate":
+            a = math.radians(n[0] if n else 0)
+            r = (math.cos(a), math.sin(a), -math.sin(a), math.cos(a), 0, 0)
+            if len(n) >= 3:
+                cx, cy = n[1], n[2]
+                t = mul(mul((1, 0, 0, 1, cx, cy), r), (1, 0, 0, 1, -cx, -cy))
+            else:
+                t = r
+        elif name == "skewX":
+            t = (1, 0, math.tan(math.radians(n[0] if n else 0)), 1, 0, 0)
+        elif name == "skewY":
+            t = (1, math.tan(math.radians(n[0] if n else 0)), 0, 1, 0, 0)
+        else:
+            continue
+        m = mul(m, t)  # type: ignore[arg-type]
+    return m
+
+
+def matrix_str(m: Matrix) -> str:
+    return "matrix(" + ",".join(fmt(x) for x in m) + ")"
+
+
+def prepend_transform(el, tf: str) -> None:
+    """Apply `tf` on top of the element's current transform (in parent space)."""
+    old = (el.get("transform") or "").strip()
+    new = f"{tf} {old}".strip() if tf else old
+    if len(_TF.findall(new)) > 4:  # keep chains short and readable
+        new = matrix_str(parse_transform(new))
+    if new and not is_ident(parse_transform(new)):
+        el.set("transform", new)
+    elif "transform" in el.attrib:
+        del el.attrib["transform"]
+
+
+def parent_ctm(el) -> Matrix:
+    """Product of ancestors' transforms (root first), excluding el's own."""
+    chain = [a for a in el.iterancestors()]
+    m = IDENT
+    for a in reversed(chain):
+        m = mul(m, parse_transform(a.get("transform")))
+    return m
+
+
+def el_ctm(el) -> Matrix:
+    return mul(parent_ctm(el), parse_transform(el.get("transform")))