get_session_messages

Retrieve and clear messages from persistent scripts in a Frida session to monitor runtime behavior and capture script output during dynamic instrumentation.

Instructions

Retrieve and clear messages sent by persistent scripts in a session.

Returns:
    A list of messages captured since the last call, or an error if the session is not found.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`session_id`	Yes	The ID of the session to retrieve messages from.

Implementation Reference

src/frida_mcp/cli.py:725-769 (handler)

The core handler function for the 'get_session_messages' tool, including registration via @mcp.tool(), input schema definition with Pydantic Field, and the logic to retrieve and clear session messages from global storage.

@mcp.tool()
def get_session_messages(
    session_id: str = Field(
        description="The ID of the session to retrieve messages from."
    ),
) -> Dict[str, Any]:
    """Retrieve and clear messages sent by persistent scripts in a session.

    Returns:
        A list of messages captured since the last call, or an error if the session is not found.
    """
    if session_id not in _scripts:
        # Check if it was a session that had persistent scripts but might have been cleared or detached
        if (
            session_id in global_persistent_scripts
            and not global_persistent_scripts[session_id]
        ):
            return {
                "status": "success",
                "messages": [],
                "info": "Session had persistent scripts that might be finished or detached.",
            }
        raise ValueError(
            f"Session with ID {session_id} not found or no persistent scripts active."
        )

    if session_id not in _message_locks or session_id not in _script_messages:
        # This case should ideally not happen if session_id is in _scripts from create_interactive_session
        return {
            "status": "error",
            "error": f"Message queue or lock not found for session {session_id}.",
        }

    lock = _message_locks[session_id]
    with lock:
        messages = list(_script_messages[session_id])  # Make a copy
        _script_messages[session_id].clear()  # Clear the queue

    return {
        "status": "success",
        "session_id": session_id,
        "messages_retrieved": len(messages),
        "messages": messages,
    }

src/frida_mcp/cli.py:77-82 (helper)

Global dictionaries that store session scripts, message queues, thread locks, and persistent scripts, essential for the get_session_messages tool to function.

# Global dictionary to store scripts and their messages
# This allows us to retrieve messages from scripts after they've been created
_scripts = {}
_script_messages = {}
_message_locks = {}
global_persistent_scripts = {}  # Added for managing persistent scripts

Frida MCP