Servidor MCP de Picard

Descripción general

Picard MCP es un sistema completo de gestión de memoria basado en el estándar del Protocolo de Contexto de Modelo (MCP) . Consta de dos componentes principales: un servidor MCP que proporciona servicios seguros de almacenamiento y recuperación de memoria, y una aplicación cliente Django que muestra cómo integrarse con el servidor MCP. El sistema permite a los usuarios almacenar, recuperar y gestionar sus memorias, controlando los permisos de acceso y permitiendo la búsqueda semántica y consultas basadas en IA basadas en las memorias almacenadas.

Cumplimiento de MCP

Esta implementación sigue el estándar del Protocolo de Contexto de Modelo (MCP), que permite a las aplicaciones LLM interactuar con el servidor de forma estandarizada. El servidor MCP expone:

• Recursos : puntos finales de solo lectura que proporcionan datos a los LLM (contenido de memoria)

• Herramientas : puntos finales funcionales que realizan acciones (creación de memoria, actualizaciones, consultas)

• Autenticación : implementación de OAuth 2.0 para acceso seguro a recursos protegidos

Componentes clave

1. Servidor MCP : una implementación basada en FastAPI del Protocolo de contexto de modelo que proporciona:

   • Autenticación y autorización OAuth 2.0 con compatibilidad con PKCE

   • Almacenamiento de memoria con incrustaciones vectoriales

   • Control de acceso a memoria basado en permisos

   • Integración de LLM para consultas basadas en memoria

2. Cliente Django : una aplicación web que demuestra la integración con el servidor MCP:

   • Registro y autenticación de usuarios

   • Implementación del cliente OAuth 2.0

   • Interfaz de usuario de creación, recuperación y gestión de memoria

   • Interfaz de consulta basada en personas

Arquitectura del sistema

Arquitectura general

El sistema Picard MCP sigue una arquitectura cliente-servidor con los siguientes componentes:

1. Servidor MCP : servicio central de backend que gestiona el almacenamiento de memoria, la recuperación y las operaciones de IA

   • Creado con FastAPI (FastMCP) para un alto rendimiento y compatibilidad asincrónica

   • Utiliza PostgreSQL con extensión pgvector para almacenamiento de vectores y búsqueda semántica

   • Implementa modelos de datos para usuarios, memorias (con incrustaciones vectoriales), clientes OAuth y tokens

   • Utiliza SQLAlchemy ORM con migraciones de Alembic para la gestión de bases de datos

   • Implementa OAuth 2.0 para autenticación y autorización seguras

   • Se integra con la API de OpenAI para incrustaciones de memoria (text-embedding-3-small)

   • Utiliza LangChain para operaciones LLM cuando está disponible

   • Proporciona modos de operación con estado y sin estado

   • Admite transporte HTTP transmitible para una mejor escalabilidad

2. Cliente Django : aplicación web que demuestra la integración con el servidor MCP

   • Proporciona registro de usuarios, autenticación y gestión de perfiles.

   • Implementa el cliente OAuth 2.0 para una comunicación segura con el servidor MCP

   • Ofrece una interfaz fácil de usar para la gestión y consulta de memoria.

   • Utiliza su propia base de datos PostgreSQL separada del servidor MCP

3. Infraestructura Docker : Implementación en contenedores para una fácil configuración y escalabilidad

   • Contenedores separados para el servidor MCP (puerto 8001), el cliente Django (puerto 8000) y las bases de datos PostgreSQL

   • Redes configuradas para una comunicación segura entre contenedores

   • Montaje de volumen para almacenamiento de datos persistentes

   • Compatible tanto con la implementación local de Docker como con la implementación en la nube de Render

Enfoques de autenticación

El sistema ofrece dos enfoques principales de autenticación:

1. Conexión directa con el flujo de tokens de contexto de usuario (recomendado)

Este enfoque simplificado permite a los usuarios autenticarse solo una vez con el cliente Django, evitando la necesidad de una autenticación separada del servidor MCP:

