forge-cpp-mcp 0.2.5__tar.gz → 0.5.0__tar.gz

{forge_cpp_mcp-0.2.5 → forge_cpp_mcp-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forge-cpp-mcp
-Version: 0.2.5
+Version: 0.5.0
 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
@@ -12,8 +12,12 @@ License-File: LICENSE
 Requires-Python: >=3.13
 Requires-Dist: markdown-it-py>=4.0
 Requires-Dist: mcp[cli]==2.1.1
+Requires-Dist: psutil<8,>=7.2
 Requires-Dist: pydantic>=2.13
+Requires-Dist: pywin32>=311; sys_platform == 'win32'
 Requires-Dist: regex>=2024.11.6
+Requires-Dist: starlette>=0.48.0
+Requires-Dist: uvicorn>=0.31.1
 Provides-Extra: build
 Requires-Dist: build>=1.3; extra == 'build'
 Provides-Extra: dev
@@ -28,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
 
@@ -43,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,
@@ -96,19 +107,20 @@ and install it in a virtual environment:
 
 ```powershell
 python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.2.5-py3-none-any.whl
+.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.5.0-py3-none-any.whl
 .\.venv\Scripts\forgemcp.exe --help
 ```
 
 The wheel includes the compiled HTML widgets and icons. No npm commands or separate
-frontend deployment are needed. CMake, Ninja, compilers, and clangd are external
+frontend deployment are needed. It also packages the local admin panel and its
+isolated widget host. CMake, Ninja, compilers, and clangd are external
 tools: install the ones needed by your workflows separately.
 The distribution name is `forge-cpp-mcp`; the Python module and server command are `forgemcp`.
 
 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.2.5
+.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.5.0
 ```
 
 ## Setup from source
@@ -152,6 +164,80 @@ builds the wheel first and then starts the server for this repository.
 
 All MCP traffic uses stdout. Operational logs must go to stderr.
 
+## Local admin panel
+
+Normal CLI launches automatically join one admin Hub for the current OS user.
+Each server remains an independent stdio process with its own workspace,
+environment, toolsets, processes, and clangd sessions. The Hub presents them as
+separate browser tabs; it does not move their services into a shared process.
+
+Open the panel while at least one server is running:
+
+```powershell
+forgemcp --open-admin
+```
+
+This command retrieves the private browser URL through same-user local IPC and
+opens the system browser, then exits. The startup message contains the public
+address and this command; the authentication token is never printed. Opening the
+public address in a new browser session alone does not authenticate that session.
+
+Each instance tab offers:
+
+- tool-call history from both MCP clients and the browser, with original arguments,
+  results, progress, timestamps, and errors;
+- the original MCP App widget, text fallback, and complete JSON result;
+- tool schemas, static resources, resource templates, and resource reading;
+- startup settings, process status, discovered toolsets, CMake configurations,
+  and retained clangd sessions;
+- browser responses to SDK elicitation requests, including external-file read
+  confirmation for commands initiated from the panel.
+
+Settings are read-only. Command controls start hidden; select **Enable command
+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.
+
+The panel listens on `127.0.0.1`, preferring port 8765 and choosing a free port when
+that port is unavailable. Widgets use a second loopback port for their isolated
+host. The Hub stops shortly after the last server session ends; browser tabs do
+not keep it running. A temporary IPC disconnect is shown as reconnecting while
+the underlying server process remains alive. Lost tool calls are never replayed
+automatically; read the instance history after reconnecting before repeating one.
+
+History and linked widget result resources live only in the server's memory.
+Stopping that server loses its history; there is no database or disk archive.
+Process transcripts retain their existing in-memory lifecycle and are not copied
+into a separate admin log.
+
+Use these operator options when needed:
+
+```powershell
+forgemcp --no-admin
+forgemcp --admin-port 9000
+forgemcp --admin-ipc forgemcp-other
+forgemcp --open-admin --admin-ipc forgemcp-other
+```
+
+`--no-admin` opts that instance out of the panel. `--admin-port` is a preference
+when starting a new Hub; it does not change an already running Hub's port.
+Instances using the same `--admin-ipc` name share a Hub; a different name creates
+a separate group for the same OS user.
+
+The normal wheel build includes `admin.html` and `sandbox.html` alongside the MCP
+widgets. After changing frontend source, use the documented wheel build or
+`npm run build --prefix frontend`. An unbuilt source checkout returns an explicit
+missing-assets page until those files are generated.
+
 ## Connect Codex or Claude Code
 
 After [installation](#install-a-release) or [source setup](#setup-from-source), copy the appropriate example into the root of the C/C++
@@ -325,9 +411,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
@@ -446,6 +542,153 @@ 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 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
@@ -479,7 +722,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,
@@ -488,6 +732,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