文件操作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-serverNPM包
发布到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之前阅读我们的投稿指南。
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
相关项目
支持
______________________________________________________________________
建于❤️ 通过 CrashBytes |生产人工智能工程教程