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

快速开始

安装

cd filesystem-mcp-server
npm install

构建

npm run build

运行

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

npm start

HTTP 模式（远程访问）

TRANSPORT=http npm start

开发模式（热重载）

npm run dev

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

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

示例

{
  "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

示例

{
  "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 文件

示例

{
  "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 的配置文件中添加：

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

环境变量配置

如需使用 HTTP 模式：

{
  "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/                 # 编译输出

开发

可用脚本

# 构建项目
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