forge-cpp-mcp 0.3.0__tar.gz → 0.5.1__tar.gz

{forge_cpp_mcp-0.3.0 → forge_cpp_mcp-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forge-cpp-mcp
-Version: 0.3.0
+Version: 0.5.1
 Summary: A safe MCP server for structured C++ project development workflows.
 Project-URL: Homepage, https://github.com/hardened-steel/ForgeMCP
 Project-URL: Repository, https://github.com/hardened-steel/ForgeMCP
@@ -32,8 +32,8 @@ Description-Content-Type: text/markdown
 ForgeMCP is a Python MCP server for structured C and C++ development workflows.
 The repository contains workspace, process, toolchain, and initial CMake services.
 Clangd tools provide read-only analysis across CMake configurations with a shared
-result widget. External file reads ask for confirmation through MCP elicitation. Quality and
-debugger modules are planned.
+result widget. External file reads ask for confirmation through MCP elicitation.
+The debugger uses LLDB-DAP for native program control and dump inspection; Quality remains planned.
 
 ## Current MCP surface
 
@@ -47,6 +47,13 @@ debugger modules are planned.
   definitions, references, document symbols, and workspace symbols. Empty
   configuration selections use all available contexts.
 - No prompts are currently registered.
+- Debugger tools launch native programs, attach to local PIDs, and open user-mode
+  dumps through an explicitly selected LLDB-DAP toolset. They inspect threads,
+  stacks, variables, modules, exceptions, memory, and instructions with typed results.
+- Git tools inspect and modify the repository rooted at the workspace: status,
+  diffs, history, blame, branches/tags/remotes, staging, commits, restore, stash,
+  fetch/pull/push, merge/rebase/cherry-pick/revert, and conflict stages and continuation.
+  Every tool has typed data, plain text, a shared Git App, and process provenance.
 - CMake tools list operator profiles, configure projects, build targets, and run
   CTest. `cmake_run_test` directly runs a project/storage test executable with
   literal command-line arguments. Each tool has its own widget with Fields/JSON views,
@@ -80,6 +87,12 @@ without making additional tool calls. Process times are readable to seconds; JSO
 copying preserve the original precision. A toolsets list shows summaries, while a
 `toolset_get` result shows the details returned by that call.
 
+When a host restores chat history without `structuredContent`, widgets can recover
+the result from a single complete JSON object retained in a text content block,
+including a fenced JSON block. This supports older JSON tool responses; current
+plain-text responses alone cannot restore the structured result. Linked result
+resources still disappear when the server restarts.
+
 ForgeMCP can directly run an explicitly selected test executable inside the
 project or storage root; it does not expose shell commands or external executable
 paths over MCP. Feature services use
@@ -100,7 +113,7 @@ and install it in a virtual environment:
 
 ```powershell
 python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.3.0-py3-none-any.whl
+.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.5.1-py3-none-any.whl
 .\.venv\Scripts\forgemcp.exe --help
 ```
 
@@ -113,7 +126,7 @@ The distribution name is `forge-cpp-mcp`; the Python module and server command a
 After the package is published to PyPI, the install command can instead be:
 
 ```powershell
-.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.3.0
+.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.5.1
 ```
 
 ## Setup from source
@@ -187,11 +200,16 @@ Each instance tab offers:
   confirmation for commands initiated from the panel.
 
 Settings are read-only. Command controls start hidden; select **Enable command
-controls** to call an existing tool with literal JSON arguments; the catalog shows
-its input schema. These
+controls** to call an existing tool using fields generated from its input schema.
+JSON input remains available for complete arguments. Resource templates provide
+parameter fields and native MCP completion suggestions, using other entered
+parameters as context. These
 calls pass through the same SDK handlers, validation, and feature locks as stdio
 calls. There is no panel-wide execution queue. Existing modules decide which
 operations may run concurrently.
+Debugger tools are excluded from the admin command catalog and rejected by the
+admin bridge even when their names are submitted directly. They remain available
+to MCP clients; completed MCP results can still be reviewed in history.
 The panel can cancel its own running commands; calls initiated by an MCP client
 remain owned by that client.
 
@@ -399,9 +417,19 @@ no source preview because explicit external reads require confirmation.
 CMake owns which configurations can supply clangd compilation contexts. After a
 successful configure/generate, ForgeMCP reads `cmakeFiles-v1` from a new CMake
 File API reply and records SHA-256 hashes of that build directory's configuration
-inputs in `project/` and `storage/`. Hashes and dependency lists live in memory;
-restart the server and run `cmake_configure` to confirm contexts again. Existing
-File API replies and `compile_commands.json` alone do not confirm current inputs.
+inputs in `project/` and `storage/`. Hashes and dependency lists live in memory.
+Each server startup configures all effective profiles once in the background after
+toolset discovery and clangd subscription setup. MCP requests remain available;
+clangd receives contexts as individual profiles finish. Existing File API replies
+and `compile_commands.json` alone do not confirm current inputs.
+
+Startup uses the same configure settings, build-directory ownership checks,
+generator-change cleanup, and 600-second per-command timeout as `cmake_configure`.
+One failed profile does not stop the remaining profiles or the server. The admin
+panel's CMake monitor retains startup results, process IDs, and any batch error;
+command transcripts remain available through `process_get`. A second client of
+the same server does not repeat startup configuration. Server shutdown cancels
+and awaits startup configure before closing clangd and managed processes.
 
 Workspace writes, edits, moves, deletions, and directory creation check known
 inputs at the operation boundary. Actual input changes withdraw affected contexts
@@ -520,6 +548,160 @@ The initial CMake slice does not yet include clean/project-inspection tools
 or syntax highlighting. Unit and in-process MCP tests cover profiles,
 command parsing, generator changes, result resources, and qualified paths.
 
+## Debugging
+
+Install `lldb-dap` in a discovered toolset, or supply its absolute executable path
+with the existing `--toolset NAME lldb-dap=PATH` operator option. Use
+`debugger_adapters` to obtain the available adapter and toolset IDs. No adapter
+starts until `debugger_launch`, `debugger_attach`, or `debugger_open_dump` is called.
+Debugging does not require CMake or a compilation database and does not rebuild a program.
+
+`debugger_launch` takes a `toolset_id`, `options`, and optional `initial` breakpoint
+plan. `options.executable` and `options.cwd` are project/storage paths;
+`arguments` are literal strings. `stop_on_entry` defaults to true. For example:
+
+```json
+{
+  "toolset_id": "system",
+  "options": {
+    "executable": "storage/build/debug/app.exe",
+    "arguments": ["--example"],
+    "cwd": "project/"
+  },
+  "initial": {
+    "sources": [
+      {"source": "project/src/main.cpp", "points": [{"line": 20}]}
+    ]
+  }
+}
+```
+
+Attach supplies `options.pid`, an optional `expected_started_at` process birth
+time, and an optional managed `executable`. Dump inspection supplies
+`options.dump_file` and an optional matching executable. Both accept
+`source_mappings` and `symbol_directories`. Dump and symbol inputs must stay in
+project/storage. Source locations may name external `root/` files; the debugger
+does not read them automatically. Source locations are marked unverified against
+the loaded binary, so changed files are not presented as confirmed build-time source.
+PDB, DWARF, and dump compatibility depend on the installed LLDB build and target.
+
+Keep the returned `session_id`. `debugger_sessions` lists retained snapshots;
+`debugger_get` reads one without contacting the adapter. Each snapshot has one
+`status` field: null, `kind=stopped` with stop details, `kind=exited` with the
+confirmed target exit code, or `kind=failed` with a session failure message.
+Connection `phase` and `target_state` distinguish adapter failure, target execution,
+partial thread stops, and dump inspection.
+Each runtime retains at most 128 sessions, including closed sessions; restart it
+to release that history when the limit is reached.
+
+Launch, attach, `debugger_continue`, `debugger_step`, and `debugger_pause` return
+an execution reference. Pass it to `debugger_wait` with the same session ID.
+The wait returns a saved stop/terminal observation, or a timeout with the current
+snapshot; timeout and cancellation of a wait leave the target running. Execution
+observations are bounded and can expire. After an uncertain command outcome, read
+state before deciding whether to repeat a control operation.
+
+Construct a stop token from `session_id` and `inspection_generation` in a stopped
+snapshot. Use `debugger_threads`, `debugger_stack`, `debugger_scopes`, and
+`debugger_variables` to inspect state. Frame, variable, and memory handles belong
+to that session and generation; continuing execution invalidates them. Stack,
+variables, and modules accept bounded `page` windows. Memory and disassembly take
+explicit bounded counts. `debugger_exception_info` supplies supported exception
+details. Available operations and exception filters appear in `capabilities`.
+
+Errors identify the affected JSON field and link retained session and adapter
+process information. Use the suggested `debugger_get` and `process_get` calls to
+inspect an unconfirmed command before deciding on further execution. Invalid initial
+source paths are rejected before launching the target. Raw adapter error payloads,
+argument text, and environment values are kept out of error messages.
+Breakpoints are managed through `debugger_breakpoints`,
+`debugger_function_breakpoints`, and `debugger_exception_breakpoints`.
+Setting source or function breakpoints replaces the complete selected set.
+
+`debugger_close` terminates a program launched by that session, detaches from an
+attached program, or releases a dump. Its result distinguishes adapter closure
+from the confirmed target disposition. Server shutdown closes all debugger
+sessions before the process service. Each adapter's `adapter_process_id` identifies
+its retained transport transcript for `process_get`; that transcript contains DAP
+messages, including adapter output events. The module exposes no arbitrary
+debugger console, expression execution, memory/variable writes, terminal input,
+remote debugging, or kernel debugging.
+
+Every debugger tool has readable text, typed structured data, progress, an icon,
+and a result-only App. The App renders the saved invocation and performs no debugger
+calls. Debugger commands cannot be run from the admin panel.
+
+## Git operations
+
+Git uses the executable and environment of `--git-toolset ID_OR_NAME` (default:
+`system`). It must be installed in that toolset. ForgeMCP does not initialize,
+clone, create, move, or remove worktrees. Run one instance in each desired worktree;
+the admin panel exposes their independent tools and histories in separate tabs.
+The configured workspace must be the repository's worktree root. Linked worktrees
+work normally: Git itself accesses their shared repository metadata, without
+extending Workspace access to external source files.
+
+Read tools are `git_status`, `git_diff`, `git_log`, `git_show`, `git_blame`,
+`git_branches`, `git_tags`, `git_remotes`, and `git_conflicts`. `git_diff` selects
+`unstaged`, `staged`, or `revision` comparisons; revision comparisons require `base`
+and optionally `target`. Log pages return a resolved revision and `next_skip`;
+reuse both to keep pagination anchored. Show uses the first parent for merges.
+Conflict results include available base/ours/theirs object IDs, modes, and UTF-8
+text; binary or gitlink stages retain metadata without invented text.
+
+`git_stage(paths)`, `git_unstage(paths)`, and `git_restore(paths, source=null)` use
+explicit literal project paths. Restore discards working-file changes using the
+index or the selected committed source. `git_commit(message, amend=false)` commits
+the current index. `git_branch` creates/deletes local branches; force deletion is
+explicit. `git_switch` optionally creates a branch. `git_stash` supports list,
+save, apply, pop, and drop, returning one consistent action-result schema.
+
+`git_fetch` selects a configured remote and optionally prunes remote-tracking
+refs. `git_pull` defaults to fast-forward only; `strategy=merge` or `rebase` is
+explicit. These operations never automatically stash local changes. `git_push`
+pushes HEAD to one destination branch; replacing published history requires
+`expected_remote_oid`, used as an explicit force-with-lease expectation. No raw
+force-push or arbitrary Git command tool is exposed. Credentials come from the
+operator's Git/SSH configuration; tools do not accept passwords or tokens.
+
+`git_merge`, `git_rebase`, `git_cherry_pick`, and `git_revert` preserve unfinished
+operations. Cherry-pick/revert accept a mainline parent for merge commits.
+Resolve conflicts using Workspace tools, stage the resolutions, then call
+`git_continue(action=continue|abort|skip)`. Skip applies only to operations that
+support it. Normal installed Git hooks remain enabled. A nonzero command may
+leave conflicts or other partial changes: mutation results report `error`, actual
+resulting HEAD, unfinished operation, conflicts, and `process_ids`. Inspect status
+after interruption before deciding whether to retry. A secondary synchronization
+failure is reported separately from a successfully completed Git operation.
+
+Mutations share Workspace serialization and coordinate with CMake and clangd.
+CMake alone determines compilation-context eligibility and notifies clangd through
+its existing subscription. Source notifications combine Git dirty paths and
+committed tree changes; unknown changes use conservative invalidation. No external
+file watcher or cross-instance execution queue is added.
+Git snapshots the existence and types of tracked and nonignored untracked paths
+before and after mutations, retaining previous paths and explicitly selected file
+paths. Index/ref changes and commits, including `nothing to commit`, keep clangd
+sessions when working-file structure and CMake inputs remain unchanged. Actual
+path/type changes or an unknown outcome can invalidate contexts. Snapshots read no
+source contents, include at most 100,000 distinct paths, and do not track ignored-only
+changes or empty directories outside the catalog.
+
+Git output is bounded to 4 MiB per command; narrow the request when the limit is
+exceeded. Each command has a 300-second deadline and each request a 620-second
+deadline. Machine names/metadata must be UTF-8; patches explicitly report decoding
+replacement. Full process transcripts retain their existing ProcessService owner.
+`forgemcp://git/status` is the last captured status, not a live scan.
+`forgemcp://git/commits/{revision}` serves previously captured log/show metadata
+with completion over retained revisions. These snapshots, the Git monitor, and
+history disappear when the instance stops. The Git App displays one invocation:
+status separates staged and working changes, history puts commit messages first,
+and patches show file groups and line numbers with a wrap toggle. Blame keeps source
+and attribution together; conflict views distinguish base, ours, theirs, missing
+stages, and binary content. Errors and analysis-refresh warnings appear before
+the current repository state. Local search, expandable details, individual copying,
+and complete original JSON remain available; the widget never executes Git actions.
+
 ## Toolchain discovery
 
 Before serving requests, ForgeMCP discovers one System toolset from `PATH` and, on
@@ -553,7 +735,8 @@ Built-ins cover CMake, CTest, Ninja, Make, MSBuild, MSVC (`cl`), `link`, Clang,
 `cppvsdbg`. The last adapter may be found as `OpenDebugAD7.exe` or VS Code's bundled
 `vsdbg.exe`; it has no portable version probe. An unknown or failed version probe
 leaves the discovered path available with a null version. Version methods for `cl`,
-`link`, `cppvsdbg`, and `lldb-dap` are not implemented in this iteration.
+`link`, and `cppvsdbg` are not implemented. LLDB-DAP has a version probe and a
+typed framed connection used by debugger sessions.
 
 Toolsets are discovered once per server lifetime; restart to discover changed
 installations. Detail tools and resources query available versions on each request,
@@ -562,6 +745,29 @@ without caching them. Listing toolsets does not launch version probes. All probe
 overview and retain their transcripts. Toolset resources omit environments; the
 environment capture's stdout is retained in its ordinary process transcript.
 
+## Understanding tool errors
+
+Expected tool errors name the invalid argument or missing prerequisite and explain
+how to correct it. Small catalogs list available values; larger catalogs point to
+an existing listing tool such as `toolsets_list`, `cmake_profiles`,
+`clangd_configurations`, `processes_overview`, or `git_remotes`. Unknown argument
+names are rejected instead of being silently ignored, with spelling suggestions
+when possible. Process transcript selector errors describe their valid JSON forms.
+
+For example, an unknown profile identifies `profiles` and either lists its valid
+names or recommends `cmake_profiles()`. A bad edit identifies `old_text` and suggests
+reading the current file or choosing a unique fragment, without repeating source
+text. Toolset installation and profile configuration errors explicitly require
+operator setup; toolsets are discovered once at startup.
+
+When a command started, use its returned process ID with `process_get` to read its
+transcript. CMake profile failures and Git mutation failures remain in the result's
+`error` fields even when the MCP exchange itself succeeded. A mutation may have
+partially completed; inspect the returned state and `git_status` before repeating
+Git operations. A synchronization warning after a completed operation does not mean
+the commit or push should be repeated. Retained process and result-resource IDs
+belong to the current server process and disappear when it stops.
+
 ## Tests
 
 Tests that need a C/C++ workspace use the shared `cpp_acceptance_project` fixture from

{forge_cpp_mcp-0.3.0 → forge_cpp_mcp-0.5.1}/README.md

@@ -3,8 +3,8 @@
 ForgeMCP is a Python MCP server for structured C and C++ development workflows.
 The repository contains workspace, process, toolchain, and initial CMake services.
 Clangd tools provide read-only analysis across CMake configurations with a shared
-result widget. External file reads ask for confirmation through MCP elicitation. Quality and
-debugger modules are planned.
+result widget. External file reads ask for confirmation through MCP elicitation.
+The debugger uses LLDB-DAP for native program control and dump inspection; Quality remains planned.
 
 ## Current MCP surface
 
@@ -18,6 +18,13 @@ debugger modules are planned.
   definitions, references, document symbols, and workspace symbols. Empty
   configuration selections use all available contexts.
 - No prompts are currently registered.
+- Debugger tools launch native programs, attach to local PIDs, and open user-mode
+  dumps through an explicitly selected LLDB-DAP toolset. They inspect threads,
+  stacks, variables, modules, exceptions, memory, and instructions with typed results.
+- Git tools inspect and modify the repository rooted at the workspace: status,
+  diffs, history, blame, branches/tags/remotes, staging, commits, restore, stash,
+  fetch/pull/push, merge/rebase/cherry-pick/revert, and conflict stages and continuation.
+  Every tool has typed data, plain text, a shared Git App, and process provenance.
 - CMake tools list operator profiles, configure projects, build targets, and run
   CTest. `cmake_run_test` directly runs a project/storage test executable with
   literal command-line arguments. Each tool has its own widget with Fields/JSON views,
@@ -51,6 +58,12 @@ without making additional tool calls. Process times are readable to seconds; JSO
 copying preserve the original precision. A toolsets list shows summaries, while a
 `toolset_get` result shows the details returned by that call.
 
+When a host restores chat history without `structuredContent`, widgets can recover
+the result from a single complete JSON object retained in a text content block,
+including a fenced JSON block. This supports older JSON tool responses; current
+plain-text responses alone cannot restore the structured result. Linked result
+resources still disappear when the server restarts.
+
 ForgeMCP can directly run an explicitly selected test executable inside the
 project or storage root; it does not expose shell commands or external executable
 paths over MCP. Feature services use
@@ -71,7 +84,7 @@ and install it in a virtual environment:
 
 ```powershell
 python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.3.0-py3-none-any.whl
+.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.5.1-py3-none-any.whl
 .\.venv\Scripts\forgemcp.exe --help
 ```
 
@@ -84,7 +97,7 @@ The distribution name is `forge-cpp-mcp`; the Python module and server command a
 After the package is published to PyPI, the install command can instead be:
 
 ```powershell
-.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.3.0
+.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.5.1
 ```
 
 ## Setup from source
@@ -158,11 +171,16 @@ Each instance tab offers:
   confirmation for commands initiated from the panel.
 
 Settings are read-only. Command controls start hidden; select **Enable command
-controls** to call an existing tool with literal JSON arguments; the catalog shows
-its input schema. These
+controls** to call an existing tool using fields generated from its input schema.
+JSON input remains available for complete arguments. Resource templates provide
+parameter fields and native MCP completion suggestions, using other entered
+parameters as context. These
 calls pass through the same SDK handlers, validation, and feature locks as stdio
 calls. There is no panel-wide execution queue. Existing modules decide which
 operations may run concurrently.
+Debugger tools are excluded from the admin command catalog and rejected by the
+admin bridge even when their names are submitted directly. They remain available
+to MCP clients; completed MCP results can still be reviewed in history.
 The panel can cancel its own running commands; calls initiated by an MCP client
 remain owned by that client.
 
@@ -370,9 +388,19 @@ no source preview because explicit external reads require confirmation.
 CMake owns which configurations can supply clangd compilation contexts. After a
 successful configure/generate, ForgeMCP reads `cmakeFiles-v1` from a new CMake
 File API reply and records SHA-256 hashes of that build directory's configuration
-inputs in `project/` and `storage/`. Hashes and dependency lists live in memory;
-restart the server and run `cmake_configure` to confirm contexts again. Existing
-File API replies and `compile_commands.json` alone do not confirm current inputs.
+inputs in `project/` and `storage/`. Hashes and dependency lists live in memory.
+Each server startup configures all effective profiles once in the background after
+toolset discovery and clangd subscription setup. MCP requests remain available;
+clangd receives contexts as individual profiles finish. Existing File API replies
+and `compile_commands.json` alone do not confirm current inputs.
+
+Startup uses the same configure settings, build-directory ownership checks,
+generator-change cleanup, and 600-second per-command timeout as `cmake_configure`.
+One failed profile does not stop the remaining profiles or the server. The admin
+panel's CMake monitor retains startup results, process IDs, and any batch error;
+command transcripts remain available through `process_get`. A second client of
+the same server does not repeat startup configuration. Server shutdown cancels
+and awaits startup configure before closing clangd and managed processes.
 
 Workspace writes, edits, moves, deletions, and directory creation check known
 inputs at the operation boundary. Actual input changes withdraw affected contexts
@@ -491,6 +519,160 @@ The initial CMake slice does not yet include clean/project-inspection tools
 or syntax highlighting. Unit and in-process MCP tests cover profiles,
 command parsing, generator changes, result resources, and qualified paths.
 
+## Debugging
+
+Install `lldb-dap` in a discovered toolset, or supply its absolute executable path
+with the existing `--toolset NAME lldb-dap=PATH` operator option. Use
+`debugger_adapters` to obtain the available adapter and toolset IDs. No adapter
+starts until `debugger_launch`, `debugger_attach`, or `debugger_open_dump` is called.
+Debugging does not require CMake or a compilation database and does not rebuild a program.
+
+`debugger_launch` takes a `toolset_id`, `options`, and optional `initial` breakpoint
+plan. `options.executable` and `options.cwd` are project/storage paths;
+`arguments` are literal strings. `stop_on_entry` defaults to true. For example:
+
+```json
+{
+  "toolset_id": "system",
+  "options": {
+    "executable": "storage/build/debug/app.exe",
+    "arguments": ["--example"],
+    "cwd": "project/"
+  },
+  "initial": {
+    "sources": [
+      {"source": "project/src/main.cpp", "points": [{"line": 20}]}
+    ]
+  }
+}
+```
+
+Attach supplies `options.pid`, an optional `expected_started_at` process birth
+time, and an optional managed `executable`. Dump inspection supplies
+`options.dump_file` and an optional matching executable. Both accept
+`source_mappings` and `symbol_directories`. Dump and symbol inputs must stay in
+project/storage. Source locations may name external `root/` files; the debugger
+does not read them automatically. Source locations are marked unverified against
+the loaded binary, so changed files are not presented as confirmed build-time source.
+PDB, DWARF, and dump compatibility depend on the installed LLDB build and target.
+
+Keep the returned `session_id`. `debugger_sessions` lists retained snapshots;
+`debugger_get` reads one without contacting the adapter. Each snapshot has one
+`status` field: null, `kind=stopped` with stop details, `kind=exited` with the
+confirmed target exit code, or `kind=failed` with a session failure message.
+Connection `phase` and `target_state` distinguish adapter failure, target execution,
+partial thread stops, and dump inspection.
+Each runtime retains at most 128 sessions, including closed sessions; restart it
+to release that history when the limit is reached.
+
+Launch, attach, `debugger_continue`, `debugger_step`, and `debugger_pause` return
+an execution reference. Pass it to `debugger_wait` with the same session ID.
+The wait returns a saved stop/terminal observation, or a timeout with the current
+snapshot; timeout and cancellation of a wait leave the target running. Execution
+observations are bounded and can expire. After an uncertain command outcome, read
+state before deciding whether to repeat a control operation.
+
+Construct a stop token from `session_id` and `inspection_generation` in a stopped
+snapshot. Use `debugger_threads`, `debugger_stack`, `debugger_scopes`, and
+`debugger_variables` to inspect state. Frame, variable, and memory handles belong
+to that session and generation; continuing execution invalidates them. Stack,
+variables, and modules accept bounded `page` windows. Memory and disassembly take
+explicit bounded counts. `debugger_exception_info` supplies supported exception
+details. Available operations and exception filters appear in `capabilities`.
+
+Errors identify the affected JSON field and link retained session and adapter
+process information. Use the suggested `debugger_get` and `process_get` calls to
+inspect an unconfirmed command before deciding on further execution. Invalid initial
+source paths are rejected before launching the target. Raw adapter error payloads,
+argument text, and environment values are kept out of error messages.
+Breakpoints are managed through `debugger_breakpoints`,
+`debugger_function_breakpoints`, and `debugger_exception_breakpoints`.
+Setting source or function breakpoints replaces the complete selected set.
+
+`debugger_close` terminates a program launched by that session, detaches from an
+attached program, or releases a dump. Its result distinguishes adapter closure
+from the confirmed target disposition. Server shutdown closes all debugger
+sessions before the process service. Each adapter's `adapter_process_id` identifies
+its retained transport transcript for `process_get`; that transcript contains DAP
+messages, including adapter output events. The module exposes no arbitrary
+debugger console, expression execution, memory/variable writes, terminal input,
+remote debugging, or kernel debugging.
+
+Every debugger tool has readable text, typed structured data, progress, an icon,
+and a result-only App. The App renders the saved invocation and performs no debugger
+calls. Debugger commands cannot be run from the admin panel.
+
+## Git operations
+
+Git uses the executable and environment of `--git-toolset ID_OR_NAME` (default:
+`system`). It must be installed in that toolset. ForgeMCP does not initialize,
+clone, create, move, or remove worktrees. Run one instance in each desired worktree;
+the admin panel exposes their independent tools and histories in separate tabs.
+The configured workspace must be the repository's worktree root. Linked worktrees
+work normally: Git itself accesses their shared repository metadata, without
+extending Workspace access to external source files.
+
+Read tools are `git_status`, `git_diff`, `git_log`, `git_show`, `git_blame`,
+`git_branches`, `git_tags`, `git_remotes`, and `git_conflicts`. `git_diff` selects
+`unstaged`, `staged`, or `revision` comparisons; revision comparisons require `base`
+and optionally `target`. Log pages return a resolved revision and `next_skip`;
+reuse both to keep pagination anchored. Show uses the first parent for merges.
+Conflict results include available base/ours/theirs object IDs, modes, and UTF-8
+text; binary or gitlink stages retain metadata without invented text.
+
+`git_stage(paths)`, `git_unstage(paths)`, and `git_restore(paths, source=null)` use
+explicit literal project paths. Restore discards working-file changes using the
+index or the selected committed source. `git_commit(message, amend=false)` commits
+the current index. `git_branch` creates/deletes local branches; force deletion is
+explicit. `git_switch` optionally creates a branch. `git_stash` supports list,
+save, apply, pop, and drop, returning one consistent action-result schema.
+
+`git_fetch` selects a configured remote and optionally prunes remote-tracking
+refs. `git_pull` defaults to fast-forward only; `strategy=merge` or `rebase` is
+explicit. These operations never automatically stash local changes. `git_push`
+pushes HEAD to one destination branch; replacing published history requires
+`expected_remote_oid`, used as an explicit force-with-lease expectation. No raw
+force-push or arbitrary Git command tool is exposed. Credentials come from the
+operator's Git/SSH configuration; tools do not accept passwords or tokens.
+
+`git_merge`, `git_rebase`, `git_cherry_pick`, and `git_revert` preserve unfinished
+operations. Cherry-pick/revert accept a mainline parent for merge commits.
+Resolve conflicts using Workspace tools, stage the resolutions, then call
+`git_continue(action=continue|abort|skip)`. Skip applies only to operations that
+support it. Normal installed Git hooks remain enabled. A nonzero command may
+leave conflicts or other partial changes: mutation results report `error`, actual
+resulting HEAD, unfinished operation, conflicts, and `process_ids`. Inspect status
+after interruption before deciding whether to retry. A secondary synchronization
+failure is reported separately from a successfully completed Git operation.
+
+Mutations share Workspace serialization and coordinate with CMake and clangd.
+CMake alone determines compilation-context eligibility and notifies clangd through
+its existing subscription. Source notifications combine Git dirty paths and
+committed tree changes; unknown changes use conservative invalidation. No external
+file watcher or cross-instance execution queue is added.
+Git snapshots the existence and types of tracked and nonignored untracked paths
+before and after mutations, retaining previous paths and explicitly selected file
+paths. Index/ref changes and commits, including `nothing to commit`, keep clangd
+sessions when working-file structure and CMake inputs remain unchanged. Actual
+path/type changes or an unknown outcome can invalidate contexts. Snapshots read no
+source contents, include at most 100,000 distinct paths, and do not track ignored-only
+changes or empty directories outside the catalog.
+
+Git output is bounded to 4 MiB per command; narrow the request when the limit is
+exceeded. Each command has a 300-second deadline and each request a 620-second
+deadline. Machine names/metadata must be UTF-8; patches explicitly report decoding
+replacement. Full process transcripts retain their existing ProcessService owner.
+`forgemcp://git/status` is the last captured status, not a live scan.
+`forgemcp://git/commits/{revision}` serves previously captured log/show metadata
+with completion over retained revisions. These snapshots, the Git monitor, and
+history disappear when the instance stops. The Git App displays one invocation:
+status separates staged and working changes, history puts commit messages first,
+and patches show file groups and line numbers with a wrap toggle. Blame keeps source
+and attribution together; conflict views distinguish base, ours, theirs, missing
+stages, and binary content. Errors and analysis-refresh warnings appear before
+the current repository state. Local search, expandable details, individual copying,
+and complete original JSON remain available; the widget never executes Git actions.
+
 ## Toolchain discovery
 
 Before serving requests, ForgeMCP discovers one System toolset from `PATH` and, on
@@ -524,7 +706,8 @@ Built-ins cover CMake, CTest, Ninja, Make, MSBuild, MSVC (`cl`), `link`, Clang,
 `cppvsdbg`. The last adapter may be found as `OpenDebugAD7.exe` or VS Code's bundled
 `vsdbg.exe`; it has no portable version probe. An unknown or failed version probe
 leaves the discovered path available with a null version. Version methods for `cl`,
-`link`, `cppvsdbg`, and `lldb-dap` are not implemented in this iteration.
+`link`, and `cppvsdbg` are not implemented. LLDB-DAP has a version probe and a
+typed framed connection used by debugger sessions.
 
 Toolsets are discovered once per server lifetime; restart to discover changed
 installations. Detail tools and resources query available versions on each request,
@@ -533,6 +716,29 @@ without caching them. Listing toolsets does not launch version probes. All probe
 overview and retain their transcripts. Toolset resources omit environments; the
 environment capture's stdout is retained in its ordinary process transcript.
 
+## Understanding tool errors
+
+Expected tool errors name the invalid argument or missing prerequisite and explain
+how to correct it. Small catalogs list available values; larger catalogs point to
+an existing listing tool such as `toolsets_list`, `cmake_profiles`,
+`clangd_configurations`, `processes_overview`, or `git_remotes`. Unknown argument
+names are rejected instead of being silently ignored, with spelling suggestions
+when possible. Process transcript selector errors describe their valid JSON forms.
+
+For example, an unknown profile identifies `profiles` and either lists its valid
+names or recommends `cmake_profiles()`. A bad edit identifies `old_text` and suggests
+reading the current file or choosing a unique fragment, without repeating source
+text. Toolset installation and profile configuration errors explicitly require
+operator setup; toolsets are discovered once at startup.
+
+When a command started, use its returned process ID with `process_get` to read its
+transcript. CMake profile failures and Git mutation failures remain in the result's
+`error` fields even when the MCP exchange itself succeeded. A mutation may have
+partially completed; inspect the returned state and `git_status` before repeating
+Git operations. A synchronization warning after a completed operation does not mean
+the commit or push should be repeated. Retained process and result-resource IDs
+belong to the current server process and disappear when it stops.
+
 ## Tests
 
 Tests that need a C/C++ workspace use the shared `cpp_acceptance_project` fixture from

forge_cpp_mcp-0.5.1/frontend/debugger-result.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Debugger result</title>
+  </head>
+  <body>
+    <main id="widget" aria-label="Debugger result"></main>
+    <script type="module" src="/src/debugger-result.js"></script>
+  </body>
+</html>

forge_cpp_mcp-0.5.1/frontend/git-result.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Git result</title>
+  </head>
+  <body>
+    <main id="widget" aria-label="Git result"></main>
+    <script type="module" src="/src/git-result.js"></script>
+  </body>
+</html>

{forge_cpp_mcp-0.3.0 → forge_cpp_mcp-0.5.1}/frontend/package-lock.json

@@ -7,6 +7,7 @@
       "name": "forgemcp-widgets",
       "dependencies": {
         "@modelcontextprotocol/ext-apps": "^1.7.5",
+        "@modelcontextprotocol/sdk": "^1.30.0",
         "markdown-it": "^15.0.2"
       },
       "devDependencies": {

{forge_cpp_mcp-0.3.0 → forge_cpp_mcp-0.5.1}/frontend/package.json

@@ -3,11 +3,12 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "build": "vite build --mode workspace && vite build --mode file && vite build --mode search && vite build --mode result && vite build --mode process && vite build --mode process-details && vite build --mode toolsets && vite build --mode cmake-profiles && vite build --mode cmake-configure && vite build --mode cmake-build && vite build --mode cmake-test && vite build --mode cmake-run-test && vite build --mode clangd && vite build --mode admin && vite build --mode sandbox",
+    "build": "vite build --mode workspace && vite build --mode file && vite build --mode search && vite build --mode result && vite build --mode process && vite build --mode process-details && vite build --mode toolsets && vite build --mode cmake-profiles && vite build --mode cmake-configure && vite build --mode cmake-build && vite build --mode cmake-test && vite build --mode cmake-run-test && vite build --mode clangd && vite build --mode git-result && vite build --mode debugger-result && vite build --mode admin && vite build --mode sandbox",
     "test": "node --test tests/*.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "markdown-it": "^15.0.2"
   },
   "devDependencies": {