Name: 本地文件搜索服务
Author: mtorange

使用说明

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=<directory>：指定要索引的目录
--debug-log=<file>：将调试日志输出到文件
--force：强制重新索引，而不管文件是否更改
--help：显示帮助

MCP工具

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

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

支持的文件格式

文本： .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） -中文语言支持

语言检测优先级

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

设置语言

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

# 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

贡献

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

许可证

MIT许可证

作者

宋 mtorange@gmail.com