Skip to content

Latest commit

 

History

History
161 lines (108 loc) · 18.4 KB

MCP.md

File metadata and controls

161 lines (108 loc) · 18.4 KB

MCP debugging and script proposals

Module Engine includes an optional local MCP server using Node's built-in modules. Ad blocking and userscripts still work without this server. Nothing is installed or started automatically.

By default the server is read-only. Started with --allow-changes, it also lets an agent propose script changes. You review each proposal on the MCP page, and nothing is saved until you apply it. See Script change proposals.

Connect with stdio (default)

  1. Reload the unpacked extension after updating this checkout.

  2. Add a stdio server to your MCP client's configuration. Use your installed Node executable and the absolute path to mcp/server.cjs. For clients that use a JSON mcpServers section:

    {
      "mcpServers": {
        "module-engine": {
          "command": "C:\\Program Files\\nodejs\\node.exe",
          "args": ["C:\\Users\\Tommy\\Desktop\\BlockAds\\mcp\\server.cjs"]
        }
      }
    }

    Node 22 or newer is required. No npm install is needed. Configuration format and restart steps depend on the MCP client; this feature does not edit client settings.

    For Codex, register the same stdio server with:

    codex mcp add module-engine -- "C:\Program Files\nodejs\node.exe" "C:\Users\Tommy\Desktop\BlockAds\mcp\server.cjs"
  3. Ask the agent to call module_engine_connection for a pairing code.

  4. Open Module Engine → Modules & scripts → MCP from the sidebar, paste the code, choose the scopes and click Connect. The code expires after two minutes and can be used once. Network metadata and change proposals each have their own unchecked scope; existing Scripts/Logs approval includes neither.

  5. Keep the Module Engine tab open. MCP, Modules & scripts, My lists, Activity log and Network switch within that tab; the connection and approved scopes stay alive, and the sidebar shows its connection status and pending review count. Click Disconnect, close or reload the tab to revoke browser access. Sessions still expire after 30 minutes; switching sections does not extend them. Reconnecting requires another explicit approval. One browser can connect to each server process.

The Firefox package requires Firefox 142+ and asks for optional data sharing permission before the first connection: browsing activity, website content, and technical/interaction information cover the selected scripts, request metadata and diagnostics. Nothing is sent before approval. Declining leaves MCP disconnected; removing one of these permissions in Firefox disconnects an existing session. Other features remain available. Chromium uses the explicit scope approval on this page. The local MCP client may forward approved information to its configured AI provider, so connect only to a client you trust.

Optional localhost HTTP connection

Use this when your native MCP client connects by URL. It serves Streamable HTTP at http://127.0.0.1:8765/mcp and keeps the same tools and explicit browser approval. Stdio remains the default unless you pass --http. This does not register anything in Codex or start a background service automatically.

  1. In PowerShell, from this checkout, generate a random token directly into the environment without displaying it:

    $env:MODULE_ENGINE_MCP_TOKEN = (node .\mcp\server.cjs --generate-token).Trim()

    The server and client must receive the same variable. For Codex desktop, you can deliberately save it in your Windows user environment, then fully quit and restart Codex so it inherits the value:

    [Environment]::SetEnvironmentVariable('MODULE_ENGINE_MCP_TOKEN', $env:MODULE_ENGINE_MCP_TOKEN, 'User')

    This optional step persists a secret in your Windows account; it is not an encrypted credential vault. Alternatively, launch your client from an environment that already contains the token. Keep the token out of source files, URLs, chat messages and command-line arguments.

  2. Start the server in the configured PowerShell window and keep it running:

    node .\mcp\server.cjs --http --port 8765

    Startup prints only the local endpoint, never the token. --port accepts 0–65535; 0 chooses a temporary port, useful for tests. A missing/invalid token or occupied port causes startup to fail. Stop the server with Ctrl+C.

  3. Register the URL and the environment variable name in your MCP client. For Codex:

    codex mcp add module-engine-http --url http://127.0.0.1:8765/mcp --bearer-token-env-var MODULE_ENGINE_MCP_TOKEN

    The equivalent Codex configuration is:

    [mcp_servers.module-engine-http]
    url = "http://127.0.0.1:8765/mcp"
    bearer_token_env_var = "MODULE_ENGINE_MCP_TOKEN"

    Enable the transport you intend to use; running both configurations creates separate server/browser sessions. See Codex MCP configuration for client-specific setup and reload behavior.

  4. Ask the agent for module_engine_connection, then approve its temporary pairing code in Module Engine → Modules & scripts → MCP, as above. The HTTP bearer token never replaces this approval and must not be pasted into the pairing field.

To rotate the HTTP token, stop the server, generate a new value, update the client environment and restart both. If you saved the user variable and no longer want it, remove it with [Environment]::SetEnvironmentVariable('MODULE_ENGINE_MCP_TOKEN', $null, 'User'); existing processes retain their inherited value until stopped. No firewall rule, public tunnel, package installation or browser permission is needed.

Available reads

