267 lines
6.1 KiB
Markdown
267 lines
6.1 KiB
Markdown
# 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
|