ahk-mcp

Efficiently discover available AHK tools without loading all 35+ tool definitions upfront. Progressive tool discovery reduces initial token usage from 17,500-70,000 tokens to 50-1,000 tokens based on detail level.

Examples: • List all file tools: { category: "file", detailLevel: "names" } - Returns only tool names (~50 tokens) • Search for analysis tools: { category: "analysis", detailLevel: "summary" } - Returns names + brief descriptions (~200 tokens) • Find tools with keyword: { keyword: "edit", detailLevel: "summary" } - Returns matching tools • Get full details: { category: "file", detailLevel: "full" } - Returns complete tool definitions (~1000+ tokens)

Categories:

• file: File operations (view, edit, create, detect)

• analysis: Code analysis and diagnostics

• execution: Script running and debugging

• docs: Documentation search and context

• library: Library management (list, info, import)

• system: System configuration and settings

Detail Levels:

• names: Just tool names (minimal tokens)

• summary: Names + brief descriptions (medium tokens)

• full: Complete tool definitions with all parameters (high tokens)

Use Cases: • Initial exploration: Use "names" or "summary" to see what's available • Targeted search: Use keyword to find specific functionality • Full details: Use "full" only when you need complete parameter schemas

See also: AHK_Config (system configuration), AHK_Analytics (usage analytics)

Analyze→fix→verify→run workflow in one call. Fix types: syntax, style, performance, all. Use dryRun to preview, summaryOnly for minimal tokens.

Ahk process request Process user requests that contain file paths and instructions for AutoHotkey scripts

Orchestrates AHK file operations with smart caching. Chains detect→analyze→view/edit. Operations: view, edit, analyze.

Ahk file DETECT AND SET ACTIVE FILE FOR EDITING - Use this immediately when user mentions any .ahk file path. This enables all other editing tools to work on the specified file. Essential first step before any file modifications.

📎 Active File: Not set. Use AHK_File_Active to select a target.

View AHK files with structure analysis. Modes: structured (default), raw, summary, outline. Supports line ranges and syntax highlighting.

📎 Active File: Not set. Use AHK_File_Active to select a target.

List AHK files with optional name search. Use nameFilter with wildcards (e.g., "Hotstring") to find specific files.

📎 Active File: Not set. Use AHK_File_Active to select a target.

Ahk auto file Automatically detect and set active AutoHotkey file from user text

📎 Active File: Not set. Use AHK_File_Active to select a target.

Ahk recent scripts List the most recent AutoHotkey scripts from configured directories. Supports overriding A_ScriptDir.

📎 Active File: Not set. Use AHK_File_Active to select a target.

Ahk file editor PRIMARY FILE EDITING TOOL - Use this IMMEDIATELY when user mentions a .ahk file path and wants to modify it. This tool automatically detects the file, sets it active, and helps determine the best editing approach. ALWAYS use this instead of generating code blocks when a file path is provided.

📎 Active File: Not set. Use AHK_File_Active to select a target.

Primary AutoHotkey file editor for direct on-disk modifications. Handles search/replace, line inserts, deletes, appends, prepends, and even new file creation. Supports regex, automatic backups, dry-run previews, and optional script execution after edits.

Common Usage

{
  "action": "replace",
  "search": "oldClassName",
  "newContent": "NewClassName",
  "filePath": "C:\\Scripts\\MyAutomation.ahk"
}

Batch Replace with Regex (Preview First)

{
  "action": "replace",
  "search": "class\\s+(\\w+)",
  "newContent": "class Refactored$1",
  "regex": true,
  "all": true,
  "dryRun": true
}

Shows a DRY RUN report instead of touching the file.

Create New Script

{
  "action": "create",
  "filePath": "C:\\AHK\\Helpers\\ClipboardTools.ahk",
  "newContent": "class ClipboardTools {\n    __New() {\n        ; init\n    }\n}"
}

What to Avoid

• Using deprecated "content" parameter - migrate to "newContent"

• Running batch replacements without dryRun: true first

• Disabling backups on production files unless absolutely necessary

See also: AHK_File_Edit_Advanced, AHK_File_Edit_Small, AHK_File_View, AHK_Smart_Orchestrator

📎 Active File: Not set. Use AHK_File_Active to select a target.

Create a new AutoHotkey v2 script on disk with full path interception support.

• Validates .ahk extension (case-insensitive) • Automatically creates parent directories (configurable) • Prevents accidental overwrite unless explicitly allowed • Supports dry-run previews and active file management

📎 Active File: Not set. Use AHK_File_Active to select a target.

Token-efficient editor for small, targeted changes. Ideal when you need a lightweight replace or line edit without loading the full diff engine. Supports regex and literal replacements, multi-file batches, optional diff previews, and dry-run mode.

Common Replace

{
  "action": "replace_literal",
  "file": "C:\\Scripts\\MyScript.ahk",
  "find": "Sleep(500)",
  "replace": "Sleep(100)"
}

Insert Before a Line (Preview)

