# 1C Debug MCP

Original WSSAWER additions are provided for noncommercial use only; commercial
use requires a separate written agreement ([PRODUCT-LICENSE.txt](PRODUCT-LICENSE.txt)).
The inherited DevTool1C code remains under its original [MIT license](LICENSE).
These terms do not revoke permissions previously granted for earlier versions.

Standalone MCP server for debugging an already running 1C:Enterprise infobase through the platform HTTP RDBG server.

The server does not launch or stop 1C, `dbgs`, Designer, or external commands. It connects to an existing RDBG endpoint, attaches current and future debug targets, manages breakpoints, reads call stacks and local variables, evaluates expressions, and continues or steps execution.

## Requirements

- Node.js 20 or newer for a source build.
- 1C:Enterprise HTTP debug server reachable from the machine running this MCP.
- A 1C client started in HTTP debug mode, for example:

  ```text
  /DEBUG -http -attach /DEBUGGERURL"http://debug-host:1550"
  ```

- An XML export of the matching configuration when resolving local `.bsl` paths for breakpoints.

## Run from source

```powershell
npm ci
npm test
npm start
```

The MCP transport is stdio. MCP Control Center can publish it through its existing worker and HTTP Gate.

## Release branch

The `release` branch is the portable runtime branch. It contains the bundled `server.cjs`, `mcp.json`, this README, and the license. The bundle does not require `npm install`; only Node.js 20+ is required.

## Typical tool sequence

1. `check_debug_server`
2. `connect_debugger` (save the returned `sessionId`)
3. `set_breakpoints`
4. Trigger the required action in 1C.
5. `poll_debug_events`
6. `get_call_stack`, `get_local_variables`, optionally `evaluate_expression`
7. `continue_or_step`
8. `disconnect_debugger`

Always continue or disconnect a stopped target so the 1C session is not left suspended.

## Debug sessions

The debugger session belongs to the MCP service, not to an individual Codex, chat, or HTTP client. Any client connected to the same MCP worker can use the active session. The current version allows one active infobase at a time; disconnect it before connecting or resuming another one.

- `list_debug_sessions` lists active and locally saved MCP-owned sessions.
- `get_debug_session_status` reports the owner process, computer, RDBG UI GUID, heartbeat, and targets.
- `resume_debug_session` restores a saved MCP-owned registration after an abnormal worker termination.
- Internally the session keeps a stable `sessionId`, allowing a future multi-infobase extension without changing its ownership model.

Session metadata is stored in `.generated/rdbg-sessions.json` beside the MCP `server` folder. Set `RDBG_SESSION_REGISTRY` to choose another location. The registry contains no 1C credentials. A normal `disconnect_debugger` or MCP shutdown removes the corresponding registration; a failed cleanup leaves it available for recovery.

The server never adopts an unknown debugger UI created by Designer or another debugger. RDBG does not expose enough ownership information to do that safely.

## Attribution

The RDBG protocol implementation was extracted and adapted from the MIT-licensed [DevTool1C](https://github.com/asweetand-a11y/DevTool1C) project.