自动键鼠-MCP

Name: 自动键鼠-MCP
Author: 012090120901209

作者：0120901209012096 星标更新：2025-11-15

项目介绍

<div align="center"> <h1>AutoHotkey v2 MCP 服务器</h1> <p> <strong>模型上下文协议</strong> </p> <p> <a href="#features"><img src="https://img.shields.io/badge/特性-blue?style=for-the-badge" alt="特性"></a> <a href="#installation"><img src="https://img.shields.io/badge/安装-green?style=for-the-badge" alt="安装"></a> <a href="#usage"><img src="https://img.shields.io/badge/用法-purple?style=for-the-badge" alt="用法"></a> <a href="#development"><img src="https://img.shields.io/badge/开发-orange?style=for-the-badge" alt="开发"></a> </p> </div>

[!IMPORTANT] 更新于 10/1/25: GitHub Spec Kit 集成完成！ 项目现在遵循规范驱动开发，具有宪法框架、架构决策记录和全面规划模板。所有工具的可靠性改进和类型安全性增强。

概述

AutoHotkey v2 MCP 服务器通过模型上下文协议提供了全面的 AutoHotkey v2 开发工具。功能包括智能代码分析、文件管理、脚本执行以及针对处理 AutoHotkey 代码的大型语言模型的上下文感知辅助。

该项目遵循规范驱动开发，使用 GitHub 的 Spec Kit 框架。请参阅 .specify/ 目录中的架构决策、规范和开发模板。

示例

一个过于简单的例子：

用户请求剪贴板管理工具：
大型语言模型创建计划，其中包括以下步骤：

用户希望我创建一个 AutoHotkey v2 的剪贴板管理脚本。让我分解一下需求：
核心功能：
监控剪贴板更改
在 GUI 中显示收集的条目
使用 F6 快捷键切换收集
关闭时将内容保存回剪贴板

MCP 从关键词中抓取这些词：剪贴板、GUI、切换、快捷键
MCP 发送更详细的上下文。对于剪贴板，这将是这样的：

用户的剪贴板可以通过内置变量 A_Clipboard 访问。如果用户的需求涉及确定剪贴板值是否已更改，请使用 OnClipboardChanged 函数对象。如果用户需要临时保存剪贴板内容，请使用 Clipboard all。操作完成后，脚本恢复原始剪贴板内容。

大型语言模型然后返回具有更高准确性的代码。

规范驱动开发

此项目遵循 GitHub 的 Spec Kit 方法论进行规范驱动开发：

📋 宪法框架

项目由 .specify/memory/constitution.md 治理 - 14 条不可谈判的原则：

第一条：类型安全（TypeScript 严格模式 + Zod）
第二条：MCP 协议合规性
第三条：AutoHotkey v2 纯度
第四条：测试先行开发（RED-GREEN-重构）
第五至第十四条：性能、安全性、模块化、用户体验等

📐 架构决策

所有重大技术决策都记录在 .specify/specs/architecture-decisions.md 中：

ADR-001：为什么选择 TypeScript 而不是 JavaScript
ADR-003：为什么选择 FlexSearch 进行文档搜索
ADR-006：为什么选择 PowerShell 进行窗口检测
ADR-011：为什么采用 AHK_* 工具命名约定
...以及更多解释架构背后“为什么”的 ADR

📚 规范与计划

主规范：.specify/specs/ahk-mcp-master-spec.md - 系统是什么以及为什么
技术计划：.specify/specs/ahk-mcp-technical-plan.md - 如何实现
模板：.specify/templates/ - 新功能的规范、计划和任务模板

🔄 开发工作流程

新功能遵循结构化过程：

定义 (/specify) - 定义什么是和为什么（非技术）
计划 (/plan) - 技术架构和决策
任务 (/tasks) - 测试先行的实施路线图
实施 - 根据规范和计划编写代码

请参阅 .specify/templates/ 获取起点。

特性

类似 LSP 的能力

