MCP Server

Пикард MCP Сервер

Обзор

Picard MCP — это полноценная система управления памятью, построенная на стандарте Model Context Protocol (MCP) . Она состоит из двух основных компонентов: сервера MCP, который предоставляет безопасные службы хранения и извлечения памяти, и клиентского приложения Django, которое демонстрирует, как интегрироваться с сервером MCP. Система позволяет пользователям хранить, извлекать и управлять своими воспоминаниями, контролируя разрешения на доступ, а также позволяет выполнять семантический поиск и запросы на основе ИИ на основе сохраненных воспоминаний.

Соответствие MCP

Эта реализация следует стандарту Model Context Protocol, который позволяет приложениям LLM взаимодействовать с сервером стандартизированным образом. Сервер MCP предоставляет:

• Ресурсы : конечные точки только для чтения, которые предоставляют данные LLM (содержимое памяти)
• Инструменты : функциональные конечные точки, которые выполняют действия (создание памяти, обновления, запросы)
• Аутентификация : реализация OAuth 2.0 для безопасного доступа к защищенным ресурсам

Ключевые компоненты

1. MCP Server : реализация протокола контекста модели на базе FastAPI, которая обеспечивает:
   • Аутентификация и авторизация OAuth 2.0 с поддержкой PKCE
   • Хранилище памяти с векторными вложениями
   • Контроль доступа к памяти на основе разрешений
   • Интеграция LLM для запросов на основе памяти
2. Клиент Django : веб-приложение, демонстрирующее интеграцию с сервером MCP:
   • Регистрация и аутентификация пользователя
   • Реализация клиента OAuth 2.0
   • Пользовательский интерфейс создания, извлечения и управления памятью
   • Интерфейс запросов на основе персоны

Архитектура системы

Общая архитектура

Система Picard MCP имеет архитектуру клиент-сервер и включает в себя следующие компоненты:

1. MCP Server : основная внутренняя служба, которая управляет хранением памяти, извлечением данных и операциями ИИ.
   • Создан с использованием FastAPI (FastMCP) для высокой производительности и асинхронной поддержки
   • Использует PostgreSQL с расширением pgvector для векторного хранения и семантического поиска
   • Реализует модели данных для пользователей, воспоминаний (с векторными вложениями), клиентов OAuth и токенов.
   • Использует SQLAlchemy ORM с миграциями Alembic для управления базами данных
   • Реализует OAuth 2.0 для безопасной аутентификации и авторизации
   • Интегрируется с API OpenAI для встраивания памяти (text-embedding-3-small)
   • Использует LangChain для операций LLM, если доступно
   • Обеспечивает как режимы работы с сохранением состояния, так и режимы работы без сохранения состояния
   • Поддерживает потоковую передачу HTTP для лучшей масштабируемости
2. Django Client : веб-приложение, демонстрирующее интеграцию с сервером MCP
   • Обеспечивает регистрацию пользователей, аутентификацию и управление профилями
   • Реализует клиент OAuth 2.0 для безопасного взаимодействия с сервером MCP
   • Предлагает удобный интерфейс для управления памятью и выполнения запросов.
   • Использует собственную базу данных PostgreSQL, отдельную от сервера MCP
3. Инфраструктура Docker : контейнерное развертывание для легкой настройки и масштабирования
   • Отдельные контейнеры для сервера MCP (порт 8001), клиента Django (порт 8000) и баз данных PostgreSQL
   • Настроенная сеть для безопасной связи между контейнерами
   • Монтирование тома для постоянного хранения данных
   • Совместимо как с локальным развертыванием Docker, так и с развертыванием облака Render.

Подходы к аутентификации

Система предлагает два основных подхода к аутентификации:

1. Прямое подключение к потоку маркеров контекста пользователя (рекомендуется)

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

1. Регистрация клиента :
   • Клиент Django регистрируется на сервере MCP, используя конечную точку /api/admin/clients/register
   • Регистрация требует аутентификации администратора и включает имя клиента, URI перенаправления и запрошенные области действия.
   • Сервер MCP выдает клиентский идентификатор на основе UUID и криптографически защищенный клиентский секрет
   • Учетные данные клиента должны храниться в безопасности и никогда не раскрываться в клиентском коде.
2. Процесс аутентификации пользователя :
   • Пользователь аутентифицируется только с помощью клиента Django
   • Когда пользователь инициирует подключение к серверу MCP, клиент Django отправляет запрос на стороне сервера к конечной точке MCP /api/user-tokens/user-token
   • Запрос включает в себя:
     • Учетные данные клиента (client_id и client_secret)
     • Информация о пользователе (имя пользователя и адрес электронной почты)
     • Возможность создания пользователя, если он не существует
   • Сервер MCP проверяет учетные данные клиента и либо находит, либо создает соответствующего пользователя.
   • Сервер MCP выдает токены доступа и обновления для пользователя
   • Клиент Django надежно хранит эти токены и использует их для запросов API.
3. API-доступ :
   • Клиент включает токен доступа в заголовок Authorization ( Authorization: Bearer {token} ) для всех запросов API.
   • Сервер MCP проверяет подпись токена, срок действия и заявления аудитории
   • Сервер MCP применяет разрешения на основе области действия для каждой конечной точки
   • Когда срок действия токена доступа истекает, клиент использует токен обновления для получения нового.
4. Функции безопасности :
   • Только конфиденциальные клиенты могут использовать этот метод, обеспечивая безопасность на уровне сервер-сервер.
   • Учетные данные клиента проверяются для каждого запроса токена.
   • Токены заносятся в черный список после использования для предотвращения атак повторного воспроизведения.
   • Токены обновления используют ротацию: каждое использование генерирует новый токен обновления и делает старый недействительным.

2. Стандартный поток кода авторизации OAuth 2.0 с PKCE (устаревший)

Система также поддерживает стандартный поток кода авторизации OAuth 2.0 с PKCE для повышения безопасности в соответствии со стандартами RFC 6749 и RFC 7636. Этот подход требует от пользователей аутентификации как на клиенте, так и на сервере MCP:

1. Поток авторизации :
   • Пользователь инициирует вход через клиент Django
   • Клиент генерирует криптографически безопасный случайный параметр state для защиты от CSRF
   • Клиент генерирует случайный PKCE code_verifier и выводит code_challenge с помощью SHA-256
   • Клиент перенаправляется на конечную точку /authorize сервера MCP с помощью:
     • response_type=code
     • client_id (формат UUID)
     • redirect_uri
     • scope (список, разделенный пробелами, например, memories:read memories:write )
     • state (для защиты от CSRF)
     • Параметры PKCE ( code_challenge и code_challenge_method=S256 )
   • Сервер MCP аутентифицирует пользователя (если он еще не аутентифицирован)
   • Сервер MCP проверяет все параметры и перенаправляет обратно клиенту с кратковременным кодом авторизации.
2. Обмен токенами :
   • Клиент проверяет, соответствует ли возвращаемый параметр state параметру, отправленному в запросе авторизации.
   • Клиент обменивается кодом авторизации на токены доступа и обновления через конечную точку /token
   • Сервер MCP выдает токен доступа JWT, токен обновления, время истечения срока действия и предоставленные области действия
3. API-доступ :
   • То же, что и в подходе Direct Connect

Модели баз данных

Сервер MCP использует SQLAlchemy ORM со следующими ключевыми моделями:

1. Модель пользователя :
   • Сохраняет информацию о пользователе с адресом электронной почты, именем пользователя и хешированным паролем.
   • Включает логические флаги для статуса учетной записи (is_active, is_superuser)
   • Связано с воспоминаниями через отношение «один ко многим»
2. Модель памяти с векторным хранением :
   • Использует расширение pgvector для хранения и запроса векторных вложений (1536 измерений)
   • Поддерживает текстовый контент с возможностью шифрования.
   • Включает элементы управления разрешениями (частные/публичные)
   • Поддерживает даты истечения срока действия для ограниченных по времени воспоминаний
   • Связан с пользователями через связь внешнего ключа
