# vencord-mcp

An MCP server that lets a coding agent read a running Discord client the way a plugin author
reads it: stores, webpack modules, patches, React props, and the gateway traffic itself.

It talks to any Chromium started with `--remote-debugging-port`, so it works on Discord with
Vencord or Equicord injected, and most of it works on any Electron app with a minified
webpack bundle.

## Why this exists

Two halves of this already existed separately, and neither was useful on its own.

There are several generic Electron and Chrome DevTools MCP servers. They take screenshots,
read the console, and evaluate JavaScript, but they know nothing about webpack, Flux stores,
or Vencord patches, so an agent using them spends its budget rediscovering the same
boilerplate every session.

On the other side, [Vencord Companion](https://github.com/Vencord/Companion) knows exactly
the right things: whether a webpack find is unique, whether a patch's match compiles. But it
is a VSCode extension, built for a human reading it in an editor.

Nothing connected the two. This does.

## What it changes

The normal loop for writing a plugin is: open devtools, hunt through a minified bundle,
write a regex and hope, compile, restart Discord, find out. Each mistake costs a restart.

With these tools the loop closes in seconds, and more importantly the agent stops guessing.
`test_patch` answers "would this patch actually run" before anything is built.
`capture_websocket` shows what the server really sent instead of what the interface implied.
`react_props` recovers the name of a failure whose UI only shows a number.

## Install

```bash
npm install
```

Register it with your MCP client. Most of them take a config block like this:

```json
{
  "mcpServers": {
    "vencord": {
      "command": "node",
      "args": ["/absolute/path/to/vencord-mcp/src/index.js"]
    }
  }
}
```

Clients that ship a CLI usually have a one-liner for the same thing, along the
lines of `mcp add vencord -- node /absolute/path/to/vencord-mcp/src/index.js`.

Then start Discord with the debugger open:

```
Discord.exe --remote-debugging-port=9223
```

The port only listens on localhost, but it is a debugger: anything that can reach it can read
your session. Close and reopen Discord normally when you are done.

## Tools

Read-only unless marked otherwise.

| Tool | What it answers |
|---|---|
| `targets` | Is the client reachable, and which page do I attach to |
| `plugins` | Which plugins are enabled, started, patched, and which have a native side |
| `patch_status` | Which patches never found their module and are doing nothing |
| `test_patch` | Is the find unique, does the match hit, how many times, what does the replacement produce |
| `list_stores` | What state exists at all |
| `describe_store` | What does this store know, and what do its getters return right now |
| `read_store` | Call one method with arguments |
| `find_module` | Find a module by exported props or by the code it contains |
| `search_modules` | Search every module source, with the module ids and surrounding code |
| `react_props` | Walk up from a DOM node and read the props holding an error or state |
| `experiment` | What did the server assign this account for an experiment |
| `capture_websocket` | Record gateway and voice frames, decoded, heartbeats dropped |
| `capture_console` | Record console output, optionally reloading first to catch startup |
| `read_settings` | Plugin settings as the running client sees them |
| `write_setting` | **Writes.** Change one setting through Vencord's own proxy |
| `dispatch` | **Writes.** Send a Flux action, for behaviour with no exported method |
| `reload` | **Writes.** Reload the renderer, the same as Ctrl+R |
| `evaluate` | Escape hatch for anything above not covered |

Every tool takes `port` (default 9223) and an optional `urlHint` for when more than one page
target is open.

## The three that are worth the install

**`test_patch`** runs the same check Vencord runs at startup, against the build that is
actually running. A find that matches no module means the patch silently never runs, and a
find that matches several means Vencord patches all of them. Both are invisible until the
plugin misbehaves in a way that looks like something else.

```
test_patch(find: '"2026-08-video-guard"', match: 'variations:\\{.{0,120}?\\}\\}', replace: 'variations:{}')
-> "find is unique and match hits exactly once"
```

**`patch_status`** answers the question `test_patch` cannot: did it actually run. Vencord drops
a patch from its pending list once its module loads, so anything still listed never matched.
That is the failure that costs the most time, because the plugin loads, reports no error, and
quietly does nothing. Patches declared `all` stay listed forever by design and are reported
separately so they do not read as broken.

**`capture_websocket`** decodes Discord's voice opcodes by name: `IDENTIFY`, `READY`,
`SESSION_DESCRIPTION`, `VIDEO`, `MEDIA_SINK_WANTS`. Reading them is the difference between
"the video did not appear" and "the server offered ssrc 267, the client asked for it at full
quality, and no packets followed", which are different bugs with different fixes.

One caveat: the Network domain only records sockets it saw being created. A connection that
was already open when the capture started is reported as
`(socket opened before capture)` — the frames are still decoded, because their content
identifies the protocol, but the URL is unknown. Make the client reconnect during the window
to get it.

## Notes

Discord ships a strict CSP that blocks `eval`. Every evaluation here sets
`allowUnsafeEvalBlockedByCSP`, which is the documented way for a debugger to run anyway;
without it every call fails with an unhelpful `EvalError`.

Each tool call opens its own debugger session and hangs up. Holding one open between calls
would only create state to get out of sync.

## Tests

```bash
node test/smoke.js
```

It speaks the real protocol to the real server over stdio: initialize, list the tools, then
exercise the live path against a Discord on port 9223 if one is running. A server that starts
is not the same as a server that answers.

## License

GPL-3.0-or-later, matching Vencord.