oid-mcp 0.3.0__py3-none-any.whl

oid_mcp-0.3.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: oid-mcp
+Version: 0.3.0
+Summary: MCP server giving AI agents eyes on OpenImageDebugger buffers in live gdb/lldb sessions
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0

oid_mcp-0.3.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+oidmcp/__init__.py,sha256=wpWx6dgrfBtzt5P4RmrSn-sqzKF33m0miL_ed8R0jnc,446
+oidmcp/_wireframe.py,sha256=LCEd7EVUfvHV6belQAUdewlCvO4qJTSrOQ8CR6rVqxw,3991
+oidmcp/analysis.py,sha256=MQTpb4N8-pcgebZ-Rm7h4EjMEnPw0H8EJYE-u3Lk6wA,7228
+oidmcp/buffers.py,sha256=ifY9YJIUwWiG2aqJRt-RdHPzuwMbFk-sF-MrCplMc7A,3191
+oidmcp/discovery.py,sha256=5tHb3Cd3f3-oScDBhfFyBE6jbDKoz8lmgKJVzAz0ics,9089
+oidmcp/protocol.py,sha256=j1A7PLvQzNlY6cBa_UnrfMEXDiUIm17sL-CmR7ZDzjk,5020
+oidmcp/render.py,sha256=TfTlgS7QlasMxZaz-Gh6G0zN7U-cak_D1b1oa5_mBao,5006
+oidmcp/server.py,sha256=dqsLeeT_lE8k3i-DmNBC2BYJSY1hDzx1tdq4nTS_bjA,18944
+oidmcp/viewer_meta.py,sha256=cjblAAOZnL109BxXA9CGD9j-OR5g0Qmjj0eKOw6KS90,1505
+oidscripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oidscripts/agentendpoint.py,sha256=hqciAuHk5J_KskIkpkNikW_v3pbSSKsgRoeMyL8oCWc,17075
+oidscripts/events.py,sha256=LrjXd-JuCjNevbRpLbg6MjHeCzUJQ64032ILpjs3kTY,1897
+oidscripts/logger.py,sha256=VV7uecLi7uZKJoyq5sJNoyfMiH-isAsI5WclpFY0h-U,403
+oidscripts/oidwindow.py,sha256=8wzH8l_ms7MuHPQm84b7aGgcpHoMBg1OW56HI3cwCo8,7375
+oidscripts/symbols.py,sha256=Rk5LrR32UwQTM5EQHhx17MZv1oVTQ_oCWdI01i4Q2rA,244
+oidscripts/sysinfo.py,sha256=cfrW-ZsSP5KGFBDzqyx9a85U2J_6rnLQTHmSMzraXXs,4455
+oidscripts/test.py,sha256=l6cQUZ1ON2Y2Vo1kSgskebL0IH3FTdB-b8Yeai5eyk4,5834
+oidscripts/typebridge.py,sha256=aWTyyvl2zylCSsLXEVcUPB9QyHmXJuttNRH5ygk4wdU,1898
+oidscripts/wireframe.py,sha256=1LzXlex4IVly9L3gad-SwIuD4xS_IDiW7plcASx49-A,3503
+oidscripts/debuggers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oidscripts/debuggers/gdbbridge.py,sha256=2sg4_78hWCXIRgF2MpXnRqp-sQm3NBp955i3a3SK-r8,6393
+oidscripts/debuggers/interfaces.py,sha256=kUhL3kopVmsq6057a2vstFlG2gj422t4Arn3Q_dqjTg,5553
+oidscripts/debuggers/lldbbridge.py,sha256=gKCxlwIt89nMIr5rEGYkfWVA8lW279eksQutNzqPHnA,10307
+oidscripts/debuggers/template_args.py,sha256=23EHXaXY6QO_rjwRAXGnbbes1cNzWICYuXZ1xanLlDM,3509
+oidscripts/ides/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oidscripts/ides/qtcreator.py,sha256=50-RF_QMmWr2TY42Gg0OnOSIBWanMdNcRtJUtGn1v0w,2141
+oidscripts/oidtypes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oidscripts/oidtypes/eigen3.py,sha256=Eh1HwmMX5V23CpWGRgxHIMmbLA5nxBnpIoKQ0GTEkNU,6075
+oidscripts/oidtypes/interface.py,sha256=juZ8UiK2QE6j-Gjl_PH69BsFnR-fMlgkQEjqRsN_Q-4,2937
+oidscripts/oidtypes/opencv.py,sha256=AqHsgxUi0QWzYB3BPLigOj4OESexRpauUw0DlghwIZQ,5989
+oid_mcp-0.3.0.dist-info/METADATA,sha256=DpWfOwoMOZDZ5RisLbpRf4qnSF2_Gmek7CPWc78fG0A,251
+oid_mcp-0.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+oid_mcp-0.3.0.dist-info/entry_points.txt,sha256=6g2FzW2uUb8W6JbijKHRXZ31d83ZtDLl26-u8-tDJeg,47
+oid_mcp-0.3.0.dist-info/RECORD,,

