Tracy and AI/LLMs

[adrian]

Hi everyone, in particular @ryan @Peter Knight@ukyo @gebeer @maximus who seem to have been most AI active lately.

I've just added dai() and bdai() dumping calls so that objects and arrays are rendered in plain text format more friendly to LLMs, but I am curious what AI/LLM integration features you think would be most useful?

Claude suggested an MCP server - here is its plan. Does this sound useful? Any other ideas?

 

Two processes, loosely coupled:

 

┌──────────────────┐                        ┌──────────────────────────┐
│ Claude / Cursor  │      stdio MCP         │ TracyDebugger site       │
│     client       │ ─────────────────►     │                          │
│                  │      HTTP + token      │  tracy-ai/* endpoints    │
└──────────────────┘ ◄─────────────────     └──────────────────────────┘

1. MCP server — a tiny program the agent launches over stdio (the MCP transport). Ships as a sibling module (TracyDebuggerMCP/) or a standalone npm package the user npx's.
2. TracyDebugger HTTP endpoints — new authenticated tracy-ai/* routes inside the ProcessWire site. The MCP server is just a thin translator between MCP tool calls and these HTTP requests.

The MCP server holds no site logic. It's a dumb adapter. All the real work (reading panels, redacting secrets, rendering plaintext) stays inside TracyDebugger where the ProcessWire API is available.

What the agent sees

A handful of tools in the MCP catalog:

 

tracy_export_bundle(preset: "debug" | "performance" | "template" | "full")
tracy_get_request_info()
tracy_get_last_errors(limit: int = 10)
tracy_get_slow_queries(limit: int = 10)
tracy_get_template_schema(template: string)
tracy_list_dumps()
tracy_run_console(code: string)           ← gated, opt-in only

Every tool returns the scrubbed plaintext/JSON produced by AIExport — same output Phase 2's "Copy" button produces.

Config on the site

New module-config section:

• aiExportHTTPEndpointEnabled (default off)
• aiExportMCPToken — a random token generated once per site, shown to the user to paste into their MCP client config
• aiExportAllowConsoleExec (default off) — gates tracy_run_console
• aiExportAllowedIPs — optional whitelist

Config on the client

User's ~/.config/claude/mcp.json or equivalent:

 

json

{
  "mcpServers": {
    "tracy": {
      "command": "npx",
      "args": ["-y", "tracy-mcp"],
      "env": {
        "TRACY_URL":   "https://mysite.test",
        "TRACY_TOKEN": "<paste token from module config>"
      }
    }
  }
}

The agent launches the MCP server locally; the MCP server talks to the site over HTTPS with the token.

Auth

• Per-site token (generated in module config, rotateable).
• Token sent as Authorization: Bearer … header on every HTTP call.
• Optional IP whitelist on the site side.
• tracy_run_console additionally requires aiExportAllowConsoleExec=true — otherwise the MCP server gets a 403 and reports "console execution disabled for this site" to the agent.

Example flow — agent debugging an error

User in Claude: "Why is /about/team throwing a 500?"

Agent:

1. Calls tracy_export_bundle(preset: "debug").
2. MCP server hits GET https://mysite.test/tracy-ai/export?bundle=debug with the bearer token.
3. Site responds with scrubbed JSON: request info, PW info, last error with stack, slow queries, recent PW logs.
4. Agent reads the traceback, sees TemplateFile.php:123 Undefined index "featured_image", asks tracy_get_template_schema(template: "team").
5. Site responds with the template's fields — no featured_image field exists.
6. Agent suggests the fix, possibly calls tracy_run_console (if enabled) to verify.

No human pasting. Agent pulls what it needs on demand, scoped by the tool it calls.

What ships where

• In TracyDebugger itself: the tracy-ai/* HTTP endpoints + auth + token config + AIExport (already built in Phase 1, extended in Phase 2).
• In the MCP server (separate repo, ~200 lines): tool definitions, HTTP calls, response shaping for MCP.

This separation matters because the MCP server can be installed independently of the site, and the site is still useful without it (you can hit tracy-ai/export with curl directly).

Footprint on production

Zero unless you explicitly enable it. The endpoints, token, and MCP config are all opt-in behind module settings.

---

That's the shape. The main design choices worth confirming before building:

1. Token-only auth, or also require the existing Tracy access? — i.e., should the agent's token have to belong to an allowed Tracy dev user, or is a separate machine token fine? I'd lean separate machine token for agents; reusing session auth is awkward over stdio.
2. Read-only by default? — I strongly recommend yes. tracy_run_console is the only write path and should be a separate opt-in.
3. Does the MCP server live in this repo or a separate repo? — I'd say separate. Different language, different release cadence, and the site works without it.

[adrian]

Maybe it would be helpful to have an AI prompt (like Ryan's Agent Tools) built-in to the Console panel so you can prompt your way to a script, or ask it to fix/extend an existing script?

[Ivan Gretsky]

I have read this a couple of times. But as I am not as fluent in AI dev I couldn't quite grasp the whole workflow idea. So let me explain as I understood it and make my points.

I think most devs develop in either IDE like VS Code with an AI extension, Zed and such or in CLI with Claude Code, OpenCode etc. They want their agents to be able to test certain url and see if there are any errors or warnings. I guess it is already possible by telling agents where the Tracy logs are and how to read them.  AI has or could easily gain access to those anyway.

An MCP could be intermediary here but does it help with anything? Another way would be to use the newly introduces CLI modules that could query an URL and return it along with debug info from Tracy.

Just maybe AI agents can now debug in the browser, but that seems like a too complicated scenario.

Am I misunderstanding something?

[szabesz]

On 4/24/2026 at 5:46 PM, adrian said:

Example flow — agent debugging an error

User in Claude: "Why is /about/team throwing a 500?"

This workflow would be really powerful, indeed. Using the MCP server as a tool, the agent could use it on its own, but also the developer could ask the LLM/agent in the console, as Adrian mentions:

On 4/24/2026 at 10:26 PM, adrian said:

built-in to the Console panel so you can prompt your way to a script, or ask it to fix/extend an existing script?