搜索工坊-MCP服务器

<img alt="ReTail 网站截图" src="./header.png"> <h1 align="center">searchcraft-mcp-server</h1> <p align="center"> 由<a href="https://searchcraft.io">Searchcraft</a>提供支持的MCP服务器——面向开发者的垂直搜索引擎。 </p> <p align="center"> <a href="https://www.typescriptlang.org/"> <img src="https://img.shields.io/badge/TypeScript-5.8-blue.svg?logo=typescript&style=flat" alt="TypeScript"> </a> <a href="https://nodejs.org/en/"> <img src="https://img.shields.io/badge/Node.js-22+-339933.svg?logo=node.js&style=flat" alt="Node.js"> </a> <a href="https://expressjs.com/"> <img src="https://img.shields.io/badge/Express-5.1-330033.svg?logo=express&style=flat" alt="Node.js"> </a> </p>

Searchcraft MCP服务器提供了一套工具，用于管理您的Searchcraft集群中的文档、索引、联邦、访问密钥和分析。它使MCP客户端（如Claude Desktop）能够通过简单的英语提示执行诸如设置搜索索引、访问密钥、导入文档、查看分析数据、搜索索引等管理操作。

使用Searchcraft MCP服务器在2分钟内构建应用程序（视频链接）

<div align="center"> <a href="https://youtu.be/Vs_98sUrFqA?si=m9aH-tvUAAFwQQVy" title="观看视频"> <img src="https://img.youtube.com/vi/Vs_98sUrFqA/hqdefault.jpg" alt="使用Searchcraft MCP服务器在2分钟内构建应用程序"> </a> </div>

示例提示

这里是一个示例提示，可以在Claude连接到Searchcraft MCP服务器后使用。

我想使用create_vite_app工具创建一个产品搜索应用程序。

请使用这个JSON数据集 https://dummyjson.com/products
首先使用Searchcraft的create_index_from_json工具创建索引并添加文档。

然后使用create_key工具为vite应用创建API读取密钥。

应用详情：
- 应用名称："my-ecommerce-app"
- 终端：http://localhost:8000
- 索引名称：my-ecommerce-app

可用工具

Searchcraft MCP服务器目前提供了三类工具：导入工具、引擎API工具和应用生成工具：

引擎API工具

这些工具提供了对您的Searchcraft集群核心功能的直接访问，用于管理索引、文档、联邦、认证和搜索操作。

索引管理

工具名称	描述
create_index	创建具有指定模式的新索引。如果索引已存在，则会清空该索引。
delete_index	永久删除索引及其所有文档。
get_all_index_stats	获取所有索引的文档数量和统计信息。
get_index_schema	获取特定索引的模式定义。
get_index_stats	获取特定索引的统计信息和元数据（例如文档数量）。
list_all_indexes	获取Searchcraft实例中所有索引的列表。
patch_index	对索引模式进行部分配置更改（例如搜索字段、权重乘数等）。
update_index	替换现有索引的所有内容为新的模式定义。

文档管理

工具名称	描述
add_documents	向索引添加一个或多个文档。文档应作为JSON对象数组提供。
delete_all_documents	删除索引中的所有文档。删除所有文档后，索引将继续存在。
delete_document_by_id	根据其内部Searchcraft ID（_id）从索引中删除单个文档。
delete_documents_by_field	根据字段匹配项从索引中删除一个或几个文档（例如，{id: 'xyz'} 或 {title: 'foo'}）。
delete_documents_by_query	根据查询匹配项从索引中删除一个或几个文档。
get_document_by_id	根据其内部Searchcraft ID（_id）从索引中获取单个文档。

联邦管理

工具名称	描述
create_federation	使用指定的配置创建或更新联邦。
delete_federation	永久删除联邦。
get_federation_details	获取特定联邦的详细信息。
get_federation_stats	获取联邦中每个索引的文档数量以及总文档数量。
get_organization_federations	获取特定组织的所有联邦列表。
list_all_federations	获取Searchcraft实例中所有联邦的列表。
update_federation	将当前联邦实体替换为更新后的实体。

认证与密钥管理

工具名称	描述
create_key	创建具有指定权限和访问控制的新认证密钥。
delete_all_keys	删除Searchcraft集群上的所有认证密钥。谨慎使用！
delete_key	永久删除特定认证密钥。
get_application_keys	获取与特定应用关联的所有认证密钥列表。
get_federation_keys	获取与特定联邦关联的所有认证密钥列表。
get_key_details	获取特定认证密钥的详细信息。
get_organization_keys	获取与特定组织关联的所有认证密钥列表。
list_all_keys	获取Searchcraft集群上所有认证密钥的列表。
update_key	更新现有认证密钥的新配置。

停用词管理

