Local File Operating

本地文件系统MCP服务器（简化）-黑曜石集成

   

专为以下目的设计的轻量级高效本地文件系统MCP服务器 黑曜石拱顶 以及markdown文件管理。通过动态路径配置和丰富的文件操作，该服务器使AI助手能够安全地与您的黑曜石笔记和知识库进行交互。

📖 项目背景

该项目是基于官方 MCP Python SDK 由Anthropic开发。在保持核心功能和安全特性的同时，此版本侧重于：

• 代码简化：与原始版本相比，代码减少60%
• 动态配置：增强的运行时路径管理
• 部分编辑：丰富的文件操作功能
• 开发者体验：更清洁的架构和更好的文档

原始项目在麻省理工学院获得许可，而这个项目遵循相同的许可。

🗂️ 黑曜石融合

非常适合黑曜石拱顶

此服务器专门针对管理进行了优化 黑曜石拱顶 以及markdown文件。它为AI助手提供了强大的工具，可以与您的知识库进行交互：

• 笔记管理：创建、阅读、更新和搜索笔记
• 内容组织：管理文件夹和文件结构
• 智能编辑：注释中的精确文本操作
• 链路管理：处理内部链接和引用

常见黑曜石用例

• 人工智能笔记：让AI助手帮助您组织和扩展笔记
• 自动内容生成：生成摘要、大纲或新内容
• 知识库维护：清理和重组你的保险库
• 助研：搜索并分析您现有的笔记
• 模板管理：创建和应用注释模板

✨ 核心功能

🚀 简化设计

• 清洁代码与原始版本相比，代码减少了60%，易于理解和维护
• 动态配置：支持环境变量和运行时路径配置
• 随时可用：无需复杂的设置，快速启动

🔧 功能丰富

• 基本操作：文件读取、写入、目录列表、内容搜索
• 部分编辑：附加、插入、替换、删除、应用补丁
• 动态管理：运行时工作目录切换
• 资源访问：通过MCP协议访问文件和目录

🛡️ 安全特性

• 根目录限制：所有操作仅限于预设根目录
• 文件类型白名单：只能操作允许的文件类型
• 大小限制：防止读取超大文件（最大10MB）

🚀 快速开始

需求

• Python 3.10+
• MCP-SDK

再进行

pip install mcp[cli]

启动服务器

# Use default configuration
python local_filesystem_mcp_simple.py

# Or set root directory via environment variable
set MCP_FILESYSTEM_ROOT=D:/your/workspace
python local_filesystem_mcp_simple.py

验证操作

启动服务器后，您将看到：

Starting Local File System MCP Server (Dynamic Path Version)...
Root Directory: D:/your/workspace
Support environment variable MCP_FILESYSTEM_ROOT for default directory
Press Ctrl+C to stop server

📋 可用工具

基本文件操作

部分文件编辑

动态路径管理

🔧 配置

环境变量

# Set default working directory
export MCP_FILESYSTEM_ROOT=/path/to/your/workspace

# Windows
set MCP_FILESYSTEM_ROOT=D:\your\workspace

运行时配置

通过工具动态设置工作目录：

# Set new working directory
await set_working_directory({"path": "/new/workspace/path"})

# Get current directory info
info = await get_working_directory()
print(info)  # {"current_directory": "/new/workspace/path", "is_dynamic": "true"}

# Reset to default directory
await reset_working_directory()

🎯 LLM使用指南

人工智能助理的基本说明

在使用任何工具之前，请务必先设置工作目录：

await set_working_directory({"path": "D:/Knowledge"})

重要提示：

1. 严格的JSON格式：调用MCP工具时，始终严格遵循JSON数据格式，确保所有括号正确对齐
2. 长文本策略：对于长文本输出或多步骤任务，请先制定计划并逐步执行。使用 write_file 要创建文件，请写开头，然后使用 append_to_file 在随后的对话中
3. 先搜索：当我提到一个笔记时，一定要先用搜索它的标题 search_files （我很少使用确切的全名）
4. 修改后打开：始终选择在修改后使用打开文件 open_after_write=True 或类似参数
5. 任务总结：完成任务后，始终总结所有修改或创建的笔记（提供链接）

