AI导哈

文件系统MCP服务器

一个轻量级的MCP服务器，通过Python和mcp库安全地暴露预配置目录中的文件内容和元数据，并集成了Anthropic的Claude AI进行自然语言交互。

  • by offeline
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 iBz-04/Filesys

使用说明

文件系统MCP

概述

filesys是一个轻量级的mcp服务器，它使用Python和mcp库构建，可以安全地从预配置的目录中公开文件内容和元数据。该项目利用FastMCP提供一组端点，允许：

  • 列出指定目录中的所有文件。
  • 读取指定文件的内容和元数据。

新 它现在包括与Anthropic的Claude AI的集成，允许用户通过自然语言对话与文件系统进行交互，使用Claude Tools安全地访问定义的MCP资源。

该项目通过验证路径和防止目录遍历攻击来确保安全的文件访问。

预览

  • 与Claude交互以列出和读取文件 safe_folder:

运作原理

核心功能分为几个部分：

  • 资源：
    在……里面 src/resources.py，两个函数负责文件操作：

    • list_files()：扫描基本目录（在中配置 config/config.json)返回可见文件的列表。
    • read_file(filename)：读取指定文件的内容，并将其与元数据（大小和上次修改的时间戳）一起返回，同时确保文件访问是安全的。

  • 服务器：
    在……里面 src/server.py，初始化FastMCP服务器并注册两个资源端点：

    • files://list：调用 list_files().
    • files://read/{filename}：调用 read_file(filename).

服务器通过启动 run.py，它利用mcp库来处理资源请求。

  • 克劳德工具客户端： 在……里面 claude_tool_client.py，功能(list_files_in_safe_folder, read_file_from_safe_folder)被定义为与正在运行的Filesys MCP服务器交互。这些函数充当桥梁，将简单的函数调用转换为MCP请求并解析响应。它们的设计便于Claude Tools使用。

  • 克劳德互动脚本： 这 interact_with_claude.py 该脚本设置了一个Anthropic客户端，根据中的函数定义了Claude Tools claude_tool_client.py，并运行命令行对话循环。用户可以向Claude提问，如“有哪些文件可用？”或“读取test.txt”，Claude将使用提供的工具（安全地调用MCP服务器）来满足请求。

  • 测试：
    单元测试 tests/test_resources.py 确保文件列表和读取功能按预期工作。

安装

  1. 克隆存储库：
    git clone https://github.com/iBz-04/Filesys.git
  2. 导航到项目目录：
    cd Filesys
  3. 创建虚拟环境（可选但推荐）：
    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  4. 安装依赖关系： 请确保您已安装Python。然后安装所需的库：
    pip install -r requirements.txt
  5. 配置API密钥：
    • 创建一个名为的文件 .env.local 在项目的根目录中。
    • 将您的Anthropic API密钥添加到此文件：
      ANTHROPIC_API_KEY=your_api_key_here
    • 注： 这 .gitignore 该文件被配置为防止此文件被提交到Git。

配置

文件服务器从以下位置读取其配置 config/config.json。默认情况下，服务器在下面指定的目录上运行：

{
  "directory": "./safe_folder"
}

如果需要，您可以修改此文件以指向其他目录。

  • 无烟煤API密钥： Claude交互脚本读取 ANTHROPIC_API_KEY 从 .env.local 文件（请参阅安装步骤5）。

用法

  1. 启动MCP服务器： 首先，确保Filesys MCP服务器在终端中运行：

    python run.py

    此命令初始化FastMCP服务器，并使 files://list 和 files://read/{filename} 端点可用。

  2. 与克劳德互动： 在一个 独立终端 （当步骤1中的服务器仍在运行时），运行Claude交互脚本：

    python interact_with_claude.py

    然后，您可以要求Claude与配置中的文件进行交互 safe_folder示例：

    • “你能看到什么文件？”
    • “列出可用文件。”
    • “你能帮我读test.txt吗？”
    • “告诉我名为test.txt的文件的内容”

  3. 直接MCP请求（可选）： 您还可以使用任何兼容MCP的客户端直接与服务器交互：

    • 列出文件： 请求 files://list.
    • 读取文件： 请求 files://read/{filename} （替换 {filename} 使用实际文件名）。

测试

  • MCP客户端功能： 您可以通过运行以下命令来测试与MCP服务器通信的功能：
    python claude_tool_client.py
    这将执行 test_tool_functions 在脚本末尾定义。确保MCP服务器(python run.py)正在提前运行。
  • 核心资源（如果存在测试）： 如果在中创建了单元测试 tests/ 目录（例如。， tests/test_resources.py)，您可以使用以下命令运行它们：
    python -m unittest discover tests

贡献

欢迎投稿！贡献：

  1. 分叉存储库。
  2. 为您的功能或错误修复创建一个新分支。
  3. 用详细的消息提交您的更改。
  4. 推送您的分支并打开拉取请求。

附加说明

  • 自定义配置(config/config.json, .env.local)根据需要。
  • 重要提示： 克劳德互动脚本(interact_with_claude.py)需要Filesys MCP服务器(run.py)在单独的进程中运行。
  • 此项目实现了基本的安全措施，以限制对配置目录的文件访问并防止目录遍历。
  • 在添加新功能或进行更改时更新此文档。

相关 MCP