MCP Filesystem Server (Node.js)

一个基于 Node.js 的 Model Context Protocol (MCP) 文件系统服务器，提供安全受限的文件操作工具，采用官方 TypeScript SDK + STDIO 传输。

• 与 Python 版本 simple_filesystem.py 功能对齐
• 安全边界：仅可访问启动参数指定的目录（及其子目录）
• 适用于 MCP Host（例如 Claude Desktop、Cursor、mcp-inspector）通过子进程方式启动

特性

• 列出目录、读取/写入文件、批量读取、编辑文件（带 diff）、创建目录、移动/重命名、查询文件信息、列出允许路径、目录树、文件搜索（通配符 * ?）
• STDIO 传输，标准 MCP server
• TypeScript 实现，内置 zod 入参校验

安装

# 在你的项目中安装
npm install mcp-math-server-nodejs
# 或全局安装（可作为命令使用）
npm install -g mcp-math-server-nodejs

注意：如果你使用 PowerShell，可能需要解除脚本执行限制： Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

构建（从源码）

npm install
npm run build

使用

本服务器采用 STDIO 传输，建议由 MCP Host 以子进程启动。

直接运行（Node.js）：

node dist/index.js <allowed_dir_1> <allowed_dir_2> ...
# 示例：仅允许访问当前目录
node dist/index.js .

全局安装后的命令（如 package.json 中 bin 字段所述）：

mcp-math-server <allowed_dir_1> <allowed_dir_2> ...

在 MCP Host（例如 mcp-inspector）中配置：

• command: node
• args: ["/absolute/path/to/dist/index.js", "D:\\code\\uav_mcp\\test"]

可用工具

• list_directory(dir_path)
• read_file(file_path)
• write_file(file_path, content)
• read_multiple_files(file_paths[])
• edit_file(file_path, edits[{oldText,newText}], dry_run=false)
• create_directory(dir_path)
• move_file(source_path, destination_path)
• get_file_info(file_path)
• list_allowed_directories()
• directory_tree(dir_path)
• search_files(start_path, pattern)

返回值均为 MCP Content 数组中的文本内容（text block）。

安全与限制

• 只能访问启动参数指定的目录（及其子目录）。使用 path.relative 校验，防止路径前缀绕过。
• 建议为生产环境增加更多安全限制（例如：最大文件大小、可写目录白名单、只读模式等）。

与 Python 版本的对应

• Python 参考：test/python_mcp/simple_filesystem.py
• 工具名、语义与行为保持一致；search_files 支持通配符 * 与 ?，大小写不敏感。
• edit_file 的 diff 为简化的行级 diff。如果你需要严格 unified diff（包含行号与上下文块），欢迎提 issue。

本地开发

npm install
npm run dev # 仅 TypeScript 编译 watch；运行仍需由 MCP Host 启动子进程连接 STDIO

许可证

本项目采用 MIT 协议，详见 LICENSE。