Embedding MCP Server

Un servidor MCP impulsado por txtai para búsqueda semántica, grafos de conocimiento y procesamiento de texto basado en IA.

GitHub

Prueba este MCPPatrocinado

Documentación

Embedding MCP Server

Una implementación de servidor de Model Context Protocol (MCP) impulsada por txtai, que proporciona búsqueda semántica, capacidades de grafo de conocimiento y procesamiento de texto impulsado por IA a través de una interfaz estandarizada.

El poder de txtai: base de datos de embeddings todo en uno

Este proyecto aprovecha txtai, una base de datos de embeddings todo en uno para RAG que aprovecha la búsqueda semántica, la construcción de grafos de conocimiento y los flujos de trabajo de modelos de lenguaje. txtai ofrece varias ventajas clave:

Base de datos vectorial unificada: combina índices vectoriales, redes de grafos y bases de datos relacionales en una única plataforma
Búsqueda semántica: encuentra información basada en el significado, no solo en palabras clave
Integración de grafos de conocimiento: construye y consulta automáticamente grafos de conocimiento a partir de tus datos
Bases de conocimiento portables: guarda bases de conocimiento completas como archivos comprimidos (.tar.gz) que se pueden compartir y cargar fácilmente
Sistema de canalizaciones extensible: procesa texto, documentos, audio, imágenes y video a través de una API unificada
Arquitectura local primero: ejecuta todo localmente sin enviar datos a servicios externos

Cómo funciona

El proyecto contiene una herramienta de construcción de bases de conocimiento y un servidor MCP. La herramienta de construcción de bases de conocimiento es una interfaz de línea de comandos para crear y gestionar bases de conocimiento. El servidor MCP proporciona una interfaz estandarizada para acceder a la base de conocimiento.

No es necesario usar la herramienta de construcción de bases de conocimiento para crear una base de conocimiento. Siempre puedes construir una base de conocimiento usando la interfaz de programación de txtai escribiendo un script de Python o incluso usando un cuaderno de Jupyter. Mientras la base de conocimiento esté construida con txtai, el servidor MCP puede cargarla. Mejor aún, la base de conocimiento puede ser una carpeta en el sistema de archivos o un archivo .tar.gz exportado. Solo entrégasela al servidor MCP y la cargará.

1. Construye una base de conocimiento con kb_builder

El módulo kb_builder proporciona una interfaz de línea de comandos para crear y gestionar bases de conocimiento:

Procesa documentos de diversas fuentes (archivos, directorios, JSON)
Extrae texto y crea embeddings
Construye grafos de conocimiento automáticamente
Exporta bases de conocimiento portables

Ten en cuenta que posiblemente tenga funcionalidad limitada y actualmente solo se proporciona por conveniencia.

2. Inicia el servidor MCP

El servidor MCP proporciona una interfaz estandarizada para acceder a la base de conocimiento:

Capacidades de búsqueda semántica
Consulta y visualización de grafos de conocimiento
Canalizaciones de procesamiento de texto (resumen, extracción, etc.)
Cumplimiento total con el Model Context Protocol

Instalación

Recomendado: usar uv con Python 3.10+

Recomendamos usar uv con Python 3.10 o superior para una mejor experiencia. Esto proporciona una mejor gestión de dependencias y garantiza un comportamiento 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: fijamos transformers en la versión 4.49.0 para evitar advertencias de obsolescencia sobre transformers.agents.tools que aparecen en la versión 4.50.0 y posteriores. Si usas una versión más reciente de transformers, es posible que veas estas advertencias, pero no afectan la funcionalidad.

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

Desde el código fuente

# 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 más 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 (sin necesidad de instalación)

uvx te permite ejecutar paquetes directamente desde PyPI sin instalarlos:

# 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 de la línea de comandos

Construcción de una base de conocimiento

Puedes usar las herramientas de línea de comandos instaladas desde PyPI, el módulo de Python directamente o los prácticos scripts de shell:

Usando los comandos instalados desde 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 (sin necesidad de instalación)

# 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 el módulo de 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 los scripts de conveniencia

El repositorio incluye scripts envoltorio convenientes que facilitan la construcción y búsqueda en bases de conocimiento:

# 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

Ejecuta ./scripts/kb_build.sh --help o ./scripts/kb_search.sh --help para más opciones.

Iniciando el servidor MCP

Usando el comando instalado desde 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 (sin necesidad de instalación)

# 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 el módulo de 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

Configuración del servidor MCP

El servidor MCP se configura mediante variables de entorno o argumentos de línea de comandos, no archivos YAML. Los archivos YAML solo se usan para configurar los componentes de txtai durante la construcción de la base de conocimiento.

Así es como se configura el 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

Opciones de configuración comunes:

