Skip to main content
Glama
deenesjakoruzh
tim0-12432

Hotkeyless AHK MCP

by tim0-12432
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Hotkeyless AHK MCP 및 스킬

License: MIT AHK Version MCP Claude Support OpenCode Support Github Copilot Support

이 저장소는 다음을 제공합니다:

  • Hotkeyless AHK HTTP API를 래핑하는 TypeScript MCP 서버.

  • OpenCode, Claude 및 일반 에이전트 런타임을 위한 재사용 가능한 스킬 문서.

  • 데스크톱 자동화 시나리오를 위한 실용적인 예제.

작업 공간 레이아웃

packages/
  mcp-server/   # Node MCP server package
  skills/       # Agent skill documents
examples/       # End-to-end usage examples

  1. MCP 서버

  1. 에이전트 스킬

Related MCP server: Desktop Commander MCP Server

MCP 서버

빠른 시작

OpenCode

opencode.json:

{
  ...
  "mcp": {
    ...
    "hotkeyless-ahk": {
      "type": "local",
      "command": ["npx", "-y", "@tim0_12432/hotkeyless-ahk-mcp-server"],
      "enabled": true,
      "environment": {
          "BLACKLIST": "shutdown,restart,kill"
          ...
      }
    }
  },
  ...
}

ClaudeCode

.mcp.json:

{
  "mcpServers": {
    ...
    "hotkeyless-ahk": {
      "command": "npx",
      "args": ["-y", "@tim0_12432/hotkeyless-ahk-mcp-server"],
      "env": {
        "BLACKLIST": "shutdown,restart,kill"
        ...
      }
    }
  }
}

Github Copilot

mcp-config.json:

{
  ...
  "mcpServers": {
    ...
    "hotkeyless-ahk": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@tim0_12432/hotkeyless-ahk-mcp-server"],
      "env": {
        "BLACKLIST": "shutdown,restart,kill"
          ...
      },
      "tools": ["*"]
    }
  },
  ...
}

소스에서 빌드

1. 서버 빌드

bun install
bun run build

npm도 문제없이 작동할 것입니다!

2. 하네스 설정

OpenCode

opencode.json:

{
  ...
  "mcp": {
    ...
    "hotkeyless-ahk": {
      "type": "local",
      "command": ["node", "<absolute path to the built files>/mcp-server/dist/index.js"],
      "enabled": true,
      "environment": {
          "BLACKLIST": "shutdown,restart,kill"
          ...
      }
    }
  },
  ...
}
ClaudeCode

.mcp.json:

{
  "mcpServers": {
    ...
    "hotkeyless-ahk": {
      "command": "node",
      "args": ["<absolute path to the built files>/mcp-server/dist/index.js"],
      "env": {
        "BLACKLIST": "shutdown,restart,kill"
        ...
      }
    }
  }
}
Github Copilot

mcp-config.json:

{
  ...
  "mcpServers": {
    ...
    "hotkeyless-ahk": {
      "type": "local",
      "command": "node",
      "args": ["<absolute path to the built files>/mcp-server/dist/index.js"],
      "env": {
        "BLACKLIST": "shutdown,restart,kill"
          ...
      },
      "tools": ["*"]
    }
  },
  ...
}

Hotkeyless AHK API 계약

  • GET /list는 { command: string, note: string }의 JSON 배열을 반환합니다.

  • GET /send/<command>는 쿼리 매개변수를 허용합니다.

구성

기본 구성은 mcp-server/dist/infrastructure/config/config.ts에 있습니다.

환경 재정의:

매개변수 재정의

기능

기본값

BASE_URL

Hotkeyless AHK 서버 주소

http://localhost:42800

TIMEOUT_MS

각 요청에 대한 타임아웃(밀리초)

4000

BLACKLIST

호출을 방지할 명령어 목록

[]

CACHE_TTL_MS

명령어 목록의 캐시 수명(밀리초)

5000

ENDPOINT_LIST

명령어 목록의 엔드포인트 주소

/list

ENDPOINT_TRIGGER

