Typesense MCP Server

Typesense MCP Server

---

Uma implementação de servidor Model Context Protocol (MCP) que fornece aos modelos de IA acesso aos recursos de busca do Typesense. Este servidor permite que LLMs descubram, pesquisem e analisem dados armazenados em coleções do Typesense.

Demonstração

Recursos

Recursos

• Liste e acesse coleções via URIs typesense://
• Cada coleção possui nome, descrição e contagem de documentos
• Tipo MIME JSON para acesso ao esquema

Ferramentas

• typesense_query

  • Pesquise documentos em coleções do Typesense com filtros poderosos
  • Entrada: texto da consulta, nome da coleção, campos de pesquisa, filtros, opções de ordenação, limite
  • Retorna documentos correspondentes com pontuações de relevância

• typesense_get_document

  • Recupere documentos específicos por ID das coleções
  • Entrada: nome da coleção, ID do documento
  • Retorna os dados completos do documento

• typesense_collection_stats

  • Obtenha estatísticas sobre uma coleção do Typesense
  • Entrada: nome da coleção
  • Retorna metadados da coleção, contagem de documentos e informações do esquema

Prompts

• analyze_collection

  • Analise a estrutura e o conteúdo da coleção
  • Entrada: nome da coleção
  • Saída: insights sobre esquema, tipos de dados e estatísticas

• search_suggestions

  • Obtenha sugestões para consultas de pesquisa eficazes para uma coleção
  • Entrada: nome da coleção
  • Saída: estratégias de pesquisa recomendadas com base no esquema da coleção

Instalação

Via npm

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

# Local installation
npm install typesense-mcp-server

Via mcp-get

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

Desenvolvimento

Instale as dependências:

npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

Instalação para Desenvolvimento

Usando o Claude Desktop

Para usar com o Claude Desktop, adicione a configuração do servidor:

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

No 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"
      ]
    },
  }
}

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Recomendamos usar o MCP Inspector, que está disponível como script de pacote:

npm run inspector

O Inspector fornecerá uma URL para acessar as ferramentas de depuração no seu navegador.

Componentes

Recursos

O servidor fornece informações sobre as coleções do Typesense:

• Esquemas de Coleção (typesense://collections/<collection>)
  • Informações de esquema JSON para cada coleção
  • Inclui nomes de campos e tipos de dados
  • Documentos de exemplo para entender a estrutura de dados

Ferramentas

O servidor fornece as seguintes ferramentas para interagir com o Typesense:

• typesense_list_collections - Liste todas as coleções disponíveis com seus esquemas

  • Permite descoberta e roteamento sem configuração
  • O LLM pode enumerar coleções em tempo de execução e escolher a(s) correta(s) antes de pesquisar
  • Útil quando as coleções variam por ambiente, locatário ou versão
  • Retorna definições de campos para inferência de esquema (campos pesquisáveis, facetáveis, numéricos)
  • Suporta o parâmetro include_fields para controlar o nível de detalhes

• typesense_query - Pesquise documentos em uma coleção

  • Pesquisa de texto completo com parâmetros personalizáveis
  • Suporta filtragem, ordenação e paginação

• typesense_get_document - Recupere um documento específico por ID

• typesense_collection_stats - Obtenha estatísticas detalhadas sobre uma coleção específica

Modelos de Recursos

O servidor fornece modelos para:

• typesense_search - Modelo para construir consultas de pesquisa do Typesense
• typesense_collection - Modelo para visualizar detalhes da coleção do Typesense

Uso com o Claude Desktop

Para usar este servidor com o aplicativo Claude Desktop, adicione a seguinte configuração à seção "mcpServers" do seu 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 de Logs

O servidor registra informações em um arquivo localizado em:

/tmp/typesense-mcp.log

Este log contém informações detalhadas sobre as operações do servidor, solicitações e quaisquer erros que ocorram.

Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.