{"_id":"@dahawa/hawa-hands","_rev":"2-9857c8e1fd5987e00d2d5dd542942b1d","name":"@dahawa/hawa-hands","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@dahawa/hawa-hands","version":"1.0.0","author":{"name":"Gang.ji"},"license":"MIT","_id":"@dahawa/hawa-hands@1.0.0","maintainers":[{"name":"icewaterpp","email":"gang.ji@outlook.com"}],"homepage":"https://www.hawacode.com","bugs":{"url":"https://github.com/italking/hawa-hands/issues"},"bin":{"hawa-hands":"dist/main.js"},"dist":{"shasum":"707a204299dda292478828dae9b04ec62844a0f0","tarball":"https://registry.npmjs.org/@dahawa/hawa-hands/-/hawa-hands-1.0.0.tgz","fileCount":3,"integrity":"sha512-aCUJlhPt0QXlzB9e4Y1v14kuVB4z4JH761kjmgwxJpqGkyk25DUjCcrexyS6BNs5QxptCBjT/zLptPHtWGbngA==","signatures":[{"sig":"MEQCIEHZ9CUs0nUZ+cZH1DTYGy1dGh7Xyl6PW/+gI016mntLAiBoUCh6kDR85ABSlJ73wxPmrzNFKD9NF9Y2UPO8IMiTbA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34979},"main":"dist/main.js","type":"module","types":"dist/index.d.ts","gitHead":"8b25165806317d23b803be061adcc92c06367d00","mcpName":"hawa-hands","scripts":{"dev":"node --import tsx src/main.ts","build":"node scripts/build.js","start":"node dist/main.js","start:http":"npm run build && cross-env MCP_TRANSPORT=http node dist/main.js"},"_npmUser":{"name":"icewaterpp","email":"gang.ji@outlook.com"},"repository":{"url":"git+https://github.com/italking/hawa-hands.git","type":"git"},"_npmVersion":"11.9.0","description":"MCP server for Hawa Code providing file & shell tools (Read, Write, Edit, Glob, Grep, Bash, PowerShell). Designed to separate Agent reasoning from tool execution so tools can later be sandboxed.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^4.1.13","diff":"^5.2.0","express":"^5.1.0","minimatch":"^10.0.1","@modelcontextprotocol/sdk":"^1.24.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.7","esbuild":"^0.28.0","typescript":"^5.9.3","@types/diff":"^5.2.3","@types/node":"^24.10.1","@types/express":"^5.0.6"},"_npmOperationalInternal":{"tmp":"tmp/hawa-hands_1.0.0_1779694694269_0.1421710488343788","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@dahawa/hawa-hands","version":"1.0.1","description":"MCP server for Hawa Code providing file & shell tools (Read, Write, Edit, Glob, Grep, Bash, PowerShell). Designed to separate Agent reasoning from tool execution so tools can later be sandboxed.","homepage":"https://www.hawacode.com","license":"MIT","author":{"name":"Gang.ji"},"repository":{"type":"git","url":"git+https://github.com/italking/hawa-hands.git"},"type":"module","main":"dist/main.js","types":"dist/index.d.ts","bin":{"hawa-hands":"dist/main.js"},"mcpName":"hawa-hands","scripts":{"start":"node dist/main.js","build":"node scripts/build.js","dev":"node --import tsx src/main.ts","start:http":"npm run build && cross-env MCP_TRANSPORT=http node dist/main.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.24.3","diff":"^5.2.0","express":"^5.1.0","minimatch":"^10.0.1","zod":"^4.1.13"},"devDependencies":{"@types/diff":"^5.2.3","@types/express":"^5.0.6","@types/node":"^24.10.1","esbuild":"^0.28.0","tsx":"^4.20.7","typescript":"^5.9.3"},"publishConfig":{"access":"public"},"gitHead":"8b25165806317d23b803be061adcc92c06367d00","_id":"@dahawa/hawa-hands@1.0.1","bugs":{"url":"https://github.com/italking/hawa-hands/issues"},"_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-U5jWV1uHuUN2VvvQY5Y6rvjCsmx9dVagg+ewBeIax1TC6WiODhNUtU97M8qJFHthFYjSOwp4POolClRO+CCRfg==","shasum":"6e577a8f2f47e40c7806dd1a9461bcfa93ccdcce","tarball":"https://registry.npmjs.org/@dahawa/hawa-hands/-/hawa-hands-1.0.1.tgz","fileCount":3,"unpackedSize":34979,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDpN6NcO+4dbjBXOm1Fyz0o69b0mc4zSUfy5SD5XbdOHgIhAJQim+oK2ijHu5eVk3geBSk+G84Jl3eGzZnAd5IQdSe+"}]},"_npmUser":{"name":"icewaterpp","email":"gang.ji@outlook.com"},"directories":{},"maintainers":[{"name":"icewaterpp","email":"gang.ji@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hawa-hands_1.0.1_1779694782615_0.9368876923307683"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T07:38:14.126Z","modified":"2026-05-25T07:39:42.851Z","1.0.0":"2026-05-25T07:38:14.417Z","1.0.1":"2026-05-25T07:39:42.749Z"},"bugs":{"url":"https://github.com/italking/hawa-hands/issues"},"author":{"name":"Gang.ji"},"license":"MIT","homepage":"https://www.hawacode.com","repository":{"type":"git","url":"git+https://github.com/italking/hawa-hands.git"},"description":"MCP server for Hawa Code providing file & shell tools (Read, Write, Edit, Glob, Grep, Bash, PowerShell). Designed to separate Agent reasoning from tool execution so tools can later be sandboxed.","maintainers":[{"name":"icewaterpp","email":"gang.ji@outlook.com"}],"readme":"# hawa-hands\n\n`hawa-hands` 是为 [Hawa Code](https://www.hawacode.com) 等 Agent 客户端提供的 **MCP 工具服务器**。\n\n它把 Hawa Code 内置的核心工具：\n\n- `Read` — 读取文件（含图片、行号格式输出）\n- `Write` — 写入/覆盖文件\n- `Edit` — 精确字符串替换\n- `Glob` — 按 glob 模式查找文件\n- `Grep` — 基于 ripgrep 的全文搜索（自带 fallback）\n- `Bash` — 执行 bash 命令（支持后台任务 + 黑名单拦截）\n- `PowerShell` — 执行 PowerShell 命令（支持后台任务 + 黑名单拦截）\n- `TaskOutput` / `TaskStop` / `TaskList` — 管理 run_in_background 任务\n\n通过 **MCP 协议**对外暴露，从而把 “Agent 模型推理” 与 “工具实际执行” 解耦：\n\n```\n┌────────────┐  MCP (stdio/http)  ┌──────────────┐\n│ Hawa Code  │ ─────────────────▶ │  hawa-hands  │ ─▶ 真实文件系统 / shell\n└────────────┘                    └──────────────┘\n                                       │\n                                       ▼\n                              （后续可放入沙箱执行）\n```\n\n后续可以将 `hawa-hands` 单独部署在容器 / VM / 沙箱内，限制其可访问的目录与命令，\n而 Agent 主进程仍只与之进行 MCP 通信。\n\n## 架构参考\n\n- 工具实现参考自：`hawa-code/src/tools/*`\n- MCP 服务器骨架参考自：`hawa-computer-use`\n\n## 用法\n\n### 1. 安装并构建\n\n```bash\nnpm install\nnpm run build\n```\n\n### 2. 作为 stdio MCP 启动（推荐用于 Hawa Code 本地集成）\n\n```bash\nnode dist/main.js\n```\n\n在 Hawa Code 的 `.mcp.json` 中加入：\n\n```json\n{\n  \"mcpServers\": {\n    \"hawa-hands\": {\n      \"url\": \"http://localhost:3000/mcp\"\n    }\n  }\n}\n```\n\n### 3. 作为 HTTP MCP 启动\n\n```bash\nMCP_TRANSPORT=http PORT=3000 node dist/main.js\n# 终端会输出: Hawa Hands MCP server running on http://localhost:3000/mcp\n```\n\n> ⚠️ HTTP 模式没有内置鉴权，只能在受信网络或反向代理后使用。\n\n## 工具备注\n\n- **Bash 工具** 在 Windows 上需要可在 PATH 中解析的 `bash`（如 Git Bash / WSL bash）。\n- **PowerShell 工具** 仅在能找到 `powershell.exe` / `pwsh` 时才会被注册。\n- **Grep 工具** 优先调用系统 `rg`，找不到时回退到内置的 Node.js 实现（功能受限）。\n- **后台任务** (`run_in_background`) 仅存活于当前服务进程；进程退出时全部丢失。\n\n## 沙箱化思路\n\n`utils/shell.ts` 中的 `spawnProcess` 是工具执行的唯一入口。要把工具放进沙箱，\n只需在该函数内换成：\n\n- Linux：`firejail` / `bubblewrap` / Docker exec\n- Windows：Windows Sandbox / 受限令牌进程\n- macOS：`sandbox-exec`\n\n文件类工具（Read / Write / Edit / Glob / Grep）可以再叠加一层路径白名单，\n只允许访问预先声明的工程目录，进一步收敛攻击面。\n","readmeFilename":"README.md"}