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 позволяет добавлять теги ко всем частям из определенного источника за одну операцию. Тегирование объединяет новые теги с существующими, сохраняя предыдущие теги.

Related MCP server: MPC Docs Server

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

Для сервера требуются следующие переменные среды (их можно задать в файле .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. Синхронизируем зависимости и обновляем файл блокировки:

uv sync

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

uv build

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

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

uv publish

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

• Токен: --token или UV_PUBLISH_TOKEN

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

Отладка

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

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

npx @modelcontextprotocol/inspector uv --directory /home/administrator/python-share/doc-lib-mcp run doc-lib-mcp

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