claude-code-skill-power/filesystem-mcp-server/README.md

# FileSystem MCP Server

一个基于 Model Context Protocol (MCP) 的文件系统服务器，提供与本地文件系统交互的工具。

## 概述

FileSystem MCP Server 是一个 Node.js/TypeScript 实现的服务端应用，通过 MCP 协议使 AI 模型能够安全地读取、浏览和搜索本地文件系统。该服务器提供三个核心工具：`read_file`、`list_directory` 和 `search_files`，支持多种输出格式和输入验证。

## 功能特性

- **安全文件读取** - 支持指定编码、行范围和字符限制的文本读取
- **目录内容浏览** - 列出目录中的文件和子目录，包含元数据
- **模式匹配搜索** - 使用 glob 模式递归搜索文件
- **双传输模式** - 支持 stdio（本地）和 HTTP（远程）两种传输方式
- **类型安全** - 完整的 TypeScript 类型定义和 Zod 输入验证

## 系统要求

- Node.js >= 18
- npm 或 yarn

## 快速开始

### 安装

```bash
cd filesystem-mcp-server
npm install
```

### 构建

```bash
npm run build
```

### 运行

**stdio 模式（默认，本地集成）**

```bash
npm start
```

**HTTP 模式（远程访问）**

```bash
TRANSPORT=http npm start
```

**开发模式（热重载）**

```bash
npm run dev
```

HTTP 模式默认监听 3000 端口，可通过 `PORT` 环境变量指定其他端口：

```bash
PORT=8080 TRANSPORT=http npm start
```

## 工具说明

### read_file

读取指定路径的文件内容。

**参数**

| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `path` | string | 是 | - | 文件的绝对路径 |
| `encoding` | string | 否 | `utf-8` | 文件编码 |
| `max_chars` | number | 否 | - | 返回的最大字符数 |
| `line_start` | number | 否 | - | 起始行号（1-based） |
| `line_end` | number | 否 | - | 结束行号（1-based） |
| `response_format` | string | 否 | `markdown` | 输出格式：`markdown` 或 `json` |

**示例**

```json
{
  "path": "/path/to/config.json",
  "encoding": "utf-8",
  "line_start": 1,
  "line_end": 100,
  "response_format": "markdown"
}
```

**输出格式**

- Markdown：人类可读的格式化输出，包含文件信息和代码块
- JSON：包含完整元数据的结构化数据

---

### list_directory

列出指定目录的内容。

**参数**

| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `path` | string | 是 | - | 目录的绝对路径 |
| `response_format` | string | 否 | `markdown` | 输出格式：`markdown` 或 `json` |

**示例**

```json
{
  "path": "/path/to/project",
  "response_format": "markdown"
}
```

**输出格式**

- Markdown：人类可读的目录结构，使用图标标识文件和目录
- JSON：包含文件和目录详细信息的结构化数据

---

### search_files

使用 glob 模式在目录中搜索文件。

**参数**

| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `path` | string | 是 | - | 搜索起始目录的绝对路径 |
| `pattern` | string | 是 | - | glob 模式（如 `*.ts`、`**/*.json`） |
| `max_results` | number | 否 | 50 | 返回的最大结果数（最大 100） |
| `include_content` | boolean | 否 | `false` | 是否在结果中包含文件内容 |
| `response_format` | string | 否 | `markdown` | 输出格式：`markdown` 或 `json` |

**模式示例**

| 模式 | 匹配 |
|------|------|
| `*.ts` | 当前目录下的所有 TypeScript 文件 |
| `**/*.json` | 任意目录下的所有 JSON 文件 |
| `src/**/*.ts` | src 目录下的所有 TypeScript 文件 |
| `*.{js,ts}` | 当前目录下的所有 JS 和 TS 文件 |

**示例**

```json
{
  "path": "/path/to/project",
  "pattern": "**/*.ts",
  "max_results": 50,
  "include_content": false,
  "response_format": "json"
}
```

**输出格式**

- Markdown：人类可读的搜索结果列表
- JSON：包含所有匹配文件详细信息的结构化数据

## 环境变量

| 变量 | 值 | 说明 |
|------|-----|------|
| `TRANSPORT` | `stdio` 或 `http` | 传输协议，默认 `stdio` |
| `PORT` | 端口号 | HTTP 模式监听的端口，默认 `3000` |

## 在 MCP 客户端中使用

### Claude Desktop 配置

在 Claude Desktop 的配置文件中添加：

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
      "disabled": false,
      "env": {}
    }
  }
}
```

### 环境变量配置

如需使用 HTTP 模式：

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
      "disabled": false,
      "env": {
        "TRANSPORT": "http",
        "PORT": "3000"
      }
    }
  }
}
```

## 项目结构

```
filesystem-mcp-server/
├── package.json          # 项目配置和依赖
├── tsconfig.json         # TypeScript 编译配置
├── README.md             # 项目文档
├── src/
│   ├── index.ts          # 服务器入口点
│   ├── types.ts          # TypeScript 类型定义
│   ├── constants.ts      # 常量配置
│   └── tools/
│       ├── index.ts      # 工具注册
│       ├── read-file.ts      # 读取文件工具实现
│       ├── list-directory.ts # 目录列表工具实现
│       └── search-files.ts   # 文件搜索工具实现
└── dist/                 # 编译输出
```

## 开发

### 可用脚本

```bash
# 构建项目
npm run build

# 开发模式（热重载）
npm run dev

# 清理构建产物
npm run clean
```

### 添加新工具

1. 在 `src/tools/` 目录中创建新的工具文件
2. 使用 `server.registerTool()` 注册工具
3. 在 `src/tools/index.ts` 中导出工具注册函数

## 错误处理

所有工具都提供清晰的错误信息：

| 错误类型 | 错误信息 |
|---------|---------|
| 文件不存在 | `Error: File not found: <path>` |
| 目录不存在 | `Error: Directory not found: <path>` |
| 权限被拒 | `Error: Permission denied to <operation>: <path>` |
| 路径是文件 | `Error: Path is a file, not a directory: <path>` |
| 路径是目录 | `Error: Path is a directory, not a file: <path>` |

## 许可证

MIT License