阿斯特拉数据库MCP

Name: 阿斯特拉数据库MCP
Author: datastax

作者：datastax37 星标更新：2025-10-20

安装使用来源：spider==github.com

项目介绍

Astra DB MCP 服务器

用于与 Astra DB 交互的 Model Context Protocol (MCP) 服务器。MCP 通过允许大型语言模型（LLMs）作为代理与外部系统进行交互，扩展了这些模型的能力。

预备条件

你需要有一个正在运行的 Astra DB 数据库。如果你还没有一个，你可以在这里创建一个免费的数据库：注册页面。在那里，你可以获取以下两项内容：

Astra DB 应用程序令牌
Astra DB API 终端节点

要了解如何获取这些内容，请参阅入门文档。

添加到 MCP 客户端

这里是如何将此服务器添加到你的 MCP 客户端中。

Claude Desktop

要在 Claude Desktop 中添加此服务器，请转到首选项 -> 开发者 -> 编辑配置，并在 claude_desktop_config.json 文件中添加以下 JSON 块：

{
  "mcpServers": {
    "astra-db-mcp": {
      "command": "npx",
      "args": ["-y", "@datastax/astra-db-mcp"],
      "env": {
        "ASTRA_DB_APPLICATION_TOKEN": "your_astra_db_token",
        "ASTRA_DB_API_ENDPOINT": "your_astra_db_endpoint"
      }
    }
  }
}

可选键空间配置： 默认情况下，此服务器使用底层 Astra DB 库中配置的键空间（通常是 default_keyspace）。如果你需要连接到特定的键空间，可以在上述 env 对象中添加 ASTRA_DB_KEYSPACE 变量，如下所示：

"env": {
  "ASTRA_DB_APPLICATION_TOKEN": "your_astra_db_token",
  "ASTRA_DB_API_ENDPOINT": "your_astra_db_endpoint",
  "ASTRA_DB_KEYSPACE": "your_desired_keyspace"
}

Windows PowerShell 用户： npx 是一个批处理命令，因此需要修改 JSON 如下：

  "command": "cmd",
  "args": ["/k", "npx", "-y", "@datastax/astra-db-mcp"],

Cursor

要在 Cursor 中添加此服务器，请转到设置 -> Cursor 设置 -> MCP

从那里，你可以通过点击“+ 添加新 MCP 服务器”按钮来添加服务器，这会带你到一个 mcp.json 文件。

提示：存在一个代表全局 MCP 设置的 ~/.cursor/mcp.json 文件，以及一个特定于项目的 .cursor/mcp.json 文件。你可能希望将这个 MCP 服务器安装到项目特定的文件中。

添加与 Claude Desktop 指南中指示相同的 JSON。

或者，你可能会遇到一个向导，在那里你可以输入以下值（针对基于 Unix 的系统）：

名称：任意名称
类型：命令
命令：

env ASTRA_DB_APPLICATION_TOKEN=your_astra_db_token ASTRA_DB_API_ENDPOINT=your_astra_db_endpoint npx -y @datastax/astra-db-mcp

注意：ASTRA_DB_KEYSPACE 是可选的。如果省略，则使用 Astra DB 库中配置的默认键空间。

添加后，你的编辑器将完全连接到你的 Astra DB 数据库。

可用工具

该服务器提供了以下工具以与 Astra DB 进行交互：

集合管理

GetCollections：获取数据库中的所有集合
CreateCollection：在数据库中创建一个新的集合（支持向量）
UpdateCollection：更新数据库中的现有集合
DeleteCollection：从数据库中删除一个集合
EstimateDocumentCount：获取集合中估计的文档数量

记录操作

ListRecords：列出数据库中集合中的记录
GetRecord：通过 ID 获取集合中的特定记录
CreateRecord：在集合中创建新的记录
UpdateRecord：更新集合中的现有记录
DeleteRecord：从集合中删除记录
FindRecord：根据字段值在集合中查找记录
FindDistinctValues：查找集合中特定字段的不同值