了解黑曜石：

1. 文件名作为标题：在《黑曜石》中，文件名作为主标题（0级标题），因此不需要额外的标题作为注释名称

输出格式：

1. 数学模块：数学块使用双美元符号，内联数学使用单美元符号
2. YAML完整性：黑曜石YAML必须从第一行开始。修改YAML时，确保不破坏此有效性

小型会议：

1. 项目完成：项目完成后，添加以下YAML属性： done: true

📚 LLM详细指南

有关LLM的全面使用说明，请参阅 LLM使用指南 其中提供了详细的示例、最佳实践和故障排除提示。

💡 使用示例

基本文件操作

# Set working directory first
await set_working_directory({"path": "D:/Knowledge"})

# Read file
content = await read_file({"file_path": "notes/readme.md"})

# Write file and open in Obsidian (recommended)
await write_file({
    "file_path": "notes/new_note.md", 
    "content": "# New Note\nThis is content",
    "create_dirs": True,
    "open_after_write": True
})

# Open existing note in Obsidian
await open_note({
    "file_path": "notes/existing_note.md"
})

# List directory
listing = await list_directory({"directory_path": "notes"})

# Search content (always search first when note name is mentioned)
results = await search_files({
    "search_term": "TODO",
    "directory_path": "notes",
    "limit": 50
})

部分文件编辑

# Append content to end of file
await append_to_file({
    "file_path": "notes/log.md",
    "content": "\n## New Record\n- Completed feature development"
})

# Insert content at specific line
await insert_into_file({
    "file_path": "notes/todo.md",
    "line_number": 3,
    "content": "- [ ] New task"
})

# Replace text
await replace_in_file({
    "file_path": "notes/config.md",
    "search_text": "old_value",
    "replace_text": "new_value"
})

# Delete specific lines
await delete_from_file({
    "file_path": "notes/temp.md",
    "line_start": 5,
    "line_end": 10
})

动态路径管理

# Switch to new working directory
await set_working_directory({"path": "/projects/current"})

# Get current directory info
info = await get_working_directory()
print(f"Current directory: {info['current_directory']}")

# Reset to default directory
await reset_working_directory()

🛡️ 安全特性

访问限制

• 根目录限制：所有文件操作仅限于预设的根目录及其子目录
• 路径解析：自动相对路径解析，防止目录遍历攻击
• 边界检查：严格验证允许范围内的所有操作路径

文件类型控制

# Allowed file extensions
ALLOWED_EXTENSIONS = {".md", ".txt", ".json", ".yaml", ".yml", ".csv"}

大小限制

• 最大文件大小：10MB以防止内存溢出
• 搜索结果限制：默认值200，最多5000个结果

🔍 故障排除

常见问题

服务器无法启动

# Check Python version
python --version

# Check MCP installation
python -c "import mcp"

权限错误

• 确保目标目录存在并具有读/写权限
• 检查文件路径是否在根目录范围内
• 验证文件类型是否在允许的列表中

文件操作失败

• 检查文件是否被其他程序锁定
• 确认文件编码为UTF-8
• 验证文件大小不超过限制

调试方法

1. 检查服务器控制台输出
2. 验证环境变量设置
3. 检查文件路径权限
4. 使用简单文件测试基本功能

🤝 贡献

我们欢迎社区捐款！以下是您如何参与：

报告问题

• 使用GitHub Issues报告错误或建议功能
• 提供详细的错误信息和复制步骤

提交代码

1. 复刻仓库
2. 创建要素分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'Add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 创建拉取请求

开发指南

• 遵循现有代码样式
• 添加适当的单元测试
• 更新相关文件
• 确保向后兼容性

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 感谢the 模型上下文协议 团队
• 感谢所有贡献者和用户

______________________________________________________________________

备注：使用前了解文件操作的风险，并定期备份重要数据。

如有疑问，请查看 问题 或提交新问题。

______________________________________________________________________

中文文档 | 英文文档