JinDaGe - filesystem-mcp-server MCP Details

article

README

🚀 文件系统协议服务器

本项目是一个基于 Model Context Protocol (MCP) 的文件系统协议服务器，它为 AI 模型提供了通过上下文协议与文件系统进行交互的能力。借助该服务器，AI 模型能够方便地对文件和目录进行各类操作。

✨ 主要特性

文件操作：支持对文件和目录进行读取、写入、更新以及删除操作。
目录管理：可创建、列出、移动和复制目录。
状态管理：能维护会话级状态，例如默认路径。
日志记录与错误处理：集成了日志记录和错误处理机制。
速率限制：具备防止滥用的保护措施。

📦 安装指南

项目使用 TypeScript 实现，提供强类型支持。
使用 npm 进行依赖管理：

npm install

编译源代码：

tsc --build

运行服务器：

node dist/server.js

💻 使用示例

基础用法

//.ReadFile.ts
export async function read_file(request: ReadFileRequest): Promise<ReadFileResponse> {
    const { path } = request;
    try {
        const content = await fs.promises.readFile(path, 'utf8');
        return { success: true, content };
    } catch (error) {
        return { success: false, error: error.message };
    }
}

📚 详细文档

文件系统结构图

+-filesystem-mcp-server/
| +-dist/                 # 编译后的 JavaScript 输出 (运行 npm run build 后生成)
| +-logs/                # 日志文件（运行时创建）
| +-node_modules/        # 项目依赖项
| +-src/                 # TypeScript 源代码
|   +-config/             # 配置加载（index.ts）
|   +-mcp-server/         # 核心 MCP 服务器逻辑
|   | +-server.ts          # 服务器初始化和工具注册
|   | +-state.ts           # 会话状态管理（例如默认路径）
|   | +-tools/             # 各个工具的实现（每个工具一个子文件夹）
|   | | +-readFile/
|   | | | +-index.ts
|   | | | +-readFileLogic.ts
|   | | | +-registration.ts
|   | | \-...              # 其他工具（writeFile, updateFile 等）
|   +-types-global/       # 共享 TypeScript 类型和接口
|   | +-errors.ts          # 自定义错误类和代码
|   | +-mcp.ts             # MCP 相关类型
|   | \-tool.ts            # 工具定义类型
|   +-utils/              # 可重用的实用工具模块
|   | +-errorHandler.ts
|   | +-idGenerator.ts
|   | +-index.ts
|   | +-logger.ts
|   | +-rateLimiter.ts
|   | +-requestContext.ts
|   | +-sanitization.ts
|   \-index.ts            # 应用程序入口点
| +-clinerules           # Cheatsheet 对于 LLM 代码助手
| +-gitignore
| +-LICENSE
| +-package.json
| +-package-lock.json
| +-README.md             # 本文件
| \-tsconfig.json         # TypeScript 编译器选项

工具列表

基本文件操作工具

| 工具名称 | 输入 | 描述 | | ---- | ---- | ---- | | read_file | {path: string} | 从指定路径读取文件内容 | | write_file | {path: string, content: string} | 将内容写入指定路径的文件，若文件不存在则创建 | | update_file | {path: string, content: string} | 更新指定路径的文件内容，保留原有内容 | | delete_file | {path: string} | 删除指定路径的文件 |

目录管理工具

| 工具名称 | 输入 | 描述 | | ---- | ---- | ---- | | create_dir | {path: string} | 创建指定路径的目录，若父目录不存在则递归创建 | | list_dirs | | 列出当前工作目录下的所有子目录 | | move_dir | {from: string, to: string} | 移动指定源目录到目标路径 | | copy_dir | {from: string, to: string} | 复制指定源目录到目标路径，保留文件结构 |

项目结构

核心组件

Server.ts：服务器主程序，负责处理连接和消息路由。
State.ts：维护会话级状态，包括默认路径等信息。
Tools/：各个文件操作工具的具体实现。

🔧 技术细节

本项目使用 TypeScript 实现，为代码提供了强类型支持，有助于提高代码的可维护性和稳定性。在项目开发过程中，使用 npm 进行依赖管理，通过 tsc --build 命令编译源代码，最终使用 node dist/server.js 来运行服务器。

📄 许可证

项目遵循 MIT 许可证，具体条款参见 LICENSE 文件。

👥 构建团队

作者：[你的名字]
贡献者：[你的名字]
维护者：[你的名字]

如需进一步了解 Model Context Protocol，请访问官方文档。

filesystem-mcp-server