文件操作代理

MCP电子试剂

一个嵌入本地HTTP服务器的最小Electron桌面应用程序，该服务器公开了一个小型的模型上下文协议（MCP）样式的清单和工具，用于在交互式用户同意的情况下进行文件操作。

特性

• 带有强化默认值的电子外壳（GPU+硬件加速禁用，上下文隔离启用）。
• 上的本地Express服务器 http://127.0.0.1:8371.
• MCP发现清单位于 /.well-known/mcp-manifest.
• 工具：
  • file.read：在白名单和同意后返回文件内容（<=200 KB）。
  • file.stat：在白名单和同意后返回元数据（大小、mtime、isDirectory）。
  • file.write （ENABLE_WRITE=1）：创建/覆盖/附加具有大小和同意控制的文本文件。
  • file.delete （ENABLE_DELETE=1）：在征得同意的情况下删除文件（以及可选的递归目录）。
  • file.list （ENABLE_LIST=1）：使用可选正则表达式列出目录条目 pattern 和 limit.
  • dir.create （ENABLE_DIR_CREATE=1）：创建目录（默认情况下是递归的）。
  • file.rename （ENABLE_RENAME=1）：在允许的范围内重命名或移动文件/目录。
• 通过以下方式保留每个目录和每个操作的同意决定（读/写/删除） electron-store.
• 可配置允许的基本目录或完整操作系统访问标志。
• 可选的承载令牌身份验证。

入门指南

npm install
npm run dev

出现主窗口；如果满足以下条件，将创建托盘图标 icon.png 存在且有效。

配置（环境变量）

使用自定义白名单+令牌运行：

ALLOWED_BASE_DIRS="$HOME:/tmp" AGENT_API_TOKEN="secret123" npm run dev

完全操作系统访问权限（危险：授予跨系统的读/写/删除权限）：

ALLOW_FULL_OS=1 ENABLE_WRITE=1 ENABLE_DELETE=1 npm run dev

端点

• GET /.well-known/mcp-manifest → 清单（工具+配置标志）。
• POST /mcp/tool/file.read JSON： { path, clientName } → { content }.
• POST /mcp/tool/file.stat JSON： { path, clientName } → { size, mtime, isDirectory, path }.
• POST /mcp/tool/file.write JSON： { path, content, clientName, mode } → { status, path, bytes }.
• POST /mcp/tool/file.delete JSON： { path, clientName, recursive? } → { status, path, recursive? }.
• POST /mcp/tool/file.list JSON： { path, clientName, pattern?, limit? } → { entries:[{name,isDirectory}], truncated }.
• POST /mcp/tool/dir.create JSON： { path, clientName, recursive? } → { status, path, recursive }.
• POST /mcp/tool/file.rename JSON： { from, to, clientName, overwrite? } → { status, from, to }.

同意流程

1. 客户端请求工具。
2. 服务器验证路径（白名单或完全访问标志）。
3. 对话框显示按钮：允许一次/始终允许 /始终允许读写删除/拒绝。
4. 用于未来操作（特定于操作或全局）的存储决策。

安全说明

• nodeIntegration 残疾人；通过预加载控制API。
• contextIsolation 启用。
• 令牌认证可选；建议在启用全操作系统访问时使用。
• 白名单或完整操作系统访问标志控制范围；出于安全考虑，更喜欢白名单。
• 不得在测试自动化之外启用AUTOCONSENT。
• 启用删除+完全访问时，请考虑在包含的VM内运行。

测试

手册：

curl -s http://127.0.0.1:8371/.well-known/mcp-manifest | jq
curl -s -X POST http://127.0.0.1:8371/mcp/tool/file.stat \
  -H 'Content-Type: application/json' \
  -d '{"path":"'$HOME'/.bashrc","clientName":"TestClient"}'

首次访问将显示同意对话框。

令牌启用测试：

export AGENT_API_TOKEN=secret123
npm run dev &
# In another terminal
curl -s -H 'Authorization: Bearer secret123' http://127.0.0.1:8371/.well-known/mcp-manifest | jq

路线图/建议改进

• 同意管理UI（查看/撤销决定）。
• 高级搜索（内容和全局）+索引。
• 增量/分块大文件支持。
• 结构化日志记录和日志查看器面板。
• 可选TLS终止。
• IPC工具事件流。
• TypeScript转换。
• 自动化测试（Jest用于API，Playwright用于对话框流）。
• 包装方式 electron-builder 或 electron-forge.
• 覆盖/删除时的备份/还原机制。
• 补丁工具（应用统一差异）以实现更安全的编辑。

代理集成（SDK）

使用 agent-client.js 以编程方式进行交互：

const client = require('./agent-client');
(async () => {
  await client.init({ baseUrl: 'http://127.0.0.1:8371', token: process.env.AGENT_API_TOKEN });
  // Create directory
  await client.createDir('/tmp/mcp-agent-demo');
  // Write file
  await client.writeFile('/tmp/mcp-agent-demo/hello.txt', 'Hello World', 'create');
  // List directory
  const listing = await client.listDir('/tmp/mcp-agent-demo');
  console.log(listing);
  // Rename file
  await client.renamePath('/tmp/mcp-agent-demo/hello.txt', '/tmp/mcp-agent-demo/greeting.txt');
  // Read file
  const file = await client.readFile('/tmp/mcp-agent-demo/greeting.txt');
  console.log(file.content);
  // Delete directory recursively
  await client.deletePath('/tmp/mcp-agent-demo', true);
})();

故障排除

许可证

内部/未指定。如果分发，请添加许可证文件。

生成的改进通道：安全强化、配置、令牌认证、第二个工具、README。上面列出的未来增强功能。