Встраиваемый MCP-сервер

Реализация сервера Model Context Protocol (MCP) на базе txtai, обеспечивающая семантический поиск, возможности графа знаний и обработку текста на основе искусственного интеллекта через стандартизированный интерфейс.

Сила txtai: Универсальная база данных вложений

В этом проекте используется txtai — универсальная база данных вложений для RAG, использующая семантический поиск, построение графа знаний и рабочие процессы языковой модели. txtai предлагает несколько ключевых преимуществ:

• Унифицированная векторная база данных : объединяет векторные индексы, графовые сети и реляционные базы данных на одной платформе.

• Семантический поиск : найдите информацию, основанную на значении, а не только на ключевых словах.

• Интеграция графа знаний : автоматическое построение и запрос графов знаний на основе ваших данных.

• Переносимые базы знаний : сохраняйте целые базы знаний в виде сжатых архивов (.tar.gz), которые можно легко загружать и распространять.

• Расширяемая конвейерная система : обработка текста, документов, аудио, изображений и видео через унифицированный API

• Архитектура Local-first : запуск всех функций локально без отправки данных на внешние сервисы.

Related MCP server: TxtAI MCP Server

Как это работает

Проект содержит инструмент построения базы знаний и сервер MCP. Инструмент построения базы знаний представляет собой интерфейс командной строки для создания и управления базами знаний. Сервер MCP предоставляет стандартизированный интерфейс для доступа к базе знаний.

Для создания базы знаний не обязательно использовать инструмент создания базы знаний. Вы всегда можете создать базу знаний с помощью программного интерфейса txtai, написав скрипт Python или даже используя блокнот Jupyter. Пока база знаний создана с помощью txtai, ее может загрузить сервер MCP. А еще лучше, база знаний может быть папкой в файловой системе или экспортированным файлом .tar.gz. Просто передайте ее серверу MCP, и он загрузит ее.

1. Создайте базу знаний с помощью kb_builder

Модуль kb_builder предоставляет интерфейс командной строки для создания и управления базами знаний:

• Обработка документов из различных источников (файлы, каталоги, JSON)

• Извлечение текста и создание вложений

• Автоматически строить графики знаний

• Экспорт переносимых баз знаний

Обратите внимание, что функциональность этой функции, возможно, ограничена, и в настоящее время она предоставляется только для удобства.

2. Запустите MCP-сервер.

Сервер MCP предоставляет стандартизированный интерфейс для доступа к базе знаний:

• Возможности семантического поиска

• Запросы и визуализация графа знаний

• Конвейеры обработки текста (суммирование, извлечение и т. д.)

• Полное соответствие Модельному Контекстному Протоколу

Установка

Рекомендуется: использование uv с Python 3.10+

Мы рекомендуем использовать uv с Python 3.10 или новее для лучшего опыта. Это обеспечивает лучшее управление зависимостями и гарантирует единообразное поведение.

# 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

Примечание : Мы закрепляем transformers на версии 4.49.0, чтобы избежать предупреждений об устаревании transformers.agents.tools , которые появляются в версии 4.50.0 и новее. Если вы используете более новую версию transformers, вы можете увидеть эти предупреждения, но они не влияют на функциональность.

Использование конда

# 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

Из источника

# 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 .

Использование УФ (более быстрая альтернатива)

# 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 .

Использование uvx (установка не требуется)

uvx позволяет запускать пакеты напрямую из PyPI без их установки:

# 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"

Использование командной строки

Создание базы знаний

Вы можете использовать инструменты командной строки, установленные из PyPI, непосредственно модуль Python или удобные скрипты оболочки:

Использование установленных команд 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

Использование uvx (установка не требуется)

# 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

Использование модуля 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

Использование удобных скриптов

Репозиторий включает удобные скрипты-оболочки, облегчающие создание и поиск в базах знаний:

# 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

Запустите ./scripts/kb_build.sh --help или ./scripts/kb_search.sh --help для получения дополнительных параметров.

Запуск MCP-сервера

Использование установленной команды 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

Использование uvx (установка не требуется)

# 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

Использование модуля 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

Конфигурация сервера MCP

Сервер MCP настраивается с помощью переменных среды или аргументов командной строки, а не файлов YAML. Файлы YAML используются только для настройки компонентов txtai во время построения базы знаний.

Вот как настроить сервер 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

Распространенные варианты конфигурации:

• --embeddings : Путь к базе знаний (обязательно)

• --host : Адрес хоста для привязки (по умолчанию: localhost)

• --port : Порт для прослушивания (по умолчанию: 8000)

• --transport : используемый транспорт, «sse» или «stdio» (по умолчанию: stdio)

