Searchcraft MCP

searchcraft-mcp-server

An MCP Server powered by Searchcraft – the developer-first vertical search engine.

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

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

示例提示

这是一个示例提示，一旦Claude连接到Searchcraft MCP服务器，就可以使用它。

I'd like to create a product search application using the create_vite_app tool.

Please use this JSON dataset https://dummyjson.com/products
First use the Searchcraft create_index_from_json tool to create the index and add the documents.

Then create an API read key for the vite app using the create_key tool.

App details:
- App name: "my-ecommerce-app"
- Endpoint: http://localhost:8000
- Index name: my-ecommerce-app

可用工具

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

发动机API工具

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

索引管理

文档管理

联合管理

身份验证和密钥管理

停用词管理

同义词管理

搜索和分析

导入工具

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

导入工具工作流

导入工具旨在以简化的工作流程协同工作：

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

或者使用一体化方法：

• 一步式 → Use create_index_from_json 在一个命令中分析、生成模式、创建索引和导入所有文档

应用生成工具

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

应用程序生成工作流

应用程序生成工具为创建搜索应用程序提供了端到端的解决方案：

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

详细的工具使用方法

使用create_index_from_json

这 create_index_from_json 该工具提供了一个完整的工作流程，可以在单个命令中从JSON数据创建Searchcraft索引。这非常适合从现有数据集中快速设置搜索索引。注意，如果您知道要导入的数据的语言，则应使用 language 参数（使用 国际标准化组织639-1 语言的两个字母代码）

参数

示例用法

从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数据创建一个完整的、可运行的搜索应用程序。它非常适合快速原型化搜索界面或创建演示应用程序。

参数

示例用法

如果你看到 提示 在文档的前面，您可以轻松使用 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. 配置环境 → 创建 .env 使用您的Searchcraft设置文件
6. 自定义模板 → 生成动态搜索结果组件
7. 更新应用程序代码 → 使用您的特定品牌和配置修改主应用程序

生成的应用程序功能

创建的应用程序包括：

• React+Vite → 现代、快速的开发设置
• Searchcraft SDK集成 → 开箱即用的完整搜索功能
• 响应式设计 → 适用于台式机和移动设备
• 自动生成的模板 → 基于数据结构的智能结果显示
• 环境配置 → 针对不同环境的轻松设置
• 开发服务器 → 热装快速定制

模板生成逻辑

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

• 标题字段检测 → 查找用作主标题的最佳字段
• 描述现场检测 → 标识描述性文本字段
• 图像场检测 → 查找图像URL以获得视觉效果
• 日期字段检测 → 查找用于时间排序的时间戳字段
• 附加字段 → 包括其他相关文本字段以获得全面结果

创建后的后续步骤

创建应用程序后，您可以：

1. 启动Vite服务器:

   cd apps/your-app-name
   yarn dev

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

1. 添加功能 → 使用过滤器、方面或高级搜索选项进行扩展

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

先决条件

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

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

以下是如何将这两个工具结合使用，从原始JSON数据转换为功能齐全的搜索应用程序：

方案1：两步法（建议用于生产）

步骤1：创建Searchcraft索引

{
  "source": "url",
  "path": "https://api.example.com/products.json",
  "index_name": "products",
  "sample_size": 100,
  "search_fields": ["title", "description", "category", "brand"],
  "weight_multipliers": {
    "title": 2.5,
    "description": 1.0,
    "category": 1.8,
    "brand": 1.5
  },
  "language": "en"
}

步骤2：创建搜索应用程序

{
  "data_source": "url",
  "data_path": "https://api.example.com/products.json",
  "app_name": "product-search-app",
  "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", "category", "brand"],
  "weight_multipliers": {
    "title": 2.5,
    "description": 1.0,
    "category": 1.8,
    "brand": 1.5
  }
}

选项2：仅应用程序流程（适用于现有索引）

如果你已经设置了Searchcraft索引，你可以直接创建应用程序：

{
  "data_source": "url",
  "data_path": "https://api.example.com/products.json",
  "app_name": "my-search-app",
  "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",
  "VITE_INDEX_NAME": "existing_index",
  "VITE_READ_KEY": "your_read_key_here"
}

两步法的好处

• 指标优化 → 与用户界面分开微调搜索索引
• 多个应用程序 → 为同一数据创建不同的搜索界面
• 生产就绪 → 更好地分离生产部署的关注点
• 更容易调试 → 独立于UI测试搜索功能

入门指南

环境变量

创建 .env 在项目的根目录下创建文件并填写值：

# Server Config
USER_AGENT=searchcraft-mcp-server/

DEBUG=true
PORT=3100

# Searchcraft Config
ENDPOINT_URL= # The endpoint url of your Searchcraft Cluster
CORE_API_KEY= # The Searchcraft API key of your Searchcraft cluster. Must match the permissions required by the tools you are using.

.env示例

远程使用

