MCP Knowledge Assistant

Сервер Model Context Protocol (MCP) только для чтения, который позволяет ИИ-клиенту выполнять поиск по базе знаний и получать полные исходные документы. Проект начинается с небольшого локального прототипа, а затем применяет тот же контракт инструментов к семантическому поиску в векторном хранилище OpenAI.

Что это демонстрирует

• Проектирование MCP-инструментов с узкими обязанностями search и fetch

• Структурированные входные и выходные данные с использованием FastMCP и Pydantic

• Семантический поиск по загруженным документам в векторном хранилище OpenAI

• Дедупликация на уровне документов, когда векторный поиск возвращает несколько подходящих фрагментов

• Потоковые транспорты MCP: Streamable HTTP и stdio

• Сквозное использование инструментов через OpenAI Responses API и защищённый MCP-туннель

• Настройка через переменные окружения, без учётных данных в исходном коде

• Модульные и протокольные тесты, не выполняющие платных вызовов API

Related MCP server: File AI

Архитектура

OpenAI Responses API
        |
        | MCP tool calls through an outbound secure tunnel
        v
Local FastMCP server (Streamable HTTP)
        |
        | vector-store search and file retrieval
        v
OpenAI vector store -> uploaded documents

Репозиторий также включает полностью локальный учебный путь:

Local demo client -> FastMCP server (stdio) -> data/documents.json

Оба сервера предоставляют один и тот же публичный контракт инструментов:

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

Структура проекта

.
├── data/documents.json                   # Sample local knowledge base
├── sample_data/cats.pdf                  # Public-domain vector-store sample
├── src/mcp_knowledge_assistant/
│   ├── knowledge_base.py                 # Local keyword retrieval
│   ├── models.py                         # Shared response schemas
│   ├── server.py                         # Local stdio MCP server
│   └── vector_store_server.py            # OpenAI vector-store MCP server
├── tests/                                # Offline unit and MCP tests
├── demo_client.py                        # Local stdio demonstration
├── vector_store_demo_client.py           # Direct HTTP MCP demonstration
└── api_client.py                         # Responses API + secure tunnel demonstration

Требования

• Python 3.11 или новее

• Проект OpenAI API с включённой оплатой для пути через векторное хранилище

• Включённый образец PDF или собственный документ, загруженный в векторное хранилище OpenAI

• Клиент туннеля OpenAI только для демонстрации защищённого туннеля

Локальный JSON-сервер и полный набор тестов не требуют API-ключа.

Атрибуция образца документа

Демонстрация с векторным хранилищем использует Cats: Their Points and Characteristics У. Гордона Стэблса, электронная книга Project Gutenberg №43429. Образец PDF размещён OpenAI и создан на основе издания Project Gutenberg. См. PDF-файл с информацией о лицензии Project Gutenberg и применимых условиях повторного использования.

Настройка

Клонируйте репозиторий, создайте виртуальное окружение и установите проект:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Для примеров с OpenAI скопируйте шаблон окружения:

cp .env.example .env.local

Затем добавьте собственные значения в .env.local:

OPENAI_API_KEY=your_project_api_key
VECTOR_STORE_ID=vs_your_vector_store_id

.env.local, настройки PyCharm, виртуальные окружения и локальные профили туннеля исключены из Git.

1. Запуск локального прототипа

Первый сервер использует stdio, поэтому MCP-клиент запускает его как дочерний процесс и взаимодействует через стандартный ввод и вывод:

python demo_client.py

Демо обнаруживает оба инструмента, выполняет поиск по образцовой JSON-базе знаний и получает выбранный документ.

Вы также можете запустить сервер через установленную команду:

mcp-knowledge-assistant

Молчаливый ожидающий процесс — это нормально для stdio-сервера без подключённого клиента.

2. Запуск сервера с векторным хранилищем

Загрузите sample_data/cats.pdf в векторное хранилище OpenAI, затем задайте OPENAI_API_KEY и VECTOR_STORE_ID в .env.local. При желании вы можете использовать собственный документ и запрос. Запустите сервер Streamable HTTP:

mcp-vector-store-assistant

По умолчанию его MCP-эндпоинт:

http://127.0.0.1:8000/mcp

Во втором терминале проверьте эндпоинт напрямую:

python vector_store_demo_client.py

Векторный поиск работает с фрагментами, поэтому длинный документ может дать несколько совпадений с одним и тем же идентификатором файла. MCP-инструмент search намеренно сворачивает эти совпадения в один результат по документу. Затем инструмент fetch получает и объединяет разобранное содержимое этого документа для модели.

3. Вызов через Responses API

Следуйте руководству OpenAI по защищённым MCP-туннелям, чтобы создать туннель, настройте его игнорируемый локальный профиль на http://127.0.0.1:8000/mcp и запустите клиент туннеля. Добавьте полученный ID в .env.local:

MCP_TUNNEL_ID=tunnel_your_tunnel_id

Клиент туннеля читает свои рабочие учётные данные из CONTROL_PLANE_API_KEY. Храните это значение также локально. Когда векторный сервер и клиент туннеля запущены, выполните:

python api_client.py

Запрос к Responses API объявляет только инструменты MCP search и fetch для чтения. Модель может выполнять поиск, получать выбранный источник и составлять ответ на основе извлечённого содержимого.

Тесты

Запустите все тесты командой:

pytest

Тесты покрывают локальное ранжирование и получение данных, обнаружение MCP-инструментов, дедупликацию результатов векторного поиска, сборку содержимого и проверку входных данных. Вызовы OpenAI имитируются, поэтому набор тестов воспроизводим и не расходует API-кредиты.

Проектные решения и область применения

• Только чтение: ни один MCP-инструмент не изменяет файлы или внешнее состояние.

• Стабильный контракт совместимости: search(query) возвращает ссылки на документы; fetch(id) возвращает полное содержимое и метаданные.

• Результаты по документам, а не по фрагментам: фрагменты — это доказательства поиска внутри векторного хранилища, а MCP-клиент получает стабильные идентификаторы файлов.

• MCP — это уровень абстракции: для одного векторного хранилища, размещённого в OpenAI, встроенный инструмент File Search в Responses API проще. MCP становится полезным, когда один и тот же интерфейс поиска должен обслуживать несколько клиентов, скрывать детали бэкенда или в дальнейшем добавлять авторизацию и доменную логику.

• Проверенная граница интеграции: локальные серверы, прямые MCP-клиенты и путь через Responses API с защищённым туннелем были опробованы в ходе разработки. Этот репозиторий не заявляет о развёрнутом публичном сервере или опубликованном приложении ChatGPT.

Замечания по безопасности

• Никогда не коммитьте .env.local, API-ключи, рабочие ключи туннеля или идентификаторы организаций.

• Используйте учётные данные с областью действия проекта и предоставляйте только необходимые разрешения.

• Держите локальный MCP-сервер за защищённым исходящим туннелем, а не открывайте входящий порт в брандмауэре.

• Проверяйте разрешения инструментов перед добавлением любых операций записи или действий с последствиями.

Ссылки

• Руководство OpenAI по MCP

• Руководство OpenAI по File Search

• Руководство OpenAI по защищённым MCP-туннелям

• Документация FastMCP