AutoHotkey v2 MCP Server

AutoHotkey v2 개발을 위한 TypeScript MCP 서버입니다. Claude Desktop과 같은 MCP 클라이언트를 위한 스크립트 분석, 파일 작업, 문서 검색, 스크립트 실행 도구를 제공합니다.

아키텍처

Related MCP server: Hotkeyless AHK MCP

주요 기능

• AutoHotkey 워크플로우를 위한 25개 이상의 AHK_* 도구

• 대상 파일 검색 및 활성 파일 인식 작업

• 프로세스 추적 및 창 감지가 포함된 스크립트 실행

• 로컬 AutoHotkey 검증 및 진단 도구

• 내장 AutoHotkey 문서 및 프롬프트/컨텍스트 헬퍼

• Stdio 및 Streamable HTTP 전송(상태 유지 또는 무상태), 레거시 SSE 엔드포인트 지원

• HTTP 모드의 옵트인 bearer-token 인증 및 DNS 리바인딩 보호

요구 사항

• Node.js 18+

• npm

• AutoHotkey v2(실행/검증 도구용)

설치

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

실행

npm start

개발 모드:

npm run dev

스모크 테스트:

npm run smoke:mcp

HTTP 모드 및 환경 변수

npm start는 stdio(Claude Desktop)를 사용합니다. /mcp에서 Streamable HTTP(및 레거시 SSE 엔드포인트)를 노출하려면 PORT를 설정하거나 --sse를 전달하세요:

npm run start:sse

동작은 환경 변수로 제어됩니다:

보안 참고: 도구 표면에는 파일 쓰기와 프로세스 실행이 포함됩니다. HTTP 포트에 자신의 머신 외의 다른 곳에서 접근할 수 있다면 AHK_MCP_AUTH_TOKEN(예: openssl rand -hex 32)과 두 허용 목록을 설정하세요 — 기본적으로 엔드포인트는 모든 요청을 수락합니다.

세션 흐름, 무상태 모드 세부 사항 및 cURL 예제는 docs/MCP_TRANSPORT_COMPATIBILITY.md를 참조하세요.

Claude Desktop 구성

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

JSON에서는 절대 경로를 사용하고 백슬래시를 이스케이프하세요.

AutoHotkey 경로 및 시작 동작 구성

AHK_Config를 사용하여 실행 파일 경로와 비차단 시작 동작을 설정하세요:

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

이 설정은 AHK_Run(및 AHK_Cloud_Validate 경로 확인)에서 사용됩니다.

핵심 도구

• AHK_Smart_Orchestrator: 다단계 편집/분석 워크플로우 축소

• AHK_File_List, AHK_File_View, AHK_File_Edit: 파일 작업

• AHK_Analyze, AHK_Diagnostics: 분석 및 진단

• AHK_Run: 스크립트 실행(대기, 비대기, 창 감지)

• AHK_Cloud_Validate: 로컬 실행 기반 검증

• AHK_Doc_Search, AHK_Tools_Search: 문서 및 도구 검색

• AHK_Config: MCP 서버 구성

개발 명령어

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

문서

• docs/README.md

• docs/QUICK_START.md

• docs/QUICKREFERENCE.md

• docs/MCP_TRANSPORT_COMPATIBILITY.md

• docs/ARCHITECTURE_DIAGRAMS.md

• docs/RELEASE_NOTES.md

기여

CONTRIBUTING.md 및 AGENTS.md를 참조하세요.

라이선스

MIT. LICENSE를 참조하세요.