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

Обзор

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

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

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

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

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

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

Related MCP server: Memory Cache Server

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

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

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

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

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

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

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

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

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

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

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

Поток авторизации :
- Пользователь инициирует вход через клиент 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 проверяет все параметры и перенаправляет обратно клиенту с кратковременным кодом авторизации.
Обмен токенами :
- Клиент проверяет, соответствует ли возвращаемый параметр state параметру, отправленному в запросе авторизации.
- Клиент обменивается кодом авторизации на токены доступа и обновления через конечную точку /token
- Сервер MCP выдает токен доступа JWT, токен обновления, время истечения срока действия и предоставленные области действия
API-доступ :
- То же, что и в подходе Direct Connect

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

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

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

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

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

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

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

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

Клонируйте репозиторий:
git clone https://github.com/yourusername/picard_mcp.git cd picard_mcp
Создайте файлы среды для обоих компонентов:
# For MCP server cp mcp_server/.env.example mcp_server/.env # For Django client cp django_client/.env.example django_client/.env
Отредактируйте файлы среды, чтобы задать свою конфигурацию:
- В mcp_server/.env : задайте учетные данные базы данных, ключ API OpenAI и учетные данные администратора.
- В django_client/.env : установите учетные данные базы данных и настройки OAuth.
Запустите службы с помощью 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
Создайте пользователя-администратора для сервера MCP:
docker-compose exec mcp_server python scripts/create_admin_user.py
Это создаст пользователя-администратора с учетными данными, указанными в переменных среды.
Зарегистрируйте клиент Django на сервере MCP:
docker-compose exec django_client python register_oauth_client.py
Это зарегистрирует клиент Django на сервере MCP и обновит файл .env клиента Django с использованием учетных данных клиента.
Доступ к приложениям:
- MCP-сервер: http://localhost:8001
- Клиент Django: http://localhost:8000
Создайте учетную запись пользователя в клиенте Django и начните использовать приложение.

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

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

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

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

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

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

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

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

Безопасность : UUID не раскрывают системную информацию или количество записей.
Масштабируемость : универсальные уникальные идентификаторы (UUID) могут генерироваться без координации с базой данных, что позволяет использовать распределенные системы.
Невозможность угадывания : UUID практически невозможно угадать, что предотвращает атаки методом перечисления.
Согласованность : использование 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

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

Лицензия

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

MCP Server