3. Модели OAuth :
   • OAuthClient : хранит данные клиентского приложения, включая client_id, client_secret, URI перенаправления и авторизованные области действия.
   • AuthorizationCode : управляет временными кодами авторизации с поддержкой PKCE.
   • Токен : хранит токены доступа и обновления с отслеживанием срока действия.

Система использует Alembic для миграции баз данных, обеспечивая управление версиями схем и простоту обновлений.

Система управления памятью

Основная функциональность Picard MCP сосредоточена вокруг управления памятью с помощью следующих компонентов:

1. Память хранения :
   • Воспоминания хранятся в виде текста с соответствующими метаданными.
   • Векторные вложения (с использованием модели text-embedding-3-small) обеспечивают возможности семантического поиска
   • Разрешения контролируют, кто может получить доступ к каждому воспоминанию.
   • Временные метки отслеживают создание, изменение и истечение срока действия
   • Текст памяти шифруется при хранении, а метаданные остаются доступными для поиска
   • Все идентификаторы используют формат UUID вместо последовательных целых чисел для масштабируемости.
   • Каждая память преобразуется в векторное вложение с использованием модели вложения OpenAI.
   • Встраивание позволяет осуществлять семантический поиск и сопоставление сходств
   • PostgreSQL с расширением pgvector обеспечивает эффективное хранение и извлечение векторов
2. Управление разрешениями :
   • Каждое воспоминание имеет уровень доступа (частный или публичный)
   • Личные воспоминания доступны только владельцу.
   • Публичные воспоминания могут быть доступны другим пользователям для запросов персон.
   • Система разработана с возможностью расширения для будущих типов разрешений (например, для статистического/агрегированного использования)
   • Доступ к общим воспоминаниям могут получить определенные пользователи или группы.
   • Владелец памяти может изменить разрешения в любое время.
3. Восстановление памяти :
   • Пользователи могут извлекать собственные воспоминания с помощью функций фильтрации и сортировки.
   • Семантический поиск позволяет находить воспоминания на основе смысла, а не только ключевых слов.
   • Вектор сходства (косинус) позволяет находить связанные воспоминания в базе данных.
   • Возвращаются первые N наиболее похожих воспоминаний на основе релевантности запроса
   • Проверка разрешений гарантирует, что пользователи имеют доступ только к авторизованным воспоминаниям.
4. Интеграция LLM :
   • Воспоминания могут использоваться в качестве контекста для запросов LLM.
   • Пользователи могут создавать персоны на основе своих публичных воспоминаний.
   • Другие пользователи могут запрашивать эти персоны, чтобы получать ответы, основанные на воспоминаниях.
   • Система автоматически управляет контекстным управлением и выполняет инжиниринг подсказок.

Основные характеристики

Возможности сервера MCP

• Аутентификация OAuth 2.0 :
  • Поток кода авторизации с PKCE для повышения безопасности
  • Система разрешений на основе области действия ( memories:read , memories:write , memories:admin )
  • Управление токенами с поддержкой обновления токенов
  • Регистрация и управление клиентами
• Управление памятью :
  • Создавайте, читайте, обновляйте и удаляйте воспоминания
  • Встраивание векторов для семантического поиска
  • Контроль доступа на основе разрешений
  • Пакетные операции для эффективного управления памятью
• Управление пользователями :
  • Регистрация и аутентификация пользователя
  • Управление профилем и настройки
  • Отслеживание активности и аналитика
  • Административные элементы управления системой
• Интеграция ИИ :
  • Интеграция API OpenAI для встраивания и запросов LLM
  • Создание персоны на основе воспоминаний пользователя
  • Обработка запросов с учетом контекста
  • Настраиваемые параметры и настройки ИИ

Возможности клиента Django

• Пользовательский интерфейс :
  • Чистый, адаптивный дизайн для настольных компьютеров и мобильных устройств
  • Интуитивно понятный интерфейс управления памятью
  • Расширенные возможности поиска и фильтрации
  • Интерфейс создания персоны и запросов
