🚀 searchcraft-mcp-server
searchcraft-mcp-server 是一个由 Searchcraft 驱动的 MCP 服务器。Searchcraft 是一款以开发者为中心的垂直搜索引擎。该服务器提供了一套工具，用于管理 Searchcraft 集群的文档、索引、联合搜索、访问密钥和分析数据。
🚀 快速开始
环境变量
在项目根目录下创建 .env 文件，并填写以下值：
# 服务器配置
USER_AGENT=searchcraft-mcp-server/<项目版本>
DEBUG=true
PORT=3100
# Searchcraft 配置
ENDPOINT_URL= # Searchcraft 集群的端点 URL
ADMIN_KEY= # Searchcraft 集群的管理员密钥（超级用户密钥）
.env 文件示例
运行服务器
确保你的环境中选择了正确版本的 Node：
nvm use
使用 Yarn 安装依赖：
yarn
构建并启动服务器：
yarn build
yarn start
✨ 主要特性
可用工具
索引管理
| 工具名称 | 描述 |
|---|---|
| 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 | 获取测量转换数据，可选择过滤和聚合参数。 |
| get_measure_summary | 获取测量摘要数据，可选择过滤和聚合参数。 |
| get_search_results | 使用 Searchcraft API 执行搜索查询，支持模糊/精确匹配、分面和日期范围。 |
| get_searchcraft_status | 获取 Searchcraft 搜索服务的当前状态。 |
💻 使用示例
与 Claude Desktop 配合使用
为了让 Claude Desktop 检测到 searchcraft-mcp-server 的工具，服务器必须处于运行状态。
searchcraft-mcp-server 使用 StreamableHTTPServerTransport，因此为了将其连接到 Claude Desktop，我们使用 mcp-remote ↗︎。
在你的 Claude Desktop 配置文件中添加以下内容：
claude_desktop_config.json
{
"mcpServers": {
"searchcraft": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:/mcp"
]
}
}
}
Claude Desktop 配置文件可以在 /Users/[My Workspace]]/Library/Application Support/Claude/claude_desktop_config.json 找到。如果此处没有文件，可以创建一个。
Claude desktop 配置示例
Claude Desktop Node 版本
我们发现，当 Claude Desktop 运行连接到 MCP 服务器的命令时，有时会选择较旧版本的 Node。如果系统上安装了较旧版本的 Node，这可能会导致问题。请确保系统上的默认 Node 版本足够高，以便正确运行服务器。
📚 详细文档
调试
要查看 Claude 的日志以进行调试，请使用 npm 脚本：
yarn claude-logs
检查工具
你可以使用检查器查看和试用可用的工具、提示和资源。当 mcp 服务器运行时，你可以启动检查器：
yarn inspect
- 选择传输类型：可流式传输的 HTTP
- 指定服务器运行的 URL，包括端口号。
- 点击“连接”
http://localhost:/mcp
检查器允许你查看可用的工具并尝试对其进行测试调用。
资源
📄 许可证
本项目采用 Apache 2.0 许可证。
由 Searchcraft 团队使用 🛰️ 构建