Merge pull request #20 from microsoft/user/oribarilan/docs_and_agentsmd

Docs and AGENTS.md

Author: oribarilan

AGENTS.md

@@ -1,30 +1,94 @@
 # Agent Guidelines for DebugMCP
 
+## Project Overview
+
+DebugMCP is a VS Code extension that embeds an MCP (Model Context Protocol) server, enabling AI coding agents to control VS Code's debugger via DAP (Debug Adapter Protocol). AI agents can start/stop debugging, step through code, set breakpoints, inspect variables, and evaluate expressions.
+
+### Architecture
+
+```
+AI Agent (Cline/Copilot/Cursor) → MCP/SSE → DebugMCPServer → DebuggingHandler → DebuggingExecutor → VS Code Debug API
+```
+
+### Key Components
+
+| Component | Responsibility | Docs |
+|-----------|----------------|------|
+| `DebugMCPServer` | MCP server, tool/resource registration | [docs/architecture/debugMCPServer.md](docs/architecture/debugMCPServer.md) |
+| `DebuggingHandler` | Operation orchestration, state change detection | [docs/architecture/debuggingHandler.md](docs/architecture/debuggingHandler.md) |
+| `DebuggingExecutor` | VS Code debug API calls, DAP requests | [docs/architecture/debuggingExecutor.md](docs/architecture/debuggingExecutor.md) |
+| `DebugState` | Debug session state model | [docs/architecture/debugState.md](docs/architecture/debugState.md) |
+| `DebugConfigurationManager` | Launch configs, language detection | [docs/architecture/debugConfigurationManager.md](docs/architecture/debugConfigurationManager.md) |
+| `AgentConfigurationManager` | AI agent auto-configuration | [docs/architecture/agentConfigurationManager.md](docs/architecture/agentConfigurationManager.md) |
+
+## Documentation Maintenance
+
+**IMPORTANT**: Keep `docs/*.md` files up to date when modifying components. These docs should remain high-level:
+- Purpose and motivation
+- Responsibility scope
+- Key concepts and patterns
+- Pointers to relevant code sections
+
+Do NOT duplicate detailed implementation in docs - that information should be inferred from the code itself.
+
 ## File Header
-Include the following header in each source file (adjust comment syntax as needed).
-`// Copyright (c) Microsoft Corporation.`
+
+Include in each source file:
+```typescript
+// Copyright (c) Microsoft Corporation.
+```
 
 ## Build/Lint/Test Commands
-- **Compile**: `npm run compile` - Compiles TypeScript to JavaScript in `out/` directory
-- **Lint**: `npm run lint` - Runs ESLint on `src/` directory
-- **Test**: `npm test` - Runs all tests (compiles + lints first via pretest)
-- **Single Test**: Use VSCode Test Explorer or `npm test` (no CLI test filtering available)
-- **Watch Mode**: `npm run watch` - Compiles TypeScript in watch mode
+
+| Command | Description |
+|---------|-------------|
+| `npm run compile` | Compile TypeScript to `out/` |
+| `npm run lint` | Run ESLint on `src/` |
+| `npm test` | Run all tests (`src/test/*.test.ts`) |
+| `npm run watch` | Compile in watch mode |
 
 ## Code Style & Conventions
