Incorporación del servidor MCP

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

El poder de txtai: Base de datos de incrustaciones todo en uno

Este proyecto aprovecha txtai , una base de datos de incrustaciones todo en uno para RAG que aprovecha la búsqueda semántica, la construcción de gráficos 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 gráficos y bases de datos relacionales en una única plataforma

• Búsqueda semántica : encuentre información basándose en el significado, no solo en palabras clave

• Integración de gráficos de conocimiento : cree y consulte automáticamente gráficos de conocimiento a partir de sus datos

• Bases de conocimiento portátiles : guarde bases de conocimiento completas como archivos comprimidos (.tar.gz) que se pueden compartir y cargar fácilmente

• Sistema de canalización extensible : procese texto, documentos, audio, imágenes y videos a través de una API unificada

• Arquitectura local : ejecuta todo localmente sin enviar datos a servicios externos

Related MCP server: TxtAI MCP Server

Cómo funciona

El proyecto incluye una herramienta para crear bases de conocimiento y un servidor MCP. Esta herramienta 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 creación de bases de conocimiento para crear una. Siempre puede crear una base de conocimiento usando la interfaz de programación de txtai, escribiendo un script en Python o incluso usando un Jupyter Notebook. Siempre que la base de conocimiento se cree con txtai, el servidor MCP podrá cargarla. Mejor aún, la base de conocimiento puede ser una carpeta en el sistema de archivos o un archivo .tar.gz exportado. Simplemente envíesela al servidor MCP y la cargará.

1. Cree una base de conocimientos con kb_builder

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

• Procesar documentos de diversas fuentes (archivos, directorios, JSON)

• Extraer texto y crear incrustaciones

• Construya gráficos de conocimiento automáticamente

• Exportar bases de conocimiento portátiles

Tenga en cuenta que es posible que tenga una funcionalidad limitada y que actualmente solo se proporciona para conveniencia.

2. Inicie el servidor MCP

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

• Capacidades de búsqueda semántica

• Consulta y visualización de gráficos de conocimiento

• Canalizaciones de procesamiento de texto (resumen, extracción, etc.)

• Cumplimiento total del Protocolo de Contexto Modelo

Instalación

Recomendado: Uso de uv con Python 3.10+

Recomendamos usar uv con Python 3.10 o posterior para obtener la 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 : Hemos fijado los transformadores a la versión 4.49.0 para evitar las advertencias de obsolescencia de transformers.agents.tools que aparecen en la versión 4.50.0 y posteriores. Si usa una versión más reciente de transformadores, es posible que vea 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

De la 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 .

Uso de uvx (no requiere instalación)

uvx le 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

Construyendo una base de conocimientos

Puede utilizar las herramientas de línea de comandos instaladas desde PyPI, el módulo Python directamente o los convenientes scripts de shell:

Uso de los comandos instalados de 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

Uso de uvx (no requiere 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 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

Uso de los scripts de conveniencia

El repositorio incluye scripts envolventes convenientes que facilitan la creación y búsqueda de 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

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

Iniciar el servidor MCP

Uso del comando de instalación de 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

Uso de uvx (no requiere 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 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. Estos archivos solo se utilizan para configurar los componentes de txtai durante la creación de la base de conocimientos.

A continuación se explica cómo configurar 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 conocimientos (obligatorio)

• --host : Dirección de host a la que vincular (predeterminado: localhost)

• --port : Puerto para escuchar (predeterminado: 8000)

• --transport : Transporte a utilizar, ya sea 'sse' o 'stdio' (predeterminado: stdio)

• --enable-causal-boost : Habilita la función de refuerzo causal para una puntuación de relevancia mejorada

• --causal-config : Ruta al archivo YAML de configuración de impulso causal personalizado

Configuración de clientes LLM para utilizar el servidor MCP

Para configurar un cliente LLM para que use el servidor MCP, debe crear un archivo de configuración de MCP. A continuación, se muestra un ejemplo: mcp_config.json

Usando el servidor directamente

Si usa un entorno virtual de Python para instalar el servidor, puede usar la siguiente configuración: tenga en cuenta que el host MCP como Claude no podrá conectarse al servidor si usa un entorno virtual, debe usar la ruta absoluta al ejecutable de Python del entorno virtual donde hizo "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 Python predeterminado del sistema

Si utiliza el Python predeterminado de su sistema, puede utilizar 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á usando uvx, suponiendo que tiene uvx instalado en su sistema a través de "brew install uvx", etc., o ha instalado uvx y lo ha hecho accesible globalmente a través de:

# 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 la instalación específica del usuario a una ubicación del sistema. Para aplicaciones macOS como Claude Desktop, puede modificar la ruta 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"
    }
  }
}

Coloque este archivo de configuración en una ubicación accesible para su cliente LLM y configúrelo para usarlo. Los pasos de configuración exactos dependerán de su cliente LLM específico.

Configuración avanzada de la base de conocimientos

Para crear una base de conocimiento con txtai se requiere un archivo de configuración YAML que controla diversos aspectos del proceso de incrustación. Esta configuración la utiliza la herramienta kb_builder , no el servidor MCP.

Es posible que sea necesario ajustar las estrategias de segmentación/fragmentación, los modelos de integración y los métodos de puntuación, así como configurar la construcción de gráficos, el refuerzo causal, los pesos de la búsqueda híbrida y más.

Afortunadamente, txtai ofrece un potente sistema de configuración YAML que no requiere programación. A continuación, se muestra un ejemplo de una configuración completa para la creació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 (más rápidos para el 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 del dominio

• base.yml : Plantilla de configuración base

• code_repositories.yml : Optimizado para repositorios de código

• data_science.yml : Configurado para documentos de ciencia de datos

• general_knowledge.yml : Base de conocimientos de propósito general

• research_papers.yml : Optimizado para artículos académicos

• technical_docs.yml : Configurado para documentación técnica

Puedes utilizarlos como puntos 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 del gráfico de conocimiento

El servidor MCP aprovecha la funcionalidad de gráficos incorporada de txtai para proporcionar potentes capacidades de gráficos de conocimiento:

• Construcción automática de gráficos : cree gráficos de conocimiento a partir de sus documentos automáticamente

• Recorrido gráfico : navegue a través de conceptos y documentos relacionados

• Búsqueda de rutas : descubre conexiones entre diferentes piezas de información

• Detección de comunidad : identificar grupos de información relacionada

Mecanismo de impulso causal

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

• Reconocimiento de patrones : detecta patrones de lenguaje causales tanto en consultas como en documentos

• Compatibilidad multilingüe : aplica automáticamente patrones apropiados según el idioma de consulta detectado

• Multiplicadores de impulso configurables : diferentes tipos de coincidencias causales reciben factores de impulso personalizables

• Relevancia mejorada : los resultados que explican las 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 de potenciación causal es altamente personalizable mediante archivos YAML, lo que permite su adaptación a diferentes dominios e idiomas.

Licencia

Licencia MIT: consulte el archivo de LICENCIA para obtener más detalles