Embedding MCP Server

Um servidor MCP alimentado por txtai para busca semântica, grafos de conhecimento e processamento de texto orientado por IA.

GitHub

Experimente este MCPPatrocinado

Documentação

Embedding MCP Server

Uma implementação de servidor Model Context Protocol (MCP) alimentada por txtai, fornecendo busca semântica, capacidades de grafo de conhecimento e processamento de texto orientado por IA através de uma interface padronizada.

O Poder do txtai: Banco de Dados de Embeddings Tudo-em-um

Este projeto utiliza txtai, um banco de dados de embeddings tudo-em-um para RAG que aproveita busca semântica, construção de grafos de conhecimento e fluxos de trabalho com modelos de linguagem. O txtai oferece várias vantagens principais:

Banco de Dados Vetorial Unificado: Combina índices vetoriais, redes de grafos e bancos de dados relacionais em uma única plataforma
Busca Semântica: Encontre informações com base no significado, não apenas em palavras-chave
Integração com Grafo de Conhecimento: Construa e consulte grafos de conhecimento automaticamente a partir dos seus dados
Bases de Conhecimento Portáteis: Salve bases de conhecimento inteiras como arquivos compactados (.tar.gz) que podem ser facilmente compartilhados e carregados
Sistema de Pipeline Extensível: Processe texto, documentos, áudio, imagens e vídeo através de uma API unificada
Arquitetura Local-first: Execute tudo localmente sem enviar dados para serviços externos

Como Funciona

O projeto contém uma ferramenta de construção de base de conhecimento e um servidor MCP. A ferramenta de construção de base de conhecimento é uma interface de linha de comando para criar e gerenciar bases de conhecimento. O servidor MCP fornece uma interface padronizada para acessar a base de conhecimento.

Não é obrigatório usar a ferramenta de construção de base de conhecimento para criar uma base de conhecimento. Você pode sempre construir uma base de conhecimento usando a interface de programação do txtai escrevendo um script Python ou até mesmo usando um jupyter notebook. Desde que a base de conhecimento seja construída com txtai, ela pode ser carregada pelo servidor MCP. Melhor ainda, a base de conhecimento pode ser uma pasta no sistema de arquivos ou um arquivo .tar.gz exportado. Basta fornecê-la ao servidor MCP e ele a carregará.

1. Construa uma Base de Conhecimento com kb_builder

O módulo kb_builder fornece uma interface de linha de comando para criar e gerenciar bases de conhecimento:

Processa documentos de várias fontes (arquivos, diretórios, JSON)
Extrai texto e cria embeddings
Constrói grafos de conhecimento automaticamente
Exporta bases de conhecimento portáteis

Observe que ela pode ser limitada em funcionalidade e atualmente é fornecida apenas por conveniência.

2. Inicie o Servidor MCP

O servidor MCP fornece uma interface padronizada para acessar a base de conhecimento:

Capacidades de busca semântica
Consulta e visualização de grafos de conhecimento
Pipelines de processamento de texto (sumarização, extração, etc.)
Conformidade total com o Model Context Protocol

Instalação

Recomendado: Usando uv com Python 3.10+

Recomendamos usar uv com Python 3.10 ou mais recente para a melhor experiência. Isso proporciona melhor gerenciamento de dependências e garante um comportamento consistente.

# Install uv if you don't have it already
pip install -U uv

# Create a virtual environment with Python 3.10 or newer
uv venv --python=3.10  # or 3.11, 3.12, etc.

# Activate the virtual environment (bash/zsh)
source .venv/bin/activate
# For fish shell
# source .venv/bin/activate.fish

# Install from PyPI
uv pip install kb-mcp-server

Nota: Fixamos transformers na versão 4.49.0 para evitar avisos de depreciação sobre transformers.agents.tools que aparecem na versão 4.50.0 e posteriores. Se você usar uma versão mais recente do transformers, poderá ver esses avisos, mas eles não afetam a funcionalidade.