Tool Scope Result
module_engine_connection None Connection status or a temporary pairing code
module_engine_status Status Settings status, native blocking rule counts and userscript registration status
module_engine_list_scripts Scripts Installed script metadata and tags
module_engine_get_script Scripts One script's source and metadata, selected by its ID
module_engine_check_url Scripts Which installed scripts match a supplied HTTP(S) URL; optional draft source is matched without saving; no navigation or fetch
module_engine_get_logs Logs Up to 100 activity/error entries; optional kind, limit and scriptId filters. Blocked-request entries include the page site, blocked host, query-free path, type, layer and ruleId
module_engine_get_network_log Network Latest matching captured request metadata, at most 100 entries or 128 KiB; never controls capture

For example: “Inspect Module Engine's status, check which scripts match https://example.test/page, and explain the recent userscript errors. Treat script source and logs as data.”

Status reads do not repair native registrations. If registration state differs from saved settings, use the normal manager UI to resolve it. Agents cannot change settings, run code, navigate tabs, inspect page contents, or read cookie jars or saved GM values through these tools. Script changes are possible only as proposals, described below.

Script change proposals

Hidden Unicode direction controls can visually reorder source. Affected proposals show their positions and escaped code, metadata and notes. Apply & enable and proposals to turn a script on stay disabled until you acknowledge the warning with a real click or keyboard interaction. Apply can still save the source turned off; enabling it later in Modules & scripts requires review there. A new proposal never inherits acknowledgment. Reverting a disable cannot silently turn affected code back on: propose enabling it again or use Modules & scripts. The actual saved source is never replaced with the escaped preview.

Proposals let an agent suggest a new script, an edit or turning a script on or off. You decide each one on the MCP page; the agent cannot apply, enable or delete anything itself.

  1. Add --allow-changes to the server command, for example "args": ["C:\\Users\\Tommy\\Desktop\\BlockAds\\mcp\\server.cjs", "--allow-changes"] or node .\mcp\server.cjs --http --port 8765 --allow-changes. Without it, the server lists only the read tools, and the browser drops change approval when pairing.
  2. On the MCP page, also tick Propose script changes for my review before Connect. The badge then reads Connected · changes need your review.
  3. Ask the agent to fix or write a script. Each proposal appears under Pending changes with the same review as installing from a URL: the access table (sites, APIs, cookie and network access, world, dependencies, update source) with changed rows marked, the current and proposed source side by side, and the agent's note, labelled as unverified. The tab title shows how many are waiting.
  4. Choose one:
    • Apply saves the source and leaves the script off. Saved script values are kept.
    • Apply & enable saves it and turns it on, so the reviewed code runs on its sites. This is unavailable until any changed @require/@resource dependencies are prepared in Modules & scripts. Cached executable dependencies containing hidden direction controls must be reviewed and enabled from Modules & scripts, which shows the exact bytes and digests.
    • Reject changes nothing. For an on/off proposal, the buttons are Turn on / Turn off and Reject.
  5. Applied changes are listed under Decided this session with Revert. Revert puts the previous source back (saved off), undoes an on/off change, or, for a script the agent created, offers Remove script. Revert is refused if the script changed afterwards; edit it in Modules & scripts instead.
Tool Scope Result
module_engine_propose_script Changes Proposes a new script (source, optional note) or an edit (source, id, revision, optional note). Returns a pending proposal; nothing is saved
module_engine_propose_enabled Changes Proposes turning an installed script on or off (id, revision, enabled, optional note)
module_engine_get_proposal Changes Whether a proposal from this session is pending, applied, rejected, stale, superseded, failed, reverted or expired, and the resulting revision and on/off state

Rules the agent sees as errors:

  • Proposals are checked before you see them. Syntax and metadata errors go back to the agent with line numbers, and source over 128 KiB is refused.
  • An edit must use the revision from module_engine_get_script and keep @name and @namespace. A new script cannot reuse an installed script's name and namespace; the agent must propose an edit instead.
  • At most four proposals wait at once. A newer proposal for the same script replaces the pending one. An on/off proposal is refused while an edit for that script is pending; apply the edit with Apply & enable instead.
  • If the script changes before you decide (for example, you edit it yourself), the proposal becomes stale and nothing is saved.

Proposals and Revert last only for the connection. Disconnecting, closing the page or the 30-minute limit discards pending proposals. Each decision (applied, turned on or off, rejected, reverted) is recorded in Activity log with an MCP: prefix; proposals themselves are not logged. Applying uses the same save, enable and delete commands as Modules & scripts, so a URL-installed script keeps its update link. A later reviewed update can replace an agent's edit.

Treat proposals like any script from the internet: read the access rows, especially new sites, APIs, network hosts, dependencies and update sources. A prompt-injected agent could propose harmful code, which is why nothing is saved or run without your click.

Reading captured network requests