oid_mcp-0.3.0.dist-info/WHEEL

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

oid_mcp-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+oid-mcp = oidmcp.server:main

oidmcp/__init__.py

@@ -0,0 +1,11 @@
+"""MCP server exposing OpenImageDebugger buffer inspection to AI agents.
+
+The stdlib-only wire framing is defined once, in
+``oidscripts.wireframe``, and shared with the in-debugger endpoint. The
+``oidmcp._wireframe`` bridge re-exports it, appending the sibling
+debugger-scripts tree to ``sys.path`` (idempotent and lowest-precedence)
+so it imports as a normal named package rather than being loaded by
+filesystem path.
+"""
+
+__version__ = "0.2.0"

oidmcp/_wireframe.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+
+"""Bridge to the single source of the wire framing: ``oidscripts.wireframe``.
+
+oid-mcp and the in-debugger endpoint must agree byte-for-byte on the wire
+format. Rather than keep a second copy in step by hand, both sides import
+the one module that defines it. oid-mcp runs from the deployed OID
+resources tree (``uv run --directory resources/oidmcp``), where
+``resources/oidscripts`` is a sibling of this package, so this bridge puts
+that directory on ``sys.path`` and re-exports the shared helpers as a
+normal named-package import -- no code is loaded by filesystem path.
+
+The append is idempotent and lowest-precedence, so it cannot shadow a
+stdlib or site module; it mirrors what the test suite's conftest already
+does to import from the debugger-scripts tree. That low precedence,
+however, also means an unrelated ``oidscripts`` earlier on ``sys.path``
+could win the import, and a foreign ``wireframe`` may carry an
+incompatible wire format. So the resolved module is verified to be the one
+shipped beside us and a mismatch is rejected loudly rather than used
+silently.
+"""
+
+import os
+import sys
+import sysconfig
+from pathlib import Path
+
+# Three supported layouts for the shared scripts tree:
+#   repo layout:      resources/oidmcp/oidmcp/_wireframe.py with the tree at
+#                     resources/oidscripts (parents[2] == resources/)
+#   installed layout: site-packages/oidmcp/_wireframe.py with oidscripts
+#                     shipped in the same site-packages by the wheel
+#                     (parents[1] == site-packages)
+#   editable-install layout: a local `uv run`/`pip install -e` dev sync
+#                     redirects oidmcp/_wireframe.py's own __file__ back to
+#                     this repo file (so parents[1] above is not the venv's
+#                     site-packages), yet the build backend still has to
+#                     materialize the force-included oidscripts tree as a
+#                     real copy in the running interpreter's site-packages,
+#                     since there is no editable/redirect mechanism for a
+#                     force-include mapped from outside the project root.
+_RESOURCES_DIR = Path(__file__).resolve().parents[2]
+_SITE_DIR = Path(__file__).resolve().parents[1]
+_PURELIB_DIR = Path(sysconfig.get_path('purelib'))
+# Single-sourced to avoid repeating the path components below.
+_OIDSCRIPTS_WIREFRAME = Path('oidscripts') / 'wireframe.py'
+_EXPECTED_WIREFRAMES = (
+    _RESOURCES_DIR / _OIDSCRIPTS_WIREFRAME,
+    _SITE_DIR / _OIDSCRIPTS_WIREFRAME,
+    _PURELIB_DIR / _OIDSCRIPTS_WIREFRAME,
+)
+if str(_RESOURCES_DIR) not in sys.path:
+    sys.path.append(str(_RESOURCES_DIR))
+
+try:
+    from oidscripts import wireframe as _wireframe  # noqa: E402
+except ImportError as exc:  # pragma: no cover - deployment misconfiguration
+    raise ImportError(
+        'oid-mcp requires the OpenImageDebugger scripts tree; expected '
+        'oidscripts alongside this package under resources/. Run oid-mcp '
+        'from the OID install (uv run --directory resources/oidmcp).'
+    ) from exc
+
+# Guard against an earlier sys.path entry resolving `oidscripts` to some
+# other tree: confirm we imported the wireframe that ships beside us. A
+# different module could encode frames incompatibly, so treat it as a
+# misconfiguration to fix, not a protocol to trust.
+_loaded = getattr(_wireframe, '__file__', None)
+if _loaded is not None and os.path.realpath(_loaded) not in {
+        os.path.realpath(str(p)) for p in _EXPECTED_WIREFRAMES}:
+    raise ImportError(  # pragma: no cover - conflicting oidscripts on path
+        'oid-mcp imported a foreign oidscripts.wireframe %s; expected '
+        'one of %s. Remove the conflicting oidscripts from sys.path / '
+        'PYTHONPATH.'
+        % (_loaded, [str(p) for p in _EXPECTED_WIREFRAMES]))
+
+MAX_FRAME_BYTES = _wireframe.MAX_FRAME_BYTES
+recv_frame = _wireframe.recv_frame
+send_frame = _wireframe.send_frame
+
+__all__ = ['MAX_FRAME_BYTES', 'recv_frame', 'send_frame']