명령어 호출을 위한 엔드포인트 주소

/send

에이전트 스킬

빠른 시작

OpenCode

  1. ./skills/.opencode/... 폴더를 다음 위치로 복사하세요.

  • 프로젝트별 스킬 설정을 위해 .opencode/skills

  • 전역 설정을 위해 %USERPROFILE%/.config/opencode/skills

  1. AGENTS.md, 사용자 지정 하위 에이전트 또는 사용자 지정 명령어를 조정하여 스킬을 참조할 수 있습니다.

  2. OpenCode(CLI 또는 데스크톱)를 다시 시작하세요.

  3. 에이전트에게 "hotkeyless AHK skills"를 사용하도록 요청하면 이제 스킬 가이드를 사용해야 합니다.

ClaudeCode

  1. ./skills/.claude/... 폴더를 다음 위치로 복사하세요.

  • 프로젝트별 스킬 설정을 위해 .claude/skills

  • 전역 설정을 위해 %USERPROFILE%/.config/claude-code/skills

  1. CLAUDE.md, 사용자 지정 하위 에이전트 또는 사용자 지정 명령어를 조정하여 스킬을 참조할 수 있습니다.

  2. Claude Code를 다시 시작하세요.

  3. 에이전트에게 "hotkeyless AHK skills"를 사용하도록 요청하면 이제 스킬 가이드를 사용해야 합니다.

Github Copilot

  1. ./skills/.claude/... 폴더를 다음 위치로 복사하세요.

  • 프로젝트별 스킬 설정을 위해 .claude/skills

  • 전역 설정을 위해 %USERPROFILE%/.config/claude-code/skills

  1. AGENTS.md, 사용자 지정 하위 에이전트 또는 사용자 지정 명령어를 조정하여 스킬을 참조할 수 있습니다.

  2. Claude Code를 다시 시작하세요.

  3. 에이전트에게 "hotkeyless AHK skills"를 사용하도록 요청하면 이제 스킬 가이드를 사용해야 합니다.

라이선스

MIT

Available Tools

4 tools
discover_commandsB

Fetch available Hotkeyless commands from /list.

ParametersJSON Schema
NameRequiredDescriptionDefault
refreshNoSet true to bypass cache and force a fresh /list request.

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description must cover behavioral traits. It only states 'Fetch' without elaborating on network dependency, caching behavior (though 'refresh' parameter hints at cache), or side effects. The description is insufficient for a read operation.

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

Conciseness5/5

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

The description is a single, succinct sentence with no redundancy. Every word is necessary and front-loaded with the core action.

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

Completeness3/5

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

Given the tool's simplicity (one optional param, no output schema), the description is adequate but lacks explicit mention of what the tool returns (e.g., list of commands). This gap moderately affects completeness.

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?

Input schema has 100% coverage with a clear description for the 'refresh' parameter. The tool description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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 action 'Fetch' and the resource 'available Hotkeyless commands from /list'. The tool name 'discover_commands' aligns with listing operations, distinguishing it from sibling action tools like 'mouse_move', 'send_keys', and 'trigger_command'.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or situations where fetch is appropriate, leaving the agent without situational awareness.

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

mouse_moveB

Move mouse cursor via optional /mouse_move endpoint. Returns clear error when endpoint is unsupported.

ParametersJSON Schema
NameRequiredDescriptionDefault
xYesTarget X coordinate.
yYesTarget Y coordinate.

TDQS

B3/5.0
Behavior2/5

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

No annotations provided, so description must disclose behavior. It mentions returning a clear error when unsupported but fails to clarify whether movement is absolute or relative, or any side effects. Minimal disclosure.

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

Conciseness3/5

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

Two sentences, but the first sentence partially repeats the tool name. Could be more concise by omitting the endpoint redundancy. Acceptable but not optimal.

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

Completeness2/5

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

No output schema exists, but the description omits key details like coordinate system (absolute vs relative), screen bounds, or error types. Incomplete for confident tool use.

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?