如果您已经通过Searchcraft Cloud上的Vectron创建了索引，您可以使用您试图访问的索引的写密钥，并使用MCP服务器执行不需要管理员权限的API操作。 重要：如果您使用带有写密钥的MCP服务器，它应该 非 公开暴露在互联网上。写入密钥旨在得到保护，通过运行MCP服务器，任何有权访问MCP服务器的用户都可以写入索引或删除数据。

安装和设置

确保您的环境选择了正确版本的节点。

nvm use

使用yarn安装依赖项

yarn

构建服务器

yarn build

这将创建两个服务器版本：

• dist/server.js -用于测试和远程部署的HTTP服务器
• dist/stdio-server.js -克劳德桌面的stdio服务器

用法

选项1:克劳德桌面（stdio）-推荐

对于Claude Desktop的本地使用，请使用提供更好性能和可靠性的stdio版本。

claude_desktop_config json

{
  "mcpServers": {
    "searchcraft": {
      "command": "node",
      "args": [
        "/path/to/searchcraft-mcp-server/dist/stdio-server.js"
      ]
    }
  }
}

claude桌面配置文件可以在以下位置找到：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

如果文件不存在，请创建它。

选项2：克劳德代码

要与Claude Code一起使用，请使用CLI配置MCP服务器：

基本设置：

# Add the Searchcraft MCP server to Claude Code
claude mcp add searchcraft -- node /path/to/searchcraft-mcp-server/dist/stdio-server.js

对于环境变量：

# Add with your Searchcraft cluster configuration
claude mcp add searchcraft \
  --env ENDPOINT_URL=https://your-cluster.searchcraft.io \
  --env CORE_API_KEY=YOUR_API_KEY \
  -- node /path/to/searchcraft-mcp-server/dist/stdio-server.js

配置范围：

• --scope local （默认）：仅在当前项目中对您可用
• --scope project：通过与团队共享 .mcp.json 文件（推荐给团队）
• --scope user：适用于所有项目

管理服务器：

# List configured servers
claude mcp list

# Check server status
/mcp

# Remove server
claude mcp remove searchcraft

选项3：打开WebUI（通过管道）

Open WebUI通过其管道框架支持MCP服务器。这需要创建一个自定义管道，将MCP服务器连接到Open WebUI。

步骤1：启动Searchcraft MCP HTTP服务器

yarn start  # Starts HTTP server on port 3100

步骤2：为Open WebUI创建MCP管道

创建一个名为的文件 searchcraft_mcp_pipeline.py:

"""
title: Searchcraft MCP Pipeline
author: Searchcraft Team
version: 1.0.0
license: Apache-2.0
description: A pipeline that integrates Searchcraft MCP server with Open WebUI
requirements: requests
"""

import requests
import json
from typing import List, Union, Generator, Iterator
from pydantic import BaseModel

class Pipeline:
    class Valves(BaseModel):
        MCP_SERVER_URL: str = "http://localhost:3100/mcp"
        ENDPOINT_URL: str = ""
        CORE_API_KEY: str = ""

    def __init__(self):
        self.name = "Searchcraft MCP Pipeline"
        self.valves = self.Valves()

    async def on_startup(self):
        print(f"on_startup:{__name__}")

    async def on_shutdown(self):
        print(f"on_shutdown:{__name__}")

    def pipe(
        self, user_message: str, model_id: str, messages: List[dict], body: dict
    ) -> Union[str, Generator, Iterator]:
        # This pipeline acts as a bridge between Open WebUI and your MCP server
        # You can customize this to handle specific Searchcraft operations

        # Example: If user mentions search operations, route to MCP server
        if any(keyword in user_message.lower() for keyword in ['search', 'index', 'document', 'searchcraft']):
            try:
                # Initialize MCP session
                init_payload = {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                        "protocolVersion": "2025-06-18",
                        "capabilities": {},
                        "clientInfo": {"name": "open-webui-pipeline", "version": "1.0.0"}
                    }
                }

                response = requests.post(self.valves.MCP_SERVER_URL, json=init_payload)

                if response.status_code == 200:
                    # Add context about available Searchcraft tools
                    enhanced_message = f"""
{user_message}

[Available Searchcraft MCP Tools: create_index, delete_index, add_documents, get_search_results, list_all_indexes, get_index_stats, create_key, delete_key, and 20+ more tools for managing Searchcraft clusters]
"""
                    return enhanced_message

            except Exception as e:
                print(f"MCP connection error: {e}")

        return user_message

步骤3：在Open WebUI中安装管道

1. 通过管理面板：

- 转到“管理设置”→ 管道 - 点击“添加管道” - 粘贴上面的管道代码 - 使用Searchcraft设置配置阀门： - MCP_SERVER_URL: http://localhost:3100/mcp - ENDPOINT_URL：您的Searchcraft集群URL - CORE_API_KEY：您的Searchcraft API密钥

1. 通过Docker环境：

   # Save the pipeline to a file and mount it
   docker run -d -p 3000:8080 \
     -v open-webui:/app/backend/data \
     -v ./searchcraft_mcp_pipeline.py:/app/backend/data/pipelines/searchcraft_mcp_pipeline.py \
     --name open-webui \
     ghcr.io/open-webui/open-webui:main

步骤4：配置Open WebUI以使用管道

1. 启动支持管道的Open WebUI：

   # Using Docker Compose (recommended)
   services:
     openwebui:
       image: ghcr.io/open-webui/open-webui:main
       ports:
         - "3000:8080"
       volumes:
         - open-webui:/app/backend/data
       environment:
         - OPENAI_API_BASE_URL=http://pipelines:9099
         - OPENAI_API_KEY=0p3n-w3bu!

     pipelines:
       image: ghcr.io/open-webui/pipelines:main
       volumes:
         - pipelines:/app/pipelines
       environment:
         - PIPELINES_API_KEY=0p3n-w3bu!

1. 在打开WebUI设置中→ 连接：

- 将OpenAI API URL设置为管道实例 - 启用Searchcraft MCP管道

选项4:HTTP服务器（用于测试/远程部署）

启动HTTP服务器进行测试、调试或远程部署：

yarn start  # Starts HTTP server on port 3100

对于带HTTP服务器的Claude Desktop，您需要 mcp遥控器:

claude_desktop_config json

{
  "mcpServers": {
    "searchcraft": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3100/mcp"
      ]
    }
  }
}

选项5:Docker

在Docker容器中运行Searchcraft MCP服务器，以便于部署和移植。

构建Docker镜像：

docker build --load -t searchcraft-mcp-server .

运行容器：

docker run -it -p 8000:8000 \
  --name searchcraft-mcp-server \
  -e ENDPOINT_URL="https://your-cluster.searchcraft.io" \
  -e CORE_API_KEY="your_searchcraft_core_API_key" \
  searchcraft-mcp-server

测试服务器：

# Health check
curl http://localhost:8000/health

# Test MCP endpoint
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

使用MCP检查员进行远程检查：

npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:8000/mcp

Docker配置：

• 使用Node.js 22 slim作为基础映像
• 默认情况下显示端口3100（可通过配置 PORT 环境变量）
• 自动处理SIGINT/SIGTERM上的优雅关机
• 针对最小图像尺寸的生产进行了优化

环境变量：

• PORT -HTTP服务器端口（默认值：8000）
• ENDPOINT_URL -您的Searchcraft集群端点URL
• CORE_API_KEY -您的Searchcraft API密钥
• DEBUG -启用调试日志记录（可选）

可用脚本

# Development
yarn dev          # Watch HTTP server
yarn dev:stdio    # Watch stdio server

# Production
yarn start        # Start HTTP server
yarn start:stdio  # Start stdio server

# Testing
yarn inspect      # Launch MCP inspector
yarn claude-logs  # View Claude Desktop logs

部署选项比较

在以下情况下使用stdio：

• 在本地使用Claude Desktop或Claude Code
• 你想要绝对最好的表现
• 您更喜欢直接的流程沟通

在以下情况下使用HTTP（本地）：

• 您需要测试/调试HTTP接口
• 您正在开发自定义集成
• 您需要多个并发本地客户端

在以下情况下使用Docker：

• 您需要远程部署
• 您想要简单、可重复的设置
• 您正在部署到云平台
• 你想要隔离和安全
• 您需要发布服务器以供检查

测试

Searchcraft MCP服务器包括一个用Vitest构建的全面测试套件。

运行测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Show test reports
npm run test:ui

测试覆盖率

• ✅ 89测试 涵盖核心功能
• ✅ 84%+覆盖率 关于助手和实用程序
• ✅ 93%以上的覆盖率 JSON分析器
• ✅ 100%覆盖率 关于服务器创建
• ✅ HTTP端点的集成测试
• ✅ 所有主要部件的单元测试

看 test/README.md 获取详细的测试文档。

调试

克劳德桌面日志

要查看Claude Desktop调试MCP连接的日志，请执行以下操作：

yarn claude-logs

MCP检验员测试

MCP检查器允许您以交互方式测试服务器工具。

对于stdio服务器（推荐）：

yarn inspect

• 选择传输类型：stdio
• 命令： node dist/stdio-server.js

对于HTTP服务器：

yarn start  # Start HTTP server first
yarn inspect

• 选择传输类型：流式HTTP
• 网址： http://localhost:3100/mcp

手动测试

测试HTTP服务器：

# Health check
curl http://localhost:3100/health

# Test MCP endpoint
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

测试stdio服务器：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/stdio-server.js

资源

• 📘 Searchcraft文档
• 🛰️ Vektron仪表板
• 💬 Searchcraft Discord
• 🧠 Searchcraft Reddit
• 🧪

问题和功能请求

访问https://github.com/searchcraft-inc/searchcraft-issues

许可证

根据 Apache 2.0许可证.

Built with 🛰️ by the Searchcraft team