Usando conda

# Create a new conda environment (optional)
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp

# Install from PyPI
pip install kb-mcp-server

A partir do Código Fonte

# Create a new conda environment
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp

# Clone the repository
git clone https://github.com/Geeksfino/kb-mcp-server.git.git
cd kb-mcp-server

# Install dependencies
pip install -e .

Usando uv (Alternativa Mais Rápida)

# Install uv if not already installed
pip install uv

# Create a new virtual environment
uv venv
source .venv/bin/activate

# Option 1: Install from PyPI
uv pip install kb-mcp-server

# Option 2: Install from source (for development)
uv pip install -e .

Usando uvx (Sem Necessidade de Instalação)

uvx permite executar pacotes diretamente do PyPI sem instalá-los:

# Run the MCP server
uvx --from kb-mcp-server@0.3.0 kb-mcp-server --embeddings /path/to/knowledge_base

# Build a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml

# Search a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "Your search query"

Uso pela Linha de Comando

Construindo uma Base de Conhecimento

Você pode usar as ferramentas de linha de comando instaladas do PyPI, o módulo Python diretamente ou os scripts de shell convenientes:

Usando os Comandos Instalados do PyPI

# Build a knowledge base from documents
kb-build --input /path/to/documents --config config.yml

# Update an existing knowledge base with new documents
kb-build --input /path/to/new_documents --update

# Export a knowledge base for portability
kb-build --input /path/to/documents --export my_knowledge_base.tar.gz

# Search a knowledge base
kb-search /path/to/knowledge_base "What is machine learning?"

# Search with graph enhancement
kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10

Usando uvx (Sem Necessidade de Instalação)

# Build a knowledge base from documents
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml

# Update an existing knowledge base with new documents
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/new_documents --update

# Export a knowledge base for portability
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --export my_knowledge_base.tar.gz

# Search a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "What is machine learning?"

# Search with graph enhancement
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10

Usando o Módulo Python

# Build a knowledge base from documents
python -m kb_builder build --input /path/to/documents --config config.yml

# Update an existing knowledge base with new documents
python -m kb_builder build --input /path/to/new_documents --update

# Export a knowledge base for portability
python -m kb_builder build --input /path/to/documents --export my_knowledge_base.tar.gz

Usando os Scripts de Conveniência

O repositório inclui scripts de wrapper convenientes que facilitam a construção e a busca em bases de conhecimento:

# Build a knowledge base using a template configuration
./scripts/kb_build.sh /path/to/documents technical_docs

# Build using a custom configuration file
./scripts/kb_build.sh /path/to/documents /path/to/my_config.yml

# Update an existing knowledge base
./scripts/kb_build.sh /path/to/documents technical_docs --update

# Search a knowledge base
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?"

# Search with graph enhancement
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?" --graph

Execute ./scripts/kb_build.sh --help ou ./scripts/kb_search.sh --help para mais opções.

Iniciando o Servidor MCP

Usando o Comando Instalado do PyPI

# Start with a specific knowledge base folder
kb-mcp-server --embeddings /path/to/knowledge_base_folder

# Start with a given knowledge base archive
kb-mcp-server --embeddings /path/to/knowledge_base.tar.gz

Usando uvx (Sem Necessidade de Instalação)

# Start with a specific knowledge base folder
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base_folder

# Start with a given knowledge base archive
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base.tar.gz

Usando o Módulo Python

# Start with a specific knowledge base folder
python -m txtai_mcp_server --embeddings /path/to/knowledge_base_folder

# Start with a given knowledge base archive
python -m txtai_mcp_server --embeddings /path/to/knowledge_base.tar.gz

Configuração do Servidor MCP

O servidor MCP é configurado usando variáveis de ambiente ou argumentos de linha de comando, não arquivos YAML. Arquivos YAML são usados apenas para configurar componentes do txtai durante a construção da base de conhecimento.