批量操作

BulkCreateRecords：一次创建多个记录
BulkUpdateRecords：一次更新多个记录
BulkDeleteRecords：一次删除多个记录

向量搜索

VectorSearch：对向量嵌入执行相似性搜索
HybridSearch：结合向量相似性搜索和文本搜索

实用工具

OpenBrowser：打开浏览器进行身份验证和设置
HelpAddToClient：获取帮助将 Astra DB 客户端添加到你的 MCP 客户端

新功能和能力

向量搜索能力

Astra DB MCP 服务器现在包括强大的向量搜索能力，适用于 AI 应用：

VectorSearch

对向量嵌入执行相似性搜索：

// 示例用法
const results = await VectorSearch({
  collectionName: "my_vector_collection",
  queryVector: [0.1, 0.2, 0.3, ...], // 你的嵌入向量
  limit: 5,                          // 可选：返回的结果数量（默认：10）
  minScore: 0.7,                     // 可选：最小相似度分数阈值
  filter: { category: "article" }    // 可选：额外的过滤条件
});

HybridSearch

结合向量相似性搜索和文本搜索以获得更准确的结果：

// 示例用法
const results = await HybridSearch({
  collectionName: "my_vector_collection",
  queryVector: [0.1, 0.2, 0.3, ...], // 你的嵌入向量
  textQuery: "气候变化",               // 要搜索的文本查询
  weights: {                          // 可选：混合搜索权重
    vector: 0.7,                      // 向量相似性的权重（0.0-1.0）
    text: 0.3                         // 文本相关性的权重（0.0-1.0）
  },
  limit: 5,                           // 可选：返回的结果数量
  fields: ["标题", "内容"]            // 可选：要搜索的文本查询字段
});

增强的集合创建

CreateCollection 工具现在支持更多的向量配置选项：

// 示例用法
const result = await CreateCollection({
  collectionName: "my_vector_collection",
  vector: true,                       // 启用向量搜索
  dimension: 1536,                    // 向量维度（例如，1536 用于 OpenAI 嵌入）
  metric: "余弦"                      // 相似度度量："余弦"、"欧几里得"或"点积"
});

查找不同值

新的 FindDistinctValues 工具允许你找到字段的独特值：

// 示例用法
const distinctValues = await FindDistinctValues({
  collectionName: "my_collection",
  field: "类别",                       // 要查找独特值的字段
  filter: { active: true }            // 可选：应用的过滤条件
});

优化的批量操作

批量操作现在使用本地批处理处理以提高性能：

// 示例：批量创建记录
const result = await BulkCreateRecords({
  collectionName: "my_collection",
  records: [
    { title: "记录 1", content: "内容 1" },
    { title: "记录 2", content: "内容 2" },
    // ... 更多记录
  ]
});

// 示例：批量更新记录
const updateResult = await BulkUpdateRecords({
  collectionName: "my_collection",
  records: [
    { id: "record1", record: { title: "更新标题 1" } },
    { id: "record2", record: { title: "更新标题 2" } },
    // ... 更多记录
  ]
});

// 示例：批量删除记录
const deleteResult = await BulkDeleteRecords({
  collectionName: "my_collection",
  recordIds: ["record1", "record2", "record3"]
});

改进的错误处理

服务器现在提供更详细的错误消息和错误代码，以便更容易诊断问题。

更新日志

所有重要的更改将在此文件中记录：更新日志。格式基于 Keep a Changelog，并且此项目遵循语义化版本控制。

运行评估

evals 包加载了一个 mcp 客户端，然后运行 index.ts 文件，因此无需在测试之间重新构建。你可以通过在 npx 命令前缀加载环境变量。完整的文档可以在此处找到：文档。

OPENAI_API_KEY=your-key  npx mcp-eval evals.ts tools.ts