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

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

Run directly:

npm start

Run in dev mode:

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:

{
  "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.