ahk-mcp

AHK_File_Edit_Small

Destructive

Make targeted edits to AutoHotkey files with regex or literal replacements, line operations, multi-file batches, and optional previews for lightweight modifications.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`action`	No	Edit action to perform (default: replace_literal for safe string matching)	replace_literal
`file`	No	Target file to edit. Defaults to the active file when omitted.
`files`	No	Apply the same edit to multiple files.
`find`	No	Text (or pattern) to search for when using replace actions.
`replace`	No	Replacement text for replace actions.
`regexFlags`	No	Additional RegExp flags (e.g. "i" for case-insensitive).
`all`	No	Replace all occurrences (false = first only).
`line`	No	Line number for line-based actions (1-based).
`startLine`	No	Start line for range operations (1-based).
`endLine`	No	End line for range delete or replace (1-based, inclusive).
`content`	No	⚠️ Deprecated alias for newContent. Prefer newContent for new text.
`newContent`	No	Content to insert or replace when using line actions. Example: "MsgBox(\"Done\")".
`preview`	No	Show a unified diff instead of writing to disk.
`dryRun`	No	Preview changes without modifying file. Shows affected lines and change count.
`backup`	No	Create a .bak backup before writing changes.
`runAfter`	No	Run the script after edits complete (single file only).

Tool Definition Quality

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate destructiveHint=true and readOnlyHint=false, which the description aligns with by discussing file modifications. The description adds valuable behavioral context beyond annotations: it explains the tool supports regex/literal replacements, multi-file batches, optional diff previews, dry-run mode, backup recommendations, and active file dependencies. It doesn't contradict annotations but provides rich operational details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (introduction, examples, warnings, see-also), but could be more concise. The examples are helpful but lengthy, and some information (like the active file note) might be redundant with schema details. Overall it's efficiently organized but slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (16 parameters, destructive operations) and the absence of an output schema, the description provides excellent contextual completeness. It covers purpose, usage guidelines, behavioral traits, parameter examples, warnings, and sibling tool relationships. The combination of annotations and detailed description gives the agent sufficient information to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema already documents all 16 parameters thoroughly. The description adds minimal parameter semantics through example JSON snippets that illustrate common usage patterns, but doesn't provide significant additional meaning beyond what's in the schema. This meets the baseline expectation for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as a 'token-efficient editor for small, targeted changes' and distinguishes it from siblings by specifying it's 'ideal when you need a lightweight replace or line edit without loading the full diff engine.' It explicitly mentions sibling tools AHK_File_Edit, AHK_File_Edit_Diff, and AHK_File_Edit_Advanced for comparison, providing clear differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool ('lightweight replace or line edit without loading the full diff engine') and when not to use it ('What to Avoid' section lists specific pitfalls). It names alternative tools (AHK_File_Edit, AHK_File_Edit_Diff, AHK_File_Edit_Advanced) and includes context about the active file requirement, offering comprehensive usage instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/TrueCrimeDev/ahk-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server