MCP Local File Search

MCP本地文件搜索

一种模型上下文协议（MCP）服务器，用于索引和搜索本地文件。

韩语版本 README_KR.md请参考。

特性

• 支持多种文件格式（txt、md、doc、docx、pdf、xls、xlsx、pptx等）
• 使用BM25算法进行高级搜索
• 文件更改检测和增量索引
• 通过MCP协议集成AI工具
• 提供命令行界面

安装

# Global installation (recommended)
npm install -g @mtorange/mcp-local-file-search

安装后，您可以使用 local-file 命令。

用法

命令

1.运行MCP模式

# After global installation
local-file mcp --dir=/path/to/file

# Or use directly with npx
npx @mtorange/mcp-local-file-search mcp --dir=/path/to/file

2.文本搜索

# After global installation
local-file search "text to search" --dir=/path/to/file

# Or use directly with npx
npx @mtorange/mcp-local-file-search search "text to search" --dir=/path/to/file

3.文件索引

# After global installation
local-file index --dir=/path/to/file

# Or use directly with npx
npx @mtorange/mcp-local-file-search index --dir=/path/to/file

4.强制重新索引

# After global installation
local-file index --dir=/path/to/file --force

# Or use directly with npx
npx @mtorange/mcp-local-file-search index --dir=/path/to/file --force

选项

• --dir=：指定要索引的目录
• --debug-log=：将调试日志输出到文件
• --force：强制重新索引，而不管文件是否更改
• --help：显示帮助

MCP工具

以下工具在MCP模式下可用：

1. 搜索本地：在本地文件中搜索文本
2. 在文件中搜索：在特定文件中搜索文本
3. 获取索引统计信息：获取索引统计信息
4. 查找类似文件：查找类似文件
5. 重新索引：重新索引文件

支持的文件格式

• 文本： .txt, .md, .json, .js, .ts, .html, .css, .xml, .csv
• 文件： .doc, .docx, .pdf
• 电子表格： .xls, .xlsx
• 演示文稿： .pptx

例子

1.基本用法

# Index current directory
local-file index

# Search for specific text
local-file search "JavaScript"

# Run MCP server
local-file mcp --debug-log=debug.log

2.使用特定目录

# Index documents directory
local-file index --dir=~/Documents

# Search in documents
local-file search "project" --dir=~/Documents

# Run MCP server
local-file mcp --dir=~/Documents

3.调试模式

# Run MCP server with debug logging
local-file mcp --dir=~/Documents --debug-log=debug.log

4.直接使用npx

# Use without global installation
npx @mtorange/mcp-local-file-search mcp --dir=/path/to/file
npx @mtorange/mcp-local-file-search search "search term" --dir=/path/to/file

索引文件

索引另存为 .local-file-index.json 在目标目录中。此文件包含：

• 文件内容和元数据
• 词频统计
• BM25计算的全球统计数据

索引文件是在运行时创建的 index 命令或运行时 mcp 命令。 因此，第一轮 mcp 命令可能需要一些时间。

性能优化

• 通过文件更改检测进行增量索引
• 排除隐藏文件和 node_modules 目录
• 自动过滤不支持的文件格式

语言支持

应用程序会自动检测系统语言并相应地显示消息。

支持的语言

• 英语（en） -默认语言
• 韩语（ko） -韩语支持
• 日语（ja） -日语支持
• 中文（zh） -中文语言支持

语言检测优先级

1. MCP_LANG 环境变量（最高优先级）
2. 语言 环境变量
3. LC_ALL 环境变量
4. LC_消息 环境变量
5. 语言 环境变量
6. Node.js国际API （系统区域设置）
7. 英语 （默认回退）

设置语言

您可以使用环境变量设置语言：

# Use Korean (global installation)
MCP_LANG=ko local-file search "검색어"

# Use Korean (with npx)
MCP_LANG=ko npx @mtorange/mcp-local-file-search search "검색어"

# Use English (global installation)
MCP_LANG=en local-file search "search term"

# Use English (with npx)
MCP_LANG=en npx @mtorange/mcp-local-file-search search "search term"

# Use Japanese (global installation)
MCP_LANG=ja local-file search "検索語"

# Use Japanese (with npx)
MCP_LANG=ja npx @mtorange/mcp-local-file-search search "検索語"

# Set system-wide language
export LANG=ko_KR.UTF-8
local-file search "검색어"
# Or with npx
export LANG=ko_KR.UTF-8
npx @mtorange/mcp-local-file-search search "검색어"

语言检测信息

检查当前语言检测：

# With global installation
local-file lang-info

# With npx
npx @mtorange/mcp-local-file-search lang-info

此命令显示：

• 当前检测到的区域设置
• 环境变量
• 以当前语言测试消息

Claude桌面集成

要与Claude Desktop集成，请将以下内容添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "local-file": {
      "command": "npx",
      "args": ["-y", "@mtorange/mcp-local-file-search@latest", "mcp", "--dir=/path/to/your/files"]
    }
  }
}

故障排除

找不到索引文件错误

# With global installation
local-file index --dir=/path/to/file

# With npx
npx @mtorange/mcp-local-file-search index --dir=/path/to/file

没有搜索结果

• 检查文件是否正确索引
• 验证支持的文件格式
• 尝试不同的搜索词

文件解析错误

• 检查文件是否损坏
• 验证是否支持文件格式
• 尝试使用重新索引 --force 选项：

# With global installation
local-file index --dir=/path/to/file --force

# With npx
npx @mtorange/mcp-local-file-search index --dir=/path/to/file --force

发展

从源头构建

git clone https://github.com/mtorange/mcp-local-file-search.git
cd mcp-local-file-search
npm install
npm start

测试

npm test

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

许可证

MIT许可证

作者

宋

链接

• 问题