AutoHotkey v2 MCP Server

Un servidor MCP de TypeScript para el desarrollo con AutoHotkey v2. Proporciona análisis de scripts, operaciones con archivos, búsqueda de documentación y herramientas de ejecución de scripts para clientes MCP como Claude Desktop.

Arquitectura

Related MCP server: Hotkeyless AHK MCP

Características destacadas

• Más de 25 herramientas AHK_* para flujos de trabajo de AutoHotkey

• Descubrimiento de archivos enfocado y operaciones conscientes del archivo activo

• Ejecución de scripts con seguimiento de procesos y detección de ventanas

• Herramientas locales de validación y diagnóstico de AutoHotkey

• Documentación integrada de AutoHotkey y asistentes de prompt/contexto

• Transportes Stdio y HTTP Streamable (con o sin estado), además de endpoints SSE heredados

• Autenticación opcional con token Bearer y protección contra DNS-rebinding para el modo HTTP

Requisitos

• Node.js 18+

• npm

• AutoHotkey v2 (para las herramientas de ejecución/validación)

Instalación

git clone https://github.com/truecrimedev/ahk-mcp.git
cd ahk-mcp
npm install
npm run build

Ejecución

npm start

Modo de desarrollo:

npm run dev

Prueba de humo:

npm run smoke:mcp

Modo HTTP y variables de entorno

npm start usa stdio (Claude Desktop). Para exponer HTTP Streamable en /mcp (además de los endpoints SSE heredados), establece PORT o pasa --sse:

npm run start:sse

El comportamiento se controla con variables de entorno:

Nota de seguridad: la superficie de herramientas incluye escritura de archivos y ejecución de procesos. Si el puerto HTTP es accesible desde cualquier otra cosa que no sea tu propia máquina, establece AHK_MCP_AUTH_TOKEN (p. ej. openssl rand -hex 32) y las dos listas de permitidos; por defecto, los endpoints aceptan cualquier solicitud.

Consulta docs/MCP_TRANSPORT_COMPATIBILITY.md para el flujo de sesión, los detalles del modo sin estado y ejemplos de cURL.

Configuración de Claude Desktop

Añade esto a claude_desktop_config.json:

{
  "mcpServers": {
    "ahk": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\YourUsername\\path\\to\\ahk-mcp\\dist\\index.js"],
      "env": {
        "NODE_ENV": "production",
        "AHK_MCP_LOG_LEVEL": "warn"
      }
    }
  }
}

Usa rutas absolutas y escapa las barras invertidas en JSON.

Configurar la ruta de AutoHotkey y el comportamiento de inicio

Usa AHK_Config para establecer la ruta del ejecutable y el comportamiento de inicio no bloqueante:

{
  "action": "set",
  "ahkPath": "C:\\Users\\YourUsername\\Documents\\Design\\Coding\\AutoHotkey\\bin\\AutoHotkey64.exe",
  "waitForStdoutLine": true,
  "stdoutLineTimeoutMs": 300
}

Esto lo usan AHK_Run (y la resolución de rutas de AHK_Cloud_Validate).

Herramientas principales

• AHK_Smart_Orchestrator: reduce los flujos de trabajo de edición/análisis en varios pasos

• AHK_File_List, AHK_File_View, AHK_File_Edit: operaciones con archivos

• AHK_Analyze, AHK_Diagnostics: análisis y diagnósticos

• AHK_Run: ejecuta scripts (espera, sin espera, detección de ventanas)

• AHK_Cloud_Validate: validación basada en ejecución local

• AHK_Doc_Search, AHK_Tools_Search: búsqueda de documentación y herramientas

• AHK_Config: configuración del servidor MCP

Comandos de desarrollo

npm run build
npm run clean
npm run lint
npm run test
npm run test:integration
npm run smoke:mcp

Documentación

• docs/README.md

• docs/QUICK_START.md

• docs/QUICKREFERENCE.md

• docs/MCP_TRANSPORT_COMPATIBILITY.md

• docs/ARCHITECTURE_DIAGRAMS.md

• docs/RELEASE_NOTES.md

Contribuciones

Consulta CONTRIBUTING.md y AGENTS.md.

Licencia

MIT. Consulta LICENSE.