使用说明

WebDAV MCP 服务器

一个支持在WebDAV上进行CRUD操作的模型上下文协议（MCP）服务器带有基本身份验证的终端。此服务器支持Claude Desktop及其他 MCP客户端通过自然语言与WebDAV文件系统进行交互命令。

特点/特性

连接到任何WebDAV服务器，并可选择进行身份验证
对文件和目录执行CRUD操作
将文件操作作为MCP资源和工具进行展示
通过stdio传输（用于Claude桌面集成）或HTTP/SSE传输运行
使用可选的基本身份验证实现安全访问
支持使用bcrypt加密的密码进行MCP服务器认证（WebDAV）由于协议限制，密码必须为明文形式
使用连接池以提升与WebDAV服务器的性能
使用 Zod 进行配置验证
结构化日志记录以实现更好的故障排除

先决条件

Node.js 18 或更高版本
npm 或 yarn
WebDAV服务器（用于实际文件操作）

安装

选项1：从npm包安装

# Global installation
npm install -g webdav-mcp-server

# Or with npx
npx -y @masx200/webdav-mcp-server

选项2：克隆并从源代码构建

# Clone repository
git clone https://github.com/masx200/webdav-mcp-server.git
cd webdav-mcp-server

# Install dependencies
npm install

# Build the application
npm run build

选项3：Docker

# Build the Docker image
docker build -t webdav-mcp-server .

# Run the container without authentication
docker run -p 3000:3000 \
  -e WEBDAV_ROOT_URL=http://your-webdav-server \
  -e WEBDAV_ROOT_PATH=/webdav \
  webdav-mcp-server

# Run the container with authentication for both WebDAV and MCP server
docker run -p 3000:3000 \
  -e WEBDAV_ROOT_URL=http://your-webdav-server \
  -e WEBDAV_ROOT_PATH=/webdav \
  -e WEBDAV_AUTH_ENABLED=true \
  -e WEBDAV_USERNAME=admin \
  -e WEBDAV_PASSWORD=password \
  -e AUTH_ENABLED=true \
  -e AUTH_USERNAME=user \
  -e AUTH_PASSWORD=pass \
  webdav-mcp-server

配置

创建一个 .env 在根目录下的文件包含以下变量：

# WebDAV configuration
WEBDAV_ROOT_URL=http://localhost:4080
WEBDAV_ROOT_PATH=/webdav

# WebDAV authentication (optional)
WEBDAV_AUTH_ENABLED=true
WEBDAV_USERNAME=admin

# WebDAV password must be plain text (required when auth enabled)
# The WebDAV protocol requires sending the actual password to the server
WEBDAV_PASSWORD=password

# Server configuration (for HTTP mode)
SERVER_PORT=3000

# Authentication configuration for MCP server (optional)
AUTH_ENABLED=true
AUTH_USERNAME=user
AUTH_PASSWORD=pass
AUTH_REALM=MCP WebDAV Server

# Auth password for MCP server can be a bcrypt hash (unlike WebDAV passwords)
# AUTH_PASSWORD={bcrypt}$2y$10$CyLKnUwn9fqqKQFEbxpZFuE9mzWR/x8t6TE7.CgAN0oT8I/5jKJBy

用于MCP服务器认证的加密密码

为了增强MCP服务器（非WebDAV连接）的安全性，您可以使用使用bcrypt加密的密码，而不是以明文形式存储：

生成一个bcrypt哈希值：

# Using the built-in utility
npm run generate-hash -- yourpassword

# Or with npx
npx webdav-mcp-generate-hash yourpassword

在你的 .env 文件中添加哈希值，并在前面加上 {bcrypt} 前缀：
```
AUTH_PASSWORD={bcrypt}$2y$10$CyLKnUwn9fqqKQFEbxpZFuE9mzWR/x8t6TE7.CgAN0oT8I/5jKJBy
```

这样，您的MCP服务器密码就能得到安全存储。请注意，WebDAV 由于协议要求，密码必须始终以明文形式存在。

使用方法

使用stdio传输运行

这种模式非常适合与Claude桌面版进行直接集成。

# If installed globally
webdav-mcp-server

# If using npx
npx -y @masx200/webdav-mcp-server

# If built from source
node dist/index.js

使用HTTP/SSE传输运行

此模式允许通过HTTP使用服务器发送事件（Server-Sent Events）来访问服务器用于实时通信。

# If installed globally
webdav-mcp-server --http

# If using npx
npx -y @masx200/webdav-mcp-server --http

# If built from source
node dist/index.js --http

使用 Docker Compose 快速入门

开始使用WebDAV服务器和MCP服务器的最简单方法是使用 Docker Compose：

# Start both WebDAV and MCP servers
cd docker
docker-compose up -d

# This will start:
# - hacdias/webdav server on port 4080 (username: admin, password: admin)
# - MCP server on port 3000 (username: user, password: pass)

这个设置使用 hacdias/webdav（可译为“hacdias的WebDAV”或保持原样，因为“hacdias/webdav”可能是一个项目名或特定标识，直接翻译可能无法准确传达其含义），一个简单的以及一个用Go语言编写的独立WebDAV服务器。WebDAV的配置服务器存储在 webdav_config.yml，你可以对其进行修改以进行调整权限、添加用户或更改其他设置。

WebDAV服务器将所有文件存储在一个名为（此处应接具体名称，但原文未给出）的Docker卷中 webdav_data，该状态在容器重启后仍会保持。

WebDAV服务器配置

这个（或“该”） webdav_config.yml 文件配置了在（系统/应用中）使用的hacdias/webdav服务器 Docker Compose 配置。以下是您可以自定义的部分：

# Server address and port
address: 0.0.0.0
port: 6060

# Root data directory
directory: /data

# Enable/disable CORS
cors:
  enabled: true
  # Additional CORS settings...

# Default permissions (C=Create, R=Read, U=Update, D=Delete)
permissions: CRUD

# User definitions
users:
  - username: admin
    password: admin # Plain text password
    permissions: CRUD # Full permissions

  - username: reader
    password: reader
    permissions: R # Read-only permissions

  # You can also use bcrypt-encrypted passwords
  - username: secure
    password: "{bcrypt}$2y$10$zEP6oofmXFeHaeMfBNLnP.DO8m.H.Mwhd24/TOX2MWLxAExXi4qgi"

如需更多高级配置选项，请参阅 hacdias/webdav 文档。

测试

运行测试：

npm test

与Claude桌面版集成

确保在Claude Desktop中已启用MCP功能

Using npx

2. Open Claude Desktop settings and click edit config (`claude_desktop_config.json`) 3. Add ```json { "mcpServers": { "webdav": { "command": "npx", "args": [ "-y", "webdav-mcp-server" ], "env": { "WEBDAV_ROOT_URL": "", "WEBDAV_ROOT_PATH": "", "WEBDAV_USERNAME": "", "WEBDAV_PASSWORD": "", "WEBDAV_AUTH_ENABLED": "true|false" } } } } ```

Using node and local build

2. Clone this repository and run `setup.sh` on mac/linux or `setup.bat` on windows 3. Open Claude Desktop settings and click edit config (`claude_desktop_config.json`) 4. Add ```json { "mcpServers": { "webdav": { "command": "node", "args": [ "/dist/index.js" ], "env": { "WEBDAV_ROOT_URL": "", "WEBDAV_ROOT_PATH": "", "WEBDAV_USERNAME": "", "WEBDAV_PASSWORD": "", "WEBDAV_AUTH_ENABLED": "true|false" } } } } ```

可用的MCP资源

webdav://{path}/list - 列出目录中的文件
webdav://{path}/content - 获取文件内容
webdav://{path}/info - 获取文件或目录信息

可用的MCP工具

webdav_create_remote_file - 在远程WebDAV服务器上创建一个新文件
webdav_get_remote_file - 从远程存储的文件中检索内容 WebDAV服务器
webdav_update_remote_file - 更新远程WebDAV上的现有文件服务器
webdav_delete_remote_item - 从远程WebDAV中删除文件或目录服务器
webdav_create_remote_directory - 在远程WebDAV上创建一个新目录服务器
webdav_move_remote_item - 在远程WebDAV上移动或重命名文件/目录服务器
webdav_copy_remote_item - 将文件/目录复制到新位置远程WebDAV服务器
webdav_list_remote_directory - 列出远程WebDAV上的文件和目录服务器

增强功能

webdav_read_remote_file - 增强的文件读取功能，支持头部/尾部选项
webdav_edit_remote_file - 智能文件编辑，支持差异预览
webdav_list_directory_with_sizes - 增强的目录列表，显示文件大小及分类；排序
webdav_search_files - 使用带排除的通配符模式搜索文件支持
webdav_get_directory_tree - 获取递归目录树的JSON表示
webdav_read_multiple_files - 同时读取多个文件
webdav_get_file_info - 获取详细的文件/目录元数据
webdav_range_request - 从文件中读取特定的字节范围（HTTP 206）部分内容）

可用的MCP提示

webdav_create_remote_file - 提示在远程WebDAV上创建一个新文件服务器
webdav_get_remote_file - 提示从远程WebDAV检索内容文件
webdav_update_remote_file - 提示更新远程WebDAV上的文件服务器
webdav_delete_remote_item - 提示从远程删除文件/目录 WebDAV服务器
webdav_list_remote_directory - 提示列出远程目录内容 WebDAV服务器
webdav_create_remote_directory - 提示在远程服务器上创建一个目录 WebDAV服务器
webdav_move_remote_item - 提示在远程移动/重命名文件/目录 WebDAV服务器
webdav_copy_remote_item - 提示复制远程WebDAV上的文件/目录服务器

Claude中的示例查询

以下是一些示例查询，您可以在启用WebDAV MCP后在Claude Desktop中使用服务器已连接：

“列出我远程WebDAV服务器上的文件”
在远程WebDAV服务器上创建一个名为notes.txt的新文本文件，内容为以下内容：Hello World
“从我的远程WebDAV服务器获取document.txt文件的内容”
“用这个新配置更新我远程WebDAV服务器上的config.json文件”
“在我的远程WebDAV服务器上创建一个名为projects的目录”
“将report.docx文件复制到我远程WebDAV服务器上的备份位置”
“将文件 old_name.txt 重命名为 new_name.txt，并移动到我的远程 WebDAV 服务器上”
“从我的远程WebDAV服务器中删除temp.txt文件”

增强的特征操作

“读取日志文件的前20行：/logs/app.log”
“搜索所有JavaScript文件：*/.js，排除 node_modules 目录
“获取项目目录的树状结构”
“按文件大小列出上传目录的内容”
“同时读取多个配置文件”
“编辑配置文件并预览更改”
“获取文件的详细元数据信息”
“读取文件的前500字节：字节范围0-499”
“读取文件的最后100字节：字节位置=400-”

程序化使用

你也可以在自己的项目中通过编程方式使用这个包：

import { startWebDAVServer } from "webdav-mcp-server";

// For stdio transport without authentication
await startWebDAVServer({
  webdavConfig: {
    rootUrl: "http://your-webdav-server",
    rootPath: "/webdav",
    authEnabled: false,
  },
  useHttp: false,
});

// For stdio transport with WebDAV authentication (password must be plain text)
await startWebDAVServer({
  webdavConfig: {
    rootUrl: "http://your-webdav-server",
    rootPath: "/webdav",
    authEnabled: true,
    username: "admin",
    password: "password",
  },
  useHttp: false,
});

// With bcrypt hash for MCP server password (HTTP auth only)
await startWebDAVServer({
  webdavConfig: {
    rootUrl: "http://your-webdav-server",
    rootPath: "/webdav",
    authEnabled: true,
    username: "admin",
    password: "password", // WebDAV password must be plain text
  },
  useHttp: true,
  httpConfig: {
    port: 3000,
    auth: {
      enabled: true,
      username: "user",
      password:
        "{bcrypt}$2y$10$CyLKnUwn9fqqKQFEbxpZFuE9mzWR/x8t6TE7.CgAN0oT8I/5jKJBy",
    },
  },
});

// For HTTP transport with MCP authentication
await startWebDAVServer({
  webdavConfig: {
    rootUrl: "http://your-webdav-server",
    rootPath: "/webdav",
    authEnabled: true,
    username: "admin",
    password: "password",
  },
  useHttp: true,
  httpConfig: {
    port: 3000,
    auth: {
      enabled: true,
      username: "user",
      password: "pass",
      realm: "MCP WebDAV Server",
    },
  },
});

// For HTTP transport without authentication
await startWebDAVServer({
  webdavConfig: {
    rootUrl: "http://your-webdav-server",
    rootPath: "/webdav",
    authEnabled: false,
  },
  useHttp: true,
  httpConfig: {
    port: 3000,
    auth: {
      enabled: false,
    },
  },
});

许可证

麻省理工学院（MIT）

WebDAV MCP 服务器增强功能文档

概述

本文档记录了基于filesystem MCP的WebDAV MCP Server的全面增强功能。服务器实现，大幅提升了文件操作能力和用户体验。

新增功能

1. 增强文件读取功能

`webdav_read_remote_file`

功能读取文件内容，支持 head/tail 参数
参数：
- path (string): 文件路径
- head (number, 可选): 返回文件的前 N 行
- tail (number, 可选): 返回文件的最后 N 行
特性：
- 内存高效：读取大文件时不会加载全部内容
- 参数验证：head 和 tail 不能同时使用
- 灵活读取：支持读取文件开头或结尾部分

2. 智能文件编辑功能

`webdav_edit_remote_file`

功能智能文件编辑，支持部分替换和diff预览
参数：
- path (string): 文件路径
- edits (array): 编辑操作数组，包含 oldText 和 newText
- dryRun (boolean, 可选): 预览模式，生成 diff 但不实际修改文件
特性：
- 精确匹配：查找并替换精确的文本序列
- 多重编辑：支持在单次操作中应用多个编辑
- Diff 预览：生成 Git 风格的差异预览
- 安全模式：干运行模式确保编辑安全

3. 高级文件搜索功能

`webdav_search_files`

功能使用 glob 模式递归搜索文件和目录
参数:
- path (string, 可选): 搜索起始目录，默认为根目录
- pattern (string): Glob 模式匹配规则（例如 *.txt， **/*.js， config.*）
- excludePatterns (array, 可选): 排除模式数组
特性：
- Glob 模式：支持标准的 glob 模式匹配
- 排除模式：支持排除特定文件或目录
- 递归搜索：深度搜索整个目录树
- 路径验证：所有路径均经过安全验证

4. 目录树结构功能

`webdav_get_directory_tree`

功能获取递归目录树结构的 JSON 表示
参数：
- path (string, 可选): 根目录路径，默认为根目录
- excludePatterns (array, 可选): 排除模式数组
特性:
- JSON 结构：返回结构化的 JSON 树形数据
- 递归遍历：完整遍历目录层次结构
- 模式排除：支持排除特定项目
- 清晰格式：2 个空格缩进的可读格式

5. 增强目录列表功能

`webdav_list_directory_with_sizes`

功能增强目录列表，包含文件大小、排序和统计信息
参数：
- path (string, 可选): 目录路径，默认为根目录
- sortBy (enum，可选): 排序方式（'name' 或 'size'），默认按名称排序
特性：
- 文件大小：显示每个文件的格式化大小
- 排序选项：支持按名称或大小排序
- 统计信息：显示文件总数、目录总数和总大小
- 格式化输出：清晰的表格格式显示

6. 详细文件信息功能

`webdav_get_file_info`

功能获取文件或目录的详细元数据
参数：
- path (字符串): 文件或目录路径
特性：
- 完整元数据：名称、路径、类型、大小、修改时间、MIME 类型
- 格式化大小：人类可读的文件大小格式
- 时间戳：详细的最后修改时间
- 类型识别：区分文件和目录类型

7. 多文件同时读取功能

`webdav_read_multiple_files`

功能同时读取多个文件内容
参数：
- paths (array): 文件路径数组
特性：
- 并行处理：并发读取多个文件以提高效率
- 错误隔离：单个文件读取失败不影响其他文件
- 格式化输出：清晰地分隔显示多个文件内容
- 错误报告：显示详细的错误信息

8. 范围请求功能

`webdav_range_request`

功能按字节范围读取文件内容，支持HTTP 206部分内容响应
参数:
- path (string): 文件路径
- range (string): 字节范围，格式如 bytes=0-499， bytes=400-， 0-499
特性：
- HTTP标准兼容：完全兼容HTTP 1.1范围请求规范
- 多种格式支持：支持 bytes=0-499， bytes=400-， 0-499 等格式
- 大文件优化：适用于大文件的部分内容读取，减少网络传输
- 元数据返回：返回 Content-Range、Content-Length、Total-Size 等信息
- Unicode支持：正确处理多字节字符的范围计算

技术实现

依赖项增强

**最小匹配（或最小匹配项）**用于 glob 模式匹配的强大库
TypeScript增强类型安全性和代码质量

核心服务扩展

WebDAV服务新增多个方法支持高级功能
智能编辑内置差异生成和文本替换逻辑
搜索算法高效的递归搜索和模式匹配

错误处理

详细的错误信息所有操作包含完整的错误描述
安全验证路径验证防止未经授权的访问
优雅降级部分失败不影响整体操作

使用示例

1. 读取文件的前10行

const result = await toolHandler("webdav_read_remote_file", {
  path: "/logs/app.log",
  head: 10,
});

2. 智能编辑文件

const result = await toolHandler("webdav_edit_remote_file", {
  path: "/config/settings.json",
  edits: [
    {
      oldText: '"debug": false',
      newText: '"debug": true',
    },
  ],
  dryRun: true, // 预览模式
});

3. 搜索所有 JavaScript 文件

const result = await toolHandler("webdav_search_files", {
  path: "/src",
  pattern: "**/*.js",
  excludePatterns: ["node_modules/**", "dist/**"],
});

4. 获取目录树结构

const result = await toolHandler("webdav_get_directory_tree", {
  path: "/project",
  excludePatterns: [".git/**", "node_modules/**"],
});

5. 列出目录详情并按大小排序

const result = await toolHandler("webdav_list_directory_with_sizes", {
  path: "/uploads",
  sortBy: "size",
});

6. 范围请求示例

// 读取文件前 500 字节
const result = await toolHandler("webdav_range_request", {
  path: "/large-file.txt",
  range: "bytes=0-499",
});

// 读取文件最后 100 字节
const result = await toolHandler("webdav_range_request", {
  path: "/large-file.txt",
  range: "bytes=400-",
});

// 读取文件中间部分
const result = await toolHandler("webdav_range_request", {
  path: "/large-file.txt",
  range: "bytes=100-199",
});

性能优化

内存效率

流式读取大文件采用内存高效的流式处理
并发操作多文件操作使用并发处理
延迟加载按需加载文件内容和元数据

网络优化

连接池复用 WebDAV 连接以减少开销
批量操作减少网络请求次数
错误重试自动处理临时网络问题

安全特性

路径验证

根目录限制所有操作限制在允许的目录内
符号链接处理安全处理符号链接以防止路径遍历攻击
路径规范化统一路径格式以防止绕过

操作安全

原子操作文件写入使用原子操作防止数据损坏
预览模式编辑操作支持预览以避免误操作
详细日志所有操作记录详细日志

兼容性

向后兼容

现有API保持所有现有工具和API不变
渐进增强新功能作为可选参数添加
默认行为保持原有默认行为不变

WebDAV 标准

协议兼容完全兼容WebDAV协议标准
多平台支持支持各种WebDAV服务器实现
认证支持保持现有认证机制

总结

这些增强功能极大地提升了WebDAV MCP服务器的性能其功能性和易用性，使其成为一个功能完整、性能优异、安全可靠的文件管理解决方案。新功能在保持向后兼容的同时，为用户提供了强大的文件操作能力，特别适合复杂的项目管理和开发工作流程。

🎯 范围请求功能

新增的范围请求功能是WebDAV MCP服务器的一个重要里程碑，它提供了：

HTTP标准兼容完全兼容HTTP 1.1范围请求规范
性能优化大文件的部分内容读取，显著减少网络传输
应用场景丰富日志分析、音视频元数据提取、大文件预览等
技术先进精确的字节范围计算和Unicode字符支持

这一功能的加入，使WebDAV MCP服务器在文件处理能力上达到了新的高度，为用户提供了更强大和灵活的文件操作体验。