mcpdebug-plugin

mcpdebug-plugin

Repo-local plugin that manages a pinned local copy of mcp-debugger and exposes it as the only debugger MCP for this workspace.

What it does

• Uses debugmcp/mcp-debugger for Python and Node.js.
• Vendors a local mcp-debugger fork with a PHP adapter package.
• Uses xdebug/vscode-php-debug as the PHP DAP bridge.
• Keeps setup Python-managed through python3.14 scripts.

Install For Codex

Use the public installer:

curl -fsSL https://raw.githubusercontent.com/EdvinToome/mcpdebug-plugin/main/install.sh | bash

The installer prompts for:

• the Git repo URL
• the Git ref to install
• the local checkout directory
• the Codex plugins directory
• the Codex marketplace path
• the marketplace id and display name
• the python3.14 command

It will then:

• clone or update the repo locally
• symlink the plugin into your Codex plugins directory
• register it in your Codex marketplace file
• run the plugin bootstrap with python3.14

If you already have the repo checked out and only want the local Codex registration step, run:

python3 ./scripts/install.py

Install For Claude Code

This plugin now ships a Claude Code marketplace at marketplace.json and a Claude plugin manifest at plugin.json.

Use the public Claude installer:

curl -fsSL https://raw.githubusercontent.com/EdvinToome/mcpdebug-plugin/main/install-claude.sh | bash

It defaults to a global user install:

• marketplace source: EdvinToome/mcpdebug-plugin
• marketplace name: edvin-toome-plugins
• plugin name: mcpdebug-plugin
• scope: user

That installer:

• adds the marketplace to Claude Code
• installs or updates the plugin globally for your user
• finds Claude’s cached plugin copy
• runs bootstrap inside the cached plugin so the bundled MCP server actually works

If you only want to rebuild the local runtime, run:

python3.14 ./plugins/mcpdebug-plugin/scripts/bootstrap.py

Bootstrap will:

• create a plugin-local virtualenv under .runtime/py314
• build the vendored vscode-php-debug
• install and build the vendored mcp-debugger workspace
• print environment status for Node, PHP, npm/pnpm, and Xdebug

MCP entry

The plugin registers one server only:

• mcp-debugger

The .mcp.json entry launches scripts/launch_mcp_debugger.py, which in turn runs the built mcp-debugger CLI with the PHP adapter bridge path injected through environment variables.

Codex plugin source

This repo no longer ships a repo-local .agents/plugins/marketplace.json.

Install into Codex through your home marketplace file instead:

• ~/.agents/plugins/marketplace.json
• ~/plugins/mcpdebug-plugin

For Claude Code, the global scope is the right default here because this plugin is not project-specific. Claude’s user scope installs to ~/.claude/settings.json and makes the plugin available across projects.

PHP support

PHP support depends on:

• a built local copy of xdebug/vscode-php-debug
• a local PHP installation
• the Xdebug extension being installed for the PHP binary you want to debug

If Xdebug is missing, the PHP adapter returns setup-required errors instead of falling back to a degraded path.