searchcraft-mcp-server

searchcraft-mcp-server

由 Searchcraft 提供支持的 MCP 服务——一款以开发者为先的垂直搜索引擎。

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 集群的核心功能，用于管理索引、文档、联合搜索、身份验证和搜索操作。

索引管理

工具名称	描述
create_index	使用指定的架构创建新索引。如果索引已存在，其内容将被清空。
delete_index	永久删除索引及其所有文档。
get_all_index_stats	获取所有索引的文档数量和统计信息。
get_index_schema	获取特定索引的架构定义。
get_index_stats	获取特定索引的统计信息和元数据（文档数量等）。
list_all_indexes	获取 Searchcraft 实例中所有索引的列表。
patch_index	对索引架构进行部分配置更改（search_fields、weight_multipliers 等）。
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. 创建 → 使用 Engine API 的 create_index 工具，根据生成的架构创建索引
4. 导入 → 使用 add_documents 将数据填充到新索引中

或者使用一体化方案：

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

应用生成工具

这些工具可根据 JSON 数据创建完整且可直接运行的搜索应用，非常适合原型开发和演示。

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

应用生成工作流

应用生成工具提供端到端的解决方案，用于创建搜索应用：

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" or "file"	✅	从 URL 获取数据还是从本地文件读取数据
path	string	✅	JSON 数据的 URL 或文件路径
index_name	string	✅	新 Searchcraft 索引的名称
sample_size	number	❌	用于生成架构的分析项目数量（默认值：10）
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" or "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）

使用示例

如果你在文档前面看到了提示词，就可以轻松使用自然语言调用 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：两步流程（推荐用于生产环境）

步骤 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 微调搜索索引
• 多个应用 → 为同一数据创建不同的搜索界面
• 适用于生产环境 → 生产部署时更好地分离关注点
• 更易调试 → 独立于 UI 测试搜索功能

开始使用

环境变量

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

# Server Config
USER_AGENT=searchcraft-mcp-server/<project-version>
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 上的 Vektron 创建索引，可以使用要访问的索引的写入密钥，并使用 MCP 服务执行不需要管理员权限的 API 操作。 重要：如果使用写入密钥连接 MCP 服务，切勿将其公开暴露到互联网上。写入密钥应妥善保管；运行 MCP 服务后，任何有权访问该 MCP 服务的用户都可以向索引写入数据或删除数据。

安装与设置

确保环境中已选择正确版本的 node。

nvm use

使用 yarn 安装依赖项

yarn

构建服务

yarn build

这会生成两个服务版本：

• dist/server.js - 用于测试和远程部署的 HTTP 服务
• dist/stdio-server.js - 用于 Claude Desktop 的 stdio 服务

使用方法

选项 1：Claude Desktop（stdio）- 推荐

在 Claude Desktop 中本地使用时，请使用 stdio 版本，以获得更好的性能和可靠性。

claude_desktop_config.json

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

Claude Desktop 配置文件位于：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

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

选项 2：Claude Code

如需在 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：Open WebUI（通过 Pipelines）

Open WebUI 通过其 Pipelines 框架支持 MCP 服务。这需要创建一个自定义 Pipeline，将 MCP 服务接入 Open WebUI。

步骤 1：启动 Searchcraft MCP HTTP 服务

yarn start  # Starts HTTP server on port 3100

步骤 2：为 Open WebUI 创建 MCP Pipeline

创建名为 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 中安装 Pipeline

1. 通过管理面板：

   • 前往 Admin Settings → Pipelines
   • 点击“Add Pipeline”
   • 粘贴上面的 Pipeline 代码
   • 使用你的 Searchcraft 设置配置各项参数：
     • MCP_SERVER_URL：http://localhost:3100/mcp
     • ENDPOINT_URL：你的 Searchcraft 集群 URL
     • CORE_API_KEY：你的 Searchcraft API 密钥

2. 通过 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 以使用 Pipelines

1. 启动支持 Pipelines 的 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!
   

2. 在 Open WebUI Settings → Connections 中：

   • 将 OpenAI API URL 设置为你的 Pipelines 实例
   • 启用 Searchcraft MCP Pipeline

选项 4：HTTP 服务（用于测试／远程部署）

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

yarn start  # Starts HTTP server on port 3100

如需在 Claude Desktop 中使用 HTTP 服务，你需要 mcp-remote：

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 Inspector 进行远程检查：

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（推荐）	HTTP（本地）	Docker
性能	✅ 最佳（直接 IPC）	⚠️ 有 HTTP 开销	✅ 良好
安全性	✅ 不暴露端口	⚠️ 需要网络端口	✅ 隔离环境
设置复杂度	✅ 简单	⚠️ 需要管理端口	✅ 简单（一个命令）
Claude Desktop	✅ 原生支持	⚠️ 需要 mcp-remote	⚠️ 需要 mcp-remote
Claude Code	✅ 原生支持	✅ 支持	✅ 支持
Open WebUI	❌ 不支持	✅ 通过 Pipelines	✅ 通过 Pipelines
远程部署	❌ 仅限本地	✅ 可行，但需手动配置	✅ 轻松容器化
测试	⚠️ 需要 MCP 工具	✅ 使用 curl 轻松测试	✅ 使用 curl 轻松测试
多个客户端	❌ 一次只能连接一个	✅ 支持并发访问	✅ 支持并发访问
可移植性	⚠️ 需要 Node.js	⚠️ 需要 Node.js	✅ 可在任何地方运行

在以下情况下使用 stdio：

• 在本地使用 Claude Desktop 或 Claude Code
• 追求最佳性能
• 偏好直接的进程间通信

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

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

在以下情况下使用 Docker：

• 需要远程部署
• 希望设置过程简单且可重复
• 正在部署到云平台
• 希望实现隔离和安全
• 需要发布服务供他人检查

测试

Searchcraft MCP Server 包含一套使用 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%+
• ✅ JSON 分析器的覆盖率达 93%+
• ✅ 服务创建的覆盖率达 100%
• ✅ HTTP 端点集成测试
• ✅ 所有主要组件的单元测试

详细测试文档请参阅 test/README.md。

调试

Claude Desktop 日志

如需查看 Claude Desktop 的日志以调试 MCP 连接：

yarn claude-logs

使用 MCP Inspector 测试

MCP Inspector 可让你交互式测试服务工具。

stdio 服务（推荐）：

yarn inspect

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

HTTP 服务：

yarn start  # Start HTTP server first
yarn inspect

• 选择传输类型：Streamable HTTP
• URL：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
• 🧪 npm 上的 Searchcraft SDK

问题与功能请求

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

许可证

基于 Apache 2.0 许可证授权。

由 Searchcraft 团队打造 🛰️