-- **TypeScript**: Strict mode enabled, target ES2022, Node16 modules
-- **Imports**: Use camelCase/PascalCase naming. Import order: vscode → external → internal (e.g., `./utils/logger`)
-- **Naming**: camelCase for variables/functions, PascalCase for classes/interfaces, prefix interfaces with `I` (e.g., `IDebuggingHandler`)
-- **Types**: Explicit types preferred, use strict null checks, avoid `any` unless necessary
-- **Error Handling**: Use try-catch with descriptive error messages, throw `Error` objects (not literals)
-- **Formatting**: Use semicolons, curly braces for all control structures, consistent indentation (tabs)
-- **Async**: Use async/await, handle promises properly, implement exponential backoff for retries
-- **VSCode API**: Import as `import * as vscode from 'vscode'`, use proper disposal in `context.subscriptions`
-- **Logging**: Use `logger` from `./utils/logger` for all logging (info/error/warn)
-- **Dependencies**: fastmcp (MCP server), express (HTTP), zod (validation), @modelcontextprotocol/sdk
-
-## Architecture Notes
-- VSCode extension with MCP server for AI agent debugging capabilities
-- Main entry: `extension.ts` → activates MCP server and registers commands
-- Core: `debuggingHandler.ts` handles debug operations, `debuggingExecutor.ts` executes VSCode debug API calls
-- State: `debugState.ts` tracks current debugging session state
+
+- **TypeScript**: Strict mode, ES2022 target, Node16 modules
+- **Imports**: vscode → external packages → internal modules
+- **Naming**: camelCase (variables/functions), PascalCase (classes/interfaces), `I` prefix for interfaces
+- **Types**: Explicit types preferred, strict null checks, avoid `any`
+- **Error Handling**: try-catch with descriptive messages, throw `Error` objects
+- **Formatting**: Semicolons, curly braces for all control structures, tabs for indentation
+- **Async**: async/await, exponential backoff for retries
+- **Logging**: Use `logger` from `./utils/logger` (not `console.log`). Simple wrapper providing `info`, `warn`, `error` methods with consistent formatting.
+- **VS Code API**: Import as `import * as vscode from 'vscode'`
+
+## Key Dependencies
+
+- `fastmcp`: MCP server framework
+- `zod`: Schema validation for tool parameters
+- `@modelcontextprotocol/sdk`: MCP protocol types
+- `express`: HTTP server (used by FastMCP)
+
+## Entry Points
+
+- **Extension activation**: `src/extension.ts` → `activate()`
+- **MCP endpoint**: `http://localhost:{port}/sse` (default port: 3001)
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `debugmcp.serverPort` | 3001 | MCP server port |
+| `debugmcp.timeoutInSeconds` | 180 | Operation timeout |
+
+## Documentation Resources
+
+The `docs/` folder contains two types of documentation:
+
+**Component docs** (referenced in Key Components table above): Developer documentation for understanding the codebase architecture.
+
+**AI Agent resources** (served via MCP at runtime):
+
+| File | Purpose |
+|------|---------|
+| `agent-resources/debug_instructions.md` | Core debugging workflow guide for AI agents |
+| `agent-resources/troubleshooting/*.md` | Language-specific debugging tips (Python, JavaScript, Java, C#) |
+
+These resource files are loaded by `DebugMCPServer` and exposed as MCP resources that AI agents can read to learn how to use the debugging tools effectively.

docs/debug_instructions.md …cs/agent-resources/debug_instructions.mddocs/debug_instructions.md renamed to docs/agent-resources/debug_instructions.md docs/debug_instructions.md renamed to docs/agent-resources/debug_instructions.md

@@ -2,10 +2,10 @@
 
 ⚠️  **CRITICAL INSTRUCTIONS - FOLLOW THESE STEPS:**
 1. **FIRST:** Use 'add_breakpoint' to set an initial breakpoint at a starting point
-1. **THEN:** Optionally use 'add_breakpoint' to set breakpoints at strategic points
-2. **THEN:** Use 'start_debugging' tool to start debugging
-3. **THEN:** Use repetitively all the other tools to navigate and inspect step by step
-3. **FINALLY:** Get to the problematic line to fully understand the root cause. If needed, restart the debug session using restart_debugging.
+2. **THEN:** Optionally use 'add_breakpoint' to set breakpoints at strategic points
+3. **THEN:** Use 'start_debugging' tool to start debugging
+4. **THEN:** Use repetitively all the other tools to navigate and inspect step by step
+5. **FINALLY:** Get to the problematic line to fully understand the root cause. If needed, restart the debug session using restart_debugging.
 
 ## 🚨 ROOT CAUSE ANALYSIS - CRITICAL FRAMEWORK
 

docs/agent-resources/troubleshooting/cpp.md

@@ -0,0 +1,78 @@
+# C/C++ Debugging Tips
+
+**C/C++-SPECIFIC GUIDANCE:**
+
+## Prerequisites:
+- Use C/C++ extension for VS Code (by Microsoft)
+- Ensure GDB or LLDB debugger is installed
+- Compile with debug symbols (`-g` flag)
+- Set breakpoints in `.c`, `.cpp`, `.cc`, `.h`, `.hpp` files
+- Use 'cppdbg' debug configuration type
+
+## C/C++-Specific Best Practices:
+- **Compilation:** Always compile with `-g` flag and disable optimizations (`-O0`) for debugging
+- **Memory Issues:** Watch for buffer overflows, memory leaks, and dangling pointers
+- **Pointers:** Carefully inspect pointer values and dereferenced contents
+- **Stack Frames:** Use call stack to trace function calls and local variables
+- **Core Dumps:** Enable core dumps for post-mortem debugging of crashes
+
+## Common C++ Debug Configurations:
+
+### GDB (Linux/Windows with MinGW):
+```json
+{
+    "type": "cppdbg",
+    "request": "launch",
+    "name": "Debug with GDB",
+    "program": "${fileDirname}/${fileBasenameNoExtension}",
+    "args": [],
+    "stopAtEntry": false,
+    "cwd": "${fileDirname}",
+    "environment": [],
+    "externalConsole": false,
+    "MIMode": "gdb",
+    "setupCommands": [
+        {
+            "description": "Enable pretty-printing for gdb",
+            "text": "-enable-pretty-printing",
+            "ignoreFailures": true
+        }
+    ]
+}
+```
+
+### LLDB (macOS):
+```json
+{
+    "type": "cppdbg",
+    "request": "launch",
+    "name": "Debug with LLDB",
+    "program": "${fileDirname}/${fileBasenameNoExtension}",
+    "args": [],
+    "stopAtEntry": false,
+    "cwd": "${fileDirname}",
+    "environment": [],
+    "externalConsole": false,
+    "MIMode": "lldb"
+}
+```
+
+## Debugging Tips:
+- Use `printf()` or `std::cout` for quick debugging
+- Watch for uninitialized variables
+- Check array bounds carefully
+- Be aware of undefined behavior from pointer arithmetic
+- Use address sanitizer (`-fsanitize=address`) to detect memory errors
+- Use valgrind for memory leak detection (Linux)
+
+## Common Issues:
+- **"Unable to start debugging":** Ensure executable is compiled with debug symbols
+- **"No symbol table":** Recompile with `-g` flag
+- **Breakpoints grayed out:** Source file doesn't match compiled binary - rebuild
+- **Segmentation fault:** Use backtrace to find the crashing line, check pointer operations
+- **Optimized away variables:** Compile with `-O0` to disable optimizations
+
+## Memory Debugging:
+- **Valgrind:** `valgrind --leak-check=full ./program`
+- **Address Sanitizer:** Compile with `-fsanitize=address -fno-omit-frame-pointer`
+- **Watch expressions:** Monitor pointer values and array indices during stepping

docs/troubleshooting/csharp.md …gent-resources/troubleshooting/csharp.mddocs/troubleshooting/csharp.md renamed to docs/agent-resources/troubleshooting/csharp.md docs/troubleshooting/csharp.md renamed to docs/agent-resources/troubleshooting/csharp.md

@@ -0,0 +1,52 @@
+# Go Debugging Tips
+
+**GO-SPECIFIC GUIDANCE:**
+
+## Prerequisites:
+- Use Go extension for VS Code (by Go Team at Google)
+- Ensure Delve debugger is installed (`go install github.com/go-delve/delve/cmd/dlv@latest`)
+- Set breakpoints in `.go` files
+- Use 'go' debug configuration type
+- Check GOPATH and GOROOT environment variables
+
+## Go-Specific Best Practices:
+- **Build Tags:** Ensure correct build tags are set for debugging
+- **Goroutines:** Be aware that goroutines run concurrently - use breakpoints in each goroutine you want to inspect
+- **Interfaces:** When debugging interface values, check both the type and value
+- **Defer Statements:** Remember deferred functions execute in LIFO order at function return
+- **Channels:** Set breakpoints at channel send/receive operations to debug concurrency
+
+## Common Go Debug Configurations:
+```json
+{
+    "type": "go",
+    "request": "launch",
+    "name": "Launch Package",
+    "mode": "debug",
+    "program": "${fileDirname}"
+}
+```
+
+## Test Debugging:
+```json
+{
+    "type": "go",
+    "request": "launch",
+    "name": "Launch Test",
+    "mode": "test",
+    "program": "${fileDirname}",
+    "args": ["-test.run", "TestFunctionName"]
+}
+```
+
+## Debugging Tips:
+- Use `fmt.Printf()` or `log.Printf()` for quick debugging
+- Watch for `nil` pointer dereferences
+- Be aware of value vs pointer receivers on methods
+- Check error return values - Go's explicit error handling is a common source of bugs
+- Use race detector (`go run -race`) to find data races before debugging
+
+## Common Issues:
+- **"could not launch process":** Ensure Delve is installed and in PATH
+- **Breakpoints not hit:** Check build mode (debug vs release) and ensure optimizations are disabled
+- **Goroutine confusion:** Use the Call Stack panel to switch between goroutines

docs/agent-resources/troubleshooting/go.md

@@ -0,0 +1,76 @@
+# AgentConfigurationManager
+
+## Purpose
+
+Handles automatic configuration of AI coding agents (Cline, GitHub Copilot, Cursor) to connect to the DebugMCP server. Provides a seamless onboarding experience.
+
+## Motivation
+
+For AI agents to use DebugMCP, they need MCP server configuration in their settings files. Rather than requiring users to manually edit JSON files, this manager auto-configures supported agents with the correct SSE endpoint.
+
+## Responsibility
+
+- Detect supported AI agents and their config file paths
+- Show post-install popup for agent selection
+- Write MCP server configuration to agent settings files
+- Handle cross-platform config path differences (Windows, macOS, Linux)
+- Track whether onboarding popup has been shown
+
+## Supported Agents
+
+| Agent | Config File | MCP Field |
+|-------|-------------|-----------|
+| Cline | `cline_mcp_settings.json` | `mcpServers` |
+| GitHub Copilot | `mcp.json` | `servers` |
+| Cursor | `mcp_settings.json` | `mcpServers` |
+
+## Key Concepts
+
+### Cross-Platform Paths
+
+Config base paths vary by OS:
+- **Windows**: `%APPDATA%` (e.g., `C:\Users\X\AppData\Roaming`)
+- **macOS**: `~/Library/Application Support`
+- **Linux**: `$XDG_CONFIG_HOME` or `~/.config`
+
+### MCP Server Configuration
+
+The configuration written to agent settings:
+```json
+{
+  "debugmcp": {
+    "autoApprove": [],
+    "disabled": false,
+    "timeout": 180,
+    "type": "sse",
+    "url": "http://localhost:3001/sse"
+  }
+}
+```
+
+### Popup State
+
+Uses VS Code's `globalState` to track whether the onboarding popup has been shown, preventing repeated prompts on every activation.
+
+## Key Code Locations
+
+- Class definition: `src/utils/agentConfigurationManager.ts`
+- Agent definitions: `getSupportedAgents()`
+- Config writing: `addDebugMCPToAgent()`
+- Path detection: `getConfigBasePath()`
+- Popup logic: `shouldShowPopup()`, `showAgentSelectionPopup()`
+
+## User Flow
+
+1. Extension activates
+2. Check if popup was previously shown
+3. If not, display multi-select dialog with supported agents
+4. For each selected agent, write/update config file
+5. Show success message with option to open config file
+6. Mark popup as shown
+
+## Commands
+
+- `debugmcp.showAgentSelectionPopup`: Manually trigger agent setup
+- `debugmcp.configureAgents`: Alternative manual configuration
+- `debugmcp.resetPopupState`: Reset for testing (re-shows popup)