Filesys

🚀 文件系統 MCP 項目文檔

本項目 filesys 是一個基於 Python 和 mcp 庫構建的輕量級 MCP 服務器，能夠安全地從預配置目錄中暴露文件內容和元數據。它利用 FastMCP 實現文件列表展示和文件內容及元數據讀取功能。同時，新增集成了 Anthropic 的 Claude AI，支持用戶通過自然語言對話與文件系統交互，安全訪問定義的 MCP 資源。

✨ 主要特性

• 可列出指定目錄中的所有文件。
• 能讀取特定文件的內容和元數據。
• 集成 Anthropic 的 Claude AI，支持通過自然語言對話與文件系統交互，使用 Claude Tools 安全訪問 MCP 資源。
• 確保安全的文件訪問，通過驗證路徑防止目錄遍歷攻擊。

📦 安裝指南

1. 克隆倉庫：

   git clone [倉庫地址]
   

2. 創建虛擬環境並安裝依賴：

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上使用 `venv\Scripts\activate`
   pip install mcp
   

3. 配置 API 密鑰：
   • 修改 config/config.json 文件，設置服務器的配置（例如端口）。
   • 創建 .env.local 文件並添加 Anthropic 的 API 密鑰。

💻 使用示例

基礎用法

1. 啟動 MCP 服務器：

   python run.py
   

2. 與 Claude 對話：

   python interact_with_claude.py
   

3. 直接發送 MCP 請求（可選）：
   • 列出文件：發送請求 files://list。
   • 讀取文件：發送請求 files://read/{filename}（將 {filename} 替換為實際文件名）。

功能預覽

• 與 Claude 對話以列出和讀取 safe_folder 中的文件：

🔧 技術細節

核心功能分為以下幾個部分：

• 資源：
  在 src/resources.py 中，兩個函數負責文件操作：

  • list_files(): 掃描指定目錄並返回所有文件的列表。
  • read_file(): 根據文件名讀取文件內容並返回其內容。

• 服務器：
  在 run.py 中，定義了一個簡單的 MCP 服務器，啟動後監聽端口並處理來自客戶端的請求。服務器會調用資源模塊中的函數來響應請求。

• Claude 工具客戶端：
  在 claude_tool_client.py 中，定義了與 MCP 服務器交互的工具函數。這些函數可以用來測試服務器的功能，併為 Claude 提供接口以發送請求。

• 測試：
  如果在 tests/ 目錄中有單元測試文件（例如 tests/test_resources.py），可以通過運行以下命令執行測試：

  python -m unittest discover tests
  

📚 詳細文檔

貢獻指南

歡迎貢獻！要參與項目，請按照以下步驟操作：

1. Fork 倉庫。
2. 創建一個新的分支用於你的功能或修復。
3. 提交更改並添加詳細的提交信息。
4. 推送分支並在 GitHub 上打開 Pull Request。

其他說明

• 根據需要自定義配置文件 (config/config.json 和 .env.local)。

⚠️ 重要提示

interact_with_claude.py 腳本要求 run.py 服務器在另一個進程中運行。

• 該項目實現了基本的安全措施，以限制對配置目錄的訪問並防止目錄遍歷攻擊。
• 如果添加新功能或進行更改，請更新此文檔。