doc-lib-mcp

doc-lib-mcp MCP-сервер

Сервер Model Context Protocol (MCP) для приема документов, разбиения на фрагменты, семантического поиска и управления заметками.

Компоненты

Ресурсы

• Реализует простую систему хранения заметок с:
  • Пользовательская схема URI note:// для доступа к отдельным заметкам
  • Каждый ресурс заметки имеет имя, описание и text/plain тип MIME.

Подсказки

• Предоставляет подсказку:
  • summary-notes : Создает сводки всех сохраненных заметок
    • Необязательный аргумент «стиль» для управления уровнем детализации (краткий/подробный)
    • Создает подсказку, объединяющую все текущие заметки с предпочтениями стиля

Инструменты

На сервере реализован широкий спектр инструментов:

• add-note : Добавить новую заметку в хранилище заметок в памяти
  • Аргументы: name (строка), content (строка)
• ingest-string : принимает и разбивает на части строку markdown или обычный текст, предоставленный через сообщение
  • Аргументы: content (строка, обязательно), source (строка, необязательно), tags (список строк, необязательно)
• ingest-markdown : Принять и разбить на части файл markdown (.md)
  • Аргументы: path (строка)
• ingest-python : Прием и разбиение файла Python (.py) на части
  • Аргументы: path (строка)
• ingest-openapi : Прием и разбиение на части JSON-файла OpenAPI
  • Аргументы: path (строка)
• ingest-html : Прием и разбиение HTML-файла на части
  • Аргументы: path (строка)
• ingest-html-url : прием и разбиение HTML-контента из URL-адреса (при желании можно использовать Playwright для динамического контента)
  • Аргументы: url (строка), dynamic (логический, необязательный)
• smart_ingestion : извлекает весь технически значимый контент из файла с помощью Gemini, а затем разбивает его на части, используя надежную логику разметки.
  • Аргументы:
    • path (строка, обязательно): Путь к файлу для загрузки.
    • prompt (строка, необязательно): Пользовательская подсказка для использования в Gemini.
    • tags (список строк, необязательно): Необязательный список тегов для классификации.
  • Использует Gemini 2.0 Flash 001 для извлечения только кода, конфигурации, структуры разметки и технических определений (без резюме или комментариев).
  • Передает извлеченный контент в блокировщик на основе mistune 3.x, который сохраняет как блоки кода, так и разметку/повествовательный контент в виде отдельных фрагментов.
  • Каждый фрагмент встраивается и сохраняется для семантического поиска и извлечения.
• search-chunks : Семантический поиск по принятому контенту
  • Аргументы:
    • query (строка): семантический поисковый запрос.
    • top_k (целое число, необязательное, по умолчанию 3): количество возвращаемых верхних результатов.
    • type (строка, необязательно): Фильтрация результатов по типу фрагмента (например, code , html , markdown ).
    • tag (строка, необязательно): Фильтрация результатов по тегу в метаданных фрагмента.
  • Возвращает наиболее релевантные фрагменты для заданного запроса, при необходимости отфильтрованные по типу и/или тегу.
• delete-source : Удалить все фрагменты из указанного источника
  • Аргументы: source (строка)
• delete-chunk-by-id : Удалить один или несколько фрагментов по идентификатору
  • Аргументы: id (целое число, необязательно), ids (список целых чисел, необязательно)
  • Вы можете удалить один фрагмент, указав id , или удалить несколько фрагментов одновременно, указав ids .
• update-chunk-type : обновить атрибут типа для фрагмента по идентификатору
  • Аргументы: id (целое число, обязательно), type (строка, обязательно)
• ingest-batch : пакетная загрузка и разбиение на части нескольких файлов документации (markdown, OpenAPI JSON, Python)
  • Аргументы: paths (список строк)
• list-sources : список всех уникальных источников (путей к файлам), которые были приняты и сохранены в памяти, с дополнительной фильтрацией по тегу или семантическому поиску.
  • Аргументы:
    • tag (строка, необязательно): Фильтрация источников по тегу в метаданных фрагмента.
    • query (строка, необязательно): Семантический поисковый запрос для поиска релевантных источников.
    • top_k (целое число, необязательное, по умолчанию 10): количество основных источников, возвращаемых при использовании запроса.
• get-context : извлечение релевантных фрагментов контента (только контент) для использования в качестве контекста ИИ с фильтрацией по тегу, типу и семантическому сходству.
  • Аргументы:
    • query (строка, необязательно): семантический поисковый запрос.
    • tag (строка, необязательно): Фильтрация результатов по определенному тегу в метаданных фрагмента.
    • type (строка, необязательно): Фильтрация результатов по типу фрагмента (например, «код», «маркдаун»).
    • top_k (целое число, необязательное, по умолчанию 5): количество наиболее релевантных фрагментов для извлечения.
• update-chunk-metadata : обновить поле метаданных для фрагмента по идентификатору
  • Аргументы: id (целое число), metadata (объект)
• tag-chunks-by-source : Добавляет указанные теги к метаданным всех фрагментов, связанных с указанным источником (URL или путь к файлу). Объединяет с существующими тегами.
  • Аргументы: source (строка), tags (список строк)
• list-notes : Список всех сохраненных на данный момент заметок и их содержимого.

Разделение на части и извлечение кода

• Файлы Markdown, Python, OpenAPI и HTML разбиваются на логические фрагменты для эффективного извлечения и поиска.
• Инструмент разметки использует API AST и регулярные выражения mistune 3.x для надежного разделения контента на блоки кода и повествования, сохраняя все исходное форматирование.
• Блоки кода и разметка/повествовательный контент сохраняются как отдельные фрагменты.
• HTML chunker использует библиотеку readability-lxml для извлечения основного контента в первую очередь, затем извлекает фрагменты кода блока из тегов <pre> как выделенные фрагменты "code". Встроенный контент <code> остается частью повествовательных фрагментов.

Семантический поиск

• Инструмент search-chunks выполняет векторный семантический поиск по всему полученному контенту, возвращая наиболее релевантные фрагменты для заданного запроса.
• Поддерживает необязательные аргументы type и tag для фильтрации результатов по типу фрагмента (например, code , html , markdown ) и/или по тегу в метаданных фрагмента перед семантическим ранжированием.
• Это позволяет осуществлять узконаправленный поиск, например, «все фрагменты кода, помеченные тегом „langfuse“, имеющие отношение к „стоимости и использованию“».

Управление метаданными

• Фрагменты включают поле metadata для категоризации и тегирования.
• Инструмент update-chunk-metadata позволяет обновлять метаданные для любого фрагмента по его идентификатору.
• Инструмент tag-chunks-by-source позволяет добавлять теги ко всем частям из определенного источника за одну операцию. Тегирование объединяет новые теги с существующими, сохраняя предыдущие теги.

Конфигурация

Для сервера требуются следующие переменные среды (их можно задать в файле .env):

Конфигурация Оллама

• OLLAMA_HOST: Имя хоста для API Ollama (по умолчанию: localhost)
• OLLAMA_PORT: Порт для API Ollama (по умолчанию: 11434)
• RAG_AGENT: модель Ollama, используемая для ответов RAG (по умолчанию: llama3)
• OLLAMA_MODEL: Модель Ollama, используемая для встраивания (по умолчанию: nomic-embed-text-v2-moe)

Конфигурация базы данных

• ХОСТ: Хост базы данных PostgreSQL (по умолчанию: localhost)
• DB_PORT: порт базы данных PostgreSQL (по умолчанию: 5432)
• DB_NAME: Имя базы данных PostgreSQL (по умолчанию: doclibdb)
• DB_USER: Пользователь базы данных PostgreSQL (по умолчанию: doclibdb_user)
• DB_PASSWORD: пароль базы данных PostgreSQL (по умолчанию: doclibdb_password)

Конфигурация реранкера

• RERANKER_MODEL_PATH: Путь к модели реранкера (по умолчанию: /srv/samba/fileshare2/AI/models/bge-reranker-v2-m3)
• RERANKER_USE_FP16: Использовать ли FP16 для повторного ранжирования (по умолчанию: True)

Быстрый старт

Установить

Клод Десктоп

В MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json В Windows: %APPDATA%/Claude/claude_desktop_config.json

Разработка

Строительство и издательское дело

Чтобы подготовить пакет к распространению:

1. Синхронизируем зависимости и обновляем файл блокировки:

2. Сборка дистрибутивов пакетов:

Это создаст исходный код и дистрибутивы wheel в каталоге dist/ .

3. Опубликовать в PyPI:

Примечание: вам необходимо задать учетные данные PyPI с помощью переменных среды или флагов команд:

• Токен: --token или UV_PUBLISH_TOKEN
• Или имя пользователя/пароль: --username / UV_PUBLISH_USERNAME и --password / UV_PUBLISH_PASSWORD

Отладка

Поскольку серверы MCP работают через stdio, отладка может быть сложной. Для лучшего опыта отладки мы настоятельно рекомендуем использовать MCP Inspector .

Вы можете запустить MCP Inspector через npm с помощью этой команды:

После запуска Инспектор отобразит URL-адрес, к которому вы можете перейти в своем браузере, чтобы начать отладку.