memscope-mcp 0.1.0__tar.gz

memscope_mcp-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

memscope_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
+    inputs:
+      target:
+        description: Publish target
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+jobs:
+  test:
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Test
+        run: pytest tests/ -v
+      - name: Lint
+        run: |
+          ruff check
+          ruff format --check
+
+  build:
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+      - name: Build
+        run: python -m build
+      - name: Metadata check
+        run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: [build]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: ${{ github.event_name == 'workflow_dispatch' && inputs.target || 'pypi' }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - name: Publish to PyPI
+        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+        uses: pypa/gh-action-pypi-publish@release/v1

memscope_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,39 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/ruff-action@v4.0.0
+        with:
+          args: check
+
+      - uses: astral-sh/ruff-action@v4.0.0
+        with:
+          args: format --check
+
+  test:
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v

memscope_mcp-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Logs and temp files
+*.log
+error_log.txt
+error_wrapper.log
+logs/
+nul
+
+# Claude temp files
+tmpclaude-*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Plugins (user-curated, keep README)
+plugins/*.py
+
+# Project specific
+mcp_wrapper.js
+lua_scripts.json
+scripts/*/
+
+# User-specific config
+.mcp.json
+.claude/

memscope_mcp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format

memscope_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,91 @@
+# memscope-mcp
+
+Windows-only MCP server for low-level memory research and reverse engineering. Python 3.10+, 10 MCP tools, embedded Lua 5.4 engine, generic inline hooking with shared ring buffer, PEB introspection without attaching.
+
+See @README.md for the project overview, @CONTRIBUTING.md for the contribution flow, @docs/hooking.md and @docs/peb.md for the two non-trivial subsystems, @docs/lua-reference.md for the full Lua surface, @CONTRIBUTING.md for the plugin interface.
+
+## Commands
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+ruff check memscope_mcp/ tests/
+ruff format --check memscope_mcp/ tests/
+```
+
+Pre-commit hooks run ruff on every commit. Config lives in `pyproject.toml` (line length 120).
+
+## Project structure
+
+```
+memscope_mcp/
+  server.py          # MCP tool definitions (thin wrappers), entry point
+  session.py         # Attach/detach, memory primitives, threads, VirtualProtect,
+                     #   allocate_near, suspend/resume, lifecycle callbacks
+  extensions/        # LuaExtension ABC + bootstrap
+    base.py          # LuaExtension, ExtensionContext
+    bootstrap.py     # Core extension + user plugin registration
+    core/            # Always-loaded: general, memory, module_scan, execution,
+                     #   hooking, process, network
+  tools/
+    server-side tool implementations + `hooking.py` (HookManager)
+    lua/             # Lua-callable function modules
+  utils/
+    shellcode.py     # x64 codegen (native calls + hook trampolines)
+    disasm.py        # Table-driven x64 length decoder + RIP-relative relocation
+    pe.py            # PE export resolution (resolveExport)
+    peb.py           # PEB reader: cmdline, env, debugger, remote modules
+  plugins/           # PluginBase (LuaExtension specialization) + loader
+  instructions/      # AI context builder (base + extensions + plugins)
+  _contrib/plugins/  # Bundled reference plugins (il2cpp, netcap)
+scripts/             # Saved Lua scripts per process (gitignored)
+logs/                # Session logs in JSONL (gitignored)
+docs/                # hooking.md, peb.md, lua-reference.md
+tests/               # pytest suite
+```
+
+## Architecture rules
+
+- **Generic core, plugins for domains.** No domain-specific code in `memscope_mcp/`. Game/engine helpers go in `memscope_mcp/_contrib/plugins/`; users install to `$MEMSCOPE_HOME/plugins/`.
+- **One contract, two activation paths.** Core features and plugins both implement `LuaExtension` (`memscope_mcp/extensions/base.py`). Core extensions are always loaded and registration failure is hard; plugins are user-curated, loaded only when their file is in `$MEMSCOPE_HOME/plugins/`, and isolated on failure.
+- **10 MCP tools, locked.** Everything new goes through Lua. `tests/test_smoke.py::test_tool_count` pins the count. Adding an MCP tool requires explicit justification.
+- **Lua for complexity.** Simple typed reads use MCP tools. Loops, conditionals, multi-step chains go in Lua.
+- **Scripts persist, addresses don't.** ASLR invalidates addresses every restart. Save the finder, not the address.
+- **AI context is expensive.** `memscope_mcp/instructions/base.py` is always loaded; per-extension `instructions` fragments are appended in registration order. Keep both terse.
+
+## Hooking and PEB invariants
+
+- Hooks require an attached process. PEB reads do not.
+- Hook installation prefers a +-2 GiB trampoline allocation so a 5-byte `JMP rel32` patch suffices. Falls back to a 14-byte `JMP [RIP+0]` with thread-suspension + IP redirect when near allocation fails.
+- The shared ring buffer is allocated lazily by `createRingBuffer`. `destroyRingBuffer` refuses while hooks are still installed.
+- Hook removal restores the saved prologue but defers trampoline free until `cleanup()` (called from `on_process_detaching` and from server shutdown). A thread may still be inside the trampoline at the moment of unhook.
+- `_safe_patch` in `HookManager` is the only writer for 14-byte patches; it suspends every thread, redirects RIPs in the danger zone, writes, and resumes. Do not patch 14 bytes outside this path.
+- The PEB reader (`memscope_mcp/utils/peb.py`) opens and closes its own handle per call. No state, no leaks.
+- PEB reads truncate silently: environment block 64 KiB, module list 1024 entries, individual wide strings 32 KiB.
+
+## Code conventions
+
+- Delete unused code; no dead functions.
+- `bare except` is deliberate in memory-read paths (any failure means "return nil"); ruff E722 is suppressed.
+- Lua functions return `nil` on failure rather than raising.
+- Addresses accept ints, hex strings (`"0x7FF6A0010000"`), and module+offset (`"module.dll+0x123"`). Use `parse_address` from `memscope_mcp/utils/memory_utils.py`.
+- Lua-side return tables are built with `ctx.table_factory(...)` inside extensions, or `engine.lua.table()` outside.
+
+## Key files
+
+- `memscope_mcp/server.py` -- MCP tool definitions, shutdown handler with hook cleanup
+- `memscope_mcp/extensions/bootstrap.py` -- the registration spine
+- `memscope_mcp/extensions/core/__init__.py` -- `CORE_EXTENSIONS` ordering
+- `memscope_mcp/tools/hooking.py` -- HookManager (ring buffer + install/remove/cleanup)
+- `memscope_mcp/tools/lua/engine.py` -- `MemscopeLuaEngine`, per-execution state
+- `tests/test_smoke.py` -- the pinned 10-tool surface; first regression catcher
+- `tests/test_extension_bootstrap.py` -- pins extension ordering and registration contract
+- `tests/conftest.py` -- imports `memscope_mcp.server` so bootstrap runs before any test collects
+
+## Gotchas
+
+- Windows-only (pymem wraps Win32). Tests run on Windows GitHub Actions runners; nothing here works on Linux/macOS.
+- Module bases cached on `attach` -- the auto-reconnect path re-caches transparently on transient restart.
+- Large Lua hex literals (>32-bit) cause parse errors. The engine preprocessor rewrites them, but explicit `addr("0x...")` is safer in user-edited scripts.
+- All MCP tool calls log to `logs/sessions/<timestamp>.jsonl`. Useful for diagnosing what the agent actually called.
+- The netcap plugin (`memscope_mcp/_contrib/plugins/netcap.py`) is *not* a core extension. It is the reference plugin built on the hooking primitives. Don't import it from the core package.

memscope_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to memscope-mcp
+
+Small focused PRs welcome. For anything large or speculative, open an issue first.
+
+## Development setup
+
+Windows x64 + Python 3.10+ are required. The `pymem` dependency is Windows-only and is skipped via an environment marker on other platforms; the package installs on macOS and Linux but `import memscope_mcp` raises `RuntimeError` there.
+
+```bash
+git clone https://github.com/Boti-Ormandi/memscope-mcp.git
+cd memscope-mcp
+pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+Pre-commit runs `ruff check --fix` and `ruff format` on every commit. CI runs the same checks plus the full pytest suite on Python 3.10 through 3.13.
+
+### Dev workflow note: MEMSCOPE_HOME
+
+By default, logs and saved Lua scripts land in `~/.memscope-mcp/`. If you want
+artefacts to land next to the cloned repository instead, set `MEMSCOPE_HOME=$PWD`
+in your shell before starting the server.
+
+## Project layout
+
+The top-level [README](README.md#architecture) has the full tree. The pieces you'll actually touch:
+
+- [`memscope_mcp/server.py`](memscope_mcp/server.py) -- `@mcp.tool()` wrappers (one per MCP tool)
+- [`memscope_mcp/tools/`](memscope_mcp/tools/) -- tool implementations (`memory.py`, `scanning.py`, `pointers.py`, `types.py`, `execute.py`, `hooking.py`, `lua_scripts.py`)
+- [`memscope_mcp/tools/lua/`](memscope_mcp/tools/lua/) -- Lua engine (`engine.py`) plus themed function modules: `memory_read`, `memory_write`, `process_info`, `scanning_helpers`, `struct_helpers`, `modules`, `code_execution`, `comparisons`, `utilities`, `hooking`, `network`
+- [`memscope_mcp/extensions/`](memscope_mcp/extensions/) -- `LuaExtension` ABC + bootstrap + the seven core extensions under `core/`
+- [`memscope_mcp/utils/`](memscope_mcp/utils/) -- address parsing, heuristics, x64 shellcode (`shellcode.py`), instruction decoder + relocator (`disasm.py`), PE export resolver (`pe.py`), PEB reader (`peb.py`)
+- [`memscope_mcp/instructions/base.py`](memscope_mcp/instructions/base.py) -- AI-facing Lua reference (token-priced, kept terse)
+- [`docs/lua-reference.md`](docs/lua-reference.md) -- human-facing Lua reference (complete)
+- [`docs/hooking.md`](docs/hooking.md) and [`docs/peb.md`](docs/peb.md) -- design docs for the hooking and PEB-introspection layers
+- [`memscope_mcp/_contrib/plugins/`](memscope_mcp/_contrib/plugins/) -- bundled reference plugins (il2cpp, netcap)
+- [`tests/`](tests/) -- pytest suite, smoke + unit + extension/hook/netcap/PEB coverage
+
+## Adding an MCP tool
+
+1. Implement in `memscope_mcp/tools/<your_tool>.py`. Follow patterns in `types.py` or `scanning.py`.
+2. Wrap with `@mcp.tool()` in `memscope_mcp/server.py`. Call `_log()` so the tool call lands in session logs.
+3. Keep the docstring terse — it becomes AI-facing context and costs tokens. List parameters, types, and return shape.
+4. Update `tests/test_smoke.py`: add the tool name to `test_tool_names` and bump `test_tool_count`. This test pins the 10-tool surface; forgetting it makes the smoke test fail immediately.
+5. Add the tool to the README tool table.
+
+## Adding a Lua function
+
+Lua functions live inside extensions. Pick the right extension first.
+
+1. Pick the extension by category:
+   - Reads -> `core/memory.py` (which dispatches to `tools/lua/memory_read.py`)
+   - Writes -> `core/memory.py` (`tools/lua/memory_write.py`)
+   - AOB / xref scans, module/address resolution -> `core/module_scan.py` (`tools/lua/scanning_helpers.py`, `tools/lua/modules.py`)
+   - Vector / matrix / declarative struct reads, comparisons, bitwise, formatting -> `core/general.py` (`tools/lua/struct_helpers.py`, `tools/lua/comparisons.py`, `tools/lua/utilities.py`)
+   - Remote calls and allocation -> `core/execution.py` (`tools/lua/code_execution.py`)
+   - Pre-attach / PEB introspection -> `core/process.py` (`tools/lua/process_info.py`)
+   - Hooking primitives -> `core/hooking.py` (`tools/lua/hooking.py`)
+   - Network helpers -> `core/network.py` (`tools/lua/network.py`)
+2. Add the function to the relevant `tools/lua/*.py` module (or directly to the extension if it is tightly scoped).
+3. Add the Lua-name -> Python-callable mapping to the dict returned by the extension's `register(ctx)`.
+4. Update the extension's `instructions` string with a one-line AI-facing description (token-priced, terse).
+5. Document the function in [`docs/lua-reference.md`](docs/lua-reference.md) under the matching category and in [`memscope_mcp/instructions/base.py`](memscope_mcp/instructions/base.py) if a shared-guidance bullet is appropriate.
+6. Conventions: return `nil` on failure (don't raise), accept addresses as int or hex string (use `parse_address`), and use `ctx.table_factory(...)` to build Lua-side return tables.
+
+## Adding an extension
+
+A core extension is appropriate when the functionality is generic enough to be useful on any target -- memory, scanning, hooking, process introspection. A user plugin (under `plugins/`) is the right shape when the functionality is target-specific.
+
+1. Create `memscope_mcp/extensions/core/<your_ext>.py`. Subclass `LuaExtension` from `memscope_mcp/extensions/base.py`. Implement `name`, `description`, `instructions`, and `register(ctx)`. Override `on_process_attached` / `on_process_detaching` if the extension holds process-bound state (allocations, hooks).
+2. Register the class in `memscope_mcp/extensions/core/__init__.py` -- import it and add it to `CORE_EXTENSIONS` in the right position (`General` first, the rest in the order the AI is likely to encounter them).
+3. Hold cross-call state on the extension instance, not on `SESSION`.
+4. If the extension introduces a new conceptual surface, write a short `docs/<topic>.md` design doc (see [`docs/hooking.md`](docs/hooking.md) and [`docs/peb.md`](docs/peb.md) for shape and tone) and link it from the README's Implementation Notes.
+5. Add a test file under `tests/test_<your_ext>.py` covering the registration path and any non-trivial logic. `tests/test_extension_bootstrap.py` already pins ordering and the basic contract.
+
+## Adding a plugin
+
+The bundled reference plugins live under `memscope_mcp/_contrib/plugins/` and ship in the wheel. Users install them to `$MEMSCOPE_HOME/plugins/` (default `~/.memscope-mcp/plugins/`) via `memscope-mcp install-plugin <name>`; the loader picks up any `.py` file placed there. Reference plugins:
+
+- [`memscope_mcp/_contrib/plugins/il2cpp.py`](memscope_mcp/_contrib/plugins/il2cpp.py) -- Unity IL2CPP runtime helpers; template for managed-runtime object walking.
+- [`memscope_mcp/_contrib/plugins/netcap.py`](memscope_mcp/_contrib/plugins/netcap.py) -- Winsock capture and analysis built on the generic hooking layer; template for API-hooking + protocol parsing.
+
+## Code style
+
+Enforced by [ruff](https://docs.astral.sh/ruff/). Configuration in `pyproject.toml`:
+
+- Line length 120
+- Rules: E, F, W, I (pycodestyle, pyflakes, isort)
+- E722 (bare `except`) is allowed: it's deliberate in memory-read paths where any failure means "return nil"
+- Type hints on public function signatures
+- Docstrings with Args/Returns on public functions
+
+## Testing
+
+The smoke suite (`tests/test_smoke.py`) is the gating invariant: it asserts the 10-tool surface, that the Lua engine initializes, that the plugin loader runs, and that the instructions builder produces output. Most regressions show up here first.
+
+Unit tests live next to features (`test_types.py`, `test_scanning.py`, `test_lua_engine.py`, etc.). Hooking and netcap have dedicated coverage in `test_disasm.py`, `test_relocation.py`, `test_hook_shellcode.py`, `test_ring_buffer.py`, `test_pe_exports.py`, `test_thread_suspension.py`, `test_netcap_plugin.py`, `test_netcap_lifecycle.py`, `test_netcap_udp.py`, `test_netcap_wsa.py`, `test_stream_assembly.py`, `test_protocol_framing.py`, `test_filter_packets.py`, `test_header_only.py`, `test_deref_args.py`, `test_phase5_hardening.py`, `test_cross_reference.py`, `test_session_recording.py`. The extension bootstrap is pinned by `test_extension_bootstrap.py`. PEB reading is covered by `test_peb.py` (self-process tests run in CI; explorer.exe-dependent tests skip gracefully when explorer is not running). Run a focused subset with `pytest -k <pattern>`.
+
+`tests/conftest.py` imports `memscope_mcp.server` once at collection time so the extension bootstrap runs before any test resolves a Lua function. If a new test needs the Lua surface initialized, it relies on this import side-effect -- nothing else is required.
+
+There's no live-process integration test -- pymem can't attach to anything useful in a clean GitHub Actions runner, so verifying tool behavior against a real target stays manual.
+
+## PR checklist
+
+- `ruff check` and `ruff format --check` pass
+- `pytest` passes locally on Windows
+- README tool table updated if you added or removed an MCP tool
+- New Lua functions documented in the relevant extension's `instructions` string and in `docs/lua-reference.md`
+- New conceptual surface (a new extension category, a new design pattern) gets a short `docs/<topic>.md`
+- One logical change per commit; PR description explains the what and the why
+
+## License
+
+By contributing, you agree your contributions will be licensed under the MIT License.

memscope_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Botond Ormandi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.