{
  "action": "line_insert_before",
  "file": "C:\\Scripts\\TrayMenu.ahk",
  "line": 42,
  "newContent": "    TrayTip(\"Menu refreshed\")",
  "dryRun": true
}

Multi-File Regex Replace

{
  "action": "replace_regex",
  "files": ["core.ahk", "ui.ahk"],
  "find": "SetTimer\\((\\w+), 5000\\)",
  "replace": "SetTimer($1, 10000)",
  "all": true
}

What to Avoid

• Mixing deprecated "content" parameter with newContent - prefer newContent

• Running multi-file edits without dryRun: true to preview

• Forgetting backup: true when touching critical scripts

See also: AHK_File_Edit (full-featured editor), AHK_File_Edit_Diff (complex diffs), AHK_File_Edit_Advanced

📎 Active File: Not set. Use AHK_File_Active to select a target.

Ahk analyze Analyzes AutoHotkey v2 scripts and provides contextual information about functions, variables, classes, and other elements used in the code. Accepts direct code or a file path (falls back to active file).

Ahk context injector Analyzes user prompts and LLM thinking to automatically inject relevant AutoHotkey v2 documentation context.

Ahk vscode problems Reads a VS Code Problems list (from file or provided JSON) and summarizes AutoHotkey LSP diagnostics.

Lint AHK v2 scripts. Levels: fast (syntax), standard (default, +structure), thorough (+semantics). Supports autoFix with dryRun preview.

Document symbols via THQBY AutoHotkey v2 LSP (vscode-autohotkey2-lsp). Returns classes, methods, functions, variables, hotkeys, and labels using the external LSP server. Accepts direct code or a file path (falls back to active file).

AHK Prompts Returns a set of built-in AHK v2 prompt templates for code generation and learning.

Ahk doc search Full-text search across AutoHotkey v2 docs using FlexSearch (functions, variables, classes, methods).

Ahk debug agent Starts a TCP listener for AutoHotkey /Debug and optionally proxies to a real debug adapter while capturing traffic.

Validate AHK v2 code with optional watch mode for auto-validation on save.

Modes:

• validate: One-shot validation of code snippet

• watch: Auto-validate file on every save

Examples:

• Validate code: { "code": "MsgBox(\"Hi\")\nExitApp" }

• Validate file: { "filePath": "C:\\Scripts\\test.ahk" }

• Start watching: { "mode": "watch", "filePath": "C:\\Scripts\\test.ahk" }

• Stop watching: { "mode": "watch", "enabled": false }

Error Patterns Detected:

• Syntax errors (line number + message)

• Runtime errors (Error, ValueError, TypeError, etc.)

• Unset variable references

AutoHotkey v2 debugger via DBGp protocol. Enables autonomous debugging: capture errors, analyze them, and auto-apply fixes.

Actions:

• start: Start DBGp listener (waits for AHK /Debug connection)

• stop: Stop DBGp listener

• status: Get connection status

• run: Continue execution

• step_into/step_over/step_out: Step debugging

• capture_error: Wait for next error with full context

• analyze_error: Build analysis prompt from error

• apply_fix: Auto-apply code fix to file

• list_errors/clear_errors: Manage error queue

• get_source: Get source lines around a line

• breakpoint_set/remove/list: Manage breakpoints

• variables_get: Get variables (context: 0=local, 1=global)

• evaluate: Evaluate expression

• stack_trace: Get call stack

Ahk config Get/Set MCP configuration for script directories, AutoHotkey executable path, and VS Code workspace.

Open the most recently edited AutoHotkey file (or a specified file) in VS Code. Defaults to the last edited file recorded by MCP and falls back to the active file. Supports WSL environments and can target a specific workspace window.

Ahk settings Manage tool settings and enable/disable features

Provides LSP-like analysis and auto-fixing for AutoHotkey v2 code. Accepts direct code or a file path (falls back to active file).

View tool usage analytics and performance metrics. Track success rates, execution times, common errors, and usage patterns across all MCP tools. Actions: summary (overall stats), tool_stats (specific tool), recent (recent calls), export (JSON data), clear (reset). Use to diagnose tool issues or optimize workflows.

List and search AutoHotkey libraries in the catalog. Search by query string or filter by category. Returns library names with descriptions.

Get detailed information about a specific AutoHotkey library. Returns metadata, documentation, classes, functions, and dependencies.

Generate #Include statements for importing a library. Resolves dependencies and provides correct import order. Supports different #Include formats (angle-brackets, relative, absolute).

Search for symbols (classes, methods, functions, properties) across all AutoHotkey libraries. Uses fuzzy matching to find symbols by partial name. Automatically scans standard AHK library paths: • ScriptDir\Lib (active file's directory) • Documents\AutoHotkey\Lib • Program Files\AutoHotkey\v2\Lib

Examples: • Find clipboard utilities: { query: "clipboard" } • Find all classes: { query: "Manager", types: ["class"] } • Find methods by name: { query: "OnClick", types: ["method"] } • Show library locations: { query: "Gui", showPaths: true }