代码补全：对函数、变量、类、方法和关键字提供智能建议
诊断：语法错误检测和 AutoHotkey v2 编码标准验证
脚本分析：带有上下文文档的综合代码分析
跳转到定义：导航到符号定义（计划中）
查找引用：在整个代码中定位符号使用（计划中）

AutoHotkey v2 特定功能

内置文档：全面的 AutoHotkey v2 函数和类参考
编码标准：强制执行 Claude 定义的 AutoHotkey v2 最佳实践
快捷键支持：智能完成快捷键定义
类分析：面向对象编程支持，包括方法和属性完成
上下文帮助：实时文档和内置元素示例

安装

先决条件

在安装 AutoHotkey v2 MCP 服务器之前，请确保您拥有：

Node.js 18.0.0 或更高版本
npm 或 yarn 包管理器

设置

克隆并安装依赖项：

git clone https://github.com/TrueCrimeAudit/ahk-mcp.git
cd ahk-mcp
npm install

构建项目：
```
npm run build
```
启动服务器：
```
npm start
```
开发模式自动重载：
```
npm run dev
```

Claude Desktop 配置

将服务器添加到您的 Claude Desktop 配置文件 (claude_desktop_config.json) 中：

Windows 配置：

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

调试配置（用于故障排除）：

{
  "mcpServers": {
    "ahk-server": {
      "autoApprove": [
        "analyze_code",
        "find_variables",
        "get_function_info",
        "get_class_info"
      ],
      "disabled": false,
      "timeout": 60,
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\path\\to\\ahk-mcp\\dist\\index.js"
      ],
      "transportType": "stdio",
      "env": {
        "NODE_ENV": "production",
        "AHK_MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

重要提示：

将 YourUsername 替换为您实际的 Windows 用户名
将 path\\to\\ahk-mcp 替换为您实际的安装路径
对于 Node.js 和脚本使用绝对路径
在 Windows 路径中使用双反斜杠 (\\) 以正确进行 JSON 转义
将 AHK_MCP_LOG_LEVEL 设置为 debug 用于故障排除，warn 用于正常用途

MCP 工具

工具命名约定

所有工具现在使用 AHK_<单词>_<单词> 格式（例如 AHK_File_View，AHK_File_Edit_Diff）。
以前的小写名称如 ahk_file_view 不再被服务器注册。
在工具链中混用旧名称会触发“未知工具”错误，因为 server.ts 只分派 ahk_* 处理程序。分派器、工具推荐和配置设置现在同意新的 AHK_* 标识符，因此链式调用可以正确进行。

核心分析工具

`AHK_Smart_Orchestrator` 🆕

智能编排文件操作以最小化冗余工具调用。自动链接检测 → 分析 → 读取 → 编辑工作流，并带有智能缓存。

关键优势：

将工具调用从 7-10 次减少到 3-4 次（减少 60%）
会话范围缓存与过期检测
自动行范围计算
生产使用中的缓存命中率：约 65%

{
  intent: string,                           // 您想要做什么（必需）
  filePath?: string,                        // 直接文件路径（跳过检测）
  targetEntity?: string,                    // 类、方法或函数名称
  operation: 'view' | 'edit' | 'analyze',  // 操作类型（默认：查看）
  forceRefresh?: boolean                    // 强制重新分析（默认：false）
}

示例：

// 查看特定类
{ intent: "查看 _Dark 类", targetEntity: "_Dark", operation: "view" }

// 使用直接路径编辑
{ intent: "修改复选框样式", filePath: "C:\\path\\to\\file.ahk",
  targetEntity: "_Dark.ColorCheckbox", operation: "edit" }

// 分析结构
{ intent: "理解文件结构", filePath: "C:\\path\\to\\file.ahk",
  operation: "analyze" }

详见 docs/SMART_ORCHESTRATOR.md。

`AHK_Run`

执行 AutoHotkey 脚本，带窗口检测和超时处理。

{
  mode: 'run' | 'test',                    // 执行模式
  filePath?: string,                       // .ahk 文件路径（或使用内容）
  content?: string,                        // 要执行的脚本内容
  wait?: boolean,                          // 等待完成（默认：true）
  detectWindow?: boolean,                  // 启用窗口检测（默认：false）
  windowDetectTimeout?: number,            // 窗口检测超时时间（毫秒）
  ahkPath?: string                         // 自定义 AutoHotkey 可执行文件路径
}

`AHK_Diagnostics`

验证代码语法并强制执行编码标准，带有详细的错误报告。

{
  code: string,                    // 要分析的 AutoHotkey v2 代码
  enableClaudeStandards?: boolean, // 应用编码标准（默认：true）
  severity?: string               // 过滤：'error' | 'warning' | 'info' | 'all'
}

`AHK_Analyze`

带有上下文文档和使用见解的综合脚本分析。

{
  code: string,                      // 要分析的 AutoHotkey v2 代码
  includeDocumentation?: boolean,    // 包含内置元素文档（默认：true）
  includeUsageExamples?: boolean,    // 包含使用示例（默认：false）
  analyzeComplexity?: boolean        // 分析代码复杂度（默认：false）
}

内置 AutoHotkey 提示

服务器包括 7 个可立即使用的 AutoHotkey v2 提示，可通过 Claude 访问：

文件系统监视器 - 使用回调监视目录更改
CPU 使用率监视器 - 显示实时 CPU 使用率的工具提示
剪贴板编辑器 - 基于 GUI 的剪贴板文本操作
快捷键切换功能 - 动态快捷键管理并带有反馈
链接管理器 - URL 验证和浏览器集成
片段管理器 - 文本片段存储和插入系统

通过 Claude 的界面输入 / 并从可用的 AutoHotkey 提示中选择访问这些提示。

文档

项目文档

快速入门：docs/QUICK_START.md - 快速上手
Claude Desktop 设置：docs/CLAUDE_DESKTOP_SETUP.md
Claude Code 设置：docs/CLAUDE_CODE_SETUP.md
设置指南：docs/SETTINGS_GUIDE.md - 配置选项
编码代理指南：docs/CODING_AGENT_GUIDE.md - AI 代理集成模式
发行说明：docs/RELEASE_NOTES.md - 版本历史

规范文档

宪法：.specify/memory/constitution.md - 项目治理
主规范：.specify/specs/ahk-mcp-master-spec.md - 系统规范
技术计划：.specify/specs/ahk-mcp-technical-plan.md - 实现细节
ADR 日志：.specify/specs/architecture-decisions.md - 决策记录

AutoHotkey v2 数据

服务器包括全面的 AutoHotkey v2 文档：

函数：200 多个内置函数及其参数和示例
类：GUI、File、Array、Map 等核心类
变量：内置变量如 A_WorkingDir、A_ScriptName
方法：带有详细参数信息的类方法
指令：#Include、#Requires 等预处理器指令

贡献

开发工作流程

此项目遵循规范驱动开发：

阅读宪法：.specify/memory/constitution.md - 不可谈判的原则
审查 ADR：.specify/specs/architecture-decisions.md - 了解过去的决策
创建规范：使用 .specify/templates/spec-template.md 定义什么是和为什么
创建计划：使用 .specify/templates/plan-template.md 定义如何
分解任务：使用 .specify/templates/tasks-template.md 进行实施
遵循测试先行：在实现之前编写测试（第四条）

关键原则

类型安全：TypeScript 严格模式 + Zod 验证
MCP 合规性：带有 isError 标志的标准响应格式
仅限 AHK v2：不支持 AutoHotkey v1
测试先行：RED-GREEN-重构周期
工具命名：AHK_Category_Action 约定

详见 CONTRIBUTING.md 以获取详细指南（即将推出）。

许可

本项目根据 MIT 许可证发布 - 详情见 LICENSE 文件。

<div align="center"> <p> <strong>为社区打造 ❤️</strong> </p> <p> <a href="https://www.autohotkey.com/docs/v2/">官方 AHK 文档</a> </p> </div>