textual-debugger 0.1.3__tar.gz → 0.1.5__tar.gz

{textual_debugger-0.1.3 → textual_debugger-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.1.3
+Version: 0.1.5
 Summary: A TUI Python debugger based on textual and debugpy
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
@@ -51,6 +51,7 @@ Requires-Dist: debugpy>=1.8.0
 Requires-Dist: pygments>=2.17.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: mcp>=1.28.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -90,7 +91,8 @@ It specifically supports modules
 
 - supports remote attachment to debugpy-enabled Python programs
 
-- includes a JSON-RPC server mode that enables programmatic debug control, making it suitable for
+- includes a JSON-RPC server mode, an MCP mode, and a `SKILL.md` file that enable
+programmatic debug control, making it suitable for
 automated, headless debugging workflows and AI-assisted debugging
 
 - can spawn the debuggee in an external terminal to enable debugging TUI applications
@@ -119,6 +121,9 @@ as open source.
 [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
 `tdb` was made almost entirely with Claude Code.
 
+- OpenAI, for providing access to Codex through the
+[Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
+
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -441,6 +446,17 @@ Snapshot depth / breadth is capped (5 levels, 50 children per container) to keep
 capture cheap even for pathological object graphs; cycles are handled via identity
 memoization.
 
+### Post-Mortem within a Docker Container
+
+The `textual-debugger` GitHub repository's `examples/` directory has three files
+that show how to run a `tdb`-enabled Python program under `tmux` in a Docker
+container so that you can attach to the container and inspect the program
+in `tdb` post-mortem analysis mode if the program hits an unhandled exception:
+
+- [post_mortem_example.py](https://github.com/AlDanial/tdb/blob/main/examples/post_mortem_example.py)
+- [post_mortem_entrypoint.sh](https://github.com/AlDanial/tdb/blob/main/examples/post_mortem_entrypoint.sh)
+- [Dockerfile.post_mortem](https://github.com/AlDanial/tdb/blob/main/examples/Dockerfile.post_mortem)
+
 ### Live Breakpoint Hook
 
 `tdb` has an improved implemenation of the standard `breakpoint()` function (or equivalently,
@@ -738,11 +754,12 @@ curl -s -X POST http://127.0.0.1:8150/rpc \
 | `set_breakpoint` | `["file:line"]` or `["file:line", "condition", "hit_condition"]` | Set a breakpoint |
 | `remove_breakpoint` | `["file:line"]` | Remove a breakpoint |
 | `list_breakpoints` | `[]` | Show all breakpoints |
-| `continue` | `[]` | Resume execution |
-| `next` | `[]` | Step over |
-| `step_in` | `[]` | Step into |
-| `step_out` | `[]` | Step out |
-| `pause` | `[]` | Pause execution |
+| `continue` | `[]` or `[timeout_s]` | Resume execution; on timeout returns `"still running — call pause or wait again"` (success) |
+| `next` | `[]` or `[timeout_s]` | Step over |
+| `step_in` | `[]` or `[timeout_s]` | Step into |
+| `step_out` | `[]` or `[timeout_s]` | Step out |
+| `pause` | `[]` | Pause execution; bypasses the dispatch lock so it can interrupt an in-flight blocking action |
+| `wait_for_stop` | `[]` or `[timeout_s]` | Wait for the next stop without issuing a step (use after `continue` returns `"still running"` to keep waiting) |
 | `inspect` | `["expr1", "expr2", ...]` | Evaluate multiple expressions |
 | `evaluate` | `["expression"]` | Evaluate a single expression |
 | `stack_up` | `[]` | Move up the call stack |
@@ -771,6 +788,89 @@ curl -N http://127.0.0.1:8150/events
 Events: `initialized`, `stopped`, `continued`, `terminated`, `exited`, `output`.
 Each is JSON with `event`, `data`, and `timestamp` fields.
 
+## MCP Integration
+
+tdb ships a Model Context Protocol (MCP) server (`tdb-mcp`) that exposes
+the debugger as a curated set of tools an AI agent can call. The MCP
+server is a third in-process consumer of the same dispatch handlers the
+TUI and the HTTP server use — so an agent gets the same lock semantics,
+including the pause-during-continue bypass, and the same DAP-backed
+inspection surface.
+
+For a worked end-to-end example (prompting an agent to find two
+runtime bugs in a sample program) see
+[docs/tutorial-mcp-debugging.md](docs/tutorial-mcp-debugging.md) and
+its companion `examples/sales_report_buggy.py`.
+
+### Running the MCP server
+
+Configure your MCP client (Claude Desktop, an IDE extension, etc.) to
+launch `tdb-mcp` over stdio. Example `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tdb": {
+      "command": "tdb-mcp"
+    }
+  }
+}
+```
+
+Three equivalent invocation forms: `tdb-mcp` (the dedicated entry
+point), `tdb --mcp` (the main CLI with the `--mcp` switch), and
+`python -m tdb.mcp` (module form). Pick whichever matches how your MCP
+client expects to launch servers.
+
+### Tool surface (16 tools, curated)
+
+| Cluster | Tools |
+|---------|-------|
+| Lifecycle | `debug_launch`, `debug_attach`, `quit` |
+| Control | `control(action, timeout_s=30)` — `action ∈ {continue, next, step_in, step_out, pause, wait_for_stop}` |
+| Inspection | `inspect(expressions)`, `read_source(file_path)`, `stack_trace()`, `status()`, `get_output()` |
+| Breakpoints | `set_breakpoint(spec, condition?, hit_condition?)`, `remove_breakpoint(spec)`, `list_breakpoints()` |
+| Differentiators | `threads(thread_id?)`, `tasks(task_name?)`, `processes(name_or_pid?)`, `wait_graph()` |
+
+`control` is intentionally one tool that takes an action enum — the six
+underlying RPC actions share a return shape, and agents perform
+measurably better with a small surface than with one tool per action.
+`threads` / `tasks` / `processes` overload list-vs-inspect via a
+single optional argument for the same reason.
+
+### Agent flow for a long-running step
+
+```
+agent → control(action="continue", timeout_s=30)
+mcp   → "still running — call pause or wait again"
+agent → control(action="pause")        # OR: control(action="wait_for_stop", timeout_s=30)
+mcp   → "<file>:<line>"
+agent → inspect(["x", "len(buf)"])
+mcp   → "x = 7\nlen(buf) = 1024"
+```
+
+`pause` bypasses the dispatch lock so it can interrupt a `continue`
+that's still mid-flight (HTTP and MCP share the same `NO_LOCK_ACTIONS`
+policy — see `tdb/server/app.py`).
+
+### Security caveat
+
+`inspect` calls debugpy's `evaluate`, which is **arbitrary Python
+execution in the debuggee process**. This is inherent to a debugger and
+not a tdb-specific concern, but MCP clients (and the humans running
+them) should apply appropriate permission models: don't auto-approve
+`inspect` against untrusted expressions, and don't expose `tdb-mcp` on
+a network — stdio transport only by design.
+
+### Deferred / out of scope (v1)
+
+- SSE-style event push — `control` and `wait_for_stop` make polling
+  efficient enough; events would also need uneven MCP-client support.
+- HTTP / streamable-HTTP transports — would require auth (which the
+  HTTP RPC server also currently lacks); stdio inherits the trust of
+  the process that spawned it.
+- Multi-session — one debug session per MCP process.
+
 ## CLI Reference
 
 ```

{textual_debugger-0.1.3/src/tdb → textual_debugger-0.1.5}/README.md

@@ -25,7 +25,8 @@ It specifically supports modules
 
 - supports remote attachment to debugpy-enabled Python programs
 
-- includes a JSON-RPC server mode that enables programmatic debug control, making it suitable for
+- includes a JSON-RPC server mode, an MCP mode, and a `SKILL.md` file that enable
+programmatic debug control, making it suitable for
 automated, headless debugging workflows and AI-assisted debugging
 
 - can spawn the debuggee in an external terminal to enable debugging TUI applications
@@ -54,6 +55,9 @@ as open source.
 [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
 `tdb` was made almost entirely with Claude Code.
 
+- OpenAI, for providing access to Codex through the
+[Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
+
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -376,6 +380,17 @@ Snapshot depth / breadth is capped (5 levels, 50 children per container) to keep
 capture cheap even for pathological object graphs; cycles are handled via identity
 memoization.
 
+### Post-Mortem within a Docker Container
+
+The `textual-debugger` GitHub repository's `examples/` directory has three files
+that show how to run a `tdb`-enabled Python program under `tmux` in a Docker
+container so that you can attach to the container and inspect the program
+in `tdb` post-mortem analysis mode if the program hits an unhandled exception:
+
+- [post_mortem_example.py](https://github.com/AlDanial/tdb/blob/main/examples/post_mortem_example.py)
+- [post_mortem_entrypoint.sh](https://github.com/AlDanial/tdb/blob/main/examples/post_mortem_entrypoint.sh)
+- [Dockerfile.post_mortem](https://github.com/AlDanial/tdb/blob/main/examples/Dockerfile.post_mortem)
+
 ### Live Breakpoint Hook
 
 `tdb` has an improved implemenation of the standard `breakpoint()` function (or equivalently,
@@ -673,11 +688,12 @@ curl -s -X POST http://127.0.0.1:8150/rpc \
 | `set_breakpoint` | `["file:line"]` or `["file:line", "condition", "hit_condition"]` | Set a breakpoint |
 | `remove_breakpoint` | `["file:line"]` | Remove a breakpoint |
 | `list_breakpoints` | `[]` | Show all breakpoints |
-| `continue` | `[]` | Resume execution |
-| `next` | `[]` | Step over |
-| `step_in` | `[]` | Step into |
-| `step_out` | `[]` | Step out |
-| `pause` | `[]` | Pause execution |
+| `continue` | `[]` or `[timeout_s]` | Resume execution; on timeout returns `"still running — call pause or wait again"` (success) |
+| `next` | `[]` or `[timeout_s]` | Step over |
+| `step_in` | `[]` or `[timeout_s]` | Step into |
+| `step_out` | `[]` or `[timeout_s]` | Step out |
+| `pause` | `[]` | Pause execution; bypasses the dispatch lock so it can interrupt an in-flight blocking action |
+| `wait_for_stop` | `[]` or `[timeout_s]` | Wait for the next stop without issuing a step (use after `continue` returns `"still running"` to keep waiting) |
 | `inspect` | `["expr1", "expr2", ...]` | Evaluate multiple expressions |
 | `evaluate` | `["expression"]` | Evaluate a single expression |
 | `stack_up` | `[]` | Move up the call stack |
@@ -706,6 +722,89 @@ curl -N http://127.0.0.1:8150/events
 Events: `initialized`, `stopped`, `continued`, `terminated`, `exited`, `output`.
 Each is JSON with `event`, `data`, and `timestamp` fields.
 
+## MCP Integration
+
+tdb ships a Model Context Protocol (MCP) server (`tdb-mcp`) that exposes
+the debugger as a curated set of tools an AI agent can call. The MCP
+server is a third in-process consumer of the same dispatch handlers the
+TUI and the HTTP server use — so an agent gets the same lock semantics,
+including the pause-during-continue bypass, and the same DAP-backed
+inspection surface.
+
+For a worked end-to-end example (prompting an agent to find two
+runtime bugs in a sample program) see
+[docs/tutorial-mcp-debugging.md](docs/tutorial-mcp-debugging.md) and
+its companion `examples/sales_report_buggy.py`.
+
+### Running the MCP server
+
+Configure your MCP client (Claude Desktop, an IDE extension, etc.) to
+launch `tdb-mcp` over stdio. Example `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tdb": {
+      "command": "tdb-mcp"
+    }
+  }
+}
+```
+
+Three equivalent invocation forms: `tdb-mcp` (the dedicated entry
+point), `tdb --mcp` (the main CLI with the `--mcp` switch), and
+`python -m tdb.mcp` (module form). Pick whichever matches how your MCP
+client expects to launch servers.
+
+### Tool surface (16 tools, curated)
+
+| Cluster | Tools |
+|---------|-------|
+| Lifecycle | `debug_launch`, `debug_attach`, `quit` |
+| Control | `control(action, timeout_s=30)` — `action ∈ {continue, next, step_in, step_out, pause, wait_for_stop}` |
+| Inspection | `inspect(expressions)`, `read_source(file_path)`, `stack_trace()`, `status()`, `get_output()` |
+| Breakpoints | `set_breakpoint(spec, condition?, hit_condition?)`, `remove_breakpoint(spec)`, `list_breakpoints()` |
+| Differentiators | `threads(thread_id?)`, `tasks(task_name?)`, `processes(name_or_pid?)`, `wait_graph()` |
+
+`control` is intentionally one tool that takes an action enum — the six
+underlying RPC actions share a return shape, and agents perform
+measurably better with a small surface than with one tool per action.
+`threads` / `tasks` / `processes` overload list-vs-inspect via a
+single optional argument for the same reason.
+
+### Agent flow for a long-running step
+
+```
+agent → control(action="continue", timeout_s=30)
+mcp   → "still running — call pause or wait again"
+agent → control(action="pause")        # OR: control(action="wait_for_stop", timeout_s=30)
+mcp   → "<file>:<line>"
+agent → inspect(["x", "len(buf)"])
+mcp   → "x = 7\nlen(buf) = 1024"
+```
+
+`pause` bypasses the dispatch lock so it can interrupt a `continue`
+that's still mid-flight (HTTP and MCP share the same `NO_LOCK_ACTIONS`
+policy — see `tdb/server/app.py`).
+
+### Security caveat
+
+`inspect` calls debugpy's `evaluate`, which is **arbitrary Python
+execution in the debuggee process**. This is inherent to a debugger and
+not a tdb-specific concern, but MCP clients (and the humans running
+them) should apply appropriate permission models: don't auto-approve
+`inspect` against untrusted expressions, and don't expose `tdb-mcp` on
+a network — stdio transport only by design.
+
+### Deferred / out of scope (v1)
+
+- SSE-style event push — `control` and `wait_for_stop` make polling
+  efficient enough; events would also need uneven MCP-client support.
+- HTTP / streamable-HTTP transports — would require auth (which the
+  HTTP RPC server also currently lacks); stdio inherits the trust of
+  the process that spawned it.
+- Multi-session — one debug session per MCP process.
+
 ## CLI Reference
 
 ```

{textual_debugger-0.1.3 → textual_debugger-0.1.5}/pyproject.toml

@@ -25,7 +25,8 @@
       "pygments>=2.17.0",
       "fastapi>=0.115.0",
       "uvicorn>=0.30.0",
-  ]
+      "mcp>=1.28.0",
+]
 
   # extras needed to run the examples and tests
   [project.optional-dependencies]
@@ -43,6 +44,7 @@
 
   [project.scripts]
   tdb = "tdb.cli:main"
+  tdb-mcp = "tdb.mcp.server:main"
 
   [build-system]
   requires = ["setuptools>=68.0"]

{textual_debugger-0.1.3 → textual_debugger-0.1.5/src/tdb}/README.md

@@ -25,7 +25,8 @@ It specifically supports modules
 
 - supports remote attachment to debugpy-enabled Python programs
 
-- includes a JSON-RPC server mode that enables programmatic debug control, making it suitable for
+- includes a JSON-RPC server mode, an MCP mode, and a `SKILL.md` file that enable
+programmatic debug control, making it suitable for
 automated, headless debugging workflows and AI-assisted debugging
 
 - can spawn the debuggee in an external terminal to enable debugging TUI applications
@@ -54,6 +55,9 @@ as open source.
 [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
 `tdb` was made almost entirely with Claude Code.
 
+- OpenAI, for providing access to Codex through the
+[Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
+
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -376,6 +380,17 @@ Snapshot depth / breadth is capped (5 levels, 50 children per container) to keep
 capture cheap even for pathological object graphs; cycles are handled via identity
 memoization.
 
+### Post-Mortem within a Docker Container
+
+The `textual-debugger` GitHub repository's `examples/` directory has three files
+that show how to run a `tdb`-enabled Python program under `tmux` in a Docker
+container so that you can attach to the container and inspect the program
+in `tdb` post-mortem analysis mode if the program hits an unhandled exception:
+
+- [post_mortem_example.py](https://github.com/AlDanial/tdb/blob/main/examples/post_mortem_example.py)
+- [post_mortem_entrypoint.sh](https://github.com/AlDanial/tdb/blob/main/examples/post_mortem_entrypoint.sh)
+- [Dockerfile.post_mortem](https://github.com/AlDanial/tdb/blob/main/examples/Dockerfile.post_mortem)
+
 ### Live Breakpoint Hook
 
 `tdb` has an improved implemenation of the standard `breakpoint()` function (or equivalently,
@@ -673,11 +688,12 @@ curl -s -X POST http://127.0.0.1:8150/rpc \
 | `set_breakpoint` | `["file:line"]` or `["file:line", "condition", "hit_condition"]` | Set a breakpoint |
 | `remove_breakpoint` | `["file:line"]` | Remove a breakpoint |
 | `list_breakpoints` | `[]` | Show all breakpoints |
-| `continue` | `[]` | Resume execution |
-| `next` | `[]` | Step over |
-| `step_in` | `[]` | Step into |
-| `step_out` | `[]` | Step out |
-| `pause` | `[]` | Pause execution |
+| `continue` | `[]` or `[timeout_s]` | Resume execution; on timeout returns `"still running — call pause or wait again"` (success) |
+| `next` | `[]` or `[timeout_s]` | Step over |
+| `step_in` | `[]` or `[timeout_s]` | Step into |
+| `step_out` | `[]` or `[timeout_s]` | Step out |
+| `pause` | `[]` | Pause execution; bypasses the dispatch lock so it can interrupt an in-flight blocking action |
+| `wait_for_stop` | `[]` or `[timeout_s]` | Wait for the next stop without issuing a step (use after `continue` returns `"still running"` to keep waiting) |
 | `inspect` | `["expr1", "expr2", ...]` | Evaluate multiple expressions |
 | `evaluate` | `["expression"]` | Evaluate a single expression |
 | `stack_up` | `[]` | Move up the call stack |
@@ -706,6 +722,89 @@ curl -N http://127.0.0.1:8150/events
 Events: `initialized`, `stopped`, `continued`, `terminated`, `exited`, `output`.
 Each is JSON with `event`, `data`, and `timestamp` fields.
 
+## MCP Integration
+
+tdb ships a Model Context Protocol (MCP) server (`tdb-mcp`) that exposes
+the debugger as a curated set of tools an AI agent can call. The MCP
+server is a third in-process consumer of the same dispatch handlers the
+TUI and the HTTP server use — so an agent gets the same lock semantics,
+including the pause-during-continue bypass, and the same DAP-backed
+inspection surface.
+
+For a worked end-to-end example (prompting an agent to find two
+runtime bugs in a sample program) see
+[docs/tutorial-mcp-debugging.md](docs/tutorial-mcp-debugging.md) and
+its companion `examples/sales_report_buggy.py`.
+
+### Running the MCP server
+
+Configure your MCP client (Claude Desktop, an IDE extension, etc.) to
+launch `tdb-mcp` over stdio. Example `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tdb": {
+      "command": "tdb-mcp"
+    }
+  }
+}
+```
+
+Three equivalent invocation forms: `tdb-mcp` (the dedicated entry
+point), `tdb --mcp` (the main CLI with the `--mcp` switch), and
+`python -m tdb.mcp` (module form). Pick whichever matches how your MCP
+client expects to launch servers.
+
+### Tool surface (16 tools, curated)
+
+| Cluster | Tools |
+|---------|-------|
+| Lifecycle | `debug_launch`, `debug_attach`, `quit` |
+| Control | `control(action, timeout_s=30)` — `action ∈ {continue, next, step_in, step_out, pause, wait_for_stop}` |
+| Inspection | `inspect(expressions)`, `read_source(file_path)`, `stack_trace()`, `status()`, `get_output()` |
+| Breakpoints | `set_breakpoint(spec, condition?, hit_condition?)`, `remove_breakpoint(spec)`, `list_breakpoints()` |
+| Differentiators | `threads(thread_id?)`, `tasks(task_name?)`, `processes(name_or_pid?)`, `wait_graph()` |
+
+`control` is intentionally one tool that takes an action enum — the six
+underlying RPC actions share a return shape, and agents perform
+measurably better with a small surface than with one tool per action.
+`threads` / `tasks` / `processes` overload list-vs-inspect via a
+single optional argument for the same reason.
+
+### Agent flow for a long-running step
+
+```
+agent → control(action="continue", timeout_s=30)
+mcp   → "still running — call pause or wait again"
+agent → control(action="pause")        # OR: control(action="wait_for_stop", timeout_s=30)
+mcp   → "<file>:<line>"
+agent → inspect(["x", "len(buf)"])
+mcp   → "x = 7\nlen(buf) = 1024"
+```
+
+`pause` bypasses the dispatch lock so it can interrupt a `continue`
+that's still mid-flight (HTTP and MCP share the same `NO_LOCK_ACTIONS`
+policy — see `tdb/server/app.py`).
+
+### Security caveat
+
+`inspect` calls debugpy's `evaluate`, which is **arbitrary Python
+execution in the debuggee process**. This is inherent to a debugger and
+not a tdb-specific concern, but MCP clients (and the humans running
+them) should apply appropriate permission models: don't auto-approve
+`inspect` against untrusted expressions, and don't expose `tdb-mcp` on
+a network — stdio transport only by design.
+
+### Deferred / out of scope (v1)
+
+- SSE-style event push — `control` and `wait_for_stop` make polling
+  efficient enough; events would also need uneven MCP-client support.
+- HTTP / streamable-HTTP transports — would require auth (which the
+  HTTP RPC server also currently lacks); stdio inherits the trust of
+  the process that spawned it.
+- Multi-session — one debug session per MCP process.
+
 ## CLI Reference
 
 ```

{textual_debugger-0.1.3 → textual_debugger-0.1.5}/src/tdb/__init__.py

@@ -1,6 +1,6 @@
 from tdb.breakpoint_hook import breakpoint
 from tdb.post_mortem import exception_hook
 
-__version__ = "0.1.3"
+__version__ = "0.1.5"
 
 __all__ = ["breakpoint", "exception_hook"]