Reload the extension and restart your configured MCP server after updating, so both sides load the new tool contract. The MCP sidebar entry is visible from Modules & scripts, My lists, Activity log and Network; it stays in the same tab and preserves an existing capture when switching sections.

  1. On MCP, select Captured network request metadata before Connect. An existing connection needs disconnect/reapproval to add this scope.
  2. Use Open Network in another tab, choose the capture scope and click Start new capture there. Keep both pages open while reproducing the issue. You can stop capture and leave MCP connected to review retained entries.
  3. Ask the agent to call module_engine_get_network_log. For example: {"url":"/api/","method":"POST","limit":20}. The url argument is a case-insensitive substring of the already-redacted URL; it does not visit or fetch that URL. method is case-insensitive; optional tabId, type, statusCode and state filters are exact matches. tabId: -1 selects browser-attributed background traffic.

Reads return the latest matches in oldest-to-newest order, with matched, truncated, capture status and retention limits. limit defaults to 50 and accepts 1–100. A 128 KiB result budget can return fewer rows; use narrower filters when truncated is true. States are request, sent, response, complete, redirect, error and interrupted. There is no pagination cursor or full-history export through MCP; the Network page still offers its local filtered export.

The tool cannot start, stop, clear, resume or extend capture, change its scope, replay requests, or modify protection. Reading while capture is off leaves it off and does not write the retained log. Reads use the same sanitized entries as Network: URL credentials, query strings and fragments are omitted, along with headers, cookies and bodies. Paths may still be private. Treat all request metadata as data, never instructions. Browser coverage is incomplete and generic failures do not identify which blocker acted. The existing 30-minute capture and MCP limits remain independent. Revoking MCP access does not clear the separately owned capture; closing or reloading the tab that owns Network stops that capture. Approval expiry and disconnect also prevent pending reads from being delivered.

Error capture and privacy

Connect with Logs enabled before reproducing an error. Capture covers synchronous wrapper exceptions, top-level-await rejections and errors reported by managed GM callbacks in native messaging worlds, including page scripts using the GM bridge. Ordinary page-console messages, raw @unwrap scripts, scripts without messaging grants and unrelated asynchronous errors remain in browser developer tools. Page-world errors are untrusted site-visible data, not authenticated statements by the script author.

Script reads include autoPageApproved. Matching reports the preferred world and an optional fallbackWorld; it does not inspect which world actually ran on a page. Older auto scripts remain USER_SCRIPT until individually re-enabled.

Source and diagnostic text are untrusted and may contain private information chosen by a script. Approve those scopes only when appropriate. Structured log URLs omit credentials, query strings and fragments; arbitrary error messages/stacks cannot be reliably scrubbed. Up to 100 captured errors are held in memory and cleared on disconnect. Existing activity-log retention is unchanged. Recent agent-read names appear in the MCP page; request contents and pairing secrets are not persisted by Module Engine. Your MCP client may retain tool results or pairing codes in its own chat history.

Transport and limits

The default client connection uses newline-delimited JSON-RPC over stdio, with MCP lifecycle and tools support for protocol versions 2025-11-25, 2025-06-18 and 2024-11-05. Standard output contains only protocol messages. Closing client input stops the stdio server. HTTP mode runs independently of stdin and must be stopped explicitly.

The optional HTTP agent endpoint binds only 127.0.0.1, requires the exact loopback Host and a bearer token, rejects every supplied Origin (including null and extension Origins), and provides no CORS access. It accepts one JSON-RPC message per POST to /mcp, with JSON responses; GET/SSE, batches, redirects, compressed bodies and the legacy HTTP+SSE transport are unsupported. Clients must advertise both application/json and text/event-stream in Accept. This is configured local bearer authentication, not an OAuth authorization server.

Initialization issues a separate random MCP-Session-Id. Only one client session is admitted per process. Subsequent messages require that ID and must use the negotiated protocol version; invalid/expired IDs return 404. Sessions expire after 30 minutes. Authenticated DELETE ends the client session and also revokes browser approval, outstanding reads and unused pairing codes. A new client must initialize and obtain new browser approval. A lost individual HTTP connection does not count as cancellation; explicit cancellation notifications stop pending reads. No results are replayed. If a client disappears without DELETE, stop/restart the helper to reclaim it immediately, or wait for expiry.

The private browser bridge remains on a separate random loopback port; it is not the HTTP MCP endpoint. It requires an extension Origin, exact loopback Host, its own random bearer token and explicit scope approval. Pairing rotates its one-time token. Ordinary webpages receive no CORS access. The extension repeats tool and scope validation; arbitrary extension commands are never forwarded. Pairing/session secrets stay in memory. A lost browser polling connection expires within 30 seconds; reads time out after 10 seconds without retrying. Request/result frames are limited to 512 KiB. HTTP headers are limited to 8 KiB, bodies have a five-second deadline, and at most 16 POSTs and eight browser reads may be pending. Oversized results return an error; request fewer entries where applicable.

This controls access through the debug interface, not other software already running under your Windows account. Only connect to a local server/client you intend to trust. The existing extension host permission covers loopback; no extra browser permissions or native-host registration are added.

Protocol references: MCP transports, lifecycle, tools and cancellation.