Local Search MCP Server

](https://www.npmjs.com/package/local-search-mcp) ](https://nodejs.org/) 

本地搜索MCP服务器

一个模型上下文协议（MCP）服务器，它使AI助手能够利用向量嵌入在索引文档中执行语义搜索。该服务器可从GitHub仓库和URL中索引文档，以支持自然语言查询并提供上下文相关的搜索结果。

目录

• 特点/特性
• 安装

- 先决条件 - 设置

• 配置
• 用法
• 工具
• 文档
• 发展
• 做出贡献
• 作者
• 许可证

特点/功能

• 语义搜索使用Transformer嵌入在索引文档上执行自然语言查询
• 仓库索引克隆并为GitHub仓库创建可配置文件模式的索引
• 文件下载从URL自动获取并索引文件
• 异步处理非阻塞操作，支持作业进度跟踪
• SQLite 存储高效向量存储与优化相似度搜索
• MCP协议与Claude Desktop及其他MCP应用程序完全兼容

快速入门

开始使用的最快方式是使用 npx（无需克隆或构建）：

# Run directly with npx
npx -y local-search-mcp

# Or install globally
npm install -g local-search-mcp

MCP 配置（npx）

添加到Claude桌面版的 claude_desktop_config.json：

{
  "mcpServers": {
    "local-search": {
      "command": "npx",
      "args": ["-y", "local-search-mcp"],
      "env": {
        "MCP_DATA_FOLDER": "/optional/custom/data/path",
        "MCP_DOCS_FOLDER": "/optional/custom/docs/path"
      }
    }
  }
}

安装

先决条件

• Node.js >= 18.0.0
• npm 或者 纱线 包管理器
• Git 用于克隆仓库（仅限开发使用）

选项1：NPM包（推荐）

# Install globally
npm install -g local-search-mcp

# Or use directly with npx (no installation needed)
npx local-search-mcp

选项2：来自源（开发）

# Clone the repository
git clone https://github.com/PatrickRuddiman/local-search-mcp.git
cd local-search-mcp

# Install dependencies
npm install

# Build the project
npm run build

MCP 配置

对于NPM包安装：

{
  "mcpServers": {
    "local-search": {
      "command": "npx",
      "args": ["-y", "local-search-mcp"],
      "env": {
        "MCP_DATA_FOLDER": "/optional/custom/data/path",
        "MCP_DOCS_FOLDER": "/optional/custom/docs/path"
      }
    }
  }
}

对于源代码安装：

{
  "mcpServers": {
    "local-search": {
      "command": "node",
      "args": ["/absolute/path/to/local-search-mcp/build/index.js"],
      "env": {
        "MCP_DATA_FOLDER": "/optional/custom/data/path",
        "MCP_DOCS_FOLDER": "/optional/custom/docs/path"
      }
    }
  }
}

使用方法

配置完成后，该服务器将在Claude Desktop及其他MCP兼容应用程序中提供语义搜索功能。

工具

本地搜索MCP服务器提供了7种用于文档索引和语义搜索的工具：

🔍 搜索工具

search_documents

执行增强AI的语义搜索，包括内容分类、领域检测和智能推荐。

参数：

• query （必需）：自然语言搜索查询
• options （可选）：搜索配置对象

- limit （数字，默认值：10）：要返回的最大结果数 - minScore （数字，默认值：0.7）：最小相似度得分（0-1） - includeMetadata (布尔值，默认：true)：在结果中包含元数据 - domainFilter (数组): 按技术领域过滤（例如，\["javascript", "python"\]） - contentTypeFilter (数组)：按内容类型过滤（“代码”、“文档”、“配置”、“混合”） - languageFilter (数组)：按编程语言过滤（例如，\["typescript", "javascript"\]） - minQualityScore (数字)：最低内容质量评分（0-1） - minAuthorityScore （数字）：最小来源权威得分（0-1）

示例：

{
  "query": "async await promises javascript",
  "options": {
    "limit": 5,
    "domainFilter": ["javascript"],
    "contentTypeFilter": ["code", "docs"]
  }
}

get_file_details

检索特定文件的详细内容及其周围的上下文块。

参数：

• filePath （必填）：文件的绝对路径
• chunkIndex （可选）：要检索的特定片段及其上下文
• contextSize （数字，默认值：3）：在目标块前后包含的块的数量

📦 内容管理工具

fetch_repo

使用repomix克隆一个Git仓库（如GitHub、Azure DevOps等），将其转换为Markdown格式，并添加到可搜索索引中。返回作业ID以便跟踪进度。

参数：

• repoUrl （必填）：Git 仓库 URL
• branch （可选）：分支/标签/提交，默认为 main/master
• options （可选）：存储库处理选项

- includePatterns (数组，默认: \["**\/\*.md\", "**/*".mdx", "\*\*/*".txt"，"**/\*."json"，"**/*".rst"，"\*\*/*\[".yml", "\*\*/\*.yaml"\]): 要包含的文件模式 - excludePatterns （数组，默认：\[“/node_modules/ 翻译为中文是：“/node_modules/（文件夹/目录）”，通常用于表示在Node.js项目中存放第三方模块的目录。在中文语境下，我们可能会直接说“node_modules目录”或“node_modules文件夹”，但“/node_modules/”本身作为路径表示，在翻译时通常保持原样，因为它是一个标准的文件系统路径表示。所以，简洁的翻译就是“/node_modules/（文件夹/目录）”，但根据上下文，有时也可以简化为“node_modules（目录）”"\]: 要排除的文件模式 - outputStyle (字符串，默认值："markdown")：输出格式（固定为markdown） - removeComments (布尔值，默认：false)：从代码文件中移除注释 - showLineNumbers (布尔值，默认: true)：在输出中显示行号

示例：

{
  "repoUrl": "https://github.com/microsoft/TypeScript",
  "branch": "main",
  "options": {
    "includePatterns": ["**/*.md", "**/*.ts"],
    "excludePatterns": ["**/node_modules/**", "**/tests/**"]
  }
}

fetch_file

从URL下载单个文件并将其添加到可搜索索引中。返回作业ID以便跟踪进度。

参数：

• url （必填）：要下载的文件的URL
• filename （必填）：希望保存的文件名
• options （可选）：下载选项

- overwrite (布尔值，默认：true)：是否覆盖现有文件 - indexAfterSave （布尔值，默认：true）：下载后自动索引 - maxFileSizeMB (数字，默认：1024)：最大文件大小（以MB为单位）

remove_file

从索引中删除一个文件及其所有相关数据块和嵌入向量。

参数：

• filePath （必需）：要删除文件的绝对路径

flush_all

清空整个数据库和所有已下载的文件。 警告此操作不可逆，将删除所有索引内容、文档和缓存文件。

参数： 无

被删除的内容：

• 数据库中的所有向量嵌入和文档块
• 所有的推荐和学习数据
• 从（某处）下载的所有文件 fetched 目录
• 从（某处）克隆的所有仓库 repositories 目录
• 所有来自（该）的临时文件 temp 目录
• 所有活跃的后台作业均被取消

示例：

{
  "name": "flush_all",
  "arguments": {}
}

⚙️ 作业管理工具

get_job_status

通过作业ID获取异步作业的状态和实时准确的进度。

参数：

• jobId （必需）：从 fetch\_\* 操作返回的工作 ID

返回：

• 作业状态：“运行中”、“已完成”或“失败”
• 进度百分比（0-100）
• 持续时间和时间戳
• 如果失败，显示错误信息
• 如已完成，结果数据如下

list_active_jobs

列出所有当前处于活动状态（运行中）的任务及其状态和进度。

参数： 无

返回：

• 活跃任务列表及进度
• 作业统计（总数、已完成数、失败数、平均持续时间）
• 实时进度更新

文档

如需详细的技术文档：

• 建筑学 - 系统设计和处理流程
• API 参考文档 - 完整的工具规格和类型
• 演出 - 优化指南和基准测试
• 使用示例 - 样本集成和工作流

发展

npm install
npm run build
npm run dev  # Development with hot reload

配置

环境变量

为自定义路径设置可选环境变量：

• MCP_DATA_FOLDER - 自定义数据库和日志目录（默认为平台特定的用户数据文件夹）
• MCP_DOCS_FOLDER - 自定义文档存储目录（默认为平台特定的用户文档文件夹）

支持的文件类型

服务器处理这些文件类型：

• 文档： .md， .txt， .rst， .yaml， .yml
• 数据： .json， .csv
• 代码： .js， .ts， .py， .java， .c， .cpp， .html， .css
• 支持高达1GB的文件

致谢

• @xenova/transformers（这个名称在中文中通常保持原样，因为它是一个特定的库或项目名称，直接翻译可能失去其原意，所以这里不做具体翻译） - 用于嵌入的JavaScript机器学习模型
• sqlite-vec（注：这是一个专有名词或项目名，直接翻译可能无法准确传达其含义，但按字面意思可译为“SQLite向量”或“SQLite向量库”，具体含义需结合上下文或项目背景来确定。） - SQLite中的原生向量搜索
• better-sqlite3（可译为“增强型 SQLite3”或保持原名，根据上下文决定是否需要意译） - 快速的 SQLite3 绑定
• 模型上下文协议 - 人工智能工具集成标准
• repomix 可以翻译为“混合仓库”或“仓库混合”，具体取决于上下文和使用场景。在软件开发或包管理的语境中，它可能指的是将多个仓库（如软件包仓库）进行混合或整合 - 仓库处理工具

发布流程

这个项目通过GitHub Actions实现了自动化语义化版本控制和发布 semantic-release（语义化发布）。

提交信息格式

关注 规范提交（或“约定式提交”） 规格：

[optional scope]: 

[optional body]

[optional footer(s)]

触发发布类型的类型：

• feat: - 新功能（小版本更新）
• fix: - 修复漏洞（补丁版本升级）
• perf: - 性能提升（补丁版本升级）
• BREAKING CHANGE: - 突破性变更（主版本号递增）

其他类型（未发布）：

• docs: - 文档更改
• style: - 代码格式化
• refactor: - 代码重构
• test: - 添加测试
• chore: - 构建过程或辅助工具的更改

贡献；做出贡献

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个具有描述性名称的特性分支
3. 按照常规的提交格式进行更改
4. 提交一个指向（目标分支的）拉取请求 main 分支
5. 在请求评审之前，确保所有持续集成（CI）检查都通过

作者

帕特里克·鲁迪曼\

许可证

MIT - 参见 许可证 详情见下。