Veja como configurar o servidor MCP:

# Start the server with command-line arguments
kb-mcp-server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# Or using uvx (no installation required)
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# Or using the Python module
python -m txtai_mcp_server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# Or use environment variables
export TXTAI_EMBEDDINGS=/path/to/knowledge_base
export MCP_SSE_HOST=0.0.0.0
export MCP_SSE_PORT=8000
python -m txtai_mcp_server

Opções de configuração comuns:

--embeddings: Caminho para a base de conhecimento (obrigatório)
--host: Endereço do host para vincular (padrão: localhost)
--port: Porta para escutar (padrão: 8000)
--transport: Transporte a usar, 'sse' ou 'stdio' (padrão: stdio)
--enable-causal-boost: Ativa o recurso de reforço causal para pontuação de relevância aprimorada
--causal-config: Caminho para o arquivo YAML de configuração de reforço causal personalizado

Configurando Clientes LLM para Usar o Servidor MCP

Para configurar um cliente LLM para usar o servidor MCP, você precisa criar um arquivo de configuração MCP. Aqui está um exemplo de mcp_config.json:

Usando o servidor diretamente

Se você usar um ambiente virtual Python para instalar o servidor, pode usar a seguinte configuração - observe que hosts MCP como Claude não conseguirão se conectar ao servidor se você usar um ambiente virtual; você precisa usar o caminho absoluto para o executável Python do ambiente virtual onde você fez "pip install" ou "uv pip install", por exemplo

{
  "mcpServers": {
    "kb-server": {
      "command": "/your/home/project/.venv/bin/kb-mcp-server",
      "args": [
        "--embeddings", 
        "/path/to/knowledge_base.tar.gz"
      ],
      "cwd": "/path/to/working/directory"
    }
  }
}

Usando o Python padrão do sistema

Se você usar o Python padrão do seu sistema, pode usar a seguinte configuração:

{
    "rag-server": {
      "command": "python3",
      "args": [
        "-m",
        "txtai_mcp_server",
        "--embeddings",
        "/path/to/knowledge_base.tar.gz",
        "--enable-causal-boost"
      ],
      "cwd": "/path/to/working/directory"
    }
}

Alternativamente, se você estiver usando uvx, supondo que tenha o uvx instalado no seu sistema via "brew install uvx" etc., ou que tenha instalado o uvx e o tornado globalmente acessível via:

# Create a symlink to /usr/local/bin (which is typically in the system PATH)
sudo ln -s /Users/cliang/.local/bin/uvx /usr/local/bin/uvx

Isso cria um link simbólico da sua instalação específica do usuário para um local em todo o sistema. Para aplicativos macOS como Claude Desktop, você pode modificar o PATH do sistema criando ou editando um arquivo de configuração launchd:

# Create a plist file to set environment variables for all GUI applications
sudo nano /Library/LaunchAgents/environment.plist

Adicione este conteúdo:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>my.startup</string>
  <key>ProgramArguments</key>
  <array>
    <string>sh</string>
    <string>-c</string>
    <string>launchctl setenv PATH $PATH:/Users/cliang/.local/bin</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

Em seguida, carregue-o:

sudo launchctl load -w /Library/LaunchAgents/environment.plist

Você precisará reiniciar o computador para que isso entre em vigor, no entanto.

{
  "mcpServers": {
    "kb-server": {
      "command": "uvx",
      "args": [
        "kb-mcp-server@0.2.6",
        "--embeddings", "/path/to/knowledge_base",
        "--host", "localhost",
        "--port", "8000"
      ],
      "cwd": "/path/to/working/directory"
    }
  }
}

Coloque este arquivo de configuração em um local acessível ao seu cliente LLM e configure o cliente para usá-lo. As etapas exatas de configuração dependerão do seu cliente LLM específico.

Configuração Avançada da Base de Conhecimento

Construir uma base de conhecimento com txtai requer um arquivo de configuração YAML que controla vários aspectos do processo de embedding. Esta configuração é usada pela ferramenta kb_builder, não pelo próprio servidor MCP.

Pode ser necessário ajustar estratégias de segmentação/divisão em blocos, modelos de embedding e métodos de pontuação, bem como configurar a construção de grafos, reforço causal, pesos da busca híbrida e muito mais.

Felizmente, o txtai fornece um poderoso sistema de configuração YAML que não requer codificação. Aqui está um exemplo de configuração abrangente para construção de base de conhecimento:

# Path to save/load embeddings index
path: ~/.txtai/embeddings
writable: true

# Content storage in SQLite
content:
  path: sqlite:///~/.txtai/content.db

# Embeddings configuration
embeddings:
  # Model settings
  path: sentence-transformers/nli-mpnet-base-v2
  backend: faiss
  gpu: true
  batch: 32
  normalize: true
  
  # Scoring settings
  scoring: hybrid
  hybridalpha: 0.75

# Pipeline configuration
pipeline:
  workers: 2
  queue: 100
  timeout: 300

# Question-answering pipeline
extractor:
  path: distilbert-base-cased-distilled-squad
  maxlength: 512
  minscore: 0.3

# Graph configuration
graph:
  backend: sqlite
  path: ~/.txtai/graph.db
  similarity: 0.75  # Threshold for creating graph connections
  limit: 10  # Maximum connections per node

Exemplos de Configuração

O diretório src/kb_builder/configs contém modelos de configuração para diferentes casos de uso e backends de armazenamento:

Configurações de Armazenamento e Backend

memory.yml: Vetores em memória (mais rápido para desenvolvimento, sem persistência)
sqlite-faiss.yml: SQLite para conteúdo + FAISS para vetores (persistência local baseada em arquivos)
postgres-pgvector.yml: PostgreSQL + pgvector (pronto para produção com persistência completa)

Configurações Específicas de Domínio

base.yml: Modelo de configuração base
code_repositories.yml: Otimizado para repositórios de código
data_science.yml: Configurado para documentos de ciência de dados
general_knowledge.yml: Base de conhecimento de propósito geral
research_papers.yml: Otimizado para artigos acadêmicos
technical_docs.yml: Configurado para documentação técnica

Você pode usá-los como pontos de partida para suas próprias configurações:

python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/technical_docs.yml

# Or use a storage-specific configuration
python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/postgres-pgvector.yml

Recursos Avançados

Capacidades de Grafo de Conhecimento

O servidor MCP aproveita a funcionalidade de grafo integrada do txtai para fornecer poderosas capacidades de grafo de conhecimento:

Construção Automática de Grafos: Construa grafos de conhecimento a partir dos seus documentos automaticamente
Navegação em Grafos: Navegue por conceitos e documentos relacionados
Descoberta de Caminhos: Descubra conexões entre diferentes partes de informações
Detecção de Comunidades: Identifique agrupamentos de informações relacionadas

Mecanismo de Reforço Causal

O servidor MCP inclui um sofisticado mecanismo de reforço causal que aprimora a relevância da busca identificando e priorizando relações causais:

Reconhecimento de Padrões: Detecta padrões de linguagem causal tanto em consultas quanto em documentos
Suporte Multilíngue: Aplica automaticamente padrões apropriados com base no idioma detectado da consulta
Multiplicadores de Reforço Configuráveis: Diferentes tipos de correspondências causais recebem fatores de reforço personalizáveis
Relevância Aprimorada: Resultados que explicam relações causais são priorizados nos resultados de busca

Este mecanismo melhora significativamente as respostas a perguntas "por que" e "como", trazendo à tona conteúdo que explica relações entre conceitos. A configuração de reforço causal é altamente personalizável através de arquivos YAML, permitindo adaptação a diferentes domínios e idiomas.

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes