# vConsole MCP

[English](./README.md) | [简体中文](./README_CN.md)

> **注意事项：** vConsole 官方不提供 MCP 链接能力，请使用 [https://github.com/Simonmie/vConsole/tree/dev](https://github.com/Simonmie/vConsole/tree/dev) 中的代码尝试。
>
> **Note:** Official vConsole does not provide MCP connectivity. To try this integration, use the code from the linked `dev` branch above.

Expose console logs, network requests, and explicitly authorized JavaScript execution from a mobile H5 page to MCP clients such as Codex and Claude Code.

```mermaid
flowchart LR
    Agent["Codex / Claude Code"] <-->|"MCP stdio"| MCP["vconsole-mcp"]
    MCP <-->|"WebSocket :8765"| Mobile["Mobile H5 + vConsole"]
    Mobile --> Data["Console / Network stores"]
```

Records stay in the mobile page and are read on demand; the MCP process does not need a database or cloud service.

## Development

```bash
pnpm install
pnpm build
node dist/index.js
```

The process uses stdio for MCP and listens for mobile WebSocket connections on `0.0.0.0:8765` by default. Startup messages are written to stderr so the MCP transport remains valid.

Options can be passed as arguments or environment variables:

```bash
node dist/index.js --host 0.0.0.0 --port 8765
VCONSOLE_MCP_HOST=0.0.0.0 VCONSOLE_MCP_PORT=8765 node dist/index.js
```

An optional pairing token prevents other pages from registering with the local bridge:

```bash
node dist/index.js --token your-development-token
VCONSOLE_MCP_TOKEN=your-development-token node dist/index.js
```

## Install in an MCP client

Build the project first, then register the absolute entry path.

```bash
codex mcp add vconsole -- node /Users/jiangkexian/Desktop/MCP/vConsole-MCP/dist/index.js
claude mcp add vconsole -- node /Users/jiangkexian/Desktop/MCP/vConsole-MCP/dist/index.js
```

With a pairing token, pass the same value to the MCP process and the mobile page:

```bash
codex mcp add vconsole --env VCONSOLE_MCP_TOKEN=your-development-token -- node /Users/jiangkexian/Desktop/MCP/vConsole-MCP/dist/index.js
```

After publishing the package, clients can use:

```bash
codex mcp add vconsole -- npx -y vconsole-mcp
claude mcp add vconsole -- npx -y vconsole-mcp
```

Only one MCP process can listen on port `8765` at a time. Run either Codex or Claude Code, or assign different ports when using both concurrently.

## Tools

- `list_pages`: list connected mobile pages.
- `get_console_logs`: read recent console records with optional level filtering.
- `get_network_requests`: read recent network records with optional failure, URL, body, and limit filters.
- `execute_javascript`: execute up to 100,000 characters of JavaScript in the page selected by its required `pageId` through `runtime.evaluate`. It requires explicit authorization from the mobile user in vConsole before the code runs. Arbitrary code may mutate page state or storage, expose sensitive data, and send network requests. The optional `timeout` is between 100 and 30,000 milliseconds and defaults to 8,000.

For the read tools, `pageId` is optional when one page is connected. `execute_javascript` always requires a `pageId`; call `list_pages` first to select the intended target.

The first three tools are read-only. `execute_javascript` is marked non-read-only, potentially destructive, non-idempotent, and open-world because arbitrary page code can change application state and communicate with external systems. It is the only execution capability exposed by this MCP package; no separate DOM, click, input, storage, or clear tools are provided.

## Mobile connection

Initialize the forked vConsole with an endpoint:

```js
const vConsole = new VConsole({
  mcp: {
    endpoint: 'ws://192.168.1.100:8765',
    token: 'your-development-token',
    autoConnect: true,
    allowJavaScriptExecution: false,
  },
});
```

Or connect later:

```js
vConsole.mcp.connect('ws://192.168.1.100:8765');
```

JavaScript execution is denied by default. Enable `Allow JavaScript Execution` in the vConsole MCP panel for the current page. The panel permission resets after a page reload; trusted automated test pages may instead initialize vConsole with `allowJavaScriptExecution: true`.

Use the computer's LAN IP instead of `localhost`, keep the phone and computer on the same network, and allow the Node.js process through the computer firewall when prompted. This initial version is intended for trusted development networks and keeps all captured data in the mobile page. For an HTTPS H5 page, put the WebSocket endpoint behind a trusted WSS reverse proxy or relay; browsers block an HTTPS page from opening `ws://` mixed content.