Astra DB

Un servidor para interactuar con la base de datos como servicio Astra DB, construida sobre Apache Cassandra.

Documentación

Servidor MCP de Astra DB

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con Astra DB. MCP extiende las capacidades de los Modelos de Lenguaje de Gran Escala (LLMs) permitiéndoles interactuar con sistemas externos como agentes.

Requisitos previos

Necesitas tener una base de datos Astra DB en ejecución. Si no tienes una, puedes crear una base de datos gratuita aquí. Desde allí, puedes obtener dos cosas que necesitas:

Un Token de Aplicación de Astra DB
El Endpoint de API de Astra DB

Para aprender cómo obtener estos, por favor lee la documentación de inicio.

Añadir a un cliente MCP

Así es como puedes añadir este servidor a tu cliente MCP.

Claude Desktop

Para añadir esto a Claude Desktop, ve a Preferencias -> Desarrollador -> Editar Configuración y añade este bloque JSON a claude_desktop_config.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"
      }
    }
  }
}

Configuración opcional de Keyspace: Por defecto, este servidor utiliza el keyspace configurado en la librería subyacente de Astra DB (típicamente default_keyspace). Si necesitas conectarte a un keyspace específico, puedes añadir la variable ASTRA_DB_KEYSPACE al objeto env anterior, de la siguiente manera:

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

Usuarios de Windows PowerShell: npx es un comando por lotes, así que modifica el JSON de la siguiente manera:

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

Cursor

Para añadir esto a Cursor, ve a Configuración -> Configuración de Cursor -> MCP

Desde allí, puedes añadir el servidor haciendo clic en el botón "+ Agregar Nuevo Servidor MCP", donde deberías ser llevado a un archivo mcp.json.

Consejo: hay un ~/.cursor/mcp.json que representa tu configuración MCP Global, y un archivo .cursor/mcp.json específico del proyecto que es específico para el proyecto. Probablemente quieras instalar este servidor MCP en el archivo específico del proyecto.

Añade el mismo JSON indicado en las instrucciones de Claude Desktop.

Alternativamente, puede que se te presente un asistente, donde puedes ingresar los siguientes valores (para sistemas basados en Unix):

Nombre: Lo que quieras
Tipo: Comando
Comando:

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

Nota: ASTRA_DB_KEYSPACE es opcional. Si se omite, se utilizará el keyspace predeterminado configurado en la librería de Astra DB.

Una vez añadido, tu editor estará completamente conectado a tu base de datos Astra DB.

Herramientas Disponibles

El servidor proporciona las siguientes herramientas para interactuar con Astra DB:

Gestión de Colecciones

GetCollections: Obtener todas las colecciones en la base de datos
CreateCollection: Crear una nueva colección en la base de datos (con soporte de vectores)
UpdateCollection: Actualizar una colección existente en la base de datos
DeleteCollection: Eliminar una colección de la base de datos
EstimateDocumentCount: Obtener una estimación del número de documentos en una colección

Operaciones de Registros

ListRecords: Listar registros de una colección en la base de datos
GetRecord: Obtener un registro específico de una colección por ID
CreateRecord: Crear un nuevo registro en una colección
UpdateRecord: Actualizar un registro existente en una colección
DeleteRecord: Eliminar un registro de una colección
FindRecord: Encontrar registros en una colección por valor de campo
FindDistinctValues: Encontrar valores distintos para un campo específico en una colección

Operaciones Masivas

BulkCreateRecords: Crear múltiples registros en una colección a la vez
BulkUpdateRecords: Actualizar múltiples registros en una colección a la vez
BulkDeleteRecords: Eliminar múltiples registros de una colección a la vez

Búsqueda Vectorial

VectorSearch: Realizar búsqueda de similitud vectorial en incrustaciones vectoriales
HybridSearch: Combinar búsqueda de similitud vectorial con búsqueda de texto

Utilidades

OpenBrowser: Abrir un navegador web para autenticación y configuración
HelpAddToClient: Obtener asistencia para añadir el cliente de Astra DB a tu cliente MCP

Nuevas Características y Capacidades

Capacidades de Búsqueda Vectorial

El servidor MCP de Astra DB ahora incluye potentes capacidades de búsqueda vectorial para aplicaciones de IA:

VectorSearch

Realizar búsqueda de similitud en incrustaciones vectoriales:

// Example usage
const results = await VectorSearch({
  collectionName: "my_vector_collection",
  queryVector: [0.1, 0.2, 0.3, ...], // Your embedding vector
  limit: 5,                          // Optional: Number of results to return (default: 10)
  minScore: 0.7,                     // Optional: Minimum similarity score threshold
  filter: { category: "article" }    // Optional: Additional filter criteria
});

HybridSearch

Combinar búsqueda de similitud vectorial con búsqueda de texto para resultados más precisos:

// Example usage
const results = await HybridSearch({
  collectionName: "my_vector_collection",
  queryVector: [0.1, 0.2, 0.3, ...], // Your embedding vector
  textQuery: "climate change",        // Text query to search for
  weights: {                          // Optional: Weights for hybrid search
    vector: 0.7,                      // Weight for vector similarity (0.0-1.0)
    text: 0.3                         // Weight for text relevance (0.0-1.0)
  },
  limit: 5,                           // Optional: Number of results to return
  fields: ["title", "content"]        // Optional: Fields to search in for text query
});

Creación de Colecciones Mejorada

La herramienta CreateCollection ahora soporta más opciones de configuración vectorial:

// Example usage
const result = await CreateCollection({
  collectionName: "my_vector_collection",
  vector: true,                       // Enable vector search
  dimension: 1536,                    // Vector dimension (e.g., 1536 for OpenAI embeddings)
  metric: "cosine"                    // Similarity metric: "cosine", "euclidean", or "dot_product"
});

Encontrar Valores Distintos

La nueva herramienta FindDistinctValues te permite encontrar valores únicos para un campo:

// Example usage
const distinctValues = await FindDistinctValues({
  collectionName: "my_collection",
  field: "category",                  // Field to find distinct values for
  filter: { active: true }            // Optional: Filter to apply
});

Operaciones Masivas Optimizadas

Las operaciones masivas ahora utilizan procesamiento por lotes nativo para un mejor rendimiento:

// Example: Bulk create records
const result = await BulkCreateRecords({
  collectionName: "my_collection",
  records: [
    { title: "Record 1", content: "Content 1" },
    { title: "Record 2", content: "Content 2" },
    // ... more records
  ]
});

// Example: Bulk update records
const updateResult = await BulkUpdateRecords({
  collectionName: "my_collection",
  records: [
    { id: "record1", record: { title: "Updated Title 1" } },
    { id: "record2", record: { title: "Updated Title 2" } },
    // ... more records
  ]
});

// Example: Bulk delete records
const deleteResult = await BulkDeleteRecords({
  collectionName: "my_collection",
  recordIds: ["record1", "record2", "record3"]
});

Manejo de Errores Mejorado

El servidor ahora proporciona mensajes de error más detallados con códigos de error para ayudar a diagnosticar problemas más fácilmente.

Registro de Cambios

Todos los cambios notables de este proyecto se documentarán en este archivo. El formato se basa en Keep a Changelog, y este proyecto se adhiere a Versionado Semántico.

Ejecución de evaluaciones

El paquete de evaluaciones carga un cliente mcp que luego ejecuta el archivo index.ts, por lo que no hay necesidad de reconstruir entre pruebas. Puedes cargar variables de entorno prefijando el comando npx. La documentación completa se puede encontrar aquí.

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