📦
ace-tool-windows
ACE MCP server for Windows (Win32)
0 installs
Trust: 39 — Low
Devtools
Installation
npx ace-tool-windowsAsk AI about ace-tool-windows
Powered by Claude · Grounded in docs
I know everything about ace-tool-windows. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Loading tools...
Reviews
Documentation
ace-tool-windows
Windows 平台的 ACE MCP Server(Rust + Win32,stdio 模式),提供 search_context 与 enhance_prompt。
1. 安装
npm i -g ace-tool-windows
2. 获取 Token
在 https://acemcp.heroman.wtf 生成并复制 token。
建议:
- 不要把 token 提交到 Git 仓库。
- 优先通过环境变量或本地 MCP 配置注入。
- 即便使用
codexprovider,search_context仍依赖远端服务,必须配置 token。
3. 模式速览(先选一个)
3.1 remote 模式
- 适合:不依赖本机
codexCLI,开箱可用。 - 依赖:远端 token/credits。
- 启动示例:
ace-tool-win --base-url https://acemcp.heroman.wtf/relay/ --token <YOUR_TOKEN> --provider remote
3.2 codex 模式
- 适合:希望本地走 Codex 增强,避免远端增强额度影响。
- 依赖:本机可执行
codexCLI(codex --version可用)。 - 启动示例:
ace-tool-win --base-url https://acemcp.heroman.wtf/relay/ --token <YOUR_TOKEN> --provider codex --codex-cmd codex --codex-reasoning-effort low
关键说明:
search_context始终走远端,所以即便是codex模式也必须有可用 token。codex_cmd推荐先用codex(PATH 方案,跨设备更稳),确实找不到再写绝对路径。- 交互窗口支持自适应布局;Codex 首轮超时会自动重试一次
reasoning_effort=none。
4. MCP 配置模板(按模式复制)
4.1 remote 模式模板
JSON(适用于支持 mcpServers 的客户端):
{
"mcpServers": {
"ace-tool-windows": {
"command": "ace-tool-win",
"args": [
"--base-url", "https://acemcp.heroman.wtf/relay/",
"--token", "<YOUR_TOKEN>",
"--provider", "remote"
]
}
}
}
TOML(Codex CLI):
[mcpServers."ace-tool-windows"]
command = "ace-tool-win"
args = [
"--base-url", "https://acemcp.heroman.wtf/relay/",
"--token", "<YOUR_TOKEN>",
"--provider", "remote"
]
4.2 codex 模式模板
JSON(适用于支持 mcpServers 的客户端):
{
"mcpServers": {
"ace-tool-windows": {
"command": "ace-tool-win",
"args": [
"--base-url", "https://acemcp.heroman.wtf/relay/",
"--token", "<YOUR_TOKEN>",
"--provider", "codex",
"--codex-cmd", "codex",
"--codex-reasoning-effort", "low"
]
}
}
}
TOML(Codex CLI):
[mcpServers."ace-tool-windows"]
command = "ace-tool-win"
args = [
"--base-url", "https://acemcp.heroman.wtf/relay/",
"--token", "<YOUR_TOKEN>",
"--provider", "codex",
"--codex-cmd", "codex",
"--codex-reasoning-effort", "low"
]
5. Provider 行为(当前版本)
- 启动时确定 provider:
--provider/ACE_TOOL_ENHANCE_PROVIDER,默认remote。 - 请求参数里的
provider仅作为提示,不用于切换模式。 - 如果请求里的
provider与启动 provider 不一致,会自动忽略,仍以启动 provider 为准。 - 不会再自动从
codex降级到remote。
6. 在 AI CLI 中触发增强
配置好 MCP 后,输入包含 -enhance 或 -enhancer 的请求即可触发 enhance_prompt。
示例:
为当前项目的代码添加详细注释 -enhance
补充:
- 用户输入里的触发后缀(
-enhance/-enhancer)会在增强前自动剥离,不会进入最终增强文本。 - 若本次调用的
prompt仅包含触发后缀,服务端会自动回退到conversation_history提取可用提示,不再直接报错中断。 - 工具入口统一为
enhance_prompt,避免同义工具名导致重复触发。 - 服务端会对短时间内完全相同的增强请求做去重(约 180 秒),避免“窗口刚关又被同参再次拉起”。
- 增强文本采用“语义自适应”排版:在不改变语义前提下提升细节和可读性,不强制固定模板。
7. 环境变量(按模式)
7.1 remote 模式
$env:ACE_TOOL_ENHANCE_PROVIDER = "remote"
7.2 codex 模式
$env:ACE_TOOL_ENHANCE_PROVIDER = "codex"
$env:ACE_TOOL_CODEX_CMD = "codex"
$env:ACE_TOOL_CODEX_REASONING_EFFORT = "low"
7.3 通用变量
ACE_TOOL_ENHANCE_TIMEOUT_SEC=90(范围 10-600;未显式配置时remote默认 90 秒,codex默认 180 秒)ACE_TOOL_UI_TIMEOUT_SEC=480(范围 30-3600)ACE_TOOL_HEADLESS=1ACE_TOOL_HEADLESS_ACTION=enhanced|end|timeoutACE_TOOL_DEBUG=1ACE_TOOL_DEBUG_VERBOSE=1ACE_TOOL_DEBUG_FILE=<path>
8. 超时规则
--enhance-timeout-sec/ACE_TOOL_ENHANCE_TIMEOUT_SEC:增强请求超时,范围 10-600 秒;未显式配置时remote默认 90 秒,codex默认 180 秒。--ui-timeout-sec/ACE_TOOL_UI_TIMEOUT_SEC:UI 会话超时(默认 480 秒,范围 30-3600)。- 超出范围的配置会回退到默认值。
- 交互模式下 UI 超时会回退到原始 prompt;headless 模式不显示 UI,由
ACE_TOOL_HEADLESS_ACTION决定动作。 codexprovider 在首轮超时时会自动重试一次(reasoning_effort=none),用于降低“首次增强卡住”的概率。
9. 故障排查
9.1 MCP 启动超时 / 连接失败
检查项:
- 必须使用 stdio 模式。
command路径可执行(绝对路径优先)。--base-url与--token是否正确。- 开启
ACE_TOOL_DEBUG=1查看日志链路。
9.2 窗口不弹出或卡住
检查项:
- 是否启用了
ACE_TOOL_HEADLESS=1。 - Windows 权限或安全软件是否拦截窗口创建。
- 调试日志中是否出现
enhance_prompt: opening ui。
9.3 Token 认证失败
典型返回:401 / 403。
处理:
- 到 https://acemcp.heroman.wtf 重新生成 token。
- 更新 MCP 配置后重启客户端。
9.4 中文显示异常 / 乱码
当前版本已增加 UTF-8/BOM/GBK 等解码兜底。若仍异常:
- 确认终端与编辑器编码为 UTF-8。
- 打开
ACE_TOOL_DEBUG=1,附带日志定位具体节点。
9.5 Codex provider 无法执行 / 退出码非 0
检查项:
--codex-cmd是否指向可执行文件,PATH 是否包含codex。- 使用相同命令在终端直接执行一次,确认 CLI 可运行。
- 开启
ACE_TOOL_DEBUG=1查看退出码与错误类型(timeout/auth/network 等)。
9.6 Codex 首次增强慢 / 高概率超时
检查项:
- 日志是否长时间停在
mcp: mcp-router starting(已默认禁用内部 mcp-router;若仍出现,确认当前进程已重启到新版本)。 - 将
--codex-reasoning-effort临时降到none或low观察改善幅度。 - 适当提高
--enhance-timeout-sec(例如 240)验证是否为纯耗时问题。
10. 从源码构建
# release
npm run release
# 构建并拷贝 bin/ace-tool-win.exe
npm run build:bin
# 本地打包验证
npm run pack:local
11. 发布到 npm
npm publish --access public
若启用 npm 2FA,请使用支持 publish 的 token 或完成二次验证。
12. 发布前检查清单
-
npm run release无 error / warning - MCP 可启动并能成功
tools/list -
enhance_prompt在remote与codex均可回包 - 中文增强回归通过(无
???) - README 中配置示例可在新机器复现
License
Apache-2.0
