Typesense MCP Server

Typesense MCP Server

---

Una implementación de servidor del Model Context Protocol (MCP) que proporciona a los modelos de IA acceso a las capacidades de búsqueda de Typesense. Este servidor permite a los LLM descubrir, buscar y analizar datos almacenados en colecciones de Typesense.

Demostración

Características

Recursos

• Listar y acceder a colecciones mediante URIs typesense://
• Cada colección tiene un nombre, una descripción y un recuento de documentos
• Tipo MIME JSON para acceso al esquema

Herramientas

• typesense_query

  • Buscar documentos en colecciones de Typesense con potentes filtros
  • Entrada: texto de consulta, nombre de la colección, campos de búsqueda, filtros, opciones de ordenación, límite
  • Devuelve documentos coincidentes con puntuaciones de relevancia

• typesense_get_document

  • Recuperar documentos específicos por ID de las colecciones
  • Entrada: nombre de la colección, ID del documento
  • Devuelve los datos completos del documento

• typesense_collection_stats

  • Obtener estadísticas sobre una colección de Typesense
  • Entrada: nombre de la colección
  • Devuelve metadatos de la colección, recuento de documentos e información del esquema

Indicaciones

• analyze_collection

  • Analizar la estructura y el contenido de la colección
  • Entrada: nombre de la colección
  • Salida: información sobre el esquema, los tipos de datos y las estadísticas

• search_suggestions

  • Obtener sugerencias para consultas de búsqueda efectivas para una colección
  • Entrada: nombre de la colección
  • Salida: estrategias de búsqueda recomendadas basadas en el esquema de la colección

Instalación

Mediante npm

# Global installation
npm install -g typesense-mcp-server

# Local installation
npm install typesense-mcp-server

Mediante mcp-get

npx @michaellatman/mcp-get@latest install typesense-mcp-server

Desarrollo

Instalar dependencias:

npm install

Compilar el servidor:

npm run build

Para desarrollo con recompilación automática:

npm run watch

Instalación para Desarrollo

Uso con Claude Desktop

Para usar con Claude Desktop, añade la configuración del servidor:

En MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

En Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "typesense": {
      "command": "node",
      "args": [
        "~/typesense-mcp-server/dist/index.js",
        "--host", "your-typesense-host",
        "--port", "8108",
        "--protocol", "http",
        "--api-key", "your-api-key"
      ]
    },
  }
}

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser un desafío. Recomendamos usar el MCP Inspector, que está disponible como script de paquete:

npm run inspector

El Inspector proporcionará una URL para acceder a las herramientas de depuración en tu navegador.

Componentes

Recursos

El servidor proporciona información sobre las colecciones de Typesense:

• Esquemas de colección (typesense://collections/<collection>)
  • Información del esquema JSON para cada colección
  • Incluye nombres de campos y tipos de datos
  • Documentos de ejemplo para comprender la estructura de datos

Herramientas

El servidor proporciona las siguientes herramientas para interactuar con Typesense:

• typesense_list_collections - Listar todas las colecciones disponibles con sus esquemas

  • Permite el descubrimiento y enrutamiento sin configuración
  • El LLM puede enumerar colecciones en tiempo de ejecución y elegir la(s) adecuada(s) antes de buscar
  • Útil cuando las colecciones varían según el entorno, el inquilino o la versión
  • Devuelve definiciones de campos para la inferencia de esquemas (campos buscables, facetables, numéricos)
  • Admite el parámetro include_fields para controlar el nivel de detalle

• typesense_query - Buscar documentos en una colección

  • Búsqueda de texto completo con parámetros personalizables
  • Admite filtrado, ordenación y paginación

• typesense_get_document - Recuperar un documento específico por ID

• typesense_collection_stats - Obtener estadísticas detalladas sobre una colección específica

Plantillas de Recursos

El servidor proporciona plantillas para:

• typesense_search - Plantilla para construir consultas de búsqueda de Typesense
• typesense_collection - Plantilla para ver detalles de la colección de Typesense

Uso con Claude Desktop

Para usar este servidor con la aplicación Claude Desktop, añade la siguiente configuración a la sección "mcpServers" de tu claude_desktop_config.json:

{
  "mcpServers": {
    "typesense": {
      "command": "npx",
      "args": [
        "-y",
        "typesense-mcp-server",
        "--host", "your-typesense-host",
        "--port", "8108",
        "--protocol", "http",
        "--api-key", "your-api-key"
      ]
    }
  }
}

Registro

El servidor registra información en un archivo ubicado en:

/tmp/typesense-mcp.log

Este registro contiene información detallada sobre las operaciones del servidor, las solicitudes y cualquier error que ocurra.

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto.