Mcpfileserver

📂 MCP文件服务器

MCP文件服务器 是一个安全的沙盒文件服务器，通过 模型控制协议（MCP）。它支持在可配置的工作目录中读取、写入、列出、创建和删除文件和目录，同时执行严格的安全检查。Git操作也可用于工作目录中的存储库。

目录

• 特性
• 安装和快速启动
• 命令行选项
• 与LM集成 工作室
• MCP API概述

- initialize - tools/list - tools/call

• 可用工具

- 文件操作 - read_file - write_file - list_files - create_directory - delete_file - delete_directory - search_in_file - Git操作 - git_status - git_log - git_checkout - git_branch_create - git_branch_delete - git_branch_list - git_add - git_commit - git_push - git_pull - git_diff - git_clone - git_submodule_add - git_submodule_update - git_submodule_list

• 安全功能

🎯 特性

• 沙盒操作 –所有路径都限制在用户指定的工作目录中。
• 路径遍历保护、文件大小限制和阻止的扩展名。
• 通过Base64编码提供二进制支持，用于安全传输非文本数据。
• 工作目录中存储库的Git操作（状态、日志、分支、提交/推送/拉取）。
• 适用于stdin/stdout集成的简单行分隔JSON-RPC协议。
• 即用型 LM 工作室 通过最小 mcp.json 配置。

📦 安装和快速启动

# Clone the repository (if not already done)
git clone https://github.com/undici77/MCPFileServer.git
cd MCPFileServer

# Ensure git is installed on your system (required for git operations)
git --version

# Run the startup script – it creates a virtual environment,
# installs dependencies, and starts the server.
./run.sh -d /path/to/working/directory

脚本将：

• 验证Python 3 可用。
• 创建一个 .venv 虚拟环境（如果缺失）。
• 安装所需的软件包(aiofiles).
• 开始 main.py 使用提供的工作目录。

📌 Git操作注意事项：git操作使用Python的 subprocess 调用系统 git CLI。Git必须在PATH中安装并可用。 📌 提示： 确保脚本具有执行权限： chmod +x run.sh

⚙️ 命令行选项

🤝 与LM集成 工作室

在项目中为文件服务器添加条目 mcp.json:

{
  "mcpServers": {
    "file-server": {
      "command": "/absolute/path/to/MCPFileServer/run.sh",
      "args": [
        "-d",
        "/absolute/path/to/working/directory"
      ],
      "env": {
        "WORKING_DIR": "."
      }
    }
  }
}

• 将路径替换为机器上的绝对位置。
• 确保 run.sh 可执行(chmod +x run.sh)并且安装了依赖项。

📡 MCP API概述

所有通信如下 JSON-RPC 2.0 通过stdin/stdout。

initialize

由客户端发送以获取服务器功能。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

服务器以协议版本、功能及其名称/版本进行响应。

tools/list

检索支持的工具的机器可读列表。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

响应包含一系列工具定义（名称、描述、输入模式）。

tools/call

调用特定工具。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "",
    "arguments": { … }
  }
}

注： 工具名称的关键字是 **name**，不 tool。这与服务器实现相匹配。

🛠️ 可用工具

文件操作

read_file

读取工作目录中文件的内容。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "example.txt",
      "binary": false
    }
  }
}

write_file

将内容写入文件（如果需要，创建中间目录）。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "write_file",
    "arguments": {
      "path": "output.txt",
      "content": "Hello, world!",
      "binary": false
    }
  }
}

列表文件

列出工作目录下的文件和目录。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
      "extensions": [".py", ".txt"],
      "recursive": true,
      "show_empty_dirs": false
    }
  }
}

create_directory

创建一个新目录（包括任何缺失的父目录）。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "create_directory",
    "arguments": { "path": "new_folder/subfolder" }
  }
}

删除文件

删除工作目录中的文件。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "delete_file",
    "arguments": { "path": "temp.txt" }
  }
}

delete_directory

删除目录，可选择强制删除其内容。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "delete_directory",
    "arguments": { "path": "old_folder", "force": true }
  }
}

search_in_file

在文件中搜索字符串，或在目录中的所有文件中递归搜索字符串，返回上下文摘录。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "search_in_file",
    "arguments": {
      "path": "log.txt",
      "search_string": "ERROR",
      "context_lines": 2,
      "case_sensitive": false,
      "max_matches": 10
    }
  }
}

______________________________________________________________________

Git操作

默认情况下，所有git操作都在工作目录上工作。要在嵌套存储库上操作，请使用 repo_path 参数。

注： 所有git工具都支持可选 repo_path 用于在子目录中的存储库上操作的参数（例如。， "repo_path": "vendor/my-repo").如果省略，操作将直接针对工作目录。

git_status

显示工作树状态。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_status",
    "arguments": { 
      "short": true,
      "repo_path": "vendor/my-repo"
    }
  }
}

git_log

显示提交日志历史记录。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_log",
    "arguments": { 
      "max_count": 10, 
      "oneline": true,
      "repo_path": "vendor/my-repo"
    }
  }
}

git_checkout

切换到其他分支或提交。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_checkout",
    "arguments": { 
      "branch": "main",
      "repo_path": "vendor/my-repo"
    }
  }
}

git_branch_create

创建一个新分支。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_branch_create",
    "arguments": { 
      "branch": "feature/new-ui",
      "start_point": "main"
    }
  }
}

git_branch_delete

删除分支。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_branch_delete",
    "arguments": { 
      "branch": "old-branch",
      "force": true
    }
  }
}

git_branch_list

列出存储库中的所有分支。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_branch_list",
    "arguments": { "all": true }
  }
}

git_add

将文件内容添加到暂存区。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_add",
    "arguments": { 
      "paths": ["src/main.py", "tests/test_main.py"] 
    }
  }
}

git_提交

将更改记录到存储库中。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_commit",
    "arguments": { 
      "message": "Add new feature",
      "all": true
    }
  }
}

git_push

将更改推送到远程存储库。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_push",
    "arguments": { 
      "remote": "origin",
      "branch": "main"
    }
  }
}

git_pull

从远程存储库获取并与之集成。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_pull",
    "arguments": { 
      "remote": "origin",
      "branch": "main"
    }
  }
}

使用 git_diff

显示提交、提交和工作树之间的变化。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_diff",
    "arguments": {
      "path": "src/main.py"
    }
  }
}

git_clone

将存储库克隆到新目录中。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_clone",
    "arguments": {
      "url": "https://github.com/owner/repo.git",
      "path": "vendor/repo",
      "branch": "main"
    }
  }
}

git_submodule_add

向存储库添加子模块。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_submodule_add",
    "arguments": {
      "url": "https://github.com/owner/lib.git",
      "path": "vendor/lib"
    }
  }
}

git_submodule_update

更新现有子模块。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_submodule_update",
    "arguments": {
      "init": true,
      "recursive": true
    }
  }
}

git_submodule_list

列出存储库中的所有子模块。 参数

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_submodule_list",
    "arguments": { "summary": true }
  }
}

______________________________________________________________________

🔐 安全功能

• 路径遍历保护 –根据工作目录解析所有路径；试图逃逸会导致错误。
• 阻止扩展名和敏感文件名 –文件，如 .exe, .bat, passwd等等，都被拒绝了。
• 文件大小限制 –读/写超过 100 MiB (MAX_FILE_SIZE)被拒绝。
• 空字节和危险模式检查 –防止格式错误的输入攻击。
• Git命令验证 -验证分支名称和路径以防止注入攻击。

______________________________________________________________________

*©2025 Undici77-保留所有权利。*