1. Registro de cliente :

   • El cliente Django se registra en el servidor MCP utilizando el punto final /api/admin/clients/register

   • El registro requiere autenticación de administrador e incluye el nombre del cliente, las URI de redireccionamiento y los alcances solicitados.

   • El servidor MCP emite un ID de cliente basado en UUID y un secreto de cliente criptográficamente seguro

   • Las credenciales del cliente deben almacenarse de forma segura y nunca exponerse en el código del lado del cliente.

2. Flujo de autenticación de usuario :

   • El usuario se autentica únicamente con el cliente Django

   • Cuando el usuario inicia la conexión al servidor MCP, el cliente Django realiza una solicitud del lado del servidor al punto final /api/user-tokens/user-token del MCP

   • La solicitud incluye:

     • Credenciales del cliente (client_id y client_secret)

     • Información del usuario (nombre de usuario y correo electrónico)

     • Opción para crear usuario si no existe

   • El servidor MCP verifica las credenciales del cliente y encuentra o crea un usuario correspondiente.

   • El servidor MCP emite tokens de acceso y actualización para el usuario

   • El cliente de Django almacena de forma segura estos tokens y los utiliza para solicitudes de API

3. Acceso API :

   • El cliente incluye el token de acceso en el encabezado de autorización ( Authorization: Bearer {token} ) para todas las solicitudes de API

   • El servidor MCP valida la firma del token, la expiración y las reclamaciones de audiencia.

   • El servidor MCP aplica permisos basados en el alcance para cada punto final

   • Cuando el token de acceso expira, el cliente utiliza el token de actualización para obtener uno nuevo

4. Características de seguridad :

   • Sólo los clientes confidenciales pueden utilizar este método, lo que proporciona seguridad de servidor a servidor.

   • Las credenciales del cliente se verifican para cada solicitud de token

   • Los tokens se incluyen en la lista negra después de su uso para evitar ataques de repetición.

   • Rotación de uso de tokens de actualización: cada uso genera un nuevo token de actualización e invalida el anterior

2. Flujo de código de autorización estándar de OAuth 2.0 con PKCE (heredado)

El sistema también es compatible con el flujo de código de autorización OAuth 2.0 estándar con PKCE para mayor seguridad, conforme a los estándares RFC 6749 y RFC 7636. Este enfoque requiere que los usuarios se autentiquen tanto con el cliente como con el servidor MCP:

1. Flujo de autorización :

   • El usuario inicia el inicio de sesión a través del cliente Django

   • El cliente genera un parámetro state aleatorio criptográficamente seguro para la protección CSRF

   • El cliente genera un code_verifier PKCE aleatorio y deriva code_challenge utilizando SHA-256

   • El cliente redirecciona al punto final /authorize del servidor MCP con:

     • response_type=code

     • client_id (formato UUID)

     • redirect_uri

     • scope (lista separada por espacios, p. ej., memories:read memories:write )

     • state (para protección CSRF)

     • Parámetros PKCE ( code_challenge y code_challenge_method=S256 )

   • El servidor MCP autentica al usuario (si aún no está autenticado)

   • El servidor MCP valida todos los parámetros y redirecciona al cliente con un código de autorización de corta duración.

2. Intercambio de tokens :

   • El cliente verifica que el parámetro state devuelto coincida con el enviado en la solicitud de autorización

   • El cliente intercambia el código de autorización para acceder y actualizar tokens a través del punto final /token

   • El servidor MCP emite un token de acceso JWT, un token de actualización, un tiempo de expiración y alcances otorgados

3. Acceso API :

   • Igual que en el enfoque de Conexión Directa

Modelos de bases de datos

El servidor MCP utiliza SQLAlchemy ORM con los siguientes modelos clave:

1. Modelo de usuario :

   • Almacena información del usuario con correo electrónico, nombre de usuario y contraseña cifrada.

   • Incluye indicadores booleanos para el estado de la cuenta (is_active, is_superuser)

   • Vinculado a los recuerdos a través de una relación de uno a muchos

2. Modelo de memoria con almacenamiento vectorial :

   • Utiliza la extensión pgvector para almacenar y consultar incrustaciones de vectores (1536 dimensiones)

   • Admite contenido de texto con cifrado opcional

   • Incluye controles de permisos (privados/públicos)

   • Admite fechas de vencimiento para memorias con límite de tiempo

   • Asociado con los usuarios a través de una relación de clave externa

3. Modelos OAuth :

   • OAuthClient : almacena detalles de la aplicación cliente, incluidos client_id, client_secret, URI de redireccionamiento y ámbitos autorizados

   • Código de autorización : administra códigos de autorización temporales con soporte PKCE

   • Token : almacena tokens de acceso y actualización con seguimiento de vencimiento

El sistema utiliza Alembic para las migraciones de bases de datos, lo que garantiza el control de versiones del esquema y actualizaciones fáciles.

Sistema de gestión de memoria

La funcionalidad principal de Picard MCP gira en torno a la gestión de memoria con los siguientes componentes:

1. Almacenamiento de memoria :

   • Los recuerdos se almacenan como texto con metadatos asociados.

   • Las incrustaciones vectoriales (que utilizan el modelo text-embedding-3-small) habilitan capacidades de búsqueda semántica

   • Los permisos controlan quién puede acceder a cada memoria

   • Las marcas de tiempo rastrean la creación, modificación y vencimiento

   • El texto de la memoria se cifra en reposo mientras que los metadatos siguen siendo buscables

   • Todos los identificadores utilizan el formato UUID en lugar de números enteros secuenciales para mayor escalabilidad.

   • Cada memoria se convierte en una incrustación vectorial utilizando el modelo de incrustación de OpenAI

   • Las incrustaciones permiten la búsqueda semántica y la coincidencia de similitudes

   • PostgreSQL con la extensión pgvector proporciona un almacenamiento y recuperación de vectores eficiente

2. Gestión de permisos :

   • Cada memoria tiene un nivel de permiso (privado o público)

   • Los recuerdos privados sólo son accesibles al propietario.

   • Otros usuarios pueden acceder a las memorias públicas para realizar consultas personales.

   • El sistema está diseñado para ser extensible para futuros tipos de permisos (por ejemplo, para uso estadístico/agregado).

   • Los recuerdos compartidos pueden ser accedidos por usuarios o grupos específicos

   • El propietario de la memoria puede modificar los permisos en cualquier momento.

3. Recuperación de memoria :

   • Los usuarios pueden recuperar sus propios recuerdos con opciones de filtrado y clasificación.

   • La búsqueda semántica permite encontrar recuerdos basándose en el significado, no solo en palabras clave.

   • La similitud vectorial (coseno) permite encontrar memorias relacionadas en la base de datos

   • Se devuelven los N recuerdos más similares según la relevancia de la consulta

   • Las comprobaciones de permisos garantizan que los usuarios solo accedan a las memorias autorizadas

4. Integración LLM :

   • Los recuerdos se pueden utilizar como contexto para las consultas LLM

   • Los usuarios pueden crear personajes basados en sus recuerdos públicos.

   • Otros usuarios pueden consultar a estas personas para obtener respuestas basadas en los recuerdos.

   • El sistema gestiona automáticamente la gestión del contexto y la ingeniería de indicaciones.

Características principales

Características del servidor MCP

• Autenticación OAuth 2.0 :

  • Flujo de código de autorización con PKCE para una mayor seguridad

  • Sistema de permisos basado en alcance ( memories:read , memories:write , memories:admin )

  • Gestión de tokens con soporte para tokens de actualización

  • Registro y gestión de clientes

• Gestión de memoria :

  • Crear, leer, actualizar y eliminar recuerdos

  • Incorporación de vectores para búsqueda semántica

  • Control de acceso basado en permisos

  • Operaciones por lotes para una gestión eficiente de la memoria

• Gestión de usuarios :

  • Registro y autenticación de usuarios

  • Gestión y configuración de perfiles

  • Seguimiento y análisis de actividades

  • Controles de administración para la gestión del sistema

• Integración de IA :

  • Integración de API de OpenAI para incrustaciones y consultas LLM

  • Creación de personajes basada en los recuerdos del usuario

  • Procesamiento de consultas según el contexto

  • Parámetros y configuraciones de IA personalizables

Características del cliente Django

• Interfaz de usuario :

  • Diseño limpio y responsivo para computadoras de escritorio y dispositivos móviles.

  • Interfaz intuitiva de gestión de memoria

  • Opciones avanzadas de búsqueda y filtrado

  • Interfaz de creación y consulta de personajes

• Implementación del cliente OAuth :

  • Almacenamiento y gestión seguros de tokens

  • Actualización automática del token

  • Disponibilidad de funciones según el alcance

  • Manejo y recuperación de errores

• Herramientas de memoria :

  • Creación de memoria con soporte de texto enriquecido

  • Importación y exportación por lotes

  • Interfaz de gestión de permisos

  • Etiquetado y categorización

Interfaz MCP

Recursos de MCP

• Recurso de memoria : memories://{memory_id}

  • Devuelve el contenido de una memoria específica con comprobaciones de permisos

  • Parámetros: memory_id (UUID)

  • Respuesta: Contenido de memoria con metadatos

• Recurso de memorias de usuario : users://{user_id}/memories

  • Devuelve una lista de recuerdos para un usuario específico con comprobaciones de permisos

  • Parámetros: user_id (UUID), filtros opcionales

  • Respuesta: Lista de resúmenes de memoria

Herramientas MCP

• Herramienta de envío de memoria : crea una nueva memoria

  • Parámetros: texto (cadena), permiso (cadena)

  • Devuelve: Detalles de la memoria creada con UUID

• Herramienta de actualización de memoria : actualiza una memoria existente

  • Parámetros: memory_id (UUID), texto (cadena)

  • Devoluciones: Detalles de memoria actualizados

• Herramienta Eliminar memoria : elimina una memoria

  • Parámetros: memory_id (UUID)

  • Devoluciones: Confirmación de éxito

• Herramienta de consulta de memoria : realiza búsquedas semánticas en las memorias

  • Parámetros: consulta (cadena), límite (entero)

  • Devoluciones: Lista de recuerdos relevantes

• Consulta de usuario : consulta la personalidad de un usuario basándose en recuerdos

  • Parámetros: user_id (UUID), consulta (cadena)

  • Devoluciones: Respuesta basada en los recuerdos del usuario

Puntos finales de API

Puntos finales de OAuth

• Registro de cliente : /register

  • Método: POST

  • Descripción: Registrar un nuevo cliente OAuth

  • Solicitud: Detalles del cliente (ID, secreto, URI de redireccionamiento, alcances)

  • Respuesta: Credenciales del cliente e información de registro

• Autorización : /authorize

  • Método: GET

  • Descripción: Iniciar el flujo de autorización OAuth

  • Parámetros: tipo_de_respuesta, id_de_cliente, uri_de_redireccionamiento, alcance, estado, desafío_de_código, método_de_desafío_de_código

  • Respuesta: Redirecciona al cliente con código de autorización

• Intercambio de tokens : /token

  • Método: POST

  • Descripción: Código de autorización de intercambio de tokens

  • Solicitud: tipo_concesión, código, uri_redireccionamiento, id_cliente, secreto_cliente, verificador_código

  • Respuesta: Token de acceso, token de actualización, vencimiento e información de alcance

Puntos finales de memoria

• Obtener memorias : /api/tools (herramienta: get_memories )

  • Método: POST

  • Descripción: Recupera recuerdos con filtrado opcional

  • Autenticación: Token de portador

  • Solicitud: parámetros de filtro opcionales (id de usuario, permiso, estado de expiración)

  • Respuesta: Lista de memorias accesibles al usuario

  • Ejemplo de solicitud:

    { "tool": "get_memories", "data": { "user_id": "550e8400-e29b-41d4-a716-446655440000", "permission": "private" } }

• Enviar memoria : /api/tools (herramienta: submit_memory )

  • Método: POST

  • Descripción: Crea una nueva memoria

  • Autenticación: Token de portador

  • Solicitud: Texto de memoria, nivel de permiso y fecha de vencimiento (formato ISO 8601, p. ej., "2025-12-31T23:59:59Z")

  • Respuesta: Se crearon detalles de la memoria, incluido el identificador UUID

  • Ejemplo de solicitud:

    { "tool": "submit_memory", "data": { "text": "This is my memory content", "permission": "private" } }

• Recuperar recuerdos : /api/tools (herramienta: retrieve_memories )

  • Método: POST

  • Descripción: Obtener todos los recuerdos del usuario autenticado

  • Autenticación: Token de portador

  • Respuesta: Lista de objetos de memoria con identificadores UUID

  • Ejemplo de solicitud:

    { "tool": "retrieve_memories", "data": {} }

