Skip to content

Commit df1d052

Browse files
CapulusCodeNinjaCapulusCodeNinja
committed
Add two list commands to help the ai clients
1 parent fbe5cf0 commit df1d052

File tree

15 files changed

+1329
-26
lines changed

15 files changed

+1329
-26
lines changed

‎README.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -111,18 +111,23 @@ Architecture, testing, contribution guide
111111

112112
> 📖 **Detailed setup instructions:** [🔧 CONFIGURATION.md](docs/CONFIGURATION.md)
113113
114-
## 🛠 Available Tools (8 tools)
114+
## 🛠 Available Tools (10 tools)
115115

116116
### Windows Debugging Tools
117117
- **Crash Dump Analysis**: `nexus_open_dump_analyze_session`, `nexus_close_dump_analyze_session`
118+
- **Session Management**: `nexus_list_dump_analyze_sessions`, `nexus_list_dump_analyze_session_async_commands`
118119
- **Remote Debugging**: `nexus_start_remote_debug`, `nexus_stop_remote_debug`
119120
- **Async Command Queue**: `nexus_dump_analyze_session_async_command`, `nexus_dump_analyze_session_async_command_status`, `nexus_debugger_command_cancel`, `nexus_list_debugger_commands`
120121

121-
**🔄 Async Workflow with Notifications:**
122+
**🔄 Complete Debugging Workflow:**
122123
```bash
123-
1. nexus_dump_analyze_session_async_command → Returns commandId
124-
2. Listen for notifications/commandStatus → Real-time progress
125-
3. OR poll nexus_dump_analyze_session_async_command_status → Get results
124+
1. nexus_open_dump_analyze_session → Create session, returns sessionId
125+
2. nexus_dump_analyze_session_async_command → Queue command, returns commandId
126+
3. Listen for notifications/commandStatus → Real-time progress updates
127+
4. nexus_dump_analyze_session_async_command_status → Get final results
128+
5. nexus_list_dump_analyze_sessions → List all active sessions
129+
6. nexus_list_dump_analyze_session_async_commands → List commands for session
130+
7. nexus_close_dump_analyze_session → Clean up resources
126131
```
127132

128133
> 📖 **Complete tool reference with examples:** **[📋 TOOLS.md](docs/TOOLS.md)**

‎docs/TOOLS.md‎

Lines changed: 69 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,38 +2,100 @@
22

33
> 🏠 **[← Back to Main README](../README.md)** | 📚 **Other Docs:** [🔧 Configuration](CONFIGURATION.md) | [🤖 Integration](INTEGRATION.md) | [👨‍💻 Development](DEVELOPMENT.md)
44
5-
## Debugging Tools (8 tools)
5+
## Debugging Tools (10 tools)
66

77
Windows debugging capabilities through WinDBG/CDB integration:
88

99
### Core Debugging Commands
1010
- **Crash Dump Analysis**: `nexus_open_dump_analyze_session`, `nexus_close_dump_analyze_session`
11+
- **Session Management**: `nexus_list_dump_analyze_sessions`, `nexus_list_dump_analyze_session_async_commands`
1112
- **Remote Debugging**: `nexus_start_remote_debug`, `nexus_stop_remote_debug`
1213
- **Command Execution**: `nexus_dump_analyze_session_async_command` (🔄 ASYNC QUEUE: Always returns commandId, use `nexus_dump_analyze_session_async_command_status` for results)
1314
- **Queue Management**: `nexus_dump_analyze_session_async_command_status`, `nexus_debugger_command_cancel`, `nexus_list_debugger_commands`
1415

15-
### 🔄 Async Command Execution Workflow
16+
### 🔄 Complete Debugging Workflow
1617

1718
**IMPORTANT**: All WinDBG commands use an async queue system with real-time notifications:
1819

1920
```bash
20-
1. Call nexus_dump_analyze_session_async_command {"command": "!analyze -v"}
21-
→ Returns: {"commandId": "abc-123", "status": "queued", ...}
21+
1. nexus_open_dump_analyze_session {"dumpPath": "C:\\crash.dmp"}
22+
→ Returns: {"sessionId": "sess-000001-abc12345-12345678-0001", ...}
2223

23-
2. Listen for real-time notifications:
24+
2. nexus_dump_analyze_session_async_command {"sessionId": "sess-000001-abc12345-12345678-0001", "command": "!analyze -v"}
25+
→ Returns: {"commandId": "cmd-000001-abc12345-12345678-0001", "status": "queued", ...}
26+
27+
3. Listen for real-time notifications:
2428
→ notifications/commandStatus: {"status": "executing", "progress": 25, ...}
2529
→ notifications/commandHeartbeat: {"elapsed": "30s", ...} (for long commands)
2630
→ notifications/commandStatus: {"status": "completed", "result": "ACTUAL_OUTPUT"}
2731

28-
3. OR poll nexus_dump_analyze_session_async_command_status {"commandId": "abc-123"}
32+
4. OR poll nexus_dump_analyze_session_async_command_status {"commandId": "cmd-000001-abc12345-12345678-0001"}
2933
→ Returns: {"status": "executing", ...} (keep polling)
3034
→ Returns: {"status": "completed", "result": "ACTUAL_OUTPUT"}
3135

32-
4. Extract the "result" field for your WinDBG command output
36+
5. nexus_list_dump_analyze_sessions {} (optional)
37+
→ Returns: {"sessions": [...]} - List all active sessions
38+
39+
6. nexus_list_dump_analyze_session_async_commands {"sessionId": "sess-000001-abc12345-12345678-0001"} (optional)
40+
→ Returns: {"commands": [...]} - List all commands for this session
41+
42+
7. nexus_close_dump_analyze_session {"sessionId": "sess-000001-abc12345-12345678-0001"}
43+
→ Returns: {"success": true, ...} - Clean up resources
3344
```
3445

3546
**⚠️ CRITICAL**: `nexus_dump_analyze_session_async_command` NEVER returns command results directly. You MUST use `nexus_dump_analyze_session_async_command_status` to get results or listen for notifications!
3647

48+
### 📋 Session Management Commands
49+
50+
#### `nexus_list_dump_analyze_sessions`
51+
Lists all active debugging sessions with detailed information.
52+
53+
**Parameters:** None
54+
55+
**Returns:**
56+
```json
57+
{
58+
"success": true,
59+
"operation": "nexus_list_dump_analyze_sessions",
60+
"message": "Found 2 active sessions",
61+
"sessions": [
62+
{
63+
"sessionId": "sess-000001-abc12345-12345678-0001",
64+
"dumpFile": "crash.dmp",
65+
"status": "Active",
66+
"createdAt": "2024-09-26 23:15:30 UTC",
67+
"lastActivity": "2024-09-26 23:20:15 UTC",
68+
"commandsProcessed": 5,
69+
"activeCommands": 2
70+
}
71+
]
72+
}
73+
```
74+
75+
#### `nexus_list_dump_analyze_session_async_commands`
76+
Lists all async commands for a specific session.
77+
78+
**Parameters:**
79+
- `sessionId` (required): The exact sessionId from `nexus_open_dump_analyze_session`
80+
81+
**Returns:**
82+
```json
83+
{
84+
"success": true,
85+
"operation": "nexus_list_dump_analyze_session_async_commands",
86+
"message": "Command listing for session: sess-000001-abc12345-12345678-0001",
87+
"commands": [
88+
{
89+
"commandId": "cmd-000001-abc12345-12345678-0001",
90+
"command": "!analyze -v",
91+
"status": "completed",
92+
"queuedAt": "2024-09-26 23:15:30 UTC",
93+
"completedAt": "2024-09-26 23:15:45 UTC"
94+
}
95+
]
96+
}
97+
```
98+
3799
## 📡 Real-Time Notifications
38100

39101
The server sends live notifications about command progress:

‎mcp_nexus/CommandQueue/CommandQueueService.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -399,7 +399,7 @@ private async Task ProcessCommandQueue()
399399
{
400400
m_logger.LogError(ex, "Error executing command {CommandId}: {Command}", queuedCommand.Id, queuedCommand.Command);
401401

402-
// IMPROVED: Better error handling with detailed error information
402+
// STANDARDIZED: Consistent error message formatting
403403
var errorMessage = ex switch
404404
{
405405
OperationCanceledException => "Command execution was cancelled",

‎mcp_nexus/Debugger/CdbSession.cs‎

Lines changed: 83 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1112,15 +1112,91 @@ public void Dispose()
11121112
logger.LogInformation("Disposing active CDB session...");
11131113
try
11141114
{
1115-
// Don't use StopSession() as it would call ThrowIfDisposed()
1116-
// Just do the basic cleanup
1115+
// IMPROVED: Proper process disposal with timeout and exception handling
11171116
lock (m_lifecycleLock)
11181117
{
1119-
m_debuggerProcess?.Dispose();
1120-
m_debuggerInput?.Dispose();
1121-
m_debuggerOutput?.Dispose();
1122-
m_debuggerError?.Dispose();
1123-
m_isActive = false;
1118+
try
1119+
{
1120+
// Try to gracefully terminate the process first
1121+
if (m_debuggerProcess != null && !m_debuggerProcess.HasExited)
1122+
{
1123+
logger.LogDebug("Attempting graceful process termination...");
1124+
try
1125+
{
1126+
m_debuggerProcess.CloseMainWindow();
1127+
1128+
// Wait for graceful shutdown with timeout
1129+
if (!m_debuggerProcess.WaitForExit(5000)) // 5 second timeout
1130+
{
1131+
logger.LogWarning("Process did not exit gracefully, forcing termination...");
1132+
m_debuggerProcess.Kill();
1133+
m_debuggerProcess.WaitForExit(2000); // 2 second timeout for kill
1134+
}
1135+
}
1136+
catch (Exception ex)
1137+
{
1138+
logger.LogWarning(ex, "Error during graceful process termination, forcing kill...");
1139+
try
1140+
{
1141+
m_debuggerProcess.Kill();
1142+
m_debuggerProcess.WaitForExit(2000);
1143+
}
1144+
catch (Exception killEx)
1145+
{
1146+
logger.LogError(killEx, "Error forcing process termination");
1147+
}
1148+
}
1149+
}
1150+
}
1151+
catch (Exception ex)
1152+
{
1153+
logger.LogError(ex, "Error during process termination");
1154+
}
1155+
finally
1156+
{
1157+
// Always dispose resources, even if process termination failed
1158+
try
1159+
{
1160+
m_debuggerProcess?.Dispose();
1161+
}
1162+
catch (Exception ex)
1163+
{
1164+
logger.LogWarning(ex, "Error disposing process");
1165+
}
1166+
1167+
try
1168+
{
1169+
m_debuggerInput?.Dispose();
1170+
}
1171+
catch (Exception ex)
1172+
{
1173+
logger.LogWarning(ex, "Error disposing input stream");
1174+
}
1175+
1176+
try
1177+
{
1178+
m_debuggerOutput?.Dispose();
1179+
}
1180+
catch (Exception ex)
1181+
{
1182+
logger.LogWarning(ex, "Error disposing output stream");
1183+
}
1184+
1185+
try
1186+
{
1187+
m_debuggerError?.Dispose();
1188+
}
1189+
catch (Exception ex)
1190+
{
1191+
logger.LogWarning(ex, "Error disposing error stream");
1192+
}
1193+
1194+
m_debuggerProcess = null;
1195+
m_debuggerInput = null;
1196+
m_debuggerOutput = null;
1197+
m_debuggerError = null;
1198+
m_isActive = false;
1199+
}
11241200
}
11251201
}
11261202
catch (Exception ex)

0 commit comments

Comments
 (0)