debugg-ai-mcp: Instructions file for Codex

Agent Instructions

This project uses bd (beads) for issue tracking. Run bd onboard to get started.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --status in_progress  # Claim work
bd close <id>         # Complete work
bd sync               # Sync with git

Testing & live verification

npm test            # unit tests (jest, ESM + ts-jest; use `import { jest } from '@jest/globals'`)
npx tsc --noEmit    # typecheck
npm run lint        # eslint
npm run build       # tsc -> dist/

Unit tests mock the backend. To verify a tool end-to-end against the real API:

• The MCP reads DEBUGGAI_API_KEY from the environment — .mcp.json references ${DEBUGGAI_API_KEY} (never a literal). Export it first: export DEBUGGAI_API_KEY=<key>.
• No dev-mode → prod api.debugg.ai. DEBUGGAI_DEV_MODE=true → local backend http://localhost:8012 (needs a local token; the prod key won't auth there).
• npm run test:integration hits the real API, self-skips without a key, and writes data — be deliberate about which backend you target.
• Fast read-only smoke of a fresh build (npm run build first) — replicate the CallTool path:

  import { getTool } from './dist/tools/index.js';
  import { validateInput } from './dist/utils/validation.js';
  const t = getTool('project');
  console.log(await t.handler(validateInput(t.inputSchema, { action: 'list' }, 'project'), { timestamp: new Date() }));
  

  Use read-only actions (list/get) on project/environment/executions.

Tunnel mechanics for localhost URLs: check_app_in_browser/probe_page/trigger_crawl auto-tunnel http(s)://localhost:* targets through one tunnel per session key (not per port) dialed at a local Caddy reverse proxy that gets repointed per dispatch under a lock — see docs/local-tunnel-multiplexer-architecture-2026-07-31.md, docs/debugg-tunnel-server-design-2026-09-19.md, and services/tunnel//services/caddy/. The tunnel is the debugg tunnel server (<id>.tunnel.debugg.ai), reached by a pure-TS websocket mux client (services/tunnel/debuggTransport.ts); the ngrok client was removed once that shipped. The caddy binary is still required for any localhost-URL call: it auto-installs via the @radically-straightforward/caddy npm dependency's postinstall (pinned version) — CADDY_BIN overrides it if that download never ran. Fails fast with CaddyBinaryNotFoundError if neither is available. test_suite {action:"run"} is the exception: dedicated per-call tunnel, bypasses Caddy, no caddy needed.