Schema coverage is 100%, with clear descriptions for x and y. The description adds no additional parameter meaning beyond what the schema provides, so baseline 3 is appropriate.

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 action (Move mouse cursor) and the resource (optional endpoint). It distinguishes from sibling tools like discover_commands and send_keys, which are unrelated to mouse movement.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description lacks context for when mouse movement is appropriate or how it relates to other commands.

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

send_keysB

Send keystrokes through optional /send_keys endpoint. Returns clear error when endpoint is unsupported.

ParametersJSON Schema
NameRequiredDescriptionDefault
keysYesKey sequence to send.

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It only discloses the error behavior when the endpoint is unsupported, but lacks details on whether the action is destructive, reversible, or any other behavioral traits.

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

Conciseness5/5

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

The description is two sentences, front-loaded with the core action, and contains no extraneous information.

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

Completeness3/5

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

For a simple tool with one parameter and no output schema, the description is minimally complete. It covers the purpose and error handling but omits details like key format or special keys, leaving some ambiguity.

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?

Schema coverage is 100% and the parameter 'keys' is described as 'Key sequence to send.' The description adds no additional meaning beyond 'keystrokes', so it meets the baseline but does not enhance understanding.

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

Purpose4/5

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

The description clearly states 'Send keystrokes' (specific verb+resource) and mentions the endpoint and error handling, but does not explicitly distinguish from sibling tools like trigger_command.

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

Usage Guidelines2/5

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

The description mentions that the endpoint is optional and will return an error if unsupported, but gives no guidance on when to use this tool versus alternatives or any prerequisites.

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

trigger_commandA

Trigger one Hotkeyless command by exact name using /trigger. Enforces blacklist and verifies command exists.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesExact command name returned by discover_commands.

TDQS

A3.8/5.0
Behavior2/5

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

No annotations provided, so description must disclose behavior fully. It mentions blacklist enforcement and existence verification but omits success/failure outcomes, side effects, permissions, or return values.

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

Conciseness5/5

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

Two short sentences, no filler, front-loaded with key action and constraints. Every word contributes.

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

Completeness2/5

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

Missing crucial details: no output schema, no description of return values or behavior after triggering. Agent cannot infer outcomes, making the description inadequate for a mutation-like tool.

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

Parameters4/5

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

Schema coverage is 100% with param description. Description adds context: exact name requirement, /trigger usage, blacklist and existence checks, enhancing beyond the schema baseline.

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?

Description clearly states verb 'Trigger' and resource 'one Hotkeyless command', with method '/trigger'. It distinguishes from siblings: discover_commands lists commands, mouse_move and send_keys are different actions.

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

Usage Guidelines4/5

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

Implies usage: call with exact name from discover_commands, but no explicit when-not or alternatives. The sibling context helps, but description lacks negative guidance.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.3
    • First observeddiscover_commands
    • First observedmouse_move
    • First observedsend_keys
    • First observedtrigger_command
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct purpose: discover_commands fetches available commands, mouse_move moves the cursor, send_keys sends keystrokes, and trigger_command executes a command. No overlap exists.

Naming Consistency5/5

All tools use a consistent verb_noun pattern with snake_case: discover_commands, mouse_move, send_keys, trigger_command. No deviations.

Tool Count5/5

With 4 tools, the count is well-scoped for the specific domain of Hotkeyless AHK automation. It covers the core functionality without being too sparse or excessive.

Completeness5/5

The tool surface covers the essential operations: listing commands, moving mouse, sending keys, and triggering commands. No obvious gaps for the intended purpose, as optional endpoints are handled with clear errors.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-opentym

    doanhtuan123
    F
    license
    Not graded
    quality
    F
    maintenance
    A lightweight MCP HTTP server giving AI assistants real tools to interact with your Windows machine, including running commands, file access, system info, web search, and browser automation.
    1
    -

  • windows-computer-use-mcp

    Einosensokami
    A
    license
    Not graded
    quality
    C
    maintenance
    A local, dependency-free MCP server that gives AI agents controlled access to the active Windows desktop, enabling automated interaction with applications through screenshots, clicks, typing, and window management.
    87 npm
    MIT