# ntop-ai-helper-mcp

MCP server that helps troubleshoot nTop issues with:

- AI diagnosis (`diagnose_ntop_error`)
- 20-agent parallel swarm mode (`swarm_diagnose_ntop`)
- Screen capture (`capture_screen`)
- Macro automation (`save_macro`, `list_macros`, `run_macro`)
- Optional direct terminal execution (`run_terminal_command`)

## Quick Start

```powershell
cd "$HOME\Documents\ntop-ai-helper-mcp"
npm install
npm run build
```

Run directly:

```powershell
npm start
```

Run in dev mode:

```powershell
npm run dev
```

## Environment Variables

Copy `.env.example` to `.env` and set values:

- `OPENAI_API_KEY` (required for real AI diagnosis/swarm)
- `OPENAI_MODEL` (default: `gpt-5.2`)
- `ENABLE_COMMAND_TOOL` (`false` by default; set to `true` to allow shell command tool)

## MCP Client Config Example

Use the built server file as the MCP command target:

```json
{
  "mcpServers": {
    "ntop-ai-helper": {
      "command": "node",
      "args": [
        "C:\\Users\\sohum\\Documents\\ntop-ai-helper-mcp\\dist\\server.js"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_KEY_HERE",
        "OPENAI_MODEL": "gpt-5.2",
        "ENABLE_COMMAND_TOOL": "false"
      }
    }
  }
}
```

## Tools

- `capture_screen`
  - Inputs: `label?`
  - Output: file path to PNG in `captures/`

- `list_macros`
  - Inputs: none
  - Output: all macros from `data/macros.json`

- `save_macro`
  - Inputs: `name`, `description?`, `steps[]`
  - Step types:
    - `sleep`: `{ "type": "sleep", "ms": 500 }`
    - `sendKeys`: `{ "type": "sendKeys", "keys": "^l" }`
    - `command`: `{ "type": "command", "command": "dir" }`

- `run_macro`
  - Inputs: `name`, `dryRun?`
  - Executes macro step-by-step and returns a run report

- `diagnose_ntop_error`
  - Inputs: `errorText`, `context?`, `goal?`
  - Uses OpenAI if available; otherwise local fallback heuristics

- `swarm_diagnose_ntop`
  - Inputs: `errorText`, `context?`, `goal?`, `agentCount?`
  - Runs up to 40 agents in parallel (default 20), plus final synthesis

- `run_terminal_command`
  - Inputs: `command`, `cwd?`, `timeoutMs?`
  - Disabled by default for safety

## Notes

- Screen capture and `sendKeys` are Windows-oriented.
- Macro steps are intentionally explicit for predictable automation.
- If you want stricter safety, keep `ENABLE_COMMAND_TOOL=false`.