• Реализация клиента OAuth :
  • Безопасное хранение и управление токенами
  • Автоматическое обновление токена
  • Доступность функций на основе области применения
  • Обработка ошибок и восстановление
• Инструменты памяти :
  • Создание памяти с поддержкой форматированного текста
  • Пакетный импорт и экспорт
  • Интерфейс управления разрешениями
  • Тегирование и категоризация

Интерфейс МКП

Ресурсы МКП

• Ресурс памяти : memories://{memory_id}
  • Возвращает содержимое определенной памяти с проверкой разрешений.
  • Параметры: memory_id (UUID)
  • Ответ: Содержимое памяти с метаданными
• Ресурс воспоминаний пользователя : users://{user_id}/memories
  • Возвращает список воспоминаний для определенного пользователя с проверкой разрешений.
  • Параметры: user_id (UUID), необязательные фильтры
  • Ответ: Список сводок памяти

Инструменты МКП

• Инструмент «Отправить память» : создает новое воспоминание
  • Параметры: текст (строка), разрешение (строка)
  • Возвращает: Созданные данные памяти с UUID
• Инструмент обновления памяти : обновляет существующую память.
  • Параметры: memory_id (UUID), текст (строка)
  • Возвращает: обновленные данные памяти.
• Инструмент удаления памяти : удаляет память.
  • Параметры: memory_id (UUID)
  • Возврат: Подтверждение успеха
• Инструмент запроса памяти : выполняет семантический поиск в воспоминаниях.
  • Параметры: запрос (строка), предел (целое число)
  • Возвращает: Список соответствующих воспоминаний.
• Запрос пользователя : запрашивает личность пользователя на основе воспоминаний.
  • Параметры: user_id (UUID), запрос (строка)
  • Возвращает: ответ, основанный на воспоминаниях пользователя.

Конечные точки API

Конечные точки OAuth

• Регистрация клиента : /register
  • Метод: ПОСТ
  • Описание: Регистрация нового клиента OAuth.
  • Запрос: данные клиента (идентификатор, секрет, URI перенаправления, области действия)
  • Ответ: Учетные данные клиента и регистрационная информация
• Авторизация : /authorize
  • Метод: ПОЛУЧИТЬ
  • Описание: Инициировать процесс авторизации OAuth
  • Параметры: response_type, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method
  • Ответ: Перенаправляет клиенту с кодом авторизации
• Обмен токенами : /token
  • Метод: ПОСТ
  • Описание: Обмен кода авторизации на токены
  • Запрос: grant_type, code, redirect_uri, client_id, client_secret, code_verifier
  • Ответ: токен доступа, токен обновления, срок действия и информация о области действия

Конечные точки памяти

• Получить воспоминания : /api/tools (инструмент: get_memories )
  • Метод: ПОСТ
  • Описание: Извлечение воспоминаний с возможностью фильтрации.
  • Аутентификация: токен на предъявителя
  • Запрос: Необязательные параметры фильтра (user_id, разрешение, срок действия)
  • Ответ: Список воспоминаний, доступных пользователю.
  • Пример запроса:
    { "tool": "get_memories", "data": { "user_id": "550e8400-e29b-41d4-a716-446655440000", "permission": "private" } }
• Отправить память : /api/tools (инструмент: submit_memory )
  • Метод: ПОСТ
  • Описание: Создайте новое воспоминание.
  • Аутентификация: токен на предъявителя
  • Запрос: текст памяти, уровень разрешения и дата истечения срока действия (формат ISO 8601, например, «2025-12-31T23:59:59Z»)
  • Ответ: Созданные данные памяти, включая идентификатор UUID.
  • Пример запроса:
    { "tool": "submit_memory", "data": { "text": "This is my memory content", "permission": "private" } }
• Извлечь воспоминания : /api/tools (инструмент: retrieve_memories )
  • Метод: ПОСТ
  • Описание: Получить все воспоминания для аутентифицированного пользователя.
  • Аутентификация: токен на предъявителя
  • Ответ: Список объектов памяти с идентификаторами UUID
  • Пример запроса:
    { "tool": "retrieve_memories", "data": {} }
