Встраиваемый MCP-сервер
Реализация сервера Model Context Protocol (MCP) на базе txtai, обеспечивающая семантический поиск, возможности графа знаний и обработку текста на основе искусственного интеллекта через стандартизированный интерфейс.
Сила txtai: Универсальная база данных вложений
В этом проекте используется txtai — универсальная база данных вложений для RAG, использующая семантический поиск, построение графа знаний и рабочие процессы языковой модели. txtai предлагает несколько ключевых преимуществ:
- Унифицированная векторная база данных : объединяет векторные индексы, графовые сети и реляционные базы данных на одной платформе.
- Семантический поиск : найдите информацию, основанную на значении, а не только на ключевых словах.
- Интеграция графа знаний : автоматическое построение и запрос графов знаний на основе ваших данных.
- Переносимые базы знаний : сохраняйте целые базы знаний в виде сжатых архивов (.tar.gz), которые можно легко загружать и распространять.
- Расширяемая конвейерная система : обработка текста, документов, аудио, изображений и видео через унифицированный API
- Архитектура Local-first : запуск всех функций локально без отправки данных на внешние сервисы.
Как это работает
Проект содержит инструмент построения базы знаний и сервер 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