oidmcp/analysis.py

@@ -0,0 +1,201 @@
+"""Exact-number inspection: stats, value crops, lossless dumps."""
+
+from __future__ import annotations
+
+import getpass
+import math
+import os
+import re
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+from .buffers import crop_region
+
+VALUES_CAP = 1024
+
+
+def _finite_or_none(value):
+    value = float(value)
+    return value if math.isfinite(value) else None
+
+
+def _channel_stats(channel: np.ndarray, floating: bool, label) -> dict:
+    """Nan-aware stat dict for one 2-D channel (all-NaN -> None stats)."""
+    finite = channel[np.isfinite(channel)] if floating else channel
+    empty = finite.size == 0
+    return {
+        'label': label,
+        'min': None if empty else _finite_or_none(finite.min()),
+        'max': None if empty else _finite_or_none(finite.max()),
+        'mean': None if empty else _finite_or_none(finite.mean()),
+        'std': None if empty else _finite_or_none(finite.std()),
+        'nan': int(np.isnan(channel).sum()) if floating else 0,
+        'inf': int(np.isinf(channel).sum()) if floating else 0,
+        'zeros': int((channel == 0).sum()),
+        'count': int(channel.size),
+    }
+
+
+def _as_hwc(arr: np.ndarray) -> np.ndarray:
+    """
+    Normalize a buffer to (H, W, C). A bare (H, W) matrix is a
+    single-channel buffer, so promote it to (H, W, 1); reject anything
+    that is neither 2-D nor 3-D with a clear error.
+    """
+    if arr.ndim == 2:
+        return arr[:, :, np.newaxis]
+    if arr.ndim != 3:
+        raise ValueError(
+            f'expected a 2-D or 3-D buffer, got {arr.ndim} dimensions')
+    return arr
+
+
+def compute_stats(arr: np.ndarray, meta: dict,
+                   region: tuple | None = None) -> dict:
+    arr = _as_hwc(arr)
+    view = crop_region(arr, region) if region is not None else arr
+    floating = np.issubdtype(arr.dtype, np.floating)
+    layout = (meta.get('pixel_layout') or '')
+    if arr.shape[2] == 1:
+        # A single-channel buffer (an Eigen matrix, a mask) has no
+        # color-channel semantics; do not label it after the layout.
+        layout = ''
+    per_channel = []
+    for index in range(view.shape[2]):
+        channel = view[:, :, index]
+        label = layout[index] if index < len(layout) else None
+        stats = {'channel': index, **_channel_stats(channel, floating, label)}
+        per_channel.append(stats)
+    return {
+        'width': arr.shape[1],
+        'height': arr.shape[0],
+        'channels': arr.shape[2],
+        'dtype': str(arr.dtype),
+        'region': list(region) if region is not None else None,
+        'per_channel': per_channel,
+    }
+
+
+def _json_safe(value):
+    if isinstance(value, float) and not math.isfinite(value):
+        if math.isnan(value):
+            return 'NaN'
+        return 'Inf' if value > 0 else '-Inf'
+    return value
+
+
+def _sanitize_tree(node):
+    if isinstance(node, list):
+        return [_sanitize_tree(item) for item in node]
+    if isinstance(node, dict):
+        return {key: _sanitize_tree(value) for key, value in node.items()}
+    return _json_safe(node)
+
+
+def extract_values(arr: np.ndarray, x: int, y: int, w: int, h: int,
+                    channel: int | None = None) -> dict:
+    """
+    Exact values for a crop; capped so results stay readable.
+    """
+    per_pixel = 1 if channel is not None else arr.shape[2]
+    total = w * h * per_pixel
+    if total > VALUES_CAP:
+        raise ValueError(
+            f'{w}x{h} crop holds {total} values, over the {VALUES_CAP} '
+            f'cap; request a smaller region or a single channel')
+    view = crop_region(arr, (x, y, w, h))
+    if channel is not None:
+        if not 0 <= channel < arr.shape[2]:
+            raise ValueError(
+                f'channel {channel} out of range; buffer has '
+                f'{arr.shape[2]}')
+        view = view[:, :, channel]
+    return {
+        'x': x, 'y': y, 'w': w, 'h': h,
+        'channel': channel,
+        'dtype': str(arr.dtype),
+        'values': _sanitize_tree(view.tolist()),
+    }
+
+
+def _current_user() -> str:
+    try:
+        return getpass.getuser()
+    except Exception:
+        return str(os.getuid()) if hasattr(os, 'getuid') else 'user'
+
+
+def _safe_dump_dir() -> Path:
+    """
+    Per-user default dump directory, hardened against a shared tempdir:
+    reject a pre-created symlink or a directory owned by another user,
+    and force 0o700 (mkdir ignores the mode when the dir pre-exists).
+    """
+    directory = Path(tempfile.gettempdir()) / ('oid-dumps-' + _current_user())
+    if directory.is_symlink():
+        raise RuntimeError('dump directory %s is a symlink' % directory)
+    directory.mkdir(mode=0o700, exist_ok=True)
+    if hasattr(os, 'getuid'):
+        info = os.stat(directory)
+        if info.st_uid != os.getuid():
+            raise RuntimeError(
+                'dump directory %s is owned by another user' % directory)
+        os.chmod(directory, 0o700)
+    return directory
+
+
+def dump_npy(arr: np.ndarray, symbol: str, stop_generation: int,
+             path: str | None = None, overwrite: bool = False) -> str:
+    """
+    Save the full decoded buffer (padding already stripped) as .npy.
+
+    Every write is confined to the hardened per-user dump directory
+    (``_safe_dump_dir()``); ``path`` may only pick a bare filename
+    inside it, never an arbitrary location. The write itself is atomic
+    and symlink-safe.
+
+    Never clobbers an existing file: if the resolved target already
+    exists, raise unless ``overwrite`` is set, so an unintended ``path``
+    cannot silently destroy the caller's data.
+    """
+    directory = _safe_dump_dir()
+    if path is None:
+        name = re.sub(r'[^A-Za-z0-9_.-]', '_', symbol)
+        filename = f'{name}_gen{stop_generation}.npy'
+    else:
+        # The client picks only a name INSIDE the hardened dump dir; a
+        # path separator, '..', or an absolute path could escape it.
+        if (os.path.isabs(path)
+                or os.path.basename(path) != path
+                or path in ('.', '..', '')):
+            raise ValueError(
+                'dump path must be a bare filename within the dump '
+                'directory')
+        filename = path if path.endswith('.npy') else f'{path}.npy'
+    target = os.path.join(str(directory), filename)
+    if os.path.islink(target):
+        raise ValueError(
+            f'{target} is a symlink; refusing to write through it')
+    if not overwrite and os.path.lexists(target):
+        raise FileExistsError(
+            f'{target} already exists; pass overwrite=true to replace it')
+    # Atomic, symlink-safe write: fill a temp file in the same 0700 dir,
+    # then os.replace() the directory entry (which never follows a
+    # symlink at the target).
+    fd, tmp = tempfile.mkstemp(dir=str(directory), suffix='.npy.tmp')
+    try:
+        with os.fdopen(fd, 'wb') as handle:
+            np.save(handle, np.ascontiguousarray(arr))
+        os.replace(tmp, target)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            # Best-effort cleanup of the temp file; a failure to unlink it
+            # (already gone, or a transient FS error) must not mask the
+            # original write error we are about to re-raise.
+            pass
+        raise
+    return os.path.abspath(target)