• Обновление памяти : /api/tools (инструмент: update_memory )
  • Метод: ПОСТ
  • Описание: Обновление существующей памяти.
  • Аутентификация: токен на предъявителя
  • Запрос: идентификатор памяти, обновленное содержимое и опционально обновленная дата истечения срока действия (формат ISO 8601)
  • Ответ: Обновленные данные памяти.
  • Пример запроса:
    { "tool": "update_memory", "data": { "memory_id": "550e8400-e29b-41d4-a716-446655440000", "text": "Updated memory content", "expiration_date": "2026-01-01T00:00:00Z" } }
• Изменить разрешения : /api/tools (инструмент: modify_permissions )
  • Метод: ПОСТ
  • Описание: Обновление уровня разрешений памяти.
  • Аутентификация: токен на предъявителя
  • Запрос: UUID памяти и новый уровень разрешений
  • Ответ: Обновленные данные памяти.
  • Пример запроса:
    { "tool": "modify_permissions", "data": { "memory_id": "550e8400-e29b-41d4-a716-446655440000", "permission": "public" } }
• Запрос пользователя : /api/tools (tool: query_user )
  • Метод: ПОСТ
  • Описание: Запрос персоны пользователя на основе воспоминаний (публичная для других пользователей, публичная+личная для себя)
  • Аутентификация: токен на предъявителя
  • Запрос: UUID пользователя и запрос запроса
  • Ответ: JSON, содержащий неистекшие воспоминания, либо все действительные воспоминания, либо первые N наиболее похожих на запрос
  • Ответ: ответ, сгенерированный искусственным интеллектом на основе воспоминаний пользователя.
  • Пример запроса:
    { "tool": "query_user", "data": { "user_id": "550e8400-e29b-41d4-a716-446655440000", "prompt": "What are your thoughts on artificial intelligence?" } }

Настройка и развертывание

Предпосылки

• Docker и Docker Compose
• Питон 3.10+
• API-ключ OpenAI

Полное руководство по настройке

1. Клонируйте репозиторий:
   git clone https://github.com/yourusername/picard_mcp.git cd picard_mcp
2. Создайте файлы среды для обоих компонентов:
   # For MCP server cp mcp_server/.env.example mcp_server/.env # For Django client cp django_client/.env.example django_client/.env
3. Отредактируйте файлы среды, чтобы задать свою конфигурацию:
   • В mcp_server/.env : задайте учетные данные базы данных, ключ API OpenAI и учетные данные администратора.
   • В django_client/.env : установите учетные данные базы данных и настройки OAuth.
4. Запустите службы с помощью Docker Compose:
   docker-compose up -d
   Это запустит следующие службы:
   • db-mcp : База данных PostgreSQL для сервера MCP
   • db-django : База данных PostgreSQL для клиента Django
   • mcp_server : MCP-сервер, работающий на http://localhost:8001
   • django_client : Клиент Django, работающий на http://localhost:8000
5. Создайте пользователя-администратора для сервера MCP:
   docker-compose exec mcp_server python scripts/create_admin_user.py
   Это создаст пользователя-администратора с учетными данными, указанными в переменных среды.
6. Зарегистрируйте клиент Django на сервере MCP:
   docker-compose exec django_client python register_oauth_client.py
   Это зарегистрирует клиент Django на сервере MCP и обновит файл .env клиента Django с использованием учетных данных клиента.
7. Доступ к приложениям:
   • MCP-сервер: http://localhost:8001
   • Клиент Django: http://localhost:8000
8. Создайте учетную запись пользователя в клиенте Django и начните использовать приложение.

Первоначальное тестирование

Чтобы проверить правильность работы вашей настройки, выполните следующие тесты:

1. Тесты сервера MCP :
   docker-compose exec mcp_server python -m pytest
   Это запустит все модульные тесты для сервера MCP, включая конечные точки OAuth, функции администрирования и управление памятью.