工具名称	描述
add_stopwords	向索引添加自定义停用词。这些停用词将添加到默认的语言特定字典之上。
delete_all_stopwords	删除索引中的所有自定义停用词。这仅影响自定义停用词，不影响默认语言字典。
delete_stopwords	删除索引中的特定自定义停用词。这仅影响自定义停用词，不影响默认语言字典。
get_index_stopwords	获取索引中的所有停用词，包括默认语言字典和自定义停用词。

同义词管理

工具名称	描述
add_synonyms	向索引添加同义词。同义词仅适用于模糊查询，不适用于精确匹配查询。
delete_all_synonyms	删除索引中的所有同义词。
delete_synonyms	根据它们的键删除索引中的特定同义词。
get_index_synonyms	获取索引中定义的所有同义词。

搜索与分析

工具名称	描述
get_measure_conversion	获取测量转换数据，可选过滤和聚合参数。*本地运行时需要Clickhouse
get_measure_summary	获取测量摘要数据，可选过滤和聚合参数。*本地运行时需要Clickhouse
get_search_results	使用Searchcraft API执行搜索查询，支持模糊/精确匹配、分面和日期范围。
get_prelim_search_data	获取搜索索引的架构字段和分面信息，以了解可用于构造查询的可用字段。
get_searchcraft_status	获取Searchcraft搜索服务的当前状态。

导入工具

这些工具提供了从JSON数据导入的工作流程，并自动生成Searchcraft架构。非常适合快速从现有数据源设置新索引。

工具名称	描述
analyze_json_from_file	从本地文件读取JSON数据并分析其结构，以理解字段类型和模式，用于生成Searchcraft索引架构。
analyze_json_from_url	从URL获取JSON数据并分析其结构，以理解字段类型和模式，用于生成Searchcraft索引架构。
generate_searchcraft_schema	根据分析的JSON结构生成完整的Searchcraft索引架构，具有可定制选项，如搜索字段、权重和其他索引设置。
create_index_from_json	完整工作流，从JSON数据创建Searchcraft索引。从URL或文件获取JSON，分析结构，生成架构，创建索引，并在一个步骤中添加所有文档。

导入工具工作流

导入工具设计为协同工作的简化工作流：

1. 分析 → 使用analyze_json_from_file或analyze_json_from_url检查您的JSON数据结构
2. 生成 → 使用generate_searchcraft_schema根据分析结果创建自定义的Searchcraft架构
3. 创建 → 使用引擎API的create_index工具根据生成的架构创建索引
4. 导入 → 使用add_documents填充您的新索引的数据

或者使用一站式方法：

• 一步完成 → 使用create_index_from_json命令分析、生成架构、创建索引并导入所有文档

应用生成工具

这些工具从您的JSON数据创建完整的、可立即运行的搜索应用程序，非常适合原型设计和演示。

工具名称	描述
create_vite_app	根据JSON数据创建完整的Vite + React搜索应用程序。自动分析您的数据结构，生成优化的搜索模板，并创建一个完全功能的Web应用程序，集成Searchcraft。

应用生成工作流

应用生成工具提供了一个端到端解决方案，用于创建搜索应用程序：

1. 数据分析 → 自动分析您的JSON结构以理解字段类型和内容
2. 模板生成 → 根据您的数据字段创建优化的搜索结果模板
3. 应用创建 → 克隆并配置完整的Vite + React应用程序
4. 环境设置 → 配置Searchcraft连接设置
5. 准备运行 → 提供一个完全功能的搜索应用程序，您可以立即启动和自定义

工具详细使用

使用create_index_from_json

create_index_from_json工具提供了一个完整的流程，在一个命令中从JSON数据创建Searchcraft索引。这对于快速从现有数据集设置搜索索引非常有用。注意，如果您知道要导入的数据的语言，应该使用language参数指定（使用ISO 639-1两字母代码表示语言）

参数

参数	类型	必填	描述
source	"url" 或 "file"	✅	是否从URL获取数据或从本地文件读取
path	string	✅	JSON数据的URL或文件路径
index_name	string	✅	新Searchcraft索引的名称
sample_size	number	❌	用于生成架构的项目数量（默认：1_0）
search_fields	string[]	❌	覆盖自动检测的搜索字段
weight_multipliers	object	❌	自定义搜索相关性字段权重（0.0-10.0）
language	string	❌	索引的语言代码（例如，“en”，“es”）
auto_commit_delay	number	❌	自动提交延迟（秒）
exclude_stop_words	boolean	❌	是否排除搜索中的停用词
time_decay_field	string	❌	时间相关性衰减的字段名

示例用法

从URL：

{
  "source": "url",
  "path": "https://api.example.com/products.json",
  "index_name": "products",
  "sample_size": 50,
  "search_fields": ["title", "description", "category"],
  "weight_multipliers": {
    "title": 2.0,
    "description": 1.0,
    "category": 1.5
  }
}

从本地文件：

{
  "source": "file",
  "path": "/path/to/data.json",
  "index_name": "my_data",
  "language": "en"
}

它做了什么

1. 获取/读取数据 → 从URL下载或从本地文件读取
2. 分析结构 → 检查JSON以理解字段类型和模式
3. 生成架构 → 创建优化的Searchcraft索引架构
4. 创建索引 → 在您的Searchcraft集群中设置索引
5. 导入文档 → 将所有JSON数据作为可搜索文档添加
6. 返回摘要 → 提供关于创建内容的详细信息

预期的JSON格式

该工具可以处理各种JSON结构：

• 对象数组：[{...}, {...}, ...]
• 带有数组属性的对象：{"data": [{...}, {...}], "meta": {...}}
• 单个对象：{...}（将被视为单个文档）

该工具会自动找到最适合使用的对象数组。

使用create_vite_app

create_vite_app工具从您的JSON数据创建一个完整的、可立即运行的搜索应用程序。它非常适合快速原型设计搜索界面或创建演示应用程序。

参数

参数	类型	必填	描述
data_source	"url" 或 "file"	✅	是否从URL获取数据或从本地文件读取
data_path	string	✅	JSON数据的URL或文件路径
app_name	string	✅	生成的应用程序名称（用于目录名称）
VITE_ENDPOINT_URL	string	✅	您的Searchcraft集群终端URL
VITE_INDEX_NAME	string	✅	要连接的Searchcraft索引名称
VITE_READ_KEY	string	✅	应用程序的Searchcraft读取密钥
sample_size	number	❌	用于生成模板的项目数量（默认：50）
search_fields	string[]	❌	覆盖自动检测的搜索字段
weight_multipliers	object	❌	自定义搜索相关性字段权重（0.0-10.0）

示例用法

如果您之前在文档中看到过prompt，您可以轻松地使用自然语言来使用create_vite_app工具。然而，如果您想要更精细的控制，您可以使用JSON参数来使用该工具。

创建产品搜索应用：

{
  "data_source": "url",
  "data_path": "https://api.example.com/products.json",
  "app_name": "product-search",
  "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",
  "VITE_INDEX_NAME": "products",
  "VITE_READ_KEY": "your_read_key_here",
  "sample_size": 100,
  "search_fields": ["title", "description", "brand"],
  "weight_multipliers": {
    "title": 2.5,
    "description": 1.0,
    "brand": 1.8
  }
}

从本地数据创建博客搜索应用：

{
  "data_source": "file",
  "data_path": "/path/to/blog-posts.json",
  "app_name": "blog-search",
  "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",
  "VITE_INDEX_NAME": "blog_posts",
  "VITE_READ_KEY": "your_read_key_here"
}

它做了什么

1. 分析数据结构 → 检查您的JSON以理解字段类型和内容模式
2. 生成搜索模板 → 根据您的数据创建优化的结果显示模板
3. 克隆Vite模板 → 下载官方的Searchcraft Vite + React模板
4. 安装依赖项 → 设置所有必需的npm包
5. 配置环境 → 创建包含您的Searchcraft设置的.env文件
6. 自定义模板 → 生成动态搜索结果组件
7. 更新应用代码 → 修改主应用以适应您的特定品牌和配置

生成的应用特性

创建的应用程序包括：

• React + Vite → 现代、快速的开发设置
• Searchcraft SDK集成 → 开箱即用的完整搜索功能
• 响应式设计 → 在桌面和移动设备上都能正常工作
• 自动生成模板 → 根据您的数据结构智能显示结果
• 环境配置 → 不同环境的简单设置
• 开发服务器 → 热重载以快速定制

模板生成逻辑

该工具智能地分析您的数据以创建最佳的搜索结果模板：

• 标题字段检测 → 找出最适合用作主要标题的字段
• 描述字段检测 → 识别描述性文本字段
• 图像字段检测 → 查找用于视觉结果的图像URL
• 日期字段检测 → 查找时间戳字段以进行时间排序
• 其他字段 → 包括其他相关的文本字段以获得全面的结果

创建后的下一步

一旦应用创建完毕，您可以：

1. 启动Vite服务器：

   cd apps/your-app-name
   yarn dev
   

2. 自定义样式 → 修改CSS和组件以匹配您的品牌

3. 添加功能 → 扩展过滤器、分面或高级搜索选项

4. 部署 → 构建并部署到您首选的托管平台

先决条件

• 现有的Searchcraft索引 → 在VITE_INDEX_NAME中指定的索引应已经存在
• 有效的读取密钥 → VITE_READ_KEY必须具有对该索引的读取权限
• 可用的Git → 该工具使用git克隆模板仓库
• Node.js & Yarn → 安装依赖项所需

完整工作流程：从JSON到搜索应用

这是如何使用这两个工具一起从原始JSON数据到一个完全功能的搜索应用程序：

方案1：两