# MCP Filesystem Server

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的文件系统服务器，使用 Python 和 FastMCP 实现。

## 🌟 特性

- 🔒 **安全访问控制**：只允许访问指定的目录
- 📁 **完整文件操作**：读取、写入、创建、移动、搜索文件
- 🛠️ **丰富的工具集**：通过 MCP 协议提供9个文件系统工具
- 📊 **资源管理**：提供文件、目录和配置资源
- 🚀 **多种启动方式**：支持 stdio、HTTP、SSE 模式
- ✅ **测试驱动开发**：完整的测试覆盖

## 🛠️ 安装

### 要求

- Python >= 3.10
- [uv](https://docs.astral.sh/uv/) (推荐) 或 pip

### 从源码安装

```bash
# 克隆仓库
git clone <your-repo-url>
cd mcp_filesystem_server

# 使用 uv 安装（推荐）
uv sync

# 或使用 pip 安装
pip install -e .
```

## 🚀 使用方法

### 基本用法

```bash
# 默认 stdio 模式，使用当前目录
mcp-filesystem-server

# 指定允许访问的目录
mcp-filesystem-server --allowed-dir /path/to/folder --allowed-dir /another/path

# HTTP 模式
mcp-filesystem-server http --port 8080 --allowed-dir /home/user

# SSE 模式
mcp-filesystem-server sse --host 0.0.0.0 --port 3000 --allowed-dir /workspace
```

### 启动模式

| 模式 | 描述 | 用途 |
|------|------|------|
| `stdio` | 标准输入输出通信（默认） | 与 MCP 客户端直接集成 |
| `http` | HTTP 服务器 | Web 应用集成 |
| `sse` | Server-Sent Events | 实时通信应用 |

### 命令选项

- `--allowed-dir` / `-d`: 允许访问的目录（可多次指定）
- `--port` / `-p`: 服务器端口（HTTP/SSE 模式）
- `--host` / `-h`: 服务器主机（HTTP/SSE 模式）

## 🔧 MCP 工具

服务器提供以下工具：

| 工具名称 | 功能 | 参数 |
|----------|------|------|
| `read_file` | 读取文件内容 | `path: str` |
| `read_multiple_files` | 读取多个文件 | `paths: List[str]` |
| `read_image` | 读取图片文件 | `path: str, max_bytes?: int` |
| `read_multiple_images` | 读取多个图片文件 | `paths: List[str], max_bytes?: int` |
| `write_file` | 写入文件 | `path: str, content: str` |
| `create_directory` | 创建目录 | `path: str` |
| `list_directory` | 列出目录内容 | `path: str` |
| `move_file` | 移动/重命名文件 | `source: str, destination: str` |
| `search_files` | 搜索文件 | `path: str, pattern: str, exclude_patterns?: List[str]` |
| `get_file_info` | 获取文件信息 | `path: str` |
| `edit_file` | 编辑文件内容 | `path: str, edits: List[Dict], dry_run?: bool` |
| `get_filesystem_info` | 获取服务器配置信息 | 无 |

## 📊 MCP 资源

服务器提供以下资源：

| 资源URI | 功能 | 描述 |
|---------|------|------|
| `file://{path}` | 文件内容 | 以资源形式访问文件 |
| `directory://{path}` | 目录内容 | JSON格式的目录列表 |
| `config://filesystem` | 服务器配置 | 服务器配置和能力信息 |

## 🧪 开发

### 安装开发依赖

```bash
# 安装 hatch 工具
uv tool install hatch

# 安装项目依赖
uv sync
```

### 运行测试

```bash
# 运行所有测试
uv tool run hatch run test

# 运行特定测试文件
uv tool run hatch run test -- tests/test_filesystem_service.py -v

# 运行测试并生成覆盖率报告
uv tool run hatch run coverage
```

### 代码格式化

```bash
# 格式化代码
uv tool run hatch run format

# 检查代码风格
uv tool run hatch run lint

# 类型检查
uv tool run hatch run typecheck

# 一键检查并修复
uv tool run hatch run fix
```

### 构建可执行文件

```bash
# 构建可执行文件
uv tool run hatch run all
```

### 项目结构

```
mcp_filesystem_server/
├── src/mcp_filesystem_server/
│   ├── __init__.py           # 包初始化
│   ├── version.py            # 版本信息
│   ├── filesystem_service.py # 核心文件系统服务
│   ├── server.py            # FastMCP 服务器实现
│   └── main.py              # CLI 入口点
├── tests/                   # 测试文件
│   ├── conftest.py          # pytest 配置
│   ├── test_filesystem_service.py
│   └── test_server.py
├── pyproject.toml           # 项目配置
└── README.md               # 项目文档
```

## 🔒 安全特性

- **路径限制**：只能访问明确允许的目录
- **路径验证**：防止目录遍历攻击
- **错误处理**：安全的错误消息，不泄露系统信息
- **权限检查**：每个操作都进行权限验证

## 📝 使用示例

### 与 Claude Desktop 集成

在 Claude Desktop 配置文件中添加：

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem-server",
      "args": ["--allowed-dir", "/your/workspace/path"]
    }
  }
}
```

### 与 MCP 客户端集成

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 创建服务器参数
server_params = StdioServerParameters(
    command="mcp-filesystem-server",
    args=["--allowed-dir", "/workspace"]
)

async def main():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # 列出可用工具
            tools = await session.list_tools()
            print(f"可用工具: {[tool.name for tool in tools]}")
            
            # 调用工具
            result = await session.call_tool("read_file", {"path": "/workspace/test.txt"})
            print(f"文件内容: {result.content}")
```

## 🤝 贡献

欢迎贡献！请确保：

1. 所有测试通过：`uv tool run hatch -e test run test`
2. 代码风格检查通过：`uv tool run hatch -e dev run lint`
3. 代码格式化：`uv tool run hatch -e dev run format`
4. 或使用一键检查：`uv tool run hatch -e dev run fix`

## 📄 许可证

MIT License - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🔗 相关链接

- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [MCP 规范](https://spec.modelcontextprotocol.io)