@memoryprocess/mcp 0.0.0-stage → 0.0.3-beta.1

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @memoryprocess/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server exposing the memoryprocess toolkit to LLM agents — the primary
+agentic surface. Stdio transport; the agent's MCP client owns the server
+process, so open process handles die with the session.
+
+## Usage
+
+Point your MCP client at the bin (works under bun or node):
+
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "memoryprocess": {
+      "command": "bun",
+      "args": ["C:/path/to/memoryprocess/packages/mcp/src/server.ts"],
+    },
+  },
+}
+```
+
+```
+memoryprocess-mcp [--no-eval] [--help] [--version]
+MEMP_NO_EVAL=1   # same as --no-eval
+```
+
+## Session model
+
+There is no implicit "current process". `proc_open` returns a session handle
+(`p1`, `p2`, …); every `mem_*` tool takes it as `session`, so an agent can
+hold several targets at once. `proc_close` releases the handle and any
+watches/freezes bound to it.
+
+## Tools
+
+| Tool                  | Description                                                                                              |
+| --------------------- | -------------------------------------------------------------------------------------------------------- |
+| `proc_list`           | List running processes `{pid,name}[]`                                                                    |
+| `proc_open`           | Open by `{pid}` or `{name}` → `{session, describe}`. `access:"ro"` = read-only                           |
+| `proc_close`          | Close a session                                                                                          |
+| `mem_describe`        | `Process.describe()`: arch, modules, writable/exec regions, threads                                      |
+| `mem_read`            | Typed read: `i8…i64/u8…u64`, `f32/f64`, `ptr`, `str`, `wstr`, `bytes[:N]` (+`len`)                       |
+| `mem_write`           | Typed write. `dryRun:true` → `{addr,current,would,bytes}` preview. Journaled                             |
+| `mem_scan`            | CE value scan → `{hits:[{addr,value}],count,truncated}` (`module`/`start`/`end`/`limit`)                 |
+| `mem_scan_next`       | Refine hits: `exact`/`changed`/`unchanged`/`increased`/`decreased`/`increasedBy`/`decreasedBy`/`between` |
+| `mem_pointer_resolve` | `module`+`rva`+`offsets[]` → resolved address (CE pointer syntax)                                        |
+| `mem_watch`           | Poll an i32 every `ms` → `{watchId}`; changes accumulate                                                 |
+| `mem_watch_poll`      | Drain recorded changes `[{value,ts}]` for a `watchId`                                                    |
+| `mem_unwatch`         | Stop a watch                                                                                             |
+| `mem_freeze`          | Re-write a value every `ms` → `{freezeId}`                                                               |
+| `mem_unfreeze`        | Stop a freeze                                                                                            |
+| `mem_undo`            | Revert last `n` journaled writes (self-correction primitive)                                             |
+| `mem_journal`         | Write-log snapshot `[{index,addr,bytes}]`                                                                |
+| `eval_js`             | Run JS with `proc` (`Process`) in scope — the escape hatch                                               |
+
+## Wire format (docs/json-conventions.md)
+
+- Every result is `{ok:true,data}` or `{ok:false,error:{code,message,win32code?}}`
+  — `error.code` is the typed code from `@memoryprocess/core`
+  (`READ_FAILED`, `PROCESS_NOT_FOUND`, …) plus `UNKNOWN_SESSION`,
+  `UNKNOWN_WATCH`, `UNKNOWN_FREEZE`, `MODULE_NOT_FOUND`, `INVALID_ARGS`,
+  `EVAL_ERROR`.
+- Addresses/pointers/64-bit values are `"0x…"` hex strings; values that fit
+  in a JS number stay numbers; raw bytes are hex strings.
+- Address args accept `"0x…"`, decimal strings, or `"module+rva"`.
+
+## Safety
+
+All writes are journaled → `mem_journal` + `mem_undo` let an agent preview
+(`dryRun`), commit, inspect, and revert. `eval_js` runs arbitrary JS on the
+host — it's on by default (agents already have code execution) and can be
+disabled with `--no-eval` / `MEMP_NO_EVAL=1`, which omits it from
+`tools/list` entirely.

package/dist/server.mjs

@@ -0,0 +1,832 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { MemoryProcessError, Process } from "@memoryprocess/core";
+// src/tools.ts
+/**
+* Session-handle tool layer for @memoryprocess/mcp.
+*
+* The MCP wire layer (server.ts) is a thin adapter over the definitions in
+* this file so the handlers are unit-testable without a stdio transport:
+* `createSessions()` + `callTool(sessions, name, args)`.
+*
+* Wire format follows docs/json-conventions.md:
+*  - every result is `{ok:true,data} | {ok:false,error:{code,message,win32code?}}`
+*  - bigints (addresses, pointers, 64-bit values) -> '0x...' strings
+*  - Buffers -> lowercase hex strings
+*  - errors carry the typed `.code` from @memoryprocess/core when available
+*/
+const hex = (v) => `0x${BigInt(v).toString(16)}`;
+/** Recursively convert a JS value into the JSON-safe wire shape. */
+function jsonSafe(v) {
+	if (typeof v === "bigint") return hex(v);
+	if (v === null || v === void 0) return v;
+	if (typeof v === "number" || typeof v === "string" || typeof v === "boolean") return v;
+	if (Buffer.isBuffer(v)) return v.toString("hex");
+	if (ArrayBuffer.isView(v)) {
+		if (v instanceof Float32Array || v instanceof Float64Array) return Array.from(v);
+		return Buffer.from(v.buffer, v.byteOffset, v.byteLength).toString("hex");
+	}
+	if (Array.isArray(v)) return v.map(jsonSafe);
+	if (typeof v === "object") {
+		const out = {};
+		for (const [k, val] of Object.entries(v)) out[k] = jsonSafe(val);
+		return out;
+	}
+	return String(v);
+}
+const fail = (code, message) => {
+	const e = new Error(message);
+	e.code = code;
+	return e;
+};
+function errorEnvelope(e) {
+	const err = e;
+	const out = {
+		code: typeof err?.code === "string" ? err.code : err instanceof MemoryProcessError ? err.code : "INTERNAL_ERROR",
+		message: err?.message ?? String(e)
+	};
+	if (typeof err?.win32code === "number") out.win32code = err.win32code;
+	return {
+		ok: false,
+		error: out
+	};
+}
+/**
+* Parse an address argument: `0x...` hex string, decimal string, or
+* `"module+rva"` (resolved against the session's module table -- the rva is
+* optional). Returns the absolute address as bigint.
+*/
+function parseAddress(proc, v, name = "addr") {
+	if (typeof v === "bigint") return v;
+	if (typeof v === "number") {
+		if (!Number.isFinite(v) || v < 0) throw fail("INVALID_ARGS", `${name} invalid`);
+		return BigInt(v);
+	}
+	if (typeof v === "string") {
+		const s = v.trim();
+		const plus = s.lastIndexOf("+");
+		if (plus > 0) {
+			const mod = proc.module(s.slice(0, plus));
+			if (!mod) throw fail("MODULE_NOT_FOUND", `module not found: ${s.slice(0, plus)} (in "${s}")`);
+			const rva = s.slice(plus + 1);
+			let off;
+			try {
+				off = BigInt(rva);
+			} catch {
+				throw fail("INVALID_ARGS", `bad rva in "${s}"`);
+			}
+			return BigInt(mod.base) + off;
+		}
+		if (/\.(exe|dll)$/i.test(s)) {
+			const mod = proc.module(s);
+			if (!mod) throw fail("MODULE_NOT_FOUND", `module not found: ${s}`);
+			return BigInt(mod.base);
+		}
+		try {
+			return BigInt(s);
+		} catch {
+			throw fail("INVALID_ARGS", `${name} must be an address ("${v}")`);
+		}
+	}
+	throw fail("INVALID_ARGS", `${name} must be an address`);
+}
+/** Parse a numeric value argument (accepts numbers, bigints, dec/hex strings). */
+function parseNumeric(v, wide, name = "value") {
+	if (typeof v === "bigint") return wide ? v : Number(v);
+	if (typeof v === "number") {
+		if (!Number.isFinite(v)) throw fail("INVALID_ARGS", `${name} must be finite`);
+		return wide ? BigInt(Math.trunc(v)) : v;
+	}
+	if (typeof v === "string") {
+		const s = v.trim();
+		if (wide) try {
+			return BigInt(s);
+		} catch {
+			throw fail("INVALID_ARGS", `${name} must be an integer ("${v}")`);
+		}
+		const n = /^0x[0-9a-f]+$/i.test(s) ? Number(BigInt(s)) : Number(s);
+		if (!Number.isFinite(n)) throw fail("INVALID_ARGS", `${name} must be a number ("${v}")`);
+		return n;
+	}
+	throw fail("INVALID_ARGS", `${name} must be a number`);
+}
+/** Agent-facing type aliases -> core WriteValueType/ScanValueType. */
+const NUMERIC_TYPES = {
+	i8: "int8",
+	u8: "uint8",
+	i16: "int16",
+	u16: "uint16",
+	i32: "int32",
+	u32: "uint32",
+	i64: "int64",
+	u64: "uint64",
+	f32: "float",
+	f64: "double",
+	ptr: "pointer",
+	int8: "int8",
+	uint8: "uint8",
+	int16: "int16",
+	uint16: "uint16",
+	int32: "int32",
+	uint32: "uint32",
+	int64: "int64",
+	uint64: "uint64",
+	float: "float",
+	double: "double",
+	pointer: "pointer"
+};
+const SCAN_TYPES = /* @__PURE__ */ new Set([
+	"int32",
+	"uint32",
+	"int64",
+	"uint64",
+	"float",
+	"double"
+]);
+const WIDE_TYPES = /* @__PURE__ */ new Set([
+	"int64",
+	"uint64",
+	"pointer"
+]);
+/**
+* Normalise an agent-facing type name to the core name.
+* Accepts `bytes`/`bytes:N` (needs `len`), `str`/`wstr`, and numeric types.
+*/
+function normType(t, name = "type") {
+	if (typeof t !== "string" || !t) throw fail("INVALID_ARGS", `${name} must be a string`);
+	const lower = t.toLowerCase();
+	const hit = NUMERIC_TYPES[lower];
+	if (hit) return hit;
+	if (lower === "str" || lower === "wstr") return lower;
+	if (lower === "bytes" || /^bytes:\d+$/.test(lower)) return "bytes";
+	throw fail("INVALID_ARGS", `unknown type "${t}"`);
+}
+var SessionStore = class {
+	procs = /* @__PURE__ */ new Map();
+	watches = /* @__PURE__ */ new Map();
+	freezes = /* @__PURE__ */ new Map();
+	seq = 0;
+	wseq = 0;
+	fseq = 0;
+	open(nameOrPid, access) {
+		const proc = access === "ro" ? Process.openReadOnly(nameOrPid) : Process.open(nameOrPid);
+		const id = `p${++this.seq}`;
+		this.procs.set(id, proc);
+		return id;
+	}
+	get(id) {
+		if (typeof id !== "string") throw fail("INVALID_ARGS", "session must be a string");
+		const p = this.procs.get(id);
+		if (!p) throw fail("UNKNOWN_SESSION", `unknown session "${id}"`);
+		return p;
+	}
+	close(id) {
+		if (typeof id !== "string") throw fail("INVALID_ARGS", "session must be a string");
+		const p = this.procs.get(id);
+		if (!p) throw fail("UNKNOWN_SESSION", `unknown session "${id}"`);
+		for (const k of [...this.watches.keys()]) if (k.startsWith(`${id}:`)) {
+			this.watches.get(k).stop();
+			this.watches.delete(k);
+		}
+		for (const k of [...this.freezes.keys()]) if (k.startsWith(`${id}:`)) {
+			this.freezes.get(k)();
+			this.freezes.delete(k);
+		}
+		this.procs.delete(id);
+		p.close();
+	}
+	addWatch(session, rec) {
+		const id = `${session}:w${++this.wseq}`;
+		this.watches.set(id, rec);
+		return id;
+	}
+	getWatch(id) {
+		if (typeof id !== "string") throw fail("INVALID_ARGS", "watchId must be a string");
+		const w = this.watches.get(id);
+		if (!w) throw fail("UNKNOWN_WATCH", `unknown watchId "${id}"`);
+		return w;
+	}
+	removeWatch(id) {
+		this.getWatch(id).stop();
+		this.watches.delete(id);
+	}
+	addFreeze(session, stop) {
+		const id = `${session}:f${++this.fseq}`;
+		this.freezes.set(id, stop);
+		return id;
+	}
+	removeFreeze(id) {
+		if (typeof id !== "string") throw fail("INVALID_ARGS", "freezeId must be a string");
+		const stop = this.freezes.get(id);
+		if (!stop) throw fail("UNKNOWN_FREEZE", `unknown freezeId "${id}"`);
+		stop();
+		this.freezes.delete(id);
+	}
+	closeAll() {
+		for (const [id] of this.procs) try {
+			this.close(id);
+		} catch {}
+		for (const [, w] of this.watches) w.stop();
+		for (const [, f] of this.freezes) f();
+		this.watches.clear();
+		this.freezes.clear();
+	}
+	get size() {
+		return this.procs.size;
+	}
+};
+function createSessions() {
+	return new SessionStore();
+}
+function readTyped(proc, addr, args) {
+	switch (normType(args.type)) {
+		case "str": return proc.readString(addr, typeof args.len === "number" ? args.len : void 0);
+		case "wstr": return proc.readWideString(addr, typeof args.len === "number" ? args.len : void 0);
+		case "bytes": {
+			const m = typeof args.type === "string" && /^bytes:(\d+)$/.exec(args.type);
+			const len = typeof args.len === "number" ? args.len : m ? Number(m[1]) : void 0;
+			if (len === void 0 || !Number.isInteger(len) || len < 1) throw fail("INVALID_ARGS", "bytes read needs len (or bytes:N)");
+			return proc.readBuffer(addr, len);
+		}
+		case "int8": return proc.readUInt8(addr) << 24 >> 24;
+		case "int16": return proc.readUInt16(addr) << 16 >> 16;
+		case "uint8": return proc.readUInt8(addr);
+		case "uint16": return proc.readUInt16(addr);
+		case "int32": return proc.readInt32(addr);
+		case "uint32": return proc.readUInt32(addr);
+		case "int64": return proc.readInt64(addr);
+		case "uint64": return proc.readUInt64(addr);
+		case "float": return proc.readFloat(addr);
+		case "double": return proc.readDouble(addr);
+		case "pointer": return proc.readPointer(addr);
+		default: throw fail("INVALID_ARGS", `unsupported read type "${args.type}"`);
+	}
+}
+function serializePreview(p) {
+	return {
+		addr: hex(p.addr),
+		current: p.current.toString("hex"),
+		would: p.would.toString("hex"),
+		bytes: p.bytes
+	};
+}
+function writeTyped(proc, addr, args) {
+	const type = normType(args.type);
+	const opts = { dryRun: args.dryRun === true };
+	const fin = (r) => r === true ? true : serializePreview(r);
+	switch (type) {
+		case "str":
+		case "wstr":
+			if (typeof args.value !== "string") throw fail("INVALID_ARGS", `${type} write needs a string value`);
+			return fin(type === "str" ? proc.writeString(addr, args.value, "utf8", opts) : proc.writeWideString(addr, args.value, opts));
+		case "bytes": {
+			const v = args.value;
+			let buf;
+			if (typeof v === "string" && /^(0x)?[0-9a-fA-F]*$/.test(v)) buf = Buffer.from(v.replace(/^0x/, ""), "hex");
+			else if (Array.isArray(v)) buf = Buffer.from(v.map((b) => Number(b) & 255));
+			else throw fail("INVALID_ARGS", "bytes write needs a hex string or byte array");
+			if (buf.length === 0) throw fail("INVALID_ARGS", "bytes write needs at least 1 byte");
+			return fin(proc.writeBuffer(addr, buf, opts));
+		}
+		case "int8":
+		case "int16":
+		case "uint8":
+		case "uint16": {
+			const v = parseNumeric(args.value, false);
+			return fin(type === "int8" || type === "uint8" ? proc.writeUInt8(addr, v, opts) : proc.writeUInt16(addr, v, opts));
+		}
+		case "int32": return fin(proc.writeInt32(addr, parseNumeric(args.value, false), opts));
+		case "uint32": return fin(proc.writeUInt32(addr, parseNumeric(args.value, false), opts));
+		case "int64": return fin(proc.writeInt64(addr, parseNumeric(args.value, true), opts));
+		case "uint64": return fin(proc.writeUInt64(addr, parseNumeric(args.value, true), opts));
+		case "float": return fin(proc.writeFloat(addr, parseNumeric(args.value, false), opts));
+		case "double": return fin(proc.writeDouble(addr, parseNumeric(args.value, false), opts));
+		case "pointer": return fin(proc.writePointer(addr, parseNumeric(args.value, true), opts));
+		default: throw fail("INVALID_ARGS", `unsupported write type "${args.type}"`);
+	}
+}
+function serializeHit(h) {
+	return {
+		addr: hex(h.addr),
+		value: jsonSafe(h.value)
+	};
+}
+function parseHits(raw, type) {
+	if (!Array.isArray(raw)) throw fail("INVALID_ARGS", "hits must be an array of {addr,value}");
+	const wide = WIDE_TYPES.has(type);
+	return raw.map((h, i) => {
+		if (typeof h !== "object" || h === null) throw fail("INVALID_ARGS", `hits[${i}] must be {addr,value}`);
+		const rec = h;
+		let addr;
+		try {
+			addr = BigInt(rec.addr);
+		} catch {
+			throw fail("INVALID_ARGS", `hits[${i}].addr is not an address`);
+		}
+		let value;
+		if (wide) try {
+			value = BigInt(rec.value);
+		} catch {
+			throw fail("INVALID_ARGS", `hits[${i}].value is not an integer`);
+		}
+		else {
+			value = Number(rec.value);
+			if (!Number.isFinite(value)) throw fail("INVALID_ARGS", `hits[${i}].value is not a number`);
+		}
+		return {
+			addr,
+			value
+		};
+	});
+}
+const sessionArg = { session: z.string().describe("session handle from proc_open") };
+const addrArg = z.union([z.string(), z.number()]).describe("address: \"0x...\" hex, decimal, or \"module+rva\"");
+const typeArg = z.string().describe("i8 u8 i16 u16 i32 u32 i64 u64 f32 f64 ptr str wstr bytes[:N]");
+const toolDefs = {
+	proc_list: {
+		description: "List running processes as {pid,name}[]",
+		schema: {},
+		handler: () => Process.list()
+	},
+	proc_open: {
+		description: "Open a process and return a session handle plus a describe() snapshot. access:\"ro\" opens read-only.",
+		schema: {
+			pid: z.number().int().optional().describe("process id (use pid OR name)"),
+			name: z.string().optional().describe("process name e.g. \"victim.exe\""),
+			access: z.enum(["rw", "ro"]).optional().describe("\"ro\" = openReadOnly")
+		},
+		handler: (s, a) => {
+			if (a.pid === void 0 && a.name === void 0) throw fail("INVALID_ARGS", "proc_open needs pid or name");
+			const target = a.pid !== void 0 ? a.pid : a.name;
+			const session = s.open(target, a.access);
+			return {
+				session,
+				describe: s.get(session).describe()
+			};
+		}
+	},
+	proc_close: {
+		description: "Close a session and release its process handle",
+		schema: sessionArg,
+		handler: (s, a) => {
+			s.close(a.session);
+			return { closed: true };
+		}
+	},
+	mem_describe: {
+		description: "Machine-readable snapshot of the target: pid, arch, modules, writable/executable regions, threads",
+		schema: sessionArg,
+		handler: (s, a) => s.get(a.session).describe()
+	},
+	mem_read: {
+		description: "Read a typed value. Integers/pointers come back as hex strings, floats as numbers, str/wstr as strings, bytes as hex.",
+		schema: {
+			...sessionArg,
+			addr: addrArg,
+			type: typeArg,
+			len: z.number().int().positive().optional().describe("byte/char count for bytes/str/wstr")
+		},
+		handler: (s, a) => {
+			const proc = s.get(a.session);
+			const addr = parseAddress(proc, a.addr);
+			return {
+				addr: hex(addr),
+				value: readTyped(proc, addr, a)
+			};
+		}
+	},
+	mem_write: {
+		description: "Write a typed value (journaled -- reversible via mem_undo). dryRun:true returns {addr,current,would,bytes} WITHOUT writing.",
+		schema: {
+			...sessionArg,
+			addr: addrArg,
+			type: typeArg,
+			value: z.union([
+				z.string(),
+				z.number(),
+				z.array(z.number())
+			]).describe("value (hex/dec strings ok; bytes takes hex string or byte array)"),
+			dryRun: z.boolean().optional().describe("preview only, do not write")
+		},
+		destructive: true,
+		handler: (s, a) => {
+			const proc = s.get(a.session);
+			const r = writeTyped(proc, parseAddress(proc, a.addr), a);
+			return r === true ? { written: true } : { preview: r };
+		}
+	},
+	mem_scan: {
+		description: "CE-style value scan: find all occurrences of `value` in committed (writable by default) memory. Returns {hits:[{addr,value}],count,truncated}.",
+		schema: {
+			...sessionArg,
+			value: z.union([z.string(), z.number()]).describe("value to find"),
+			type: z.string().optional().describe("i32 u32 i64 u64 f32 f64 (default i32)"),
+			module: z.string().optional().describe("restrict to a module"),
+			start: addrArg.optional().describe("range start"),
+			end: addrArg.optional().describe("range end"),
+			onlyWritable: z.boolean().optional(),
+			limit: z.number().int().positive().optional().describe("max hits returned (default 1000)")
+		},
+		handler: async (s, a) => {
+			const proc = s.get(a.session);
+			const type = normType(a.type ?? "i32");
+			if (!SCAN_TYPES.has(type)) throw fail("INVALID_ARGS", `mem_scan type must be a scan type, got "${a.type ?? "i32"}"`);
+			const value = parseNumeric(a.value, WIDE_TYPES.has(type));
+			const hits = await proc.scanValue(value, {
+				type,
+				module: a.module,
+				start: a.start !== void 0 ? parseAddress(proc, a.start, "start") : void 0,
+				end: a.end !== void 0 ? parseAddress(proc, a.end, "end") : void 0,
+				onlyWritable: a.onlyWritable
+			});
+			const limit = a.limit ?? 1e3;
+			return {
+				count: hits.length,
+				truncated: hits.length > limit,
+				hits: hits.slice(0, limit).map(serializeHit)
+			};
+		}
+	},
+	mem_scan_next: {
+		description: "Refine a previous mem_scan hit list (CE \"next scan\"). mode: exact|changed|unchanged|increased|decreased|increasedBy|decreasedBy|between; relative modes compare against each hit's stored value.",
+		schema: {
+			...sessionArg,
+			hits: z.array(z.object({
+				addr: z.union([z.string(), z.number()]),
+				value: z.union([z.string(), z.number()])
+			})).describe("hits from mem_scan / a previous mem_scan_next"),
+			mode: z.enum([
+				"exact",
+				"changed",
+				"unchanged",
+				"increased",
+				"decreased",
+				"increasedBy",
+				"decreasedBy",
+				"between"
+			]).describe("refine mode"),
+			value: z.union([z.string(), z.number()]).optional().describe("target for exact/increasedBy/decreasedBy"),
+			lo: z.union([z.string(), z.number()]).optional().describe("between low"),
+			hi: z.union([z.string(), z.number()]).optional().describe("between high"),
+			type: z.string().optional().describe("same type as the original scan"),
+			limit: z.number().int().positive().optional()
+		},
+		handler: async (s, a) => {
+			const proc = s.get(a.session);
+			const type = normType(a.type ?? "i32");
+			if (!SCAN_TYPES.has(type)) throw fail("INVALID_ARGS", `mem_scan_next type must be a scan type`);
+			const wide = WIDE_TYPES.has(type);
+			const mode = a.mode;
+			let m;
+			switch (mode) {
+				case "exact":
+					m = {
+						type: "exact",
+						value: parseNumeric(a.value, wide)
+					};
+					break;
+				case "increasedBy":
+				case "decreasedBy":
+					m = {
+						type: mode,
+						value: parseNumeric(a.value, wide)
+					};
+					break;
+				case "between":
+					m = {
+						type: "between",
+						lo: parseNumeric(a.lo, wide, "lo"),
+						hi: parseNumeric(a.hi, wide, "hi")
+					};
+					break;
+				case "changed":
+				case "unchanged":
+				case "increased":
+				case "decreased":
+					m = { type: mode };
+					break;
+				default: throw fail("INVALID_ARGS", `unknown mode "${mode}"`);
+			}
+			const hits = await proc.nextScan(parseHits(a.hits, type), m, { type });
+			const limit = a.limit ?? 1e3;
+			return {
+				count: hits.length,
+				truncated: hits.length > limit,
+				hits: hits.slice(0, limit).map(serializeHit)
+			};
+		}
+	},
+	mem_scan_pattern: {
+		description: "AOB signature scan: find all matches of a byte pattern like \"48 8B ?? 10\" (\"??\" wildcards). Returns {hits:[hexaddr],count,truncated}.",
+		schema: {
+			...sessionArg,
+			pattern: z.string().describe("byte pattern, hex bytes separated by spaces, \"??\" wildcards"),
+			module: z.string().optional().describe("restrict to a module"),
+			section: z.string().optional().describe("restrict to a PE section of `module` (e.g. \".text\")"),
+			start: addrArg.optional().describe("range start"),
+			end: addrArg.optional().describe("range end"),
+			onlyReadable: z.boolean().optional().describe("only scan readable regions (default true)"),
+			limit: z.number().int().positive().optional().describe("max hits returned (default 1000)")
+		},
+		handler: async (s, a) => {
+			const proc = s.get(a.session);
+			if (typeof a.pattern !== "string" || !a.pattern.trim()) throw fail("INVALID_ARGS", "mem_scan_pattern needs a pattern string");
+			const hits = await proc.scan(a.pattern, {
+				module: a.module,
+				section: a.section,
+				start: a.start !== void 0 ? parseAddress(proc, a.start, "start") : void 0,
+				end: a.end !== void 0 ? parseAddress(proc, a.end, "end") : void 0,
+				onlyReadable: a.onlyReadable
+			});
+			const limit = a.limit ?? 1e3;
+			return {
+				count: hits.length,
+				truncated: hits.length > limit,
+				hits: hits.slice(0, limit).map((h) => hex(h))
+			};
+		}
+	},
+	mem_regions: {
+		description: "VirtualQueryEx map of the target's memory regions: [{base,size,protect,state,type}] -- base/size are hex, protect/state/type are hex flag values. writableOnly/executableOnly filter on protection.",
+		schema: {
+			...sessionArg,
+			writableOnly: z.boolean().optional().describe("only regions whose protection allows writes"),
+			executableOnly: z.boolean().optional().describe("only regions whose protection allows execution")
+		},
+		handler: (s, a) => {
+			const proc = s.get(a.session);
+			const WRITABLE = 204;
+			const EXECUTABLE = 240;
+			let regions = proc.regions();
+			if (a.writableOnly === true) regions = regions.filter((r) => (r.protection & WRITABLE) !== 0);
+			if (a.executableOnly === true) regions = regions.filter((r) => (r.protection & EXECUTABLE) !== 0);
+			return {
+				count: regions.length,
+				regions: regions.map((r) => ({
+					base: hex(r.baseAddress),
+					size: hex(r.size),
+					protect: hex(r.protection),
+					state: hex(4096),
+					type: hex(r.type)
+				}))
+			};
+		}
+	},
+	mem_pointer_resolve: {
+		description: "Resolve module+rva plus a pointer chain: base = module base + rva, then dereference each offset (CE \"module.exe+RVA, offsets\" style).",
+		schema: {
+			...sessionArg,
+			module: z.string().describe("module basename e.g. \"victim.exe\""),
+			rva: z.union([z.string(), z.number()]).describe("offset from module base (hex ok)"),
+			offsets: z.array(z.union([z.string(), z.number()])).describe("pointer-chain offsets; all but the last dereference")
+		},
+		handler: (s, a) => {
+			const proc = s.get(a.session);
+			const mod = proc.module(a.module);
+			if (!mod) throw fail("MODULE_NOT_FOUND", `module not found: ${a.module}`);
+			let rva;
+			try {
+				rva = BigInt(a.rva);
+			} catch {
+				throw fail("INVALID_ARGS", `bad rva "${a.rva}"`);
+			}
+			const offsets = a.offsets.map((o, i) => {
+				const n = typeof o === "string" ? Number(BigInt(o)) : Number(o);
+				if (!Number.isFinite(n)) throw fail("INVALID_ARGS", `offsets[${i}] invalid`);
+				return n;
+			});
+			const base = BigInt(mod.base) + rva;
+			const addr = offsets.length === 0 ? base : proc.resolvePointer(base, offsets);
+			return {
+				base: hex(base),
+				addr: hex(addr)
+			};
+		}
+	},
+	mem_watch: {
+		description: "Poll an i32 at addr every ms (default 50); changes are recorded and drained by mem_watch_poll.",
+		schema: {
+			...sessionArg,
+			addr: addrArg,
+			ms: z.number().int().positive().optional().describe("poll interval ms")
+		},
+		handler: (s, a) => {
+			const proc = s.get(a.session);
+			const addr = parseAddress(proc, a.addr);
+			const events = [];
+			const stop = proc.watch(addr, (v) => events.push({
+				value: v,
+				ts: Date.now()
+			}), a.ms ?? 50);
+			return { watchId: s.addWatch(a.session, {
+				events,
+				stop
+			}) };
+		}
+	},
+	mem_watch_poll: {
+		description: "Drain the recorded changes for a watchId: returns [{value,ts}] since the last poll.",
+		schema: { watchId: z.string() },
+		handler: (s, a) => {
+			const w = s.getWatch(a.watchId);
+			const events = w.events;
+			w.events = [];
+			return {
+				events,
+				count: events.length
+			};
+		}
+	},
+	mem_unwatch: {
+		description: "Stop a watch created by mem_watch",
+		schema: { watchId: z.string() },
+		handler: (s, a) => {
+			s.removeWatch(a.watchId);
+			return { stopped: true };
+		}
+	},
+	mem_freeze: {
+		description: "Freeze a value: rewrites `value` at addr every ms (default 50) until mem_unfreeze.",
+		schema: {
+			...sessionArg,
+			addr: addrArg,
+			type: z.string().describe("i8 u8 i16 u16 i32 u32 i64 u64 f32 f64 ptr"),
+			value: z.union([z.string(), z.number()]),
+			ms: z.number().int().positive().optional()
+		},
+		destructive: true,
+		handler: (s, a) => {
+			const proc = s.get(a.session);
+			const addr = parseAddress(proc, a.addr);
+			const type = normType(a.type);
+			if (type === "str" || type === "wstr" || type === "bytes") throw fail("INVALID_ARGS", `freeze needs a numeric type, got "${a.type}"`);
+			const ms = a.ms ?? 50;
+			let stop;
+			if (type === "int8" || type === "uint8" || type === "int16" || type === "uint16") {
+				const v = Number(parseNumeric(a.value, false));
+				const write = type === "int8" || type === "uint8" ? () => proc.writeUInt8(addr, v & 255) : () => proc.writeUInt16(addr, v & 65535);
+				const timer = setInterval(() => {
+					try {
+						write();
+					} catch {}
+				}, ms);
+				if (typeof timer.unref === "function") timer.unref();
+				stop = () => clearInterval(timer);
+			} else stop = proc.freeze(addr, type, parseNumeric(a.value, WIDE_TYPES.has(type)), ms);
+			return { freezeId: s.addFreeze(a.session, stop) };
+		}
+	},
+	mem_unfreeze: {
+		description: "Stop a freeze created by mem_freeze",
+		schema: { freezeId: z.string() },
+		handler: (s, a) => {
+			s.removeFreeze(a.freezeId);
+			return { stopped: true };
+		}
+	},
+	mem_undo: {
+		description: "Revert the last n journaled writes (default 1), most-recent first -- the self-correction primitive.",
+		schema: {
+			...sessionArg,
+			n: z.number().int().positive().optional()
+		},
+		destructive: true,
+		handler: (s, a) => {
+			return { reverted: s.get(a.session).undo(a.n ?? 1) };
+		}
+	},
+	mem_journal: {
+		description: "Snapshot of the write journal for this session: [{index,addr,bytes|null}] -- bytes is the pre-write hex that undo() restores.",
+		schema: sessionArg,
+		handler: (s, a) => s.get(a.session).writeLog
+	},
+	eval_js: {
+		description: "Escape hatch: run JS with the bound Process in scope as `proc`. Code is wrapped in an async body -- use `return` for a result, `await` is allowed.",
+		schema: {
+			...sessionArg,
+			code: z.string().describe("JS body; `proc` is the open Process")
+		},
+		destructive: true,
+		handler: async (s, a) => {
+			const proc = s.get(a.session);
+			if (typeof a.code !== "string" || !a.code) throw fail("INVALID_ARGS", "eval_js needs a code string");
+			try {
+				return { result: await new Function("proc", "Process", `return (async () => { ${a.code} })()`)(proc, Process) };
+			} catch (e) {
+				const err = e;
+				throw fail(err?.code ?? "EVAL_ERROR", err?.message ?? String(e));
+			}
+		}
+	}
+};
+const TOOL_DEFS = toolDefs;
+function toolNames(opts = {}) {
+	const evalEnabled = opts.evalEnabled ?? true;
+	return Object.keys(toolDefs).filter((n) => evalEnabled || n !== "eval_js");
+}
+/** Direct dispatcher used by both the stdio server and the tests. */
+async function callTool(sessions, name, args, opts = {}) {
+	try {
+		const evalEnabled = opts.evalEnabled ?? true;
+		const def = toolDefs[name];
+		if (!def || name === "eval_js" && !evalEnabled) throw fail("UNKNOWN_TOOL", `unknown tool "${name}"`);
+		const parsed = z.object(def.schema).safeParse(args ?? {});
+		if (!parsed.success) {
+			const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+			throw fail("INVALID_ARGS", msg);
+		}
+		return {
+			ok: true,
+			data: jsonSafe(await def.handler(sessions, parsed.data))
+		};
+	} catch (e) {
+		return errorEnvelope(e);
+	}
+}
+// src/server.ts
+/**
+* @memoryprocess/mcp -- MCP server exposing the memoryprocess toolkit to
+* LLM agents over stdio (the primary agentic surface).
+*
+* Usage:
+*   memoryprocess-mcp              # serve MCP over stdio
+*   memoryprocess-mcp --no-eval    # omit the eval_js tool (restricted mode)
+*   memoryprocess-mcp --help       # list tools + exit
+*   memoryprocess-mcp --version
+*
+* Env: MEMP_NO_EVAL=1 is equivalent to --no-eval.
+*/
+const dir = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(dir, "..", "package.json"), "utf8"));
+const argv = process.argv.slice(2);
+const evalEnabled = !argv.includes("--no-eval") && process.env.MEMP_NO_EVAL !== "1";
+if (argv.includes("--version") || argv.includes("-v")) {
+	console.log(`${pkg.name} ${pkg.version}`);
+	process.exit(0);
+}
+if (argv.includes("--help") || argv.includes("-h")) {
+	console.log(`${pkg.name} ${pkg.version}`);
+	console.log("MCP server exposing the memoryprocess toolkit to LLM agents (stdio).");
+	console.log("");
+	console.log("Usage: memoryprocess-mcp [--no-eval] [--help] [--version]");
+	console.log("       MEMP_NO_EVAL=1 is equivalent to --no-eval");
+	console.log("");
+	console.log("Session model: proc_open returns a handle; every mem_* tool");
+	console.log("takes it as `session`. Writes are journaled (mem_journal) and");
+	console.log("reversible (mem_undo); mem_write supports dryRun previews.");
+	console.log("");
+	console.log("Tools:");
+	const names = toolNames({ evalEnabled });
+	const width = Math.max(...names.map((n) => n.length));
+	for (const n of names) {
+		const def = TOOL_DEFS[n];
+		console.log(`  ${n.padEnd(width)}  ${def.description}`);
+	}
+	if (!evalEnabled) console.log("\n(eval_js is disabled by --no-eval / MEMP_NO_EVAL=1)");
+	process.exit(0);
+}
+const sessions = createSessions();
+const server = new McpServer({
+	name: pkg.name,
+	version: pkg.version
+}, { instructions: "Process-memory toolkit. proc_open a target to get a session handle; all mem_* tools take it. Writes are journaled: mem_write with dryRun:true previews, mem_undo reverts. Prefer the coarse tools; eval_js is the escape hatch for anything else." });
+for (const name of toolNames({ evalEnabled })) {
+	const def = TOOL_DEFS[name];
+	server.registerTool(name, {
+		description: def.description,
+		inputSchema: def.schema,
+		annotations: {
+			readOnlyHint: !def.destructive,
+			destructiveHint: def.destructive === true
+		}
+	}, async (args) => {
+		const result = await callTool(sessions, name, args, { evalEnabled });
+		const data = result.ok === true ? result.data !== null && typeof result.data === "object" && !Array.isArray(result.data) ? result.data : { result: result.data } : void 0;
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(result)
+			}],
+			structuredContent: data,
+			isError: result.ok !== true
+		};
+	});
+}
+const shutdown = () => {
+	try {
+		sessions.closeAll();
+	} finally {
+		process.exit(0);
+	}
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`${pkg.name} ${pkg.version} ready on stdio (${toolNames({ evalEnabled }).length} tools${evalEnabled ? "" : ", eval_js disabled"})\n`);
+export {};

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@memoryprocess/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.3-beta.1",
+  "description": "MCP server exposing the memoryprocess toolkit to LLM agents — the primary agentic surface.",
+  "type": "module",
+  "packageManager": "bun@1.4.4",
+  "bin": {
+    "memoryprocess-mcp": "./dist/server.mjs"
+  },
+  "exports": {
+    ".": "./dist/server.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "os": [
+    "win32"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "bun check",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memoryprocess/memoryprocess.git",
+    "directory": "packages/mcp"
+  },
+  "author": "JoShMiQueL",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "process",
+    "windows",
+    "reverse-engineering",
+    "llm",
+    "agent"
+  ],
+  "dependencies": {
+    "@memoryprocess/core": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.4"
+  }
+}