PyMemoryEditor 2.2.0__tar.gz → 3.0.0__tar.gz

{pymemoryeditor-2.2.0 → pymemoryeditor-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: PyMemoryEditor
-Version: 2.2.0
+Version: 3.0.0
 Summary: Read, write and scan process memory in a few lines of Python — Cheat Engine-style scans, pointer chains and AOB search on Windows, Linux and macOS.
 Project-URL: Homepage, https://github.com/JeanExtreme002/PyMemoryEditor
 Project-URL: Documentation, https://pymemoryeditor.readthedocs.io
@@ -12,7 +12,7 @@ Author-email: Jean Loui Bernard Silva de Jesus <contact@jeanloui.dev>
 Maintainer-email: Jean Loui Bernard Silva de Jesus <contact@jeanloui.dev>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: aob-scan,cheat-engine,ctypes,debugging,game-hacking,introspection,memory-editor,memory-scanner,pattern-scan,pointer-scan,process-memory,reverse-engineering
+Keywords: ai-agent,aob-scan,cheat-engine,ctypes,debugging,game-hacking,introspection,llm-tools,mcp,memory-editor,memory-scanner,model-context-protocol,pattern-scan,pointer-scan,process-memory,reverse-engineering
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
@@ -41,6 +41,7 @@ Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: flake8; extra == 'dev'
 Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: mcp<3,>=2; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: psutil<7,>=5.9; extra == 'dev'
 Requires-Dist: pyside6>=6.5; extra == 'dev'
@@ -49,6 +50,8 @@ Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest-qt; extra == 'dev'
 Requires-Dist: pytest-xdist; extra == 'dev'
 Requires-Dist: twine; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == 'mcp'
 Provides-Extra: speed
 Requires-Dist: numpy>=1.24; extra == 'speed'
 Provides-Extra: tests
@@ -71,18 +74,19 @@ A pure-Python library (built on [ctypes](https://docs.python.org/3/library/ctype
   <i>One unified API. Three operating systems. No C compiler. No native build step.</i>
 </p>
 
-<p align="center">
-  Runs on <b>🪟 Windows</b> · <b>🐧 Linux</b> · <b>🍎 macOS</b> — 32-bit and 64-bit.
-</p>
-
 <p align="center">
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor/actions/workflows/python-package.yml"><img src="https://github.com/JeanExtreme002/PyMemoryEditor/actions/workflows/python-package.yml/badge.svg" alt="Python Package" /></a>
+  <a href="https://codecov.io/gh/JeanExtreme002/PyMemoryEditor"><img src="https://codecov.io/gh/JeanExtreme002/PyMemoryEditor/branch/main/graph/badge.svg" alt="Coverage" /></a>
   <a href="https://pypi.org/project/PyMemoryEditor/"><img src="https://img.shields.io/pypi/v/PyMemoryEditor" alt="Pypi" /></a>
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor"><img src="https://img.shields.io/pypi/l/PyMemoryEditor" alt="License" /></a>
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor"><img src="https://img.shields.io/badge/python-3.10+-8A2BE2" alt="Python Version" /></a>
   <a href="https://pypi.org/project/PyMemoryEditor/"><img src="https://static.pepy.tech/personalized-badge/pymemoryeditor?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Downloads" alt="Downloads" /></a>
 </p>
 
+<p align="center">
+  Runs on <b>Windows</b> · <b>Linux</b> · <b>macOS</b> — 32-bit and 64-bit.
+</p>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/JeanExtreme002/PyMemoryEditor/main/assets/screenshots/app.png" alt="PyMemoryEditor app attached to a running process" width="820" />
 </p>
@@ -114,6 +118,13 @@ selective scans:
 ```bash
 pip install "PyMemoryEditor[speed]"
 ```
+
+To let an AI assistant drive the library over the Model Context Protocol, use
+the `mcp` extra (see [below](#let-an-ai-assistant-do-it-mcp)):
+
+```bash
+pip install "PyMemoryEditor[mcp]"
+```
 📖 Full guide at **[Read the Docs](https://pymemoryeditor.readthedocs.io)**.
 
 ---
@@ -138,6 +149,38 @@ That's it — read, write or scan another process in three lines, the same way o
 
 ---
 
+## Let an AI assistant do it (MCP)
+
+PyMemoryEditor ships a **Model Context Protocol server**, so an AI assistant can run the whole loop itself:
+
+> *"Find the health value in my game. It's 100 right now."*
+>
+> It scans, asks you to take damage, refines the matches, and hands you the address.
+
+```bash
+pip install "PyMemoryEditor[mcp]"
+claude mcp add pymemoryeditor -- pymemoryeditor-mcp
+```
+
+Or in any client that reads `mcpServers` JSON (Claude Desktop, editors, …):
+
+```json
+{
+  "mcpServers": {
+    "pymemoryeditor": {
+      "command": "pymemoryeditor-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Fourteen tools cover the full workflow, with scan results kept server-side behind a handle, so a 40 000-hit first scan costs a few tokens instead of your whole context.
+
+Read the [MCP guide](https://pymemoryeditor.readthedocs.io/en/latest/mcp.html) to learn more.
+
+---
+
 ## 📖 Documentation
 
 Full documentation lives at **[pymemoryeditor.readthedocs.io](https://pymemoryeditor.readthedocs.io)** — installation, the Cheat Engine workflow, every method and parameter, the GUI app guide, platform notes and troubleshooting.
@@ -145,15 +188,16 @@ Full documentation lives at **[pymemoryeditor.readthedocs.io](https://pymemoryed
 A quick map of where to go:
 
 <table>
-<tr><td><a href="docs/quickstart.md"><b>Quick Start</b></a></td><td>Open a process, read, write and run your first scan.</td></tr>
-<tr><td><a href="docs/guide/searching.md"><b>Searching memory</b></a></td><td>Value scans, ranges, refining results, the Cheat Engine loop.</td></tr>
-<tr><td><a href="docs/guide/pattern-scan.md"><b>Pattern scan</b></a></td><td>Find code/data with byte signatures (AOB) and regex.</td></tr>
-<tr><td><a href="docs/guide/pointers.md"><b>Pointers</b></a></td><td>Multi-level pointer chains and the live <code>RemotePointer</code>.</td></tr>
-<tr><td><a href="docs/guide/pointer-scan.md"><b>Pointer scan</b></a></td><td>Find static pointers that survive ASLR.</td></tr>
-<tr><td><a href="docs/app.md"><b>The GUI app</b></a></td><td>The bundled Cheat Engine-style scanner.</td></tr>
-<tr><td><a href="docs/api/openprocess.md"><b>API reference</b></a></td><td>Every public class, method and parameter.</td></tr>
-<tr><td><a href="docs/platform-notes.md"><b>Platform notes</b></a></td><td>Permissions and quirks on Windows, Linux and macOS.</td></tr>
-<tr><td><a href="docs/troubleshooting.md"><b>Troubleshooting</b></a></td><td>Common errors and how to fix them.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/quickstart.html"><b>Quick Start</b></a></td><td>Open a process, read, write and run your first scan.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/guide/searching.html"><b>Searching memory</b></a></td><td>Value scans, ranges, refining results, the Cheat Engine loop.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/guide/pattern-scan.html"><b>Pattern scan</b></a></td><td>Find code/data with byte signatures (AOB) and regex.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/guide/pointers.html"><b>Pointers</b></a></td><td>Multi-level pointer chains and the live <code>RemotePointer</code>.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/guide/pointer-scan.html"><b>Pointer scan</b></a></td><td>Find static pointers that survive ASLR.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/app.html"><b>The GUI app</b></a></td><td>The bundled Cheat Engine-style scanner.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/mcp.html"><b>The MCP server</b></a></td><td>Let an AI assistant drive the scan/refine loop.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/api/openprocess.html"><b>API reference</b></a></td><td>Every public class, method and parameter.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/platform-notes.html"><b>Platform notes</b></a></td><td>Permissions and quirks on Windows, Linux and macOS.</td></tr>
+<tr><td><a href="https://pymemoryeditor.readthedocs.io/en/latest/troubleshooting.html"><b>Troubleshooting</b></a></td><td>Common errors and how to fix them.</td></tr>
 </table>
 
 ---
@@ -175,7 +219,7 @@ A quick map of where to go:
 ## 🤝 Contributing
 
 Pull requests, bug reports and feature ideas are very welcome. Read
-[`CONTRIBUTING.md`](CONTRIBUTING.md) for the development setup, test layout and
+[`CONTRIBUTING.md`](https://github.com/JeanExtreme002/PyMemoryEditor/blob/main/CONTRIBUTING.md) for the development setup, test layout and
 the small set of platform-specific quirks to be aware of.
 
 If PyMemoryEditor helped your project, please ⭐ the repo — it's the easiest way to
@@ -185,4 +229,4 @@ support the work and to help others discover the library.
 
 ## License
 
-Released under the [MIT License](LICENSE) — free for personal and commercial use.
+Released under the [MIT License](https://github.com/JeanExtreme002/PyMemoryEditor/blob/main/LICENSE) — free for personal and commercial use.

{pymemoryeditor-2.2.0 → pymemoryeditor-3.0.0}/PyMemoryEditor/__init__.py

@@ -8,7 +8,7 @@ Supported platforms: Windows, Linux and macOS (32-bit and 64-bit).
 """
 
 __author__ = "Jean Loui Bernard Silva de Jesus"
-__version__ = "2.2.0"
+__version__ = "3.0.0"
 
 import logging
 import sys

{pymemoryeditor-2.2.0 → pymemoryeditor-3.0.0}/PyMemoryEditor/linux/functions.py

@@ -32,6 +32,7 @@ from ..util import (
     _validate_pytype,
     as_writable_c_buffer,
     get_c_type_of,
+    sign_extend_narrow_int,
     values_to_bytes,
 )
 from ..util.pattern import PatternLike, compile_pattern
@@ -369,13 +370,23 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
     _validate_pytype(pytype)
 
     data = get_c_type_of(pytype, bufflength)
-    _process_vm_readv(pid, addressof(data), address, sizeof(data))
+    # `bufflength`, not `sizeof(data)`. The two differ whenever the width
+    # rounds up to a wider C type — `int` at 3 bytes gets a `c_int32` — and
+    # passing the buffer size made this backend read 4 bytes where Windows and
+    # macOS read 3, so the same call returned a different value per platform
+    # (0x11223344 here against 0x223344 there). `get_c_type_of` guarantees
+    # `sizeof(data) >= bufflength`, so reading into the front of a larger,
+    # zero-initialised buffer is safe and matches the other two backends.
+    _process_vm_readv(pid, addressof(data), address, bufflength)
 
     if pytype is str:
         return bytes(data).decode("utf-8", errors="replace")
     elif pytype is bytes:
         return bytes(data)
     else:
+        # Narrow widths pad with zeroes, which reads a signed value as
+        # unsigned -- and a scan for the same bytes is signed.
+        sign_extend_narrow_int(data, pytype, bufflength)
         return data.value
 
 
@@ -525,7 +536,12 @@ def write_process_memory(
     data = get_c_type_of(pytype, bufflength)
     data.value = value.encode() if isinstance(value, str) else value
 
-    _process_vm_writev(pid, addressof(data), address, sizeof(data))
+    # `bufflength`, not `sizeof(data)` — this one corrupted memory rather than
+    # merely disagreeing. A write of 3 bytes sized a 4-byte `c_int32` and then
+    # wrote all four, destroying a byte the caller never asked to touch, while
+    # Windows and macOS wrote exactly three. Verified on Linux: `w=3` touched 4
+    # bytes and `w=5` touched 8.
+    _process_vm_writev(pid, addressof(data), address, bufflength)
     return value
 
 

{pymemoryeditor-2.2.0 → pymemoryeditor-3.0.0}/PyMemoryEditor/macos/functions.py

@@ -30,6 +30,7 @@ from ..util import (
     _validate_pytype,
     as_writable_c_buffer,
     get_c_type_of,
+    sign_extend_narrow_int,
     values_to_bytes,
 )
 from ..util.pattern import PatternLike, compile_pattern
@@ -311,6 +312,31 @@ _PAGE_GONE_KRS = (
     KERN_MEMORY_ERROR,
 )
 
+# KERN_PROTECTION_FAILURE is tolerated by a full-address-space *sweep* only,
+# never by a read of caller-supplied addresses — hence a second tuple rather
+# than another entry above.
+#
+# The sweeps walk every region the filter accepted and have no opinion about
+# any single one: a range the kernel declines to hand over is a range with no
+# matches in it, and aborting the whole scan over it loses every region that
+# came after. `search_values_by_addresses` is the opposite case — the caller
+# named those addresses, and its documented `raise_error=True` must still be
+# able to report that one of them could not be read. Anything in the tuple
+# above is swallowed even when `raise_error` is set (see
+# process.scanning.iter_values_for_addresses), so putting kr=2 there would
+# silently turn "permission denied" into the same `(address, None)` the caller
+# gets for an address in a gap.
+#
+# Honest limits of what is known here. This was added because a plain
+# search_by_value over the current process died with kr=2 on GitHub's
+# virtualized macOS runners, on a 22 MB region that reported VM_PROT_READ and
+# Shared=False. The mechanism was not established. It does *not* reproduce
+# locally: probing all 135 scannable regions of a live process yields only kr=1
+# and kr=10, and a page deliberately re-protected to PROT_NONE (or never
+# mapped) answers KERN_INVALID_ADDRESS, not kr=2 — so the usual
+# "protection changed under us" story does not explain it.
+_SWEEP_SKIPPABLE_KRS = _PAGE_GONE_KRS + (KERN_PROTECTION_FAILURE,)
+
 
 class MachReadError(OSError):
     """OSError subclass that carries the underlying kern_return_t."""
@@ -494,6 +520,14 @@ def _is_transient(exc: BaseException) -> bool:
     return isinstance(exc, MachReadError) and exc.kr in _PAGE_GONE_KRS
 
 
+def _is_skippable_by_sweep(exc: BaseException) -> bool:
+    """
+    Same as :func:`_is_transient`, plus the codes only a full-address-space
+    sweep may skip. See :data:`_SWEEP_SKIPPABLE_KRS`.
+    """
+    return isinstance(exc, MachReadError) and exc.kr in _SWEEP_SKIPPABLE_KRS
+
+
 def _query_region(task: int, address: int):
     """Return the region containing `address`, or None when the query fails."""
     addr = mach_vm_address_t(address)
@@ -554,6 +588,9 @@ def read_process_memory(
     elif pytype is bytes:
         return bytes(data)
     else:
+        # Narrow widths pad with zeroes, which reads a signed value as
+        # unsigned -- and a scan for the same bytes is signed.
+        sign_extend_narrow_int(data, pytype, bufflength)
         return data.value
 
 
@@ -683,7 +720,7 @@ def search_addresses_by_value(
         scan_type,
         _make_read_chunk(task),
         progress_information=progress_information,
-        transient_error_check=_is_transient,
+        transient_error_check=_is_skippable_by_sweep,
     )
 
 
@@ -1044,7 +1081,7 @@ def search_addresses_by_pattern(
         length,
         _make_read_chunk(task),
         progress_information=progress_information,
-        transient_error_check=_is_transient,
+        transient_error_check=_is_skippable_by_sweep,
     )
 
 

pymemoryeditor-3.0.0/PyMemoryEditor/mcp/__init__.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+
+"""
+A Model Context Protocol server for PyMemoryEditor.
+
+Exposes the library's process-memory tools over MCP so an AI assistant can run
+the Cheat Engine loop itself — enumerate processes, attach, scan for a value,
+narrow the matches as the value changes, then read (and optionally write) the
+address it converged on.
+
+Install and run::
+
+    pip install "PyMemoryEditor[mcp]"
+    pymemoryeditor-mcp                 # asks before attaching; writes allowed
+    pymemoryeditor-mcp --read-only     # never modifies a target
+
+Or register it with a client — Claude Code::
+
+    claude mcp add pymemoryeditor -- pymemoryeditor-mcp
+
+...and any client that reads ``mcpServers`` JSON::
+
+    {
+      "mcpServers": {
+        "pymemoryeditor": {
+          "command": "pymemoryeditor-mcp",
+          "args": []
+        }
+      }
+    }
+
+No flags are needed, because consent is asked for where it can actually be
+given: attaching to a process the operator did not pre-approve **asks the
+user**, and every ``write_value`` call is confirmed by their client.
+``--read-only`` drops the write tool entirely, ``--allow-process NAME``
+pre-approves a target so it stops prompting, and ``--allow-any-process`` turns
+prompting off for scripted runs. Read :doc:`the MCP guide </mcp>` before
+pointing it at anything you care about — it runs with your privileges and it is
+**not a sandbox**.
+
+Layout: :mod:`~PyMemoryEditor.mcp.toolset` holds the tools (and imports no MCP
+SDK, so it is testable on its own), :mod:`~PyMemoryEditor.mcp.session` the
+process/scan handles, :mod:`~PyMemoryEditor.mcp.policy` the access rules, and
+:mod:`~PyMemoryEditor.mcp.server` the protocol wiring.
+"""
+
+from .config import ServerConfig, build_parser, parse_args
+from .policy import AccessDecision, ProcessPolicy
+from .server import INSTRUCTIONS, build_server, main
+from .session import ScanResult, Session, SessionError, SessionStore
+from .toolset import MemoryToolset, ToolError
+
+__all__ = (
+    "INSTRUCTIONS",
+    "AccessDecision",
+    "MemoryToolset",
+    "ProcessPolicy",
+    "ScanResult",
+    "ServerConfig",
+    "Session",
+    "SessionError",
+    "SessionStore",
+    "ToolError",
+    "build_parser",
+    "build_server",
+    "main",
+    "parse_args",
+)

pymemoryeditor-3.0.0/PyMemoryEditor/mcp/__main__.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+"""``python -m PyMemoryEditor.mcp`` — the same entry point as the console script.
+
+Useful when the console script is not on PATH, which is the usual situation
+when an MCP client launches the server from a virtualenv it did not activate::
+
+    {"command": "/path/to/venv/bin/python",
+     "args": ["-m", "PyMemoryEditor.mcp", "--allow-process", "game.exe"]}
+"""
+
+import sys
+
+from .server import main
+
+if __name__ == "__main__":
+    sys.exit(main())