2. Тесты клиента Django :
   docker-compose exec django_client python manage.py test
   Это позволит протестировать интеграцию клиента Django с сервером MCP.
3. Ручное тестирование :
   • Создайте учетную запись пользователя в клиенте Django по адресу http://localhost:8000/register
   • Авторизуйтесь и подключитесь к серверу MCP через OAuth
   • Создавайте, извлекайте и управляйте воспоминаниями
   • Тестирование функциональности семантического поиска

Соображения безопасности

Защита данных

• Содержимое текстовой памяти шифруется при хранении с помощью симметричного шифрования Python Fernet (AES-128 в режиме CBC с дополнением PKCS7), при этом метаданные остаются доступными для поиска.
• Персональные данные (PII) защищены с помощью шифрования текстовых полей.
• Срок действия токенов доступа составляет 1 час, что позволяет ограничить риск
• Токены обновления долговечны, но используют ротацию: каждое использование генерирует новый токен обновления и делает старый недействительным.
• Токены OAuth надежно хранятся в базе данных PostgreSQL клиента Django.

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

Все идентификаторы в системе используют формат UUID v4 вместо последовательных целых чисел по нескольким причинам:

1. Безопасность : UUID не раскрывают системную информацию или количество записей.
2. Масштабируемость : универсальные уникальные идентификаторы (UUID) могут генерироваться без координации с базой данных, что позволяет использовать распределенные системы.
3. Невозможность угадывания : UUID практически невозможно угадать, что предотвращает атаки методом перечисления.
4. Согласованность : использование UUID во всей системе упрощает интеграцию с другими службами.

Все идентификаторы в API (user_id, memory_id, client_id и т. д.) должны быть в формате UUID.

Лучшие практики OAuth

• Все коммуникации OAuth должны использовать HTTPS в производственных средах.
• Коды авторизации являются одноразовыми и имеют короткий срок действия (максимум 5 минут).
• PKCE требуется для всех клиентов, даже конфиденциальных, для глубокой защиты
• Токены обновления долговечны, но могут быть отозваны пользователями или администраторами.
• Система ведет черный список токенов для отозванных токенов.

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

API-документация

Сервер MCP включает документацию Swagger/OpenAPI для всех конечных точек:

• Доступ к пользовательскому интерфейсу Swagger по адресу /docs при работающем сервере.
• Спецификация OpenAPI доступна по адресу /openapi.json
• Все конечные точки API полностью документированы со схемами запросов/ответов и примерами.

Дополнительные файлы документации

• TESTING.md : Полное руководство по тестированию приложения
  • Описывает все реализованные тесты и их цели
  • Инструкции по запуску тестов локально и в CI/CD
  • Документирует охват тестированием и определяет области, требующие дополнительного тестирования.
• DEBUGGING.md : отслеживает проблемы и их решения
  • Регистрирует известные ошибки, которые еще не исправлены.
  • Документы ранее решенных ошибок и их решения
  • Предоставляет руководство по устранению распространенных неполадок
• PLANNING.md : Отслеживает распределение задач, необходимых для реализации сайта.
  • Перечисляет задачи и подзадачи, необходимые для реализации сайта
  • Документирует, выполнено ли задание, с помощью флажка

Развертывание

Этот проект включает docker-compose.yml для локальной разработки и render.yaml для развертывания в Render. Та же кодовая база работает как локально в контейнерах Docker, так и при развертывании в облачных сервисах Render.

Развертывание сервера MCP

1. Развертывание Docker (рекомендуется для производства):
   docker-compose up -d
   Конфигурация Docker Compose включает в себя:
   • Конфигурация сети для межконтейнерной связи
   • Монтирование томов для постоянного хранения данных
   • Конфигурация переменных среды из файлов .env
   • Сопоставление портов (8000 для клиента Django, 8001 для сервера MCP)
   • Проверки работоспособности зависимостей служб
2. Развертывание Render Cloud : используйте прилагаемый проект render.yaml для развертывания в Render.

Лицензия

Массачусетский технологический институт