AI导哈

文件操作服务器

为Claude Desktop及兼容LLM客户端提供生产级文件系统操作服务的MCP服务器。

  • by CrashBytes
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 CrashBytes/mcp-file-server-typescript

使用说明

文件操作MCP服务器

生产级MCP服务器，为Claude Desktop和兼容的LLM客户端提供文件系统操作。

部分 CrashBytes生产MCP教程系列。请参阅 完整教程 了解实施细节。

特性

  • 读取文件：使用可配置的编码（UTF-8、Base64）访问文件内容
  • 写入文件：使用原子写入和目录创建创建或更新文件
  • 搜索文件：基于Glob的文件搜索，具有可配置的深度和模式匹配
  • 生产就绪：全面的错误处理、验证、日志记录和测试
  • 类型安全：具有严格模式的完整TypeScript实现
  • 经过充分测试：单元和集成测试的代码覆盖率超过80%

安装

全局安装（建议用于Claude Desktop）

npm install -g @crashbytes/mcp-file-server-typescript

本地安装

npm install @crashbytes/mcp-file-server-typescript

配置

通过环境变量进行配置：

变量 描述 默认值
MCP_ALLOWED_PATHS 逗号分隔的允许目录列表 所有路径
MCP_MAX_FILE_SIZE 最大文件大小（字节） 10MB
MCP_LOG_LEVEL 日志记录级别（调试、信息、警告、错误） 信息
MCP_BLOCKED_EXTENSIONS 以逗号分隔的被阻止文件扩展名列表 .exe、.dll

用法

Claude桌面集成

添加到Claude Desktop的MCP配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "file-operations": {
      "command": "mcp-file-server",
      "env": {
        "MCP_ALLOWED_PATHS": "/Users/yourname/Documents,/Users/yourname/Projects",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

重新启动Claude Desktop以加载服务器。

程序化使用

import { FileServer } from '@crashbytes/mcp-file-server-typescript';

const server = new FileServer();
await server.start();

可用工具

read_file

使用可配置的编码读取文件内容。

{
  "name": "read_file",
  "arguments": {
    "path": "/path/to/file.txt",
    "encoding": "utf-8"  // or "base64"
  }
}

write_file

将内容写入文件。

{
  "name": "write_file",
  "arguments": {
    "path": "/path/to/file.txt",
    "content": "Hello, World!",
    "encoding": "utf-8",
    "createDirectories": true
  }
}

搜索文件

搜索与模式匹配的文件。

{
  "name": "search_files",
  "arguments": {
    "directory": "/path/to/search",
    "pattern": "*.ts",
    "recursive": true,
    "maxResults": 100
  }
}

安全

  • 路径验证：防止目录遍历攻击
  • 允许的路径：可配置的白名单限制文件系统访问
  • 文件大小限制：防止资源耗尽
  • 扩展阻塞：默认情况下阻止危险的文件类型
  • 输入验证：Zod模式验证所有工具输入

发展

先决条件

  • Node.js 18或更高版本
  • npm或纱线

设置

git clone https://github.com/CrashBytes/mcp-file-server-typescript.git
cd mcp-file-server-typescript
npm install

构建

npm run build

测试

npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage report

开发模式

npm run dev

棉绒

npm run lint            # Check for issues
npm run lint:fix        # Fix auto-fixable issues

项目结构

mcp-file-server-typescript/
├── src/
│   ├── server.ts           # Main server implementation
│   ├── config.ts           # Configuration management
│   ├── validators.ts       # Zod validation schemas
│   ├── tools/              # Tool implementations
│   │   ├── readFile.ts
│   │   ├── writeFile.ts
│   │   └── searchFiles.ts
│   └── utils/              # Utilities
│       ├── logger.ts       # Structured logging
│       └── errors.ts       # Custom error types
├── tests/
│   ├── unit/               # Unit tests
│   └── integration/        # Integration tests
├── package.json
├── tsconfig.json
└── README.md

测试

该项目包括全面的测试覆盖范围：

  • 单元测试：使用模拟依赖关系测试单个工具实现
  • 集成测试：测试完整的MCP协议实施
  • 覆盖目标：分支、函数、行和语句之间的最小值为80%

运行覆盖率测试：

npm run test:coverage

部署

码头工人

docker build -t mcp-file-server .
docker run -i mcp-file-server

NPM包

发布到npm以便于安装：

npm install -g @crashbytes/mcp-file-server-typescript

文档

完整的API文档可通过TypeDoc获得：

npm run docs

文件将在 docs/ 目录。

教程

此存储库附带 构建生产MCP服务器 CrashBytes教程。本教程包括：

  • MCP协议架构和设计模式
  • 具有严格类型安全的TypeScript实现
  • 运行时类型检查的Zod验证
  • 全面的错误处理策略
  • 测试方法（单元和集成）
  • 生产安全考虑
  • 部署模式和CI/CD
  • 性能优化技术
  • 监控和可观察性

阅读完整教程： 教程.crashbytes.com/building-product-nmcp-servers-typescript-claude-2025

贡献

欢迎投稿！请在提交PR之前阅读我们的投稿指南。

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

相关项目

支持

建于❤️ 通过 CrashBytes |生产人工智能工程教程

相关 MCP