AI导哈

搜索索引管理服务器

Typesense MCP Server 是一个用于查询和管理 Typesense 搜索索引的模型上下文协议服务器，支持全文、向量和混合搜索，提供元数据读取和写入操作。

  • by fogx
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 fogx/typesense-mcp

使用说明

Typesense MCP服务器

用于查询和管理Typesense搜索索引的模型上下文协议服务器。

工具

search --文本、矢量或混合搜索

单个搜索端点支持全文、矢量（通过嵌入或文档ID）和混合（文本+矢量与阿尔法混合）。

lookup --读取元数据

发货人 action: collections, schema, document, count, aliases, synonyms.

manage --写操作（在只读源上被阻止）

发货人 action: upsert_documents, delete_documents, upsert_alias, delete_alias, create_collection, delete_collection, upsert_synonym, delete_synonym.

仅当至少有一个源已注册时 readonly = false.

资源

collection://{source}/{collection} --具有类型和属性的字段模式。

设置

1.创建配置文件

创建 typesense-mcp.toml 与您的Typesense连接详细信息。请参阅 配置参考 下面是所有可用选项。

[[sources]]
id = "production"
host = "your-cluster.a1.typesense.net"
api_key = "your-api-key"
readonly = true
collections = ["products*", "orders*"]

添加多个 [[sources]] 用于不同环境（生产、暂存、本地等）的块。

2.添加到 .mcp.json

{
  "mcpServers": {
    "typesense": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "typesense-mcp", "path/to/typesense-mcp.toml"]
    }
  }
}

重新启动Claude代码和 mcp__typesense__* 工具将可用。

配置参考

每 [[sources]] 块定义了到Typesense集群的连接。您可以配置多个源，使LLM能够访问不同的环境或集群。

源字段

字段 类型 必填 默认 描述
id 字符串 是 -- 此源的唯一标识符。在所有工具调用中用于定位正确的集群。
host 字符串 是 -- Typesense主机（例如。 your-cluster.a1.typesense.net).支持 环境变量.
api_key 字符串 是 - Typesense API密钥。支持 环境变量.
collections string[] 是 — 收集模式 控制此源可以访问哪些集合。
port 编号 否 443 Typesense服务器端口
protocol "https" "http" 没有 "https"
readonly boolean 否 false 何时 true，阻止对此源的所有写入操作。看 只读模式.
connection_timeout 编号 否 5 连接超时（秒）。
max_search_results 编号 否 250 最大值 per_page 搜索结果的价值。任何具有更高搜索请求 per_page 上限为该值。

集合

这 collections 字段是主要的访问控制机制。它决定了LLM可以在整个服务器上查看和交互哪些集合。

模式语法：每个条目都是一个精确的集合名称或一个带有尾随的前缀 * 通配符。

# Exact match — only this specific collection
collections = ["products"]

# Wildcard — any collection starting with "products"
# Matches: products, products_v2, products_2024-01-15T00:00:00Z
collections = ["products*"]

# Multiple patterns
collections = ["products*", "orders*", "users"]

什么 collections 控制：

效果 描述
架构缓存 在启动时，服务器从Typesense获取模式，并仅缓存与您的模式匹配的集合。这决定了哪些模式可以立即使用，而不是需要实时查找。
架构资源 The collection://{source}/{collection} MCP资源只公开与您的模式匹配的集合。这是LLM在搜索之前读取以了解字段名称和类型的内容。
收藏发现 lookup action=collections 过滤结果——LLM只看到与您的模式匹配的集合。
别名发现 lookup action=aliases 过滤器别名——只返回指向允许的集合的别名。
门禁 每一个 search, manage，并且特定于收藏 lookup 调用在执行之前根据您的模式验证所请求的集合。对不匹配集合的请求被拒绝。

这 ["*"] 通配符：设置 collections = ["*"] 匹配集群上的每个集合。这有效地禁用了集合级访问控制。适合当地发展，但在共享或生产集群上，这意味着LLM可以访问（以及 readonly = false，修改）任何集合。

推荐方法：使用适用于您环境的特定前缀。这对于带时间戳的集合名称特别有用：

# Production — read-only, scoped to production collections
[[sources]]
id = "production"
host = "cluster.typesense.net"
api_key = "${TYPESENSE_PROD_KEY}"
readonly = true
collections = ["products_production*", "orders_production*"]

# Staging — writable, scoped to staging collections
[[sources]]
id = "staging"
host = "cluster.typesense.net"
api_key = "${TYPESENSE_STAGING_KEY}"
collections = ["products_staging*", "orders_staging*"]

只读模式

当 readonly = true，the manage 该工具阻止对该源的所有写入操作，并返回错误消息。这使您可以安全地将管理员API密钥用于读取操作（架构查找、搜索），而不会有意外突变的风险。

如果 全部 来源是只读的 manage 该工具根本没有注册——LLM甚至不会将其视为可用工具。

[[sources]]
id = "production"
host = "cluster.typesense.net"
api_key = "admin-key-here"
readonly = true  # safe to use admin key — writes are blocked
collections = ["products_production*"]

或者，您可以创建 作用域API密钥 在Typesense中，只有搜索权限，这也在Typesens层提供了防御。

环境变量

这 host 和 api_key 字段支持环境变量替换，以避免在配置文件中存储机密：

[[sources]]
id = "production"
host = "${TYPESENSE_HOST}"
api_key = "${TYPESENSE_API_KEY}"
collections = ["products*"]

两者 ${VAR_NAME} 和 $VAR_NAME 支持语法。如果未设置引用的变量，服务器将在启动时抛出错误。

日志记录

设置 LOG_LEVEL 用于控制日志详细程度的环境变量。日志被写入stderr。

级别 描述
debug 详细输出，包括客户端创建和缓存详细信息
info 启动进度和操作事件（默认）
warn 非致命问题（例如，无法获取源的别名）
error 工具执行或关闭时出错

完整示例

# Production — locked down for safe exploration
[[sources]]
id = "production"
host = "${TYPESENSE_HOST}"
api_key = "${TYPESENSE_PROD_KEY}"
port = 443
protocol = "https"
readonly = true
connection_timeout = 10
max_search_results = 100
collections = ["products_production*", "orders_production*"]

# Staging — writable for testing
[[sources]]
id = "staging"
host = "${TYPESENSE_HOST}"
api_key = "${TYPESENSE_STAGING_KEY}"
readonly = false
collections = ["products_staging*", "orders_staging*"]

# Local — wide open for development
[[sources]]
id = "local"
host = "localhost"
port = 8108
protocol = "http"
api_key = "xyz"
collections = ["*"]

启动行为

当服务器启动时，它：

  1. 解析和验证 TOML配置——如果任何必填字段丢失或无效，服务器将立即退出。
  2. 扩展环境变量 在 host 和 api_key 领域。
  3. 预热架构缓存 --连接到每个源，检索所有集合，根据配置的模式对其进行过滤，并缓存字段模式。这意味着服务器运行后，模式查找是即时的。
  4. 注册工具 — search 和 lookup 总是注册的。 manage 仅当至少有一个源具有 readonly = false.
  5. 注册架构资源 --暴露 collection://{source}/{collection} 对于所有允许的收藏。
  6. 通过stdio连接 并且准备好处理请求。

如果在预热过程中无法访问某个源，服务器会记录一条警告并继续——其他源仍将工作。在源可用之前，无法访问的源的架构查找将返回“无缓存架构”。

发展

git clone https://github.com/fogx/typesense-mcp.git
cd typesense-mcp
npm install
npm run build
npm test

释放

  1. 添加变更集： npx changeset
  2. 版本： npx changeset version
  3. 承诺并推动
  4. 创建GitHub版本——CI将发布到npm

相关 MCP