🔍 Better Finder MCP

类似于Git的工作流程，用于智能文件搜索和与Claude MCP的集成

Better Finder通过语义搜索、混合匹配以及熟悉的Git风格工作流程来改变文件发现的方式。索引您的文档，使用自然语言进行搜索，并无缝集成到Claude Desktop。

🚀 快速开始

安装

# 克隆并安装
git clone https://github.com/GitHamza0206/better-finder-mcp.git
cd better-finder-mcp
uv venv
source .venv/bin/activate
pip install -e .

# 使用uv全局安装
uv tool install -e .

基本工作流程

# 1. 索引文件（类似git add）
better-finder add ~/Documents

# 2. 查看已添加的文件
better-finder status

# 3. 索引已添加的文件
better-finder index

# 4. 搜索文件
better-finder search "季度财务报告"

📋 命令

文件添加

• better-finder add <路径> - 添加文件或文档以供索引
• better-finder rm <路径> - 从待索引列表中移除文件
• better-finder status - 显示已添加的文件
• better-finder index - 索引已添加的文件

搜索与管理

• better-finder search <查询> - 搜索已索引的文件
• better-finder stats - 显示索引统计信息
• better-finder clear-index - 清除所有已索引的数据
• better-finder server - 启动MCP服务器以便在Claude中使用

工具

• better-finder show <文件> - 显示文件内容
• better-finder remove-file <文件> - 从索引中移除文件

🎯 主要功能

混合搜索

结合语义搜索、关键词匹配和模糊文件名搜索，提供全面的结果。

类似Git的工作流程

熟悉的添加过程让您能够精确控制哪些文件被索引。

.betterfinderignore 支持

使用忽略模式排除敏感文件：

# .betterfinderignore
secrets/
*.key
temp-*.pdf
node_modules/

支持的文件类型

• 文档：PDF, DOC, DOCX, TXT, MD, RTF, ODT
• 电子表格：XLSX, XLS, CSV, ODS
• 演示文稿：PPTX, PPT
• 数据：JSON, XML

Claude MCP 集成

启动MCP服务器，以便在Claude Desktop中直接使用Better Finder：

better-finder server

添加到您的Claude Desktop配置（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "better-f-inder": {
      "command": "better-finder",
      "args": ["server"]
    }
  }
}

🔧 配置

Better Finder使用智能默认设置：

• 默认扫描路径：~/Documents, ~/Desktop, ~/Downloads
• 忽略的目录：.git, node_modules, .venv, 缓存文件夹
• 块大小：2000字符以获得更好的上下文
• 搜索阈值：0.4以获得全面的结果

💡 示例

文档发现

# 查找关于销售的演示文稿
better-finder search "销售演示 Q4"

# 查找特定类型的文件
better-finder search "预算" --type excel

# 获取更多结果
better-finder search "会议记录" --max 20

添加工作流程

# 添加整个项目文档
better-finder add ./docs

# 移除敏感文件
better-finder rm ./docs/secrets/

# 查看将被索引的内容
better-finder status

# 索引所有已添加的内容
better-finder index

MCP 集成

一旦服务器运行，可以向Claude询问：

• "在我的文档中搜索预算报告"
• "查找关于项目时间表的演示文稿"
• "显示与客户提案相关的文件"

🏗️ 架构

• 文件处理器：从不同格式中提取内容
• FAISS 向量存储：使用句子转换器进行快速相似性搜索
• SQLite 元数据：高效地存储文件元数据和块
• 添加系统：具有JSON持久化的类似Git的文件管理
• MCP 服务器：与Claude集成的模型上下文协议

📊 性能

• 索引：每分钟约100-500个文件
• 搜索：亚秒级结果
• 内存：对于典型集合，约200-500MB
• 存储：每1000个文档约1-5MB

📝 许可证

MIT 许可证 - 详情见LICENSE文件。

---

专为希望使用熟悉的Git样控制进行智能文件发现的开发者设计。