--embeddings: ruta a la base de conocimiento (obligatorio)
--host: dirección de host a la que vincularse (predeterminado: localhost)
--port: puerto de escucha (predeterminado: 8000)
--transport: transporte a usar, ya sea 'sse' o 'stdio' (predeterminado: stdio)
--enable-causal-boost: habilita la función de refuerzo causal para una mejor puntuación de relevancia
--causal-config: ruta al archivo YAML de configuración personalizada de refuerzo causal

Configuración de clientes LLM para usar el servidor MCP

Para configurar un cliente LLM para usar el servidor MCP, necesitas crear un archivo de configuración MCP. Aquí tienes un ejemplo mcp_config.json:

Usando el servidor directamente

Si usas un entorno virtual de Python para instalar el servidor, puedes usar la siguiente configuración: ten en cuenta que un host MCP como Claude no podrá conectarse al servidor si usas un entorno virtual; necesitas usar la ruta absoluta al ejecutable de Python del entorno virtual donde hiciste "pip install" o "uv pip install", por ejemplo

{
  "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 el Python predeterminado del sistema

Si usas el Python predeterminado de tu sistema, puedes usar la siguiente configuración:

{
    "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, si estás usando uvx, asumiendo que tienes uvx instalado en tu sistema mediante "brew install uvx" u otro método, o has instalado uvx y lo has hecho accesible globalmente mediante:

# 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

Esto crea un enlace simbólico desde tu instalación específica de usuario a una ubicación de todo el sistema. Para aplicaciones de macOS como Claude Desktop, puedes modificar el PATH del sistema creando o editando un archivo de configuración de launchd:

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

Añade este contenido:

<?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>

Luego cárgalo:

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

Sin embargo, necesitarás reiniciar tu computadora para que esto surta efecto.

{
  "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"
    }
  }
}

Coloca este archivo de configuración en una ubicación accesible para tu cliente LLM y configura el cliente para usarlo. Los pasos exactos de configuración dependerán de tu cliente LLM específico.

Configuración avanzada de la base de conocimiento

Construir una base de conocimiento con txtai requiere un archivo de configuración YAML que controla varios aspectos del proceso de embeddings. Esta configuración la usa la herramienta kb_builder, no el servidor MCP en sí.

Es posible que necesites ajustar estrategias de segmentación/división en fragmentos, modelos de embeddings y métodos de puntuación, así como configurar la construcción de grafos, el refuerzo causal, los pesos de la búsqueda híbrida y más.

Afortunadamente, txtai proporciona un potente sistema de configuración YAML que no requiere programación. Aquí tienes un ejemplo de una configuración completa para la construcción de bases de conocimiento:

# 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

Ejemplos de configuración

El directorio src/kb_builder/configs contiene plantillas de configuración para diferentes casos de uso y backends de almacenamiento:

Configuraciones de almacenamiento y backend

memory.yml: vectores en memoria (los más rápidos para desarrollo, sin persistencia)
sqlite-faiss.yml: SQLite para contenido + FAISS para vectores (persistencia local basada en archivos)
postgres-pgvector.yml: PostgreSQL + pgvector (listo para producción con persistencia completa)

Configuraciones específicas de dominio

base.yml: plantilla de configuración base
code_repositories.yml: optimizada para repositorios de código
data_science.yml: configurada para documentos de ciencia de datos
general_knowledge.yml: base de conocimiento de propósito general
research_papers.yml: optimizada para artículos académicos
technical_docs.yml: configurada para documentación técnica

Puedes usarlas como punto de partida para tus propias configuraciones:

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

Funciones avanzadas

Capacidades de grafo de conocimiento

El servidor MCP aprovecha la funcionalidad de grafos integrada de txtai para proporcionar potentes capacidades de grafo de conocimiento:

Construcción automática de grafos: construye grafos de conocimiento a partir de tus documentos automáticamente
Recorrido de grafos: navega a través de conceptos y documentos relacionados
Búsqueda de rutas: descubre conexiones entre diferentes piezas de información
Detección de comunidades: identifica grupos de información relacionada

Mecanismo de refuerzo causal

El servidor MCP incluye un sofisticado mecanismo de refuerzo causal que mejora la relevancia de la búsqueda al identificar y priorizar relaciones causales:

Reconocimiento de patrones: detecta patrones de lenguaje causal tanto en consultas como en documentos
Soporte multilingüe: aplica automáticamente los patrones apropiados según el idioma detectado en la consulta
Multiplicadores de refuerzo configurables: diferentes tipos de coincidencias causales reciben factores de refuerzo personalizables
Relevancia mejorada: los resultados que explican relaciones causales se priorizan en los resultados de búsqueda

Este mecanismo mejora significativamente las respuestas a preguntas de "por qué" y "cómo" al mostrar contenido que explica las relaciones entre conceptos. La configuración del refuerzo causal es altamente personalizable mediante archivos YAML, lo que permite la adaptación a diferentes dominios e idiomas.

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles