Typesense MCP (Fogx)

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能够访问不同的环境或集群。

源字段

集合

这 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 控制：

**这 ["*"] 通配符**：设置 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。

完整示例

# 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