oidmcp/buffers.py

@@ -0,0 +1,93 @@
+"""Decode raw endpoint payloads into numpy arrays."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+
+import numpy as np
+
+# Keep in sync with oidscripts/symbols.py (OID_TYPES_*). Value 1 is
+# historically unused.
+DTYPES = {
+    0: np.uint8,
+    2: np.uint16,
+    3: np.int16,
+    4: np.int32,
+    5: np.float32,
+    6: np.float64,
+}
+
+
+def decode_buffer(meta: dict, raw: bytes) -> np.ndarray:
+    """
+    Return an (H, W, C) array in display orientation; channel order is
+    the storage order (pixel_layout is applied only when rendering).
+
+    Metadata semantics (matching the debugger bridges): width/height/
+    row_stride describe the buffer as stored; row_stride counts pixels,
+    including padding; transpose_buffer means the stored rows run along
+    the display's width axis.
+    """
+    if meta['type'] not in DTYPES:
+        raise ValueError(f"unsupported buffer type {meta['type']}")
+    dtype = np.dtype(DTYPES[meta['type']])
+    height, width = int(meta['height']), int(meta['width'])
+    channels = int(meta['channels'])
+    stride = int(meta['row_stride'])
+    if height <= 0 or width <= 0 or channels <= 0:
+        raise ValueError(
+            f'invalid buffer dimensions: {width}x{height}x{channels}')
+    if stride < width:
+        raise ValueError(
+            f'row_stride {stride} is smaller than width {width}')
+    count = height * stride * channels
+    if len(raw) < count * dtype.itemsize:
+        raise ValueError(
+            f'buffer payload is {len(raw)} bytes; expected at least '
+            f'{count * dtype.itemsize}')
+    arr = np.frombuffer(raw, dtype=dtype, count=count)
+    arr = arr.reshape(height, stride, channels)[:, :width, :]
+    if meta.get('transpose_buffer'):
+        arr = arr.transpose(1, 0, 2)
+    return arr
+
+
+def crop_region(arr: np.ndarray,
+                region: tuple[int, int, int, int]) -> np.ndarray:
+    """
+    Crop (x, y, w, h), in display coordinates (x = column, y = row).
+    """
+    if len(region) != 4:
+        raise ValueError('region must be [x, y, w, h]')
+    x, y, w, h = (int(v) for v in region)
+    rows, cols = arr.shape[:2]
+    if w <= 0 or h <= 0 or x < 0 or y < 0 or x + w > cols or y + h > rows:
+        raise ValueError(
+            f'region (x={x}, y={y}, w={w}, h={h}) is outside the '
+            f'{cols}x{rows} buffer')
+    return arr[y:y + h, x:x + w, :]
+
+
+# (session pid, token, symbol, stop generation) -> (metadata, decoded array)
+CacheKey = tuple[int, str, str, int]
+CacheValue = tuple[dict, np.ndarray]
+
+
+class BufferCache:
+    """Small LRU keyed by (session pid, token, symbol, stop generation)."""
+
+    def __init__(self, capacity: int = 4):
+        self._capacity = capacity
+        self._entries: OrderedDict[CacheKey, CacheValue] = OrderedDict()
+
+    def get(self, key: CacheKey) -> CacheValue | None:
+        if key not in self._entries:
+            return None
+        self._entries.move_to_end(key)
+        return self._entries[key]
+
+    def put(self, key: CacheKey, value: CacheValue) -> None:
+        self._entries[key] = value
+        self._entries.move_to_end(key)
+        while len(self._entries) > self._capacity:
+            self._entries.popitem(last=False)