Plugin API reference

A plugin is a Python file activated under $MEMSCOPE_HOME/plugins/. It contributes Lua functions to the existing lua MCP tool. The supported public contract consists of PluginBase, LuaExtension, and ExtensionContext.

Imports

from memscope_mcp.extensions.base import ExtensionContext, LuaExtension
from memscope_mcp.plugins import PluginBase

PluginBase is a thin specialization of LuaExtension. A plugin implements name, description, instructions, and register(ctx).

Registration context

The registration callback receives a context bound to the current DebugSession and engine composition:

class ExamplePlugin(PluginBase):
    name = "example"
    description = "Small example helper"
    instructions = "## Example\nProvides exampleValue()."

    def register(self, ctx: ExtensionContext):
        session = ctx.session
        table = ctx.table_factory
        hook_manager = ctx.hook_manager

        def example_value():
            return table(attached=session.pm is not None)

        return {"exampleValue": example_value}

The supported context fields for plugin implementation are ctx.session, ctx.table_factory, and ctx.hook_manager. A plugin stores its state on self, checks manager/session identity when it uses hooks, and returns a complete mapping of Lua names to callables.

The raw Lua runtime is not a plugin interface. Do not use ctx.lua, ctx.engine.lua, ExtensionContext.lua, memscope_mcp.tools.hooking.HOOK_MANAGER, module-level SESSION, or module/session globals. table_factory is guarded and is valid only during engine-owned bootstrap or execution callbacks.

Function mappings

register returns a dict[str, callable]. Bootstrap validates the complete mapping before accepting any name. Duplicate Lua names, duplicate extension names, invalid names, non-callables, and lifecycle-name collisions isolate the ordinary plugin without publishing a partial mapping. A later plugin cannot replace an earlier accepted function.

Use ordinary Python values and tables from ctx.table_factory at the boundary. The Lua engine rejects executable Lua handles, userdata, threads, functions, and cyclic tables when converting results to MCP data.

Lifecycle

Optional callbacks are:

def on_process_attached(self, session): ...


def on_process_detaching(self, session, process_alive): ...

Attach callbacks run after a successful process attach or switch. Detach callbacks run before the process handle closes. process_alive indicates whether target-side cleanup can still run. Callback failures are isolated; plugin state must still reset on both live and already-exited detach paths.

Use the session passed to register and lifecycle callbacks. The retained DebugSession.modules property provides a defensive dictionary compatibility view; it does not permit write-through mutation of the immutable module snapshot. openProcess remains a supported Lua alias for attach-by-PID behavior.

Plugin metadata

name is the declared extension name. description is a short summary. instructions is appended to the server instruction bundle only when the plugin activates successfully. A plugin does not add an MCP tool.

Loading rules

The runtime scans only $MEMSCOPE_HOME/plugins/*.py, nonrecursively, in sorted filename order, excluding underscore-prefixed files. The loader instantiates the first PluginBase subclass it finds in each file. Bundled files under memscope_mcp/_contrib/plugins/ are catalog/install sources, not an automatic runtime root.

Earlier activated files win extension-name and Lua-function collisions. Import, metadata, construction, registration, and lifecycle failures are isolated for ordinary exceptions. Core failures and fatal composition failures quarantine the engine. See Extension composition and Plugin lifecycle.

Source and tests

View this page’s repository source