MCP Server - File Search Tool 🗂️

MCP 服务 - 文件搜索工具 🗂️

一个 MCP（Model Context Protocol）服务，可通过 MCP 协议提供强大的文件系统搜索和检查功能。使用此工具可列出目录、搜索文件名、读取文件内容（包括 PDF 和 DOCX），并在搜索正则表达式匹配的内容时显示上下文。

功能

• 列出文件路径：按广度优先或深度优先顺序列出，并支持分页和嵌套层级控制。
• 搜索文件名：基于正则表达式搜索文件名。
• 读取文件：读取文本、PDF 和 DOCX 文件，并可选择限制字符数。
• 搜索文件内容：基于正则表达式搜索内容，并可配置上下文行数。
• 允许的路径：将服务限制为仅浏览和搜索配置的目录。
• 排除路径：阻止访问敏感目录。
• 隐藏隐藏文件：可选择忽略以点号开头的文件和目录。
• 路径掩码：用令牌替换配置的路径片段，以保护隐私。

先决条件

• Python 3.10 或更高版本
• uv - 快速的 Python 包管理器

安装

1. 克隆仓库：

git clone https://github.com/RJTPP/mcp-server-file-search-tool
cd mcp-server-file-search-tool

2. 创建虚拟环境并安装依赖项：

uv sync

运行服务

启动服务（默认端口为 6277）：

uv run server.py

Claude Desktop 集成

要将此服务添加到 Claude Desktop：

mcp install server.py --name "File Search Tool"

或者手动将其添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "File Search Tool": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-sever-file-search-tool/",
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "server.py"
      ]
    }
  }
}

配置

1. 复制示例配置：

   cp config_example.json config.json

2. 编辑 config.json 以进行自定义：

{
  "DEFAULT_TIME_LIMIT": 10,
  "HIDE_HIDDEN_FILES": true,
  "HOST": "127.0.0.1",
  "PORT": 6277,
  "ALLOWED_PATHS": [
    "/path/to/allowed/directory"
  ],
  "EXCLUDE_PATHS": [
    "/path/to/excluded/directory"
  ],
  "PATH_MASKER": {
    "ENABLED": true,
    "MODE": "segment",
    "MASK_TOKEN": "MASK",
    "LOOK_FOR": [
      "path_to_mask"
    ]
  }
}

必填字段

• ALLOWED_PATHS 为必填项。除非至少配置一个允许的路径，否则服务不会启动。

配置字段说明

字段	类型	说明
DEFAULT_TIME_LIMIT	int	搜索的最长执行时间（秒）。
HIDE_HIDDEN_FILES	bool	若为 true，则忽略以 . 开头的文件和目录。
HOST	string	服务绑定的 IP 地址（例如 "127.0.0.1"）。
PORT	int	侦听端口号（例如 6277）。
ALLOWED_PATHS	list[string]	必填。 服务获准访问和搜索的目录。
EXCLUDE_PATHS	list[string]	明确禁止访问的目录，即使它们位于允许的路径中也不例外。
PATH_MASKER	object	可选的隐私保护掩码设置。
PATH_MASKER.ENABLED	bool	启用或禁用路径掩码。
PATH_MASKER.MODE	"segment" or "prefix"	掩码模式："segment" 替换匹配的路径片段；"prefix" 掩盖完整路径前缀。
PATH_MASKER.MASK_TOKEN	string	用于替换匹配路径片段的令牌（例如 "MASK"）。
PATH_MASKER.LOOK_FOR	list[string]	要在完整路径中查找并掩码的路径片段列表。

安全性

警告

此服务未实现身份验证或加密。
它仅适用于本地个人使用。 请勿将服务暴露到不可信网络，也不要在生产环境中使用，除非已添加适当的安全措施。

许可证

本项目根据 MIT License 发布。

您可以根据 MIT License 的条款自由使用、修改和分发此软件。详细条款和条件请参阅 LICENSE 文件。