• Actualizar memoria : /api/tools (herramienta: update_memory )

  • Método: POST

  • Descripción: Actualizar una memoria existente

  • Autenticación: Token de portador

  • Solicitud: ID de memoria, contenido actualizado y fecha de vencimiento actualizada opcionalmente (formato ISO 8601)

  • Respuesta: Detalles de memoria actualizados

  • Ejemplo de solicitud:

    { "tool": "update_memory", "data": { "memory_id": "550e8400-e29b-41d4-a716-446655440000", "text": "Updated memory content", "expiration_date": "2026-01-01T00:00:00Z" } }

• Modificar permisos : /api/tools (herramienta: modify_permissions )

  • Método: POST

  • Descripción: Actualizar el nivel de permiso de memoria

  • Autenticación: Token de portador

  • Solicitud: UUID de memoria y nuevo nivel de permiso

  • Respuesta: Detalles de memoria actualizados

  • Ejemplo de solicitud:

    { "tool": "modify_permissions", "data": { "memory_id": "550e8400-e29b-41d4-a716-446655440000", "permission": "public" } }

• Consulta de usuario : /api/tools (herramienta: query_user )

  • Método: POST

  • Descripción: Consulta la personalidad de un usuario basándose en recuerdos (públicos para otros usuarios, públicos+privados para uno mismo)

  • Autenticación: Token de portador

  • Solicitud: UUID del usuario y solicitud de consulta

  • Respuesta: JSON que contiene memorias no vencidas, ya sean todas las memorias válidas o las N más similares a la consulta

  • Respuesta: Respuesta generada por IA basada en los recuerdos del usuario.

  • Ejemplo de solicitud:

    { "tool": "query_user", "data": { "user_id": "550e8400-e29b-41d4-a716-446655440000", "prompt": "What are your thoughts on artificial intelligence?" } }

Configuración e implementación

Prerrequisitos

• Docker y Docker Compose

• Python 3.10+

• Clave API de OpenAI

Guía de instalación completa

1. Clonar el repositorio:

   git clone https://github.com/yourusername/picard_mcp.git cd picard_mcp

2. Cree archivos de entorno para ambos componentes:

   # For MCP server cp mcp_server/.env.example mcp_server/.env # For Django client cp django_client/.env.example django_client/.env

3. Edite los archivos de entorno para establecer su configuración:

   • En mcp_server/.env : configure sus credenciales de base de datos, la clave de API de OpenAI y las credenciales de administrador

   • En django_client/.env : configure las credenciales de su base de datos y la configuración de OAuth

4. Inicie los servicios usando Docker Compose:

   docker-compose up -d

   Esto iniciará los siguientes servicios:

   • db-mcp : base de datos PostgreSQL para el servidor MCP

   • db-django : base de datos PostgreSQL para el cliente Django

   • mcp_server : servidor MCP que se ejecuta en http://localhost:8001

   • django_client : cliente de Django que se ejecuta en http://localhost:8000

5. Cree un usuario administrador para el servidor MCP:

   docker-compose exec mcp_server python scripts/create_admin_user.py

   Esto creará un usuario administrador con las credenciales especificadas en sus variables de entorno.

6. Registra el cliente Django con el servidor MCP:

   docker-compose exec django_client python register_oauth_client.py

   Esto registrará el cliente Django con el servidor MCP y actualizará el archivo .env del cliente Django con las credenciales del cliente.

7. Acceder a las aplicaciones:

   • Servidor MCP: http://localhost:8001

   • Cliente Django: http://localhost:8000

8. Cree una cuenta de usuario en el cliente Django y comience a utilizar la aplicación.

Pruebas iniciales

Para verificar que su configuración funciona correctamente, ejecute las siguientes pruebas:

1. Pruebas del servidor MCP :

   docker-compose exec mcp_server python -m pytest

   Esto ejecutará todas las pruebas unitarias para el servidor MCP, incluidos los puntos finales de OAuth, la funcionalidad de administración y la gestión de memoria.

2. Pruebas del cliente de Django :

   docker-compose exec django_client python manage.py test

   Esto probará la integración del cliente Django con el servidor MCP.

3. Pruebas manuales :

   • Cree una cuenta de usuario en el cliente Django en http://localhost:8000/register

   • Inicie sesión y conéctese al servidor MCP a través de OAuth

   • Crea, recupera y gestiona recuerdos

   • Pruebe la funcionalidad de búsqueda semántica

Consideraciones de seguridad

Protección de datos

• El contenido del texto de la memoria se cifra en reposo utilizando el cifrado simétrico Fernet de Python (AES-128 en modo CBC con relleno PKCS7) mientras que los metadatos siguen siendo buscables.

• La información de identificación personal (PII) está protegida mediante el cifrado del campo de texto

• Los tokens de acceso tienen un tiempo de vencimiento de 1 hora para limitar la exposición.

• Los tokens de actualización son de larga duración, pero utilizan rotación: cada uso genera un nuevo token de actualización e invalida el anterior.

• Los tokens OAuth se almacenan de forma segura en la base de datos PostgreSQL del cliente Django

Uso de UUID

Todos los identificadores del sistema utilizan el formato UUID v4 en lugar de números enteros secuenciales por varias razones:

1. Seguridad : Los UUID no exponen información del sistema ni registran recuentos

2. Escalabilidad : Los UUID se pueden generar sin coordinación de bases de datos, lo que permite sistemas distribuidos.

3. Imposibilidad de adivinar : los UUID son prácticamente imposibles de adivinar, lo que evita ataques de enumeración.

4. Coherencia : el uso de UUID en todo el sistema simplifica la integración con otros servicios

Todos los ID en la API (user_id, memory_id, client_id, etc.) deben estar en formato UUID.

Mejores prácticas de OAuth

• Toda comunicación OAuth debe utilizar HTTPS en entornos de producción

• Los códigos de autorización son de un solo uso y de corta duración (máximo 5 minutos).

• PKCE es necesario para todos los clientes, incluso los confidenciales, para una defensa en profundidad.

• Los tokens de actualización tienen una larga duración, pero los usuarios o administradores pueden revocarlos.

• El sistema mantiene una lista negra de tokens revocados

Documentación

Documentación de la API

El servidor MCP incluye documentación Swagger/OpenAPI para todos los puntos finales:

• Acceda a la interfaz de usuario de Swagger en /docs cuando el servidor esté en ejecución

• La especificación OpenAPI está disponible en /openapi.json

• Todos los puntos finales de la API están completamente documentados con esquemas de solicitud/respuesta y ejemplos.

Archivos de documentación adicional

• TESTING.md : Guía completa para probar la aplicación

  • Describe todas las pruebas implementadas y sus propósitos.

  • Instrucciones para ejecutar pruebas localmente y en CI/CD

  • Documenta la cobertura de las pruebas e identifica áreas que necesitan pruebas adicionales

• DEBUGGING.md : Realiza un seguimiento de los problemas y sus resoluciones

  • Registra errores conocidos que aún no se han solucionado

  • Documenta errores resueltos previamente y sus soluciones.

  • Proporciona orientación para la resolución de problemas comunes.

• PLANNING.md : Realiza un seguimiento del desglose de las tareas necesarias para implementar el sitio

  • Enumera las tareas y subtareas necesarias para implementar el sitio

  • Documenta si una tarea se ha completado con una casilla de verificación

Despliegue

Este proyecto incluye un docker-compose.yml para desarrollo local y un plano render.yaml para implementación en Render. El mismo código base funciona tanto localmente en contenedores Docker como al implementarse en servicios en la nube de Render.

Implementación del servidor MCP

1. Implementación de Docker (recomendado para producción):

   docker-compose up -d

   La configuración de Docker Compose incluye:

   • Configuración de red para la comunicación entre contenedores

   • Montajes de volumen para almacenamiento de datos persistentes

   • Configuración de variables de entorno desde archivos .env

   • Mapeos de puertos (8000 para el cliente Django, 8001 para el servidor MCP)

   • Comprobaciones de estado de las dependencias del servicio

2. Implementación de Render Cloud : use el plano render.yaml incluido para implementar en Render.

Licencia

Instituto Tecnológico de Massachusetts (MIT)