AX本地操作 MCP 服务器 v2.6.0

一个功能强大的 MCP (Model Context Protocol) 服务器，名为 ax_local_operations，为大模型应用提供安全的本地文件操作、行级编辑、文件搜索、文件比较、文件哈希、文件权限、文件压缩、文件监控、命令执行和任务管理功能。

作者本人推荐,特点:

• 使用这个ax_local_operations，你可以在任何接受MCP的对话应用里, 把它变成可以操作电脑的助手. 而不仅仅是一个对话聊天工具.
• 最佳实践: 使用 Qwen 应用, 加入 ax_local_operations 这个MCP之后, qwen 可以接受用户的指示, 从而完成一些诸如编码, 部署环境, 检测设备硬件等等的实际工作. 而不是仅仅聊天. 还可以使用 Jan,lmStudio 这些应用都可以加入ax_local_operations 这个MCP之后，从而实现更智能的助手功能。
• 对比其它MCP, 比如其它的本地文件MCP, 专注于文件操作. 但没有命令执行工具，所以这个MCP适合做对话应用，而不是命令行工具。

使用注意,:

• 在对话中建议第一句就告诉AI: "当前的工作目录是: /User/research/work", 这样可以让AI在工作中使用临时写入文件不必影响原设备环境.

🌐 平台兼容性

支持的平台

平台	支持状态	说明
macOS	✅ 完全支持	所有工具均可正常使用
Linux	✅ 完全支持	所有工具均可正常使用（包括 sudo_config）
Windows	✅ 基本支持	11个工具可用，2个工具部分支持

工具平台支持详情

完全跨平台支持（Windows/macOS/Linux）

以下工具在所有平台上均可正常使用：

• ✅ file_operation - 文件操作
• ✅ file_edit - 文件编辑
• ✅ file_search - 文件搜索
• ✅ file_compare - 文件比较
• ✅ file_hash - 文件哈希
• ✅ file_permissions - 文件权限管理（使用系统对应的命令：attrib/icacls 或 chmod）
• ✅ file_watch - 文件监控
• ✅ execute_command - 命令执行
• ✅ task_manager - 任务管理
• ✅ time_tool - 时间工具
• ✅ environment_memory - 环境记忆

平台限制

file_archive - 文件压缩工具

• macOS/Linux: ✅ 完全支持（使用系统命令 zip/unzip/tar/gzip）
• Windows: ⚠️ 需要安装额外工具
  • 需要安装 Git Bash、WSL 或第三方压缩工具
  • 或手动安装 zip/unzip/tar/gzip 命令行工具

sudo_config - Sudo配置工具

• Linux: ✅ 完全支持
• macOS: ❌ 不支持（不适用）
• Windows: ❌ 不支持（不适用）

Windows 用户注意事项

1. 路径格式: 使用反斜杠 \ 或正斜杠 / 均可，Node.js 会自动处理
2. 权限管理: 使用 Windows 原生的 attrib 和 icacls 命令
3. 压缩工具: 如需使用 file_archive，建议：
   • 安装 Git for Windows（自带 Bash 和常用工具）
   • 或使用 WSL (Windows Subsystem for Linux)
   • 或安装 7-Zip 并将其添加到系统 PATH

🔧 开发者与 API 状态概览

本项目已完成核心工具的参数别名与统一输出格式重构（API-001 / API-002 进入“接近完成”阶段）：

标准	描述	状态
API-001	参数别名统一（path/file_path/dir_path 等）	NEAR DONE
API-002	统一输出格式：`output_format = text	json

剩余仅为边缘场景再审阅与未来可选增强（例如更精细的 diff 输出拆分、搜索流式增量返回等）。

开发新增工具请阅读：tools/tools_dev_guide.md（已提供安全、参数、输出、测试、Checklist 全量规范）。

统一输出机制简述

所有工具通过 output_format 控制输出：

• text：人类可读摘要
• json：结构化数据（适合上层模型二次推理/程序化处理）
• both：同时返回（先文本后 JSON）

典型调用示例（文件比较）：

{
  "name": "file_compare",
  "arguments": {
    "file1": "/path/to/a.js",
    "file2": "/path/to/b.js",
    "output_format": "both"
  }
}

典型 JSON 片段（仅示例）：

{
  "action": "compare",
  "left": "/path/to/a.js",
  "right": "/path/to/b.js",
  "diff_stats": { "added": 12, "removed": 4, "modified": 3 }
}

搜索工具示例（限制深度 + 超时 + 忽略策略）：

{
  "name": "file_search",
  "arguments": {
    "search_path": "src",
    "pattern": "class ",
    "max_depth": 6,
    "timeout_ms": 4000,
    "ignore": ["node_modules", "*.log"],
    "output_format": "json"
  }
}

若结果被截断（大小/超时/数量），JSON 中会包含 truncated: true 或 timed_out: true 等标记字段。

✨ 功能特性

📁 文件操作工具

• 读取文件 - 安全读取本地文件内容
• 写入文件 - 创建或更新文件内容
• 列出目录 - 查看目录结构和文件列表
• 创建目录 - 创建新的目录结构
• 删除文件/目录 - 安全删除文件和目录

✏️ 文件编辑工具 (v1.1.0 新增)

• 删除行 - 删除指定行号范围的内容
• 插入行 - 在指定位置插入新内容
• 替换行 - 替换指定行号范围的内容
• 追加行 - 在文件末尾追加新内容

🔍 文件搜索工具 (v1.2.0 新增)

• 内容搜索 - 在文件中搜索指定内容
• 正则表达式 - 支持正则表达式搜索
• 文件类型过滤 - 按文件类型过滤搜索结果
• 大小写控制 - 支持区分/不区分大小写搜索

📊 文件比较工具 (v1.2.0 新增)

• 差异对比 - 比较两个文件的差异
• 行级对比 - 显示具体的行级差异
• 多种输出格式 - 支持文本和JSON格式输出

🔐 文件哈希工具 (v1.2.0 新增)

• 多种算法 - 支持MD5、SHA1、SHA256、SHA512
• 文件完整性 - 验证文件完整性
• 快速计算 - 高效的文件哈希计算

🛡️ 文件权限工具 (v1.2.0 新增)

• 权限修改 - 修改文件权限
• 递归应用 - 支持递归应用权限
• 权限显示 - 显示详细的权限信息

📦 文件压缩工具 (v1.2.0 新增)

• 多种格式 - 支持ZIP、TAR、GZ、TAR.GZ格式
• 压缩解压 - 支持压缩和解压操作
• 批量处理 - 支持目录批量压缩

👁️ 文件监控工具 (v1.2.0 新增)

• 实时监控 - 监控文件变化
• 事件类型 - 支持创建、删除、修改事件
• 定时监控 - 可设置监控时长

📋 任务管理工具 (v2.0.1 新增)

• 任务分解 - 支持创建复杂任务和子任务
• 优先级管理 - 支持低、中、高、紧急四个优先级
• 进度跟踪 - 实时跟踪任务完成进度
• 排期管理 - 支持设置截止日期
• 状态管理 - 待处理、进行中、已完成、已取消
• 模型隔离 - 不同模型拥有独立的任务列表

🧠 环境记忆工具 (v2.1.0 新增)

• 环境信息管理 - 自动读取和存储环境变量信息
• 动态更新 - 识别会话中的环境相关信息并自动记录
• 智能使用 - 根据会话上下文智能使用记忆的环境信息
• 文件存储 - 信息存储在 ~/.local_file_operations/.env 文件中

⚡ 命令执行工具

• 执行本地命令 - 在指定工作目录下执行系统命令
• 安全限制 - 自动过滤危险命令，保护系统安全

🔒 安全特性

🕒 时间工具 (v2.0.2 新增)

• 当前时间 - 获取当前真实时间

• 多种格式 - ISO、RFC3339、UNIX(秒/毫秒)、本地格式

• 时区支持 - 指定 IANA 时区（如 Asia/Shanghai）

• 路径限制 - 禁止访问敏感系统目录

• 命令过滤 - 阻止执行危险的系统命令

• 权限控制 - 确保操作在安全范围内

🚀 快速开始

环境要求

• Node.js >= 18.0.0
• npm 或 yarn

安装依赖

cd /Users/abc/research/mcp
npm install

📋 配置说明

LM Studio 配置

{
  "mcpServers": {
    "ax_local_operations": {
      "command": "/Users/abc/.nvm/versions/node/v22.16.0/bin/node",
      "args": ["/Users/abc/research/mcp/index.js"],
      "env": {
        "PATH": "/Users/abc/.nvm/versions/node/v22.16.0/bin:/usr/local/bin:/usr/bin:/bin",
        "NODE_PATH": "/Users/abc/research/mcp"
      }
    }
  }
}

### 注意这里的 "/Users/abc/research/mcp"   是下载到的文件夹的位置.要改成自己的路径.

Qwen 配置

{
  "mcpServers": {
    "ax_local_operations": {
      "command": "npx",
      "args": [
        "-y",
        "ax-local-operations-mcp@file:/Users/abc/research/mcp"
      ],
      "env": {
        "NODE_PATH": "/Users/abc/research/mcp",
        "PATH": "/Users/abc/.nvm/versions/node/v22.16.0/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

### 注意这里的 "ax-local-operations-mcp@file:/Users/abc/research/mcp"   @file: 后面是下载到的文件夹的位置.要改成自己的路径.

🛠️ 工具使用

文件操作工具

工作目录概念

为了安全性和灵活性，MCP服务器支持工作目录概念：

• 工作目录：通过 working_directory 参数指定一个安全的基础目录
• 相对路径：在 path 参数中使用相对路径，会自动基于工作目录解析
• 智能检测：自动识别常见的项目目录模式，支持直接使用绝对路径
• 安全限制：只有在允许的项目目录下的操作才被允许
• 跨平台兼容：不硬编码特定路径，适用于不同用户和系统

允许的项目目录模式

系统自动识别以下目录模式，允许直接使用绝对路径：

• /isoftstone/ - 项目目录
• /Desktop/ - 桌面
• /Documents/ - 文档
• /Downloads/ - 下载
• /Projects/ - 项目
• /Workspace/ - 工作空间
• /Code/ - 代码
• /Development/ - 开发
• /Work/ - 工作
• /Study/ - 学习
• /Research/ - 研究

读取文件

{
  "name": "file_operation",
  "arguments": {
    "operation": "read",
    "path": "/path/to/file.txt"
  }
}

写入文件

{
  "name": "file_operation",
  "arguments": {
    "operation": "write",
    "path": "/path/to/file.txt",
    "content": "文件内容"
  }
}

列出目录

{
  "name": "file_operation",
  "arguments": {
    "operation": "list",
    "path": "/path/to/directory"
  }
}

创建目录

{
  "name": "file_operation",
  "arguments": {
    "operation": "create_dir",
    "path": "/path/to/new/directory"
  }
}

使用工作目录（推荐）

{
  "name": "file_operation",
  "arguments": {
    "operation": "create_dir",
    "path": "售前类业务/自动HMI",
    "working_directory": "/Users/abc/isoftstone"
  }
}

删除文件/目录

{
  "name": "file_operation",
  "arguments": {
    "operation": "delete",
    "path": "/path/to/file_or_directory"
  }
}

文件编辑工具

删除行

{
  "name": "file_edit",
  "arguments": {
    "operation": "delete_lines",
    "path": "/path/to/file.txt",
    "start_line": 3,
    "end_line": 5
  }
}

插入行

{
  "name": "file_edit",
  "arguments": {
    "operation": "insert_lines",
    "path": "/path/to/file.txt",
    "start_line": 3,
    "content": "新插入的内容"
  }
}

替换行

{
  "name": "file_edit",
  "arguments": {
    "operation": "replace_lines",
    "path": "/path/to/file.txt",
    "start_line": 3,
    "end_line": 5,
    "content": "替换后的内容"
  }
}

追加行

{
  "name": "file_edit",
  "arguments": {
    "operation": "append_lines",
    "path": "/path/to/file.txt",
    "content": "追加到文件末尾的内容"
  }
}

命令执行工具

执行命令

{
  "name": "execute_command",
  "arguments": {
    "command": "ls -la",
    "working_directory": "/path/to/working/dir"
  }
}

文件搜索工具

搜索文件内容

{
  "name": "file_search",
  "arguments": {
    "search_path": "/path/to/search",
    "pattern": "function.*\\(",
    "file_types": "js,ts",
    "case_sensitive": false,
    "max_results": 50,
    "max_depth": 8,
    "timeout_ms": 5000,
    "ignore": ["node_modules", "*.log"]
  }
}

参数新增说明：

• max_depth (默认 8)：限制目录递归深度，防止深层/循环结构拖慢搜索。
• timeout_ms (默认 5000)：整体搜索的软超时，超时后会提前结束并返回已收集结果（结尾标注“超时截断”）。
• ignore：可忽略的文件/目录通配（支持前缀/后缀 * 简单匹配，如 *.log、build*、*cache）。

文件比较工具

比较两个文件

{
  "name": "file_compare",
  "arguments": {
    "file1": "/path/to/file1.txt",
    "file2": "/path/to/file2.txt",
    "output_format": "text"
  }
}

文件哈希工具

计算文件哈希

{
  "name": "file_hash",
  "arguments": {
    "path": "/path/to/file.txt",
    "algorithm": "sha256"
  }
}

文件权限工具

修改文件权限

{
  "name": "file_permissions",
  "arguments": {
    "path": "/path/to/file.txt",
    "mode": "755",
    "recursive": false
  }
}

文件压缩工具

压缩文件

{
  "name": "file_archive",
  "arguments": {
    "operation": "compress",
    "source": "/path/to/source",
    "destination": "/path/to/archive.zip",
    "format": "zip"
  }
}

解压文件

{
  "name": "file_archive",
  "arguments": {
    "operation": "extract",
    "source": "/path/to/archive.zip",
    "destination": "/path/to/extract"
  }
}

文件监控工具

监控文件变化

{
  "name": "file_watch",
  "arguments": {
    "path": "/path/to/watch",
    "events": "create,delete,modify",
    "duration": 60,
    "output_format": "text"
  }
}

任务管理工具

时间工具

获取当前时间（ISO，含毫秒）

{
  "name": "time_tool",
  "arguments": {
    "format": "iso",
    "include_milliseconds": true
  }
}

获取 UNIX 时间戳（秒）

{
  "name": "time_tool",
  "arguments": {
    "format": "unix"
  }
}

获取本地时间并指定时区

{
  "name": "time_tool",
  "arguments": {
    "format": "locale",
    "time_zone": "Asia/Shanghai",
    "include_milliseconds": false
  }
}

创建任务

{
  "name": "task_manager",
  "arguments": {
    "operation": "create",
    "model_name": "claude-3.5-sonnet",
    "title": "完成项目文档",
    "description": "编写API文档和使用说明",
    "priority": "high",
    "due_date": "2024-01-15T10:00:00Z",
    "subtasks": ["编写API文档", "创建使用示例", "更新README"]
  }
}

列出任务

{
  "name": "task_manager",
  "arguments": {
    "operation": "list",
    "model_name": "claude-3.5-sonnet",
    "status": "pending"
  }
}

更新任务

{
  "name": "task_manager",
  "arguments": {
    "operation": "update",
    "model_name": "claude-3.5-sonnet",
    "task_id": "task_1758140089301_bi4kwqkcl",
    "status": "in_progress",
    "progress": 50
  }
}

完成任务

{
  "name": "task_manager",
  "arguments": {
    "operation": "complete",
    "model_name": "claude-3.5-sonnet",
    "task_id": "task_1758140089301_bi4kwqkcl"
  }
}

🔧 工作原理

MCP 协议通信

1. 大模型应用启动 - 根据配置自动启动 MCP 服务器进程
2. 建立连接 - 通过 stdio 协议建立通信连接
3. 工具发现 - 大模型应用发送 ListTools 请求获取可用工具
4. 工具调用 - 当需要文件操作时，发送工具调用请求
5. 自动管理 - 大模型应用负责管理 MCP 服务器的生命周期

安全机制

本服务器采用分层安全模型：

1. 路径沙箱

• 仅允许访问用户主目录及其子目录（相对路径会被解析到用户 home）。
• 所有工具统一调用 securityValidator.resolveAndAssert() 进行归一化解析与主目录断言。
• 非法越界将返回错误码 E_PATH_DENIED。

2. 命令策略（Phase 0 重构后）

• 使用 lib/commandPolicy.js：正则匹配分级 deny | warn | allow。
• deny：抛出 E_DANGEROUS_CMD；warn：需调用方添加 { "confirm": true } 复确认。
• 典型 deny：passwd；典型 warn：rm -rf, sudo, chown, chmod 777。

3. 错误与输出统一

• 错误通过自定义 ToolError(code, message) 抛出。
• 主要错误码：
  • E_PATH_DENIED 路径不允许
  • E_NOT_FOUND 文件/目录不存在
  • E_INVALID_ARGS 参数或操作无效
  • E_DANGEROUS_CMD 危险命令
  • E_LIMIT_REACHED 递归/资源限制
• 输出封装：responses.text() / responses.json() / responses.both()。

4. 递归深度限制

• file_permissions 工具递归模式默认 max_depth = 5，超过抛 E_LIMIT_REACHED。

5. 压缩/解压安全

• 使用 child_process.spawn 参数数组替换字符串拼接，降低命令注入风险。

6. 未来计划（Phase 1+）

• file_search 增加 max_depth、timeout_ms 与 ignore 列表
• 工具注册解耦 & 生命周期钩子

若需要在企业内部开放更宽权限，可在外层代理做白名单前置，再调用此 MCP。

标准行为变化（自 v2.1.0-alpha.1 起）

变更	旧行为	新行为
路径解析	各工具独立解析	统一 home 基础 + 断言
危险命令	简单 substring 检测	策略分级 + confirm 机制
错误格式	抛普通 Error 文本	ToolError 结构化（内部）
压缩执行	拼接命令字符串	spawn 参数数组
递归权限	无深度限制	默认最大 5 层

示例：高风险命令确认

{
  "name": "execute_command",
  "arguments": { "command": "rm -rf tmp_cache", "confirm": true }
}

示例：递归权限并限制深度

{
  "name": "file_permissions",
  "arguments": { "path": "project", "mode": "755", "recursive": true, "max_depth": 3 }
}

📁 项目结构

mcp/
├── index.js              # MCP 服务器主文件
├── package.json          # Node.js 项目配置
├── mcp_config.json       # LM Studio 配置
├── qwen_config_final.json # Qwen 配置
├── mcp_config_template.json # 配置模板
├── tools/                # 工具模块目录
│   ├── fileOperation.js        # 文件操作工具
│   ├── fileEdit.js             # 文件编辑工具
│   ├── fileSearch.js           # 文件搜索工具
│   ├── fileCompare.js          # 文件比较工具
│   ├── fileHash.js             # 文件哈希工具
│   ├── filePermissions.js      # 文件权限工具
│   ├── fileArchive.js          # 文件压缩工具
│   ├── fileWatch.js            # 文件监控工具
│   ├── commandExecution.js     # 命令执行工具
│   ├── taskManager.js          # 任务管理工具
│   ├── timeTool.js             # 时间工具
│   ├── environmentMemory.js    # 环境记忆工具核心模块
│   ├── environmentMemoryAdapter.js # 环境记忆工具适配器
│   └── securityValidator.js    # 安全验证模块
├── temps/                # 临时文件目录（自动创建）
│   └── todo_<model_name>.json # 任务数据存储（运行时生成）
├── share4u.md            # 中文分享文档
├── share4u_en.md         # 英文分享文档
├── share4u_jp.md         # 日文分享文档
└── README.md             # 项目文档

🎯 支持的大模型应用

• ✅ LM Studio - 使用直接 node 执行
• ✅ Qwen - 使用 npx 本地包
• ✅ 其他支持 MCP 协议的应用

🔍 故障排除

常见问题

1. 连接失败 - 检查 Node.js 路径和文件权限
2. 工具不可用 - 确认 MCP 服务器正常启动
3. 权限错误 - 检查文件系统权限

调试方法

1. 手动测试 - 运行 npx -y ax-local-operations-mcp@file:/Users/abc/research/mcp
2. 检查日志 - 查看大模型应用的错误日志
3. 验证配置 - 确认配置文件格式正确

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

享受强大的本地文件操作能力！ 🚀✨

📚 版本历史

v2.6.0 (2025-02-04)

• 添加 MCP annotations 支持（readOnlyHint, destructiveHint 等）
• 添加 isError 标记到错误响应
• 重构命令执行为 spawn 模式提高安全性
• 添加 outputSchema 定义支持响应验证
• 完善参数描述和使用示例
• 添加文件大小限制（10MB）和截断处理
• 新增 CLAUDE.md 为 AI 开发提供指导

v2.5.0 (2025-12-05)

• 将版本号从 2.4.1 升级到 2.5.0
• 各种功能更新和改进

v2.1.0-alpha.1 (预发布)

• 路径解析与安全校验统一（pathUtils + securityValidator.resolveAndAssert）
• 命令执行引入策略分级（deny/warn/allow）
• 新增统一错误模块 errors.js 与响应封装 responses.js
• file_archive 使用 spawn 避免命令注入
• file_permissions 增加递归深度限制（默认 5）
• 为后续重构（工具注册 / 性能限制）奠定基础

v2.1.0 (2024-09-25)

• 新增环境记忆工具，用于管理环境变量信息
• 支持自动读取和存储环境信息
• 支持动态更新环境信息

环境记忆工具使用示例

读取环境信息

{
  "name": "environment_memory",
  "arguments": {
    "operation": "read"
  }
}

更新环境信息

{
  "name": "environment_memory",
  "arguments": {
    "operation": "update",
    "key": "PROJECT_PATH",
    "value": "/Users/username/projects/myproject"
  }
}

获取特定环境变量

{
  "name": "environment_memory",
  "arguments": {
    "operation": "get",
    "key": "PROJECT_PATH"
  }
}

v2.0.2 (2024-01-15)

• 新增时间工具，支持获取当前时间
• 支持多种时间格式（ISO、RFC3339、UNIX、本地格式）
• 支持时区设置

v2.0.1 (2024-01-10)

• 新增任务管理工具
• 支持任务创建、更新、完成等操作
• 支持优先级管理和进度跟踪
• 支持模型隔离的任务管理

v1.2.0 (2023-12-20)

• 新增文件搜索工具
• 新增文件比较工具
• 新增文件哈希工具
• 新增文件权限工具
• 新增文件压缩工具
• 新增文件监控工具

v1.1.0 (2023-12-10)

• 新增文件编辑工具
• 支持行级编辑操作（删除、插入、替换、追加）

v1.0.0 (2023-12-01)

• 初始版本发布
• 支持基本文件操作（读取、写入、列出、创建、删除）
• 支持命令执行工具

---

📦 安装与使用（无需下载源码）

支持通过 npm 全局安装或直接使用 npx 运行，无需手动克隆仓库或修改本地路径。

全局安装

npm install -g ax-local-operations-mcp

安装后，可在支持 MCP 的客户端中直接引用可执行文件 ax-local-operations-mcp。

直接使用 npx

无需安装，直接启动：

npx -y ax-local-operations-mcp

在 LM Studio 中使用

将可执行文件设置为 ax-local-operations-mcp（无需绝对路径）：

{
  "mcpServers": {
    "ax_local_operations": {
      "command": "ax-local-operations-mcp"
    }
  }
}

在 Qwen 中使用

使用 npx 直接调用（无需本地源码路径）：

{
  "mcpServers": {
    "ax_local_operations": {
      "command": "npx",
      "args": ["-y", "ax-local-operations-mcp"]
    }
  }
}

提示：若公司网络限制 npm，亦可发布到 GitHub Packages 或设置内部 npm 镜像，详见 dev.md 发布章节。