• --enable-causal-boost : включить функцию причинного усиления для улучшенной оценки релевантности

• --causal-config : Путь к пользовательскому файлу конфигурации YAML причинного усиления

Настройка клиентов LLM для использования сервера MCP

Чтобы настроить клиент LLM для использования сервера MCP, вам необходимо создать файл конфигурации MCP. Вот пример mcp_config.json :

Использование сервера напрямую

Если вы используете виртуальную среду Python для установки сервера, вы можете использовать следующую конфигурацию. Обратите внимание, что хост MCP, такой как Claude, не сможет подключиться к серверу, если вы используете виртуальную среду. Вам необходимо использовать абсолютный путь к исполняемому файлу Python виртуальной среды, в которой вы выполнили «pip install» или «uv pip install», например.

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

Использование системного Python по умолчанию

Если вы используете системный Python по умолчанию, вы можете использовать следующую конфигурацию:

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

В качестве альтернативы, если вы используете uvx, предположим, что uvx установлен в вашей системе с помощью «brew install uvx» и т. д., или вы установили uvx и сделали его глобально доступным с помощью:

# 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

Это создает символическую ссылку из вашей пользовательской установки в системное местоположение. Для приложений macOS, таких как Claude Desktop, вы можете изменить системный PATH, создав или отредактировав файл конфигурации launchd:

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

Добавьте этот контент:

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

Затем загрузите его:

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

Однако, чтобы изменения вступили в силу, вам придется перезагрузить компьютер.

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

Поместите этот файл конфигурации в место, доступное вашему клиенту LLM, и настройте клиент для его использования. Точные шаги настройки будут зависеть от вашего конкретного клиента LLM.

Расширенная конфигурация базы знаний

Для создания базы знаний с помощью txtai требуется файл конфигурации YAML, который управляет различными аспектами процесса встраивания. Эта конфигурация используется инструментом kb_builder , а не самим сервером MCP.

Возможно, потребуется настроить стратегии сегментации/разбиения на фрагменты, модели внедрения и методы оценки, а также настроить построение графа, причинно-следственное усиление, веса гибридного поиска и многое другое.

К счастью, txtai предоставляет мощную систему конфигурации YAML, которая не требует кодирования. Вот пример комплексной конфигурации для построения базы знаний:

# 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

Примеры конфигурации

Каталог src/kb_builder/configs содержит шаблоны конфигурации для различных вариантов использования и серверных хранилищ:

Конфигурации хранилища и бэкэнда

• memory.yml : Векторы в памяти (самые быстрые для разработки, без сохранения)

• sqlite-faiss.yml : SQLite для контента + FAISS для векторов (локальное файловое сохранение)

• postgres-pgvector.yml : PostgreSQL + pgvector (готов к использованию с полным сохранением)

Конфигурации, специфичные для домена

• base.yml : Базовый шаблон конфигурации

• code_repositories.yml : Оптимизировано для репозиториев кода

• data_science.yml : настроен для документов по науке о данных

• general_knowledge.yml : База знаний общего назначения

• research_papers.yml : Оптимизировано для научных работ

• technical_docs.yml : Настроен для технической документации

Вы можете использовать их в качестве отправных точек для своих собственных конфигураций:

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

Расширенные функции

Возможности Сети Знаний

Сервер MCP использует встроенную функциональность графов txtai для предоставления мощных возможностей графа знаний:

• Автоматическое построение графиков : автоматическое построение графиков знаний на основе ваших документов.

• Обход графа : навигация по связанным концепциям и документам

• Поиск пути : найдите связи между различными фрагментами информации.

• Обнаружение сообщества : определение кластеров связанной информации

Механизм причинно-следственной связи

Сервер MCP включает в себя сложный механизм причинно-следственной связи, который повышает релевантность поиска путем выявления и приоритизации причинно-следственных связей:

• Распознавание образов : обнаруживает причинно-следственные языковые шаблоны как в запросах, так и в документах.

• Многоязыковая поддержка : автоматически применяет соответствующие шаблоны на основе обнаруженного языка запроса.

• Настраиваемые коэффициенты усиления : различные типы причинных соответствий получают настраиваемые коэффициенты усиления.

• Повышенная релевантность : результаты, объясняющие причинно-следственные связи, имеют приоритет в результатах поиска.

Этот механизм значительно улучшает ответы на вопросы «почему» и «как», выводя на поверхность контент, который объясняет связи между концепциями. Конфигурация каузального усиления легко настраивается с помощью файлов YAML, что позволяет адаптировать ее к различным доменам и языкам.

Лицензия

Лицензия MIT — подробности см. в файле LICENSE