### 2. Instalar dependencias de Python```bat
pip install pybag mcp

Reinicie Claude Desktop. Las 55 herramientas de depuración aparecerán automáticamente.

---

### Claude Code (CLI)

Ejecute el siguiente comando una vez para registrar el servidor. Claude Code almacena la entrada
en su propia configuración MCP y hace que las herramientas estén disponibles en cada sesión posterior.```bash
claude mcp add windbg-mcp python C:\path\to\windbg-mcp\windbg_mcp.py

Para eliminarlo después:```bash
claude mcp remove windbg-mcp

3. Guarda y reinicia Cowork. Las herramientas estarán disponibles en tu próxima sesión.

#### Opción B — Instalar como un paquete de plugins `.mcpb`

Un archivo `.mcpb` es un archivo zip del directorio de plugins que Cowork puede instalar
directamente. Este es el enfoque recomendado cuando se comparte el servidor con un equipo o
entre máquinas.

**Paso 1 — Construir el archivo `.mcpb`**

Desde la raíz del repositorio clonado, ejecuta:```bat
powershell -Command "Compress-Archive -Path '.\*' -DestinationPath 'windbg-mcp.zip'; Rename-Item 'windbg-mcp.zip' 'windbg-mcp.mcpb'"

`${__dirname}` se resuelve en el momento de la instalación al directorio donde Cowork desempaquetó el paquete, por lo que no necesita codificar rutas de forma fija.

---

### OpenAI Codex CLI

Agregue el servidor a su archivo de configuración de Codex CLI. El archivo normalmente se encuentra en
`~/.codex/config.json` (Linux/macOS) o `%USERPROFILE%\.codex\config.json` (Windows).```json
{
  "mcpServers": {
    "windbg-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
    }
  }
}

{
  "mcpServers": {
    "WinDbg": {
      "command": "python",
      "args": [
        "-m",
        "codex_windbg_server",
        "--llm-provider",
        "openai",
        ...
      ]
    }
  }
}
``````json
{
  "windbg-mcp": {
    "command": "python",
    "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
  }
}

Recarga la extensión Continue. Las 55 herramientas de depuración aparecerán en la lista de herramientas.

---

### Agentes personalizados y el SDK de MCP

Si estás construyendo tu propio agente o pipeline de automatización, conéctate a WinDbg MCP a través del transporte stdio estándar de MCP. El servidor habla JSON-RPC 2.0 sobre stdin/stdout.

#### Python (usando el SDK `mcp`)```python
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="python",
    args=[r"C:\path\to\windbg-mcp\windbg_mcp.py"],
)

async def main():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List all available tools
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            # Load a crash dump
            result = await session.call_tool(
                "load_dump",
                arguments={"path": r"C:\crashes\crash.dmp"},
            )
            print(result.content)

            # Read 64 bytes at RSP
            result = await session.call_tool(
                "read_mem",
                arguments={"addr": "0x00000000001FF000", "size": 64},
            )
            print(result.content)

asyncio.run(main())

#### LangChain / LangGraph```python
from langchain_mcp_adapters.tools import load_mcp_tools
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="python",
    args=[r"C:\path\to\windbg-mcp\windbg_mcp.py"],
)

async def get_tools():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            return await load_mcp_tools(session)

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}' | npx @anthropic-ai/claude-code --json-stdin

---

## Herramientas Disponibles (55 en total)

### Gestión de Sesiones

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `status` | — | `{connected, type, pid, bitness}` |
| `list_processes` | — | `[{pid, name, description}]` |
| `create` | `path` (requerido), `args`, `initial_break` | `{status, pid, bitness}` |
| `attach` | `pid` **o** `name` (no ambos), `initial_break` | `{status, pid, bitness}` |
| `kernel_attach` | `connect_string` (requerido), `initial_break` | `{status, type, connect_string}` |
| `load_dump` | `path` (requerido) | `{status, bitness, rip, symbol_at_rip}` |
| `connect` | `options` (requerido) | `{status, options}` |
| `detach` | — | `{status}` |
| `terminate` | — | `{status}` |

**`create`** — Inicia un nuevo proceso bajo el depurador. Establece `initial_break=True` (por defecto) para detenerse en el punto de entrada del proceso.

**`attach`** — Se adjunta a un proceso en ejecución. Proporciona `pid` (entero) o `name` (nombre del archivo del proceso). No proporcione ambos.

**`kernel_attach`** — Conecta con un depurador remoto del kernel. `connect_string` usa sintaxis KD, ej. `"net:port=55000,key=1.2.3.4"`.

**`load_dump`** — Abre un archivo `.dmp` para análisis post-mortem. Devuelve la dirección del fallo y el símbolo más cercano inmediatamente.

**`connect`** — Conecta con un servidor de procesos para depuración remota en modo usuario. `options` usa sintaxis de conexión DbgEng, ej. `"tcp:server=192.168.1.10,port=5555"`.

---

### Control de Ejecución

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `go` | `timeout` (ms, por defecto 30000) | `{status, rip, symbol, new_captures, captures}` |
| `step_into` | `count` (por defecto 1) | `{rip, instruction, symbol}` |
| `step_over` | `count` (por defecto 1) | `{rip, instruction, symbol}` |
| `step_out` | — | `{rip, instruction, symbol}` |
| `goto` | `expr` (requerido) | `{rip, symbol}` |
| `trace` | `count` (por defecto 10) | `{instructions: [{rip, instruction, symbol}], count}` |

**`go`** — Reanuda la ejecución y se bloquea hasta el siguiente evento de depuración (breakpoint, excepción o timeout). Devuelve el nuevo RIP y cualquier captura recolectada durante la ejecución.

**`step_into`** — Avanza a la siguiente instrucción, siguiendo las llamadas a funciones llamadas.

**`step_over`** — Salta sobre la siguiente instrucción, tratando las llamadas como un solo paso.

**`step_out`** — Ejecuta hasta que la función actual retorna.

**`goto`** — Ejecuta hasta alcanzar un símbolo específico o dirección hexadecimal, ej. `"Kernel32!ExitProcess"` o `"0x7fff12340000"`.

**`trace`** — Realiza N iteraciones de un solo paso y registra cada instrucción visitada.

---

### Puntos de Interrupción

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `bp` | `expr` (requerido), `capture`, `action`, `oneshot`, `passcount` | `{id, expr, addr, capture}` |
| `hw_bp` | `addr` (requerido), `size`, `access`, `capture`, `action`, `oneshot` | `{id, addr, size, access}` |
| `list_bps` | — | `[{id, expr, type, capture, action, ...}]` |
| `remove_bp` | `id` (requerido) | `{status, id}` |
| `enable_bp` | `id` (requerido) | `{status, id}` |
| `disable_bp` | `id` (requerido) | `{status, id}` |

**`bp`** — Establece un breakpoint de software (código) en un símbolo o dirección.
- `expr`: símbolo (`"ntdll!NtCreateFile"`) o dirección hexadecimal (`"0x7ff800001234"`)
- `capture`: cuando es `true` (por defecto), guarda automáticamente el estado completo — registros, pila, memoria — en el búfer de captura cada vez que este breakpoint se dispara
- `action`: `"go"` (por defecto) continúa la ejecución después de la captura; `"break"` se detiene
- `oneshot`: elimina el breakpoint después de dispararse una vez
- `passcount`: se dispara solo después de N pasadas por la ubicación

**`hw_bp`** — Establece un breakpoint de hardware / datos (watchpoint).
- `addr`: dirección hexadecimal a vigilar
- `size`: ancho de vigilancia en bytes — `1`, `2`, `4` o `8` (por defecto `4`)
- `access`: `"e"` ejecución, `"w"` escritura (por defecto), `"r"` lectura/escritura
- `capture`, `action`, `oneshot`: misma semántica que `bp`

**`list_bps`** — Devuelve todos los breakpoints actualmente activos con sus IDs, expresiones, tipos y configuraciones.

**`remove_bp` / `enable_bp` / `disable_bp`** — Gestiona breakpoints mediante el `id` devuelto por `bp` o `hw_bp`.

---

### Capturas de Estado

Los breakpoints con `capture: true` (por defecto) guardan automáticamente una instantánea completa del depurador cada vez que se disparan. La instantánea incluye todos los registros, la pila de llamadas, 64 bytes de memoria de pila en RSP y 32 bytes de código en RIP. Las instantáneas se acumulan en un búfer y se pueden recuperar en cualquier momento con `get_captures`.

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `get_captures` | — | `{count, captures: [{bp_id, expr, timestamp, registers, rip, symbol_at_rip, instruction, stack, context_memory}]}` |
| `clear_captures` | — | `{status}` |
| `capture_state` | — | `{timestamp, registers, rip, symbol_at_rip, instruction, disasm_5, stack_at_rsp, call_stack}` |

**`get_captures`** — Devuelve todas las capturas recolectadas desde el último `clear_captures`. Cada captura contiene:
- `registers` — todos los valores de registros como cadenas hexadecimales `{name: "0x..."}`
- `rip` — puntero de instrucción en el momento de la captura
- `symbol_at_rip` — símbolo más cercano a RIP
- `instruction` — desensamblado de la instrucción en RIP
- `stack` — los 10 marcos superiores de la pila de llamadas con direcciones y direcciones de retorno
- `context_memory.stack_at_rsp` — 64 bytes en RSP como hexadecimal, con formato y ASCII
- `context_memory.code_at_rip` — 32 bytes en RIP como hexadecimal y con formato

**`clear_captures`** — Limpia el búfer de captura. Útil antes de iniciar una nueva ejecución.

**`capture_state`** — Toma una instantánea inmediata bajo demanda del estado actual. Úselo cuando ya esté detenido, en lugar de esperar a que se dispare un breakpoint.

---

### Memoria

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `read_mem` | `addr` (requerido), `size` (por defecto 16) | `{addr, size, hex, formatted, ascii}` |
| `write_mem` | `addr` (requerido), `data` (requerido, cadena hexadecimal) | `{status, addr, bytes_written}` |
| `read_ptr` | `addr` (requerido), `count` (por defecto 1) | `{addr, values: ["0x..."]}` |
| `poi` | `addr` (requerido) | `{addr, value}` |
| `read_str` | `addr` (requerido), `wide` (por defecto false) | `{addr, value, wide}` |
| `dump_mem` | `addr` (requerido), `count` (por defecto 8) | `{addr, output}` |
| `mem_info` | `addr` (requerido) | `{addr, info}` |
| `mem_list` | — | `[region_description_strings]` |

**`read_mem`** — Lee `size` bytes sin procesar desde `addr`. Devuelve los datos como `hex` (compacto), `formatted` (bytes separados por espacios) y `ascii` (caracteres imprimibles, `.` para no imprimibles).

**`write_mem`** — Escribe bytes en la memoria. `data` es una cadena hexadecimal: los espacios y los prefijos `\x` se eliminan automáticamente, ej. `"90909090"`, `"\\x90\\x90\\x90\\x90"` o `"90 90 90 90"`.

**`read_ptr`** — Lee `count` valores consecutivos del tamaño de un puntero (4 bytes en 32 bits, 8 bytes en 64 bits) comenzando en `addr`.

**`poi`** — Desreferencia un solo puntero en `addr` (puntero de interés).

**`read_str`** — Lee una cadena terminada en nulo. Establezca `wide=true` para UTF-16LE (WCHAR de Windows).

**`dump_mem`** — Volcado de dword/puntero formateado, equivalente a `dd`/`dp` en WinDbg.

**`mem_info`** — Devuelve las propiedades de la región de memoria para la página que contiene `addr`: dirección base, tamaño, tipo, estado y banderas de protección.

**`mem_list`** — Enumera todas las regiones de memoria virtual en el espacio de direcciones del proceso objetivo.

---

### Registros

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `get_regs` | — | `{rax, rbx, rcx, rdx, rsi, rdi, rbp, rsp, rip, r8–r15, eflags, ...}` |
| `get_reg` | `name` (requerido) | `{name, value}` |
| `set_reg` | `name` (requerido), `value` (requerido) | `{status, name, value}` |
| `get_pc` | — | `{value, symbol, instruction}` |
| `get_sp` | — | `{value}` |

**`get_regs`** — Devuelve todos los registros disponibles como `{name: "0x..."}`. El conjunto exacto depende de la arquitectura objetivo (x86 vs x64).

**`get_reg`** — Devuelve un único registro, ej. `name="rax"`, `name="eflags"`.

**`set_reg`** — Sobrescribe un registro. `value` acepta cadenas hexadecimales (`"0x1234"`) o cadenas de enteros decimales.

**`get_pc`** — Devuelve el puntero de instrucción con resolución de símbolos y el texto de instrucción decodificada en esa dirección.

**`get_sp`** — Devuelve el valor actual del puntero de pila.

---

### Símbolos y Desensamblado

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `resolve` | `name` (requerido) | `{name, addr}` o `{name, addr: null, error}` |
| `find_symbols` | `pattern` (requerido) | `[symbol_strings]` |
| `addr_to_symbol` | `addr` (requerido) | `{addr, symbol}` |
| `disasm` | `addr` (por defecto: RIP actual), `count` (por defecto 10) | `{addr, output}` |
| `whereami` | `addr` (opcional, por defecto: RIP actual) | `{description}` |

**`resolve`** — Resuelve un nombre de símbolo a su dirección virtual. Use formato `Module!Function`, ej. `"Kernel32!WriteFile"`, `"ntdll!NtCreateFile"`.

**`find_symbols`** — Búsqueda de símbolos con comodín, ej. `"ntdll!*Alloc*"`, `"kernel32!*File*"`. Devuelve todas las cadenas de símbolos coincidentes.

**`addr_to_symbol`** — Resolución inversa de una dirección virtual al nombre de símbolo más cercano.

**`disasm`** — Desensambla `count` instrucciones comenzando en `addr`. Por defecto usa el RIP actual si no se proporciona ninguna dirección.

**`whereami`** — Devuelve una descripción legible por humanos del módulo, función y desplazamiento en la dirección dada.

---

### Módulos

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `list_modules` | — | `[{name, base, size}]` |
| `module_info` | `name` (requerido) | `{name, entry_point, sections}` |
| `get_exports` | `name` (requerido) | `[export_strings]` |
| `get_imports` | `name` (requerido) | `[import_strings]` |

**`list_modules`** — Enumera todos los módulos cargados en el objetivo, con su dirección base y tamaño.

**`module_info`** — Devuelve el punto de entrada y la lista de secciones (nombre, dirección virtual, tamaño) para un módulo específico, ej. `"kernel32.dll"`, `"ntdll.dll"`.

**`get_exports`** — Devuelve la tabla de exportaciones completa de un módulo como una lista de cadenas.

**`get_imports`** — Devuelve la tabla de importaciones completa de un módulo como una lista de cadenas.

---

### Hilos y Pila

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `list_threads` | — | `[thread_description_strings]` |
| `get_thread` | — | `{current_thread}` |
| `set_thread` | `id` (requerido) | `{status, thread}` |
| `get_stack` | `frames` (por defecto 20) | `{frames: [{frame, addr, return_addr, frame_ptr}], count}` |
| `get_teb` | — | `{addr}` |
| `get_peb` | — | `{addr}` |

**`list_threads`** — Enumera todos los hilos en el proceso objetivo.

**`get_thread`** — Devuelve el contexto del hilo actualmente activo.

**`set_thread`** — Cambia el contexto del hilo activo por ID de hilo (de `list_threads`).

**`get_stack`** — Devuelve la pila de llamadas como datos estructurados. Cada marco incluye la dirección de instrucción, dirección de retorno y puntero de marco.

**`get_teb`** — Devuelve la dirección del Bloque de Entorno del Hilo (TEB) para el hilo actual.

**`get_peb`** — Devuelve la dirección del Bloque de Entorno del Proceso (PEB).

---

### Proceso y Utilidades

| Herramienta | Parámetros | Devuelve |
|------|-----------|---------|
| `get_handles` | — | `[handle_description_strings]` |
| `get_bitness` | — | `{bits}` |
| `raw` | `cmd` (requerido) | `{output}` |

**`get_handles`** — Enumera todos los identificadores (handles) abiertos en el proceso objetivo.

**`get_bitness`** — Devuelve `32` o `64` dependiendo de la arquitectura objetivo.

**`raw`** — Ejecuta cualquier comando de WinDbg y devuelve la salida como texto. Úselo como vía de escape para cualquier cosa no cubierta por las otras herramientas:```
raw(cmd="!heap -stat")
raw(cmd="dt _PEB @$peb")
raw(cmd="!locks")
raw(cmd="lm")
raw(cmd="!address @rsp")

En `get_captures`, inspecciona `captures[0].registers.rip`:
- `"0x4141414141414141"` — controlas RIP con bytes 'A'
- Cualquier valor que coincida con tu patrón — controlado
- Una dirección de apariencia válida — fallo pero aún no controlado

Verifica `captures[0].context_memory.stack_at_rsp.formatted` para ver padding, direcciones de retorno o bytes de shellcode en la pila.

---

### Análisis del volcado de memoria```
1. load_dump(path="C:/crashes/crash.dmp")
2. get_regs()             → full register state at crash time
3. get_stack(frames=30)   → call stack at crash
4. get_sp()               → read RSP value
5. read_mem(addr=<rsp>, size=64) → stack contents
6. disasm()               → instructions at the crash address

### Verificación de ASLR```
1. create(path="C:/target/target.exe")
2. resolve(name="kernel32!WriteFile")   → record base address
3. terminate()
4. create(path="C:/target/target.exe")
5. resolve(name="kernel32!WriteFile")   → compare: changed = ASLR on, same = ASLR off

---

### Inspección de hilos```
1. attach(pid=1234)
2. list_threads()          → all thread IDs
3. set_thread(id=2)        → switch context
4. get_stack(frames=20)    → call stack for that thread
5. get_regs()              → registers for that thread
6. get_teb()               → TEB address

**Ajuste de tiempo de espera** — `go()` por defecto es de 30 segundos. Para objetivos que se ejecutan más tiempo antes de alcanzar un punto de interrupción:```
go(timeout=120000)   # 2 minutes
go(timeout=300000)   # 5 minutes

---

## Licencia

MIT