[{"_1":2,"_381":-5,"_382":-5},"loaderData",{"_3":4,"_22":23,"_292":293},"root",{"_5":6,"_7":8},"toasts",[],"visitor",{"_9":10,"_11":12},"viewportWidth",1280,"visitorSession",{"_13":14,"_16":17,"_18":-5,"_19":20,"_21":-5},"attributes",[15],"bot","id",22248096,"membership","referenceId","019a3c9b-43cc-72d8-8c00-496521d6e6ee","userAccount","routes/_public/mcp/servers/~namespace/~slug/_pages/_layout",{"_24":25,"_81":-5,"_82":39,"_27":83,"_209":210,"_291":196},"availableLocales",[26,39,46,53,60,67,74],{"_27":28,"_35":36,"_37":38},"mcpServer",{"_29":30,"_31":32,"_33":34},"description","Eine Django-basierte Implementierung des Model Context Protocol (MCP) zur Verwaltung politischer Präferenzen und Zukunftsvisionen.","displayName","MCP-Server","readme","# Picard MCP Server\n\n## Überblick\n\nPicard MCP ist ein umfassendes Speicherverwaltungssystem, das auf dem [Model Context Protocol (MCP)](https://modelcontextprotocol.io) -Standard basiert. Es besteht aus zwei Hauptkomponenten: einem MCP-Server, der sichere Speicherspeicher- und -abrufdienste bereitstellt, und einer Django-Client-Anwendung, die die Integration mit dem MCP-Server demonstriert. Das System ermöglicht Benutzern das Speichern, Abrufen und Verwalten ihrer Speicher unter Kontrolle der Zugriffsberechtigungen und ermöglicht semantische Suche und KI-gestützte Abfragen basierend auf gespeicherten Speicherdaten.\n\n### MCP-Konformität\n\nDiese Implementierung folgt dem Model Context Protocol-Standard, der LLM-Anwendungen eine standardisierte Interaktion mit dem Server ermöglicht. Der MCP-Server stellt Folgendes bereit:\n\n* **Ressourcen** : Nur-Lese-Endpunkte, die Daten an LLMs (Speicherinhalte) liefern\n* **Tools** : Funktionale Endpunkte, die Aktionen ausführen (Speichererstellung, Aktualisierungen, Abfragen)\n* **Authentifizierung** : OAuth 2.0-Implementierung für sicheren Zugriff auf geschützte Ressourcen\n\n### Schlüsselkomponenten\n\n1. **MCP-Server** : Eine FastAPI-basierte Implementierung des Model Context Protocol, die Folgendes bietet:\n\n * OAuth 2.0-Authentifizierung und -Autorisierung mit PKCE-Unterstützung\n * Speicher mit Vektoreinbettungen\n * Berechtigungsbasierte Speicherzugriffskontrolle\n * LLM-Integration für speicherbasierte Abfragen\n\n2. **Django-Client** : Eine Webanwendung, die die Integration mit dem MCP-Server demonstriert:\n\n * Benutzerregistrierung und Authentifizierung\n * OAuth 2.0-Clientimplementierung\n * Benutzeroberfläche zum Erstellen, Abrufen und Verwalten von Speicher\n * Persona-basierte Abfrageschnittstelle\n\n## Systemarchitektur\n\n### Gesamtarchitektur\n\nDas Picard MCP-System folgt einer Client-Server-Architektur mit den folgenden Komponenten:\n\n1. **MCP-Server** : Zentraler Backend-Dienst, der Speicherspeicherung, -abruf und KI-Operationen übernimmt\n\n * Erstellt mit FastAPI (FastMCP) für hohe Leistung und asynchrone Unterstützung\n * Verwendet PostgreSQL mit pgvector-Erweiterung für Vektorspeicherung und semantische Suche\n * Implementiert Datenmodelle für Benutzer, Erinnerungen (mit Vektoreinbettungen), OAuth-Clients und Token\n * Verwendet SQLAlchemy ORM mit Alembic-Migrationen für die Datenbankverwaltung\n * Implementiert OAuth 2.0 für sichere Authentifizierung und Autorisierung\n * Integriert mit OpenAI API für Speichereinbettungen (text-embedding-3-small)\n * Verwendet LangChain für LLM-Operationen, sofern verfügbar\n * Bietet sowohl zustandsbehaftete als auch zustandslose Betriebsmodi\n * Unterstützt streambaren HTTP-Transport für bessere Skalierbarkeit\n\n2. **Django-Client** : Webanwendung, die die Integration mit dem MCP-Server demonstriert\n\n * Bietet Benutzerregistrierung, Authentifizierung und Profilverwaltung\n * Implementiert OAuth 2.0-Client für die sichere Kommunikation mit dem MCP-Server\n * Bietet eine benutzerfreundliche Oberfläche für Speicherverwaltung und Abfragen\n * Verwendet eine eigene PostgreSQL-Datenbank, getrennt vom MCP-Server\n\n3. **Docker-Infrastruktur** : Containerisierte Bereitstellung für einfache Einrichtung und Skalierung\n\n * Separate Container für MCP-Server (Port 8001), Django-Client (Port 8000) und PostgreSQL-Datenbanken\n * Konfiguriertes Netzwerk für sichere Kommunikation zwischen Containern\n * Volume-Mounting für dauerhafte Datenspeicherung\n * Kompatibel sowohl mit der lokalen Docker-Bereitstellung als auch mit der Render-Cloud-Bereitstellung\n\n### Authentifizierungsansätze\n\nDas System bietet zwei Hauptauthentifizierungsansätze:\n\n#### 1. Direktverbindung mit User Context Token Flow (empfohlen)\n\nDieser vereinfachte Ansatz ermöglicht es Benutzern, sich nur einmal beim Django-Client zu authentifizieren, wodurch die Notwendigkeit einer separaten MCP-Serverauthentifizierung vermieden wird:\n\n1. **Kundenregistrierung** :\n\n * Der Django-Client registriert sich beim MCP-Server über den Endpunkt `/api/admin/clients/register`\n * Die Registrierung erfordert eine Administratorauthentifizierung und umfasst den Clientnamen, Umleitungs-URIs und die angeforderten Bereiche.\n * Der MCP-Server gibt eine UUID-basierte Client-ID und ein kryptografisch sicheres Client-Geheimnis aus\n * Client-Anmeldeinformationen sollten sicher gespeichert und niemals im clientseitigen Code offengelegt werden\n\n2. **Ablauf der Benutzerauthentifizierung** :\n\n * Der Benutzer authentifiziert sich nur mit dem Django-Client\n * Wenn der Benutzer eine Verbindung zum MCP-Server initiiert, sendet der Django-Client eine serverseitige Anfrage an den Endpunkt `/api/user-tokens/user-token` des MCP.\n * Die Anfrage umfasst:\n * Client-Anmeldeinformationen (Client-ID und Client-Geheimnis)\n * Benutzerinformationen (Benutzername und E-Mail)\n * Option zum Erstellen eines Benutzers, falls nicht vorhanden\n * Der MCP-Server überprüft die Client-Anmeldeinformationen und findet oder erstellt einen entsprechenden Benutzer\n * Der MCP-Server stellt Zugriffs- und Aktualisierungstoken für den Benutzer aus\n * Der Django-Client speichert diese Token sicher und verwendet sie für API-Anfragen\n\n3. **API-Zugriff** :\n\n * Der Client schließt das Zugriffstoken in den Autorisierungsheader ( `Authorization: Bearer {token}` ) für alle API-Anfragen ein\n * Der MCP-Server validiert die Token-Signatur, das Ablaufdatum und die Zielgruppenansprüche\n * Der MCP-Server erzwingt bereichsbasierte Berechtigungen für jeden Endpunkt\n * Wenn das Zugriffstoken abläuft, verwendet der Client das Aktualisierungstoken, um ein neues zu erhalten\n\n4. **Sicherheitsfunktionen** :\n\n * Nur vertrauliche Clients können diese Methode verwenden, wodurch Server-zu-Server-Sicherheit gewährleistet wird\n * Die Client-Anmeldeinformationen werden bei jeder Token-Anforderung überprüft\n * Token werden nach der Verwendung auf die schwarze Liste gesetzt, um Replay-Angriffe zu verhindern\n * Rotation der Aktualisierungstoken: Jede Verwendung generiert ein neues Aktualisierungstoken und macht das alte ungültig\n\n#### 2. Standard-OAuth 2.0-Autorisierungscode-Flow mit PKCE (Legacy)\n\nDas System unterstützt außerdem den standardmäßigen OAuth 2.0-Autorisierungscode-Flow mit PKCE für erhöhte Sicherheit gemäß den Standards RFC 6749 und RFC 7636. Dieser Ansatz erfordert die Authentifizierung von Benutzern sowohl beim Client als auch beim MCP-Server:\n\n1. **Autorisierungsablauf** :\n\n * Der Benutzer initiiert die Anmeldung über den Django-Client\n * Der Client generiert einen kryptografisch sicheren `state` zum CSRF-Schutz\n * Der Client generiert einen zufälligen PKCE- `code_verifier` und leitet `code_challenge` mithilfe von SHA-256 ab.\n * Der Client leitet zum `/authorize` -Endpunkt des MCP-Servers weiter mit:\n * `response_type=code`\n * `client_id` (UUID-Format)\n * `redirect_uri`\n * `scope` (durch Leerzeichen getrennte Liste, z. B. `memories:read memories:write` )\n * `state` (für CSRF-Schutz)\n * PKCE-Parameter ( `code_challenge` und `code_challenge_method=S256` )\n * Der MCP-Server authentifiziert den Benutzer (sofern nicht bereits authentifiziert)\n * Der MCP-Server validiert alle Parameter und leitet mit einem kurzlebigen Autorisierungscode zurück zum Client.\n\n2. **Token-Austausch** :\n\n * Der Client überprüft, ob der zurückgegebene `state` mit dem in der Autorisierungsanfrage gesendeten übereinstimmt.\n * Der Client tauscht den Autorisierungscode gegen Zugriffs- und Aktualisierungstoken über `/token` -Endpunkt aus\n * Der MCP-Server stellt ein JWT-Zugriffstoken, ein Aktualisierungstoken, eine Ablaufzeit und gewährte Bereiche aus\n\n3. **API-Zugriff** :\n\n * Wie beim Direct Connect-Ansatz\n\n### Datenbankmodelle\n\nDer MCP-Server verwendet SQLAlchemy ORM mit den folgenden Schlüsselmodellen:\n\n1. **Benutzermodell** :\n\n * Speichert Benutzerinformationen mit E-Mail, Benutzername und gehashtem Passwort\n * Enthält boolesche Flags für den Kontostatus (is\\_active, is\\_superuser)\n * Durch eine Eins-zu-viele-Beziehung mit Erinnerungen verknüpft\n\n2. **Speichermodell mit Vektorspeicher** :\n\n * Verwendet die pgvector-Erweiterung zum Speichern und Abfragen von Vektoreinbettungen (1536 Dimensionen)\n * Unterstützt Textinhalte mit optionaler Verschlüsselung\n * Beinhaltet Berechtigungskontrollen (privat/öffentlich)\n * Unterstützt Ablaufdaten für zeitlich begrenzte Erinnerungen\n * Mit Benutzern durch Fremdschlüsselbeziehung verknüpft\n\n3. **OAuth-Modelle** :\n\n * **OAuthClient** : Speichert Client-Anwendungsdetails, einschließlich Client-ID, Client-Geheimnis, Umleitungs-URIs und autorisierte Bereiche\n * **AuthorizationCode** : Verwaltet temporäre Autorisierungscodes mit PKCE-Unterstützung\n * **Token** : Speichert Zugriffs- und Aktualisierungstoken mit Ablaufverfolgung\n\nDas System verwendet Alembic für Datenbankmigrationen und gewährleistet so Schemaversionierung und einfache Updates.\n\n### Speicherverwaltungssystem\n\nDie Kernfunktionalität von Picard MCP dreht sich um die Speicherverwaltung mit den folgenden Komponenten:\n\n1. **Speicherkapazität** :\n\n * Erinnerungen werden als Text mit zugehörigen Metadaten gespeichert\n * Vektor-Einbettungen (unter Verwendung des Text-Embedding-3-Small-Modells) ermöglichen semantische Suchfunktionen\n * Berechtigungen steuern, wer auf jeden Speicher zugreifen kann\n * Zeitstempel protokollieren Erstellung, Änderung und Ablauf\n * Der gespeicherte Text wird im Ruhezustand verschlüsselt, während die Metadaten durchsuchbar bleiben\n * Alle Bezeichner verwenden zur Skalierbarkeit das UUID-Format anstelle von sequentiellen Ganzzahlen\n * Jeder Speicher wird mithilfe des Einbettungsmodells von OpenAI in eine Vektoreinbettung umgewandelt\n * Einbettungen ermöglichen semantische Suche und Ähnlichkeitsabgleich\n * PostgreSQL mit pgvector-Erweiterung bietet effiziente Vektorspeicherung und -abfrage\n\n2. **Berechtigungsverwaltung** :\n\n * Jeder Speicher hat eine Berechtigungsstufe (privat oder öffentlich)\n * Private Erinnerungen sind nur für den Besitzer zugänglich\n * Öffentliche Erinnerungen können von anderen Benutzern für Persona-Abfragen abgerufen werden\n * Das System ist so konzipiert, dass es für zukünftige Berechtigungstypen erweiterbar ist (z. B. für die statistische/aggregierte Verwendung).\n * Auf freigegebene Erinnerungen können bestimmte Benutzer oder Gruppen zugreifen\n * Berechtigungen können vom Speicherbesitzer jederzeit geändert werden\n\n3. **Gedächtnisabruf** :\n\n * Benutzer können ihre eigenen Erinnerungen mit Filter- und Sortieroptionen abrufen\n * Die semantische Suche ermöglicht das Auffinden von Erinnerungen anhand ihrer Bedeutung, nicht nur anhand von Schlüsselwörtern\n * Vektorähnlichkeit (Kosinus) ermöglicht das Auffinden verwandter Erinnerungen in der gesamten Datenbank\n * Die Top-N-ähnlichsten Erinnerungen werden basierend auf der Abfragerelevanz zurückgegeben\n * Berechtigungsprüfungen stellen sicher, dass Benutzer nur auf autorisierte Speicher zugreifen\n\n4. **LLM-Integration** :\n\n * Erinnerungen können als Kontext für LLM-Abfragen verwendet werden\n * Benutzer können Personas basierend auf ihren öffentlichen Erinnerungen erstellen\n * Andere Benutzer können diese Personas abfragen, um Antworten zu erhalten, die auf den Erinnerungen basieren\n * Das System übernimmt automatisch Kontextmanagement und Prompt Engineering\n\n## Hauptmerkmale\n\n### MCP-Serverfunktionen\n\n* **OAuth 2.0-Authentifizierung** :\n\n * Autorisierungscode-Fluss mit PKCE für erhöhte Sicherheit\n * Umfangsbasiertes Berechtigungssystem ( `memories:read` , `memories:write` , `memories:admin` )\n * Tokenverwaltung mit Aktualisierungstoken-Unterstützung\n * Kundenregistrierung und -verwaltung\n\n* **Speicherverwaltung** :\n\n * Erinnerungen erstellen, lesen, aktualisieren und löschen\n * Vektoreinbettung für die semantische Suche\n * Berechtigungsbasierte Zugriffskontrolle\n * Stapelverarbeitung für effiziente Speicherverwaltung\n\n* **Benutzerverwaltung** :\n\n * Benutzerregistrierung und Authentifizierung\n * Profilverwaltung und -einstellungen\n * Aktivitätsverfolgung und -analyse\n * Administratorkontrollen für die Systemverwaltung\n\n* **KI-Integration** :\n\n * OpenAI-API-Integration für Einbettungen und LLM-Abfragen\n * Persona-Erstellung basierend auf Benutzererinnerungen\n * Kontextbezogene Abfrageverarbeitung\n * Anpassbare KI-Parameter und -Einstellungen\n\n### Django-Clientfunktionen\n\n* **Benutzeroberfläche** :\n\n * Klares, ansprechendes Design für Desktop und Mobilgeräte\n * Intuitive Speicherverwaltungsoberfläche\n * Erweiterte Such- und Filteroptionen\n * Persona-Erstellungs- und Abfrageschnittstelle\n\n* **OAuth-Client-Implementierung** :\n\n * Sichere Token-Speicherung und -Verwaltung\n * Automatische Token-Aktualisierung\n * Umfangsbasierte Funktionsverfügbarkeit\n * Fehlerbehandlung und Wiederherstellung\n\n* **Speichertools** :\n\n * Speichererstellung mit Rich-Text-Unterstützung\n * Batch-Import und -Export\n * Berechtigungsverwaltungsschnittstelle\n * Tagging und Kategorisierung\n\n## MCP-Schnittstelle\n\n### MCP-Ressourcen\n\n* **Speicherressource** : `memories://{memory_id}`\n\n * Gibt den Inhalt eines bestimmten Speichers mit Berechtigungsprüfungen zurück\n * Parameter: memory\\_id (UUID)\n * Antwort: Speicherinhalt mit Metadaten\n\n* **Benutzererinnerungsressource** : `users://{user_id}/memories`\n\n * Gibt eine Liste von Erinnerungen für einen bestimmten Benutzer mit Berechtigungsprüfungen zurück\n * Parameter: Benutzer-ID (UUID), optionale Filter\n * Antwort: Liste der Speicherzusammenfassungen\n\n### MCP-Tools\n\n* **Erinnerungstool übermitteln** : Erstellt eine neue Erinnerung\n\n * Parameter: Text (Zeichenfolge), Berechtigung (Zeichenfolge)\n * Rückgabe: Erstellte Speicherdetails mit UUID\n\n* **Update Memory Tool** : Aktualisiert einen vorhandenen Speicher\n\n * Parameter: memory\\_id (UUID), Text (Zeichenfolge)\n * Rückgabe: Aktualisierte Speicherdetails\n\n* **Werkzeug „Speicher löschen“** : Löscht einen Speicher\n\n * Parameter: memory\\_id (UUID)\n * Rückgabe: Erfolgsbestätigung\n\n* **Query Memory Tool** : Führt eine semantische Suche in Erinnerungen durch\n\n * Parameter: Abfrage (Zeichenfolge), Limit (Ganzzahl)\n * Rückgabe: Liste relevanter Erinnerungen\n\n* **Benutzer abfragen** : Fragt die Persona eines Benutzers anhand von Erinnerungen ab\n\n * Parameter: Benutzer-ID (UUID), Abfrage (Zeichenfolge)\n * Rückgabe: Antwort basierend auf den Erinnerungen des Benutzers\n\n## API-Endpunkte\n\n### OAuth-Endpunkte\n\n* **Kundenregistrierung** : `/register`\n\n * Methode: POST\n * Beschreibung: Einen neuen OAuth-Client registrieren\n * Anfrage: Clientdetails (ID, Geheimnis, Umleitungs-URIs, Bereiche)\n * Antwort: Client-Anmeldeinformationen und Registrierungsinformationen\n\n* **Autorisierung** : `/authorize`\n\n * Methode: GET\n * Beschreibung: OAuth-Autorisierungsablauf initiieren\n * Parameter: Antworttyp, Client-ID, Umleitungs-URI, Bereich, Status, Code-Challenge, Code-Challenge-Methode\n * Antwort: Weiterleitung zum Client mit Autorisierungscode\n\n* **Token-Austausch** : `/token`\n\n * Methode: POST\n * Beschreibung: Autorisierungscode für Token austauschen\n * Anfrage: grant\\_type, code, redirect\\_uri, client\\_id, client\\_secret, code\\_verifier\n * Antwort: Zugriffstoken, Aktualisierungstoken, Ablauf und Umfangsinformationen\n\n### Speicherendpunkte\n\n* **Erinnerungen abrufen** : `/api/tools` (Tool: `get_memories` )\n\n * Methode: POST\n\n * Beschreibung: Erinnerungen abrufen mit optionaler Filterung\n\n * Authentifizierung: Bearer-Token\n\n * Anfrage: Optionale Filterparameter (Benutzer-ID, Berechtigung, Ablaufstatus)\n\n * Antwort: Liste der für den Benutzer zugänglichen Speicher\n\n * Beispielanfrage:\n\n ```json\n {\n \"tool\": \"get_memories\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **Speicher übermitteln** : `/api/tools` (Tool: `submit_memory` )\n\n * Methode: POST\n\n * Beschreibung: Erstellen Sie eine neue Erinnerung\n\n * Authentifizierung: Bearer-Token\n\n * Anfrage: Speichertext, Berechtigungsstufe und Ablaufdatum (ISO 8601-Format, z. B. „2025-12-31T23:59:59Z“)\n\n * Antwort: Erstellte Speicherdetails einschließlich UUID-Kennung\n\n * Beispielanfrage:\n\n ```json\n {\n \"tool\": \"submit_memory\",\n \"data\": {\n \"text\": \"This is my memory content\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **Erinnerungen abrufen** : `/api/tools` (Tool: `retrieve_memories` )\n\n * Methode: POST\n\n * Beschreibung: Alle Erinnerungen für den authentifizierten Benutzer abrufen\n\n * Authentifizierung: Bearer-Token\n\n * Antwort: Liste der Speicherobjekte mit UUID-Kennungen\n\n * Beispielanfrage:\n\n ```json\n {\n \"tool\": \"retrieve_memories\",\n \"data\": {}\n }\n ```\n\n* **Speicher aktualisieren** : `/api/tools` (Tool: `update_memory` )\n\n * Methode: POST\n\n * Beschreibung: Aktualisieren eines vorhandenen Speichers\n\n * Authentifizierung: Bearer-Token\n\n * Anfrage: Speicher-ID, aktualisierter Inhalt und optional aktualisiertes Ablaufdatum (ISO 8601-Format)\n\n * Antwort: Speicherdetails aktualisiert\n\n * Beispielanfrage:\n\n ```json\n {\n \"tool\": \"update_memory\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"text\": \"Updated memory content\",\n \"expiration_date\": \"2026-01-01T00:00:00Z\"\n }\n }\n ```\n\n* **Berechtigungen ändern** : `/api/tools` (Tool: `modify_permissions` )\n\n * Methode: POST\n\n * Beschreibung: Speicherberechtigungsstufe aktualisieren\n\n * Authentifizierung: Bearer-Token\n\n * Anfrage: Speicher-UUID und neue Berechtigungsstufe\n\n * Antwort: Speicherdetails aktualisiert\n\n * Beispielanfrage:\n\n ```json\n {\n \"tool\": \"modify_permissions\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"public\"\n }\n }\n ```\n\n* **Abfragebenutzer** : `/api/tools` (Tool: `query_user` )\n\n * Methode: POST\n\n * Beschreibung: Abfrage der Persona eines Benutzers basierend auf Erinnerungen (öffentlich für andere Benutzer, öffentlich+privat für einen selbst)\n\n * Authentifizierung: Bearer-Token\n\n * Anfrage: Benutzer-UUID und Abfrageaufforderung\n\n * Antwort: JSON mit nicht abgelaufenen Speichern, entweder alle gültigen Speicher oder die Top-N, die der Abfrage am ähnlichsten sind\n\n * Antwort: KI-generierte Antwort basierend auf den Erinnerungen des Benutzers\n\n * Beispielanfrage:\n\n ```json\n {\n \"tool\": \"query_user\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"prompt\": \"What are your thoughts on artificial intelligence?\"\n }\n }\n ```\n\n## Einrichtung und Bereitstellung\n\n### Voraussetzungen\n\n* Docker und Docker Compose\n* Python 3.10+\n* OpenAI-API-Schlüssel\n\n### Vollständiges Setup-Handbuch\n\n1. Klonen Sie das Repository:\n\n ```bash\n git clone https://github.com/yourusername/picard_mcp.git\n cd picard_mcp\n ```\n\n2. Erstellen Sie Umgebungsdateien für beide Komponenten:\n\n ```bash\n # For MCP server\n cp mcp_server/.env.example mcp_server/.env\n\n # For Django client\n cp django_client/.env.example django_client/.env\n ```\n\n3. Bearbeiten Sie die Umgebungsdateien, um Ihre Konfiguration festzulegen:\n\n * In `mcp_server/.env` : Legen Sie Ihre Datenbankanmeldeinformationen, den OpenAI-API-Schlüssel und die Administratoranmeldeinformationen fest\n * In `django_client/.env` : Legen Sie Ihre Datenbankanmeldeinformationen und OAuth-Einstellungen fest\n\n4. Starten Sie die Dienste mit Docker Compose:\n\n ```bash\n docker-compose up -d\n ```\n\n Dadurch werden die folgenden Dienste gestartet:\n\n * `db-mcp` : PostgreSQL-Datenbank für den MCP-Server\n * `db-django` : PostgreSQL-Datenbank für den Django-Client\n * `mcp_server` : MCP-Server läuft auf \n * `django_client` : Django-Client, der auf ausgeführt wird\n\n5. Erstellen Sie einen Administratorbenutzer für den MCP-Server:\n\n ```bash\n docker-compose exec mcp_server python scripts/create_admin_user.py\n ```\n\n Dadurch wird ein Administratorbenutzer mit den in Ihren Umgebungsvariablen angegebenen Anmeldeinformationen erstellt.\n\n6. Registrieren Sie den Django-Client beim MCP-Server:\n\n ```bash\n docker-compose exec django_client python register_oauth_client.py\n ```\n\n Dadurch wird der Django-Client beim MCP-Server registriert und die `.env` Datei des Django-Clients mit den Client-Anmeldeinformationen aktualisiert.\n\n7. Greifen Sie auf die Anwendungen zu:\n\n * MCP-Server: \n * Django-Client: \n\n8. Erstellen Sie im Django-Client ein Benutzerkonto und beginnen Sie mit der Verwendung der Anwendung.\n\n### Erste Tests\n\nUm zu überprüfen, ob Ihr Setup ordnungsgemäß funktioniert, führen Sie die folgenden Tests aus:\n\n1. **MCP-Servertests** :\n\n ```bash\n docker-compose exec mcp_server python -m pytest\n ```\n\n Dadurch werden alle Unit-Tests für den MCP-Server ausgeführt, einschließlich OAuth-Endpunkte, Administratorfunktionen und Speicherverwaltung.\n\n2. **Django-Client-Tests** :\n\n ```bash\n docker-compose exec django_client python manage.py test\n ```\n\n Dadurch wird die Integration des Django-Clients mit dem MCP-Server getestet.\n\n3. **Manuelles Testen** :\n\n * Erstellen Sie ein Benutzerkonto im Django-Client unter \n * Melden Sie sich an und stellen Sie über OAuth eine Verbindung zum MCP-Server her\n * Erinnerungen erstellen, abrufen und verwalten\n * Testen Sie die semantische Suchfunktion\n\n## Sicherheitsüberlegungen\n\n### Datenschutz\n\n* Der Speichertextinhalt wird im Ruhezustand mit der symmetrischen Fernet-Verschlüsselung von Python (AES-128 im CBC-Modus mit PKCS7-Padding) verschlüsselt, während die Metadaten durchsuchbar bleiben\n* Personenbezogene Daten (PII) werden durch Textfeldverschlüsselung geschützt\n* Zugriffstoken haben eine Ablaufzeit von einer Stunde, um die Gefährdung zu begrenzen\n* Aktualisierungstoken sind langlebig, verwenden aber Rotation: Jede Verwendung generiert ein neues Aktualisierungstoken und macht das alte ungültig\n* OAuth-Token werden sicher in der PostgreSQL-Datenbank des Django-Clients gespeichert\n\n### UUID-Verwendung\n\nAlle Bezeichner im System verwenden aus mehreren Gründen das UUID v4-Format anstelle von fortlaufenden Ganzzahlen:\n\n1. **Sicherheit** : UUIDs geben keine Systeminformationen oder Datensatzzahlen preis\n2. **Skalierbarkeit** : UUIDs können ohne Datenbankkoordination generiert werden, was verteilte Systeme ermöglicht\n3. **Nicht-Erratbarkeit** : UUIDs sind praktisch unmöglich zu erraten, was Enumerationsangriffe verhindert\n4. **Konsistenz** : Die Verwendung von UUIDs im gesamten System vereinfacht die Integration mit anderen Diensten\n\nAlle IDs in der API (Benutzer-ID, Speicher-ID, Client-ID usw.) müssen im UUID-Format vorliegen.\n\n### Bewährte Methoden für OAuth\n\n* Die gesamte OAuth-Kommunikation muss in Produktionsumgebungen HTTPS verwenden.\n* Autorisierungscodes sind nur einmalig verwendbar und von kurzer Dauer (max. 5 Minuten).\n* PKCE ist für alle Clients, auch vertrauliche, zur umfassenden Verteidigung erforderlich\n* Aktualisierungstoken sind langlebig, können aber von Benutzern oder Administratoren widerrufen werden\n* Das System führt eine Token-Blacklist für widerrufene Token\n\n## Dokumentation\n\n### API-Dokumentation\n\nDer MCP-Server enthält Swagger/OpenAPI-Dokumentation für alle Endpunkte:\n\n* Greifen Sie bei laufendem Server unter `/docs` auf die Swagger-Benutzeroberfläche zu\n* Die OpenAPI-Spezifikation ist unter `/openapi.json` verfügbar.\n* Alle API-Endpunkte sind vollständig mit Anfrage-/Antwortschemata und Beispielen dokumentiert\n\n### Zusätzliche Dokumentationsdateien\n\n* **TESTING.md** : Umfassender Leitfaden zum Testen der Anwendung\n\n * Beschreibt alle implementierten Tests und deren Zweck\n * Anweisungen zum Ausführen von Tests lokal und in CI/CD\n * Dokumentiert die Testabdeckung und identifiziert Bereiche, die zusätzliche Tests erfordern\n\n* **DEBUGGING.md** : Verfolgt Probleme und deren Lösungen\n\n * Protokolliert bekannte Fehler, die noch nicht behoben wurden\n * Dokumentiert zuvor behobene Fehler und deren Lösungen\n * Bietet Anleitungen zur Fehlerbehebung bei häufigen Problemen\n\n* **PLANNING.md** : Verfolgt die Aufschlüsselung der Aufgaben, die zur Implementierung der Site erforderlich sind\n\n * Listet die Aufgaben und Unteraufgaben auf, die zur Implementierung der Site erforderlich sind\n * Dokumentiert die Erledigung einer Aufgabe mit einem Kontrollkästchen\n\n## Einsatz\n\nDieses Projekt enthält eine `docker-compose.yml` für die lokale Entwicklung und `render.yaml` Blaupause für die Bereitstellung in Render. Dieselbe Codebasis funktioniert sowohl lokal in Docker-Containern als auch bei der Bereitstellung in Render-Cloud-Diensten.\n\n### MCP-Serverbereitstellung\n\n1. **Docker-Bereitstellung** (für die Produktion empfohlen):\n\n ```bash\n docker-compose up -d\n ```\n\n Die Docker Compose-Konfiguration umfasst:\n\n * Netzwerkkonfiguration für die Kommunikation zwischen Containern\n * Volume-Mounts für die dauerhafte Datenspeicherung\n * Umgebungsvariablenkonfiguration aus .env-Dateien\n * Portzuordnungen (8000 für Django-Client, 8001 für MCP-Server)\n * Integritätsprüfungen für Dienstabhängigkeiten\n\n2. **Render Cloud-Bereitstellung** : Verwenden Sie die enthaltene `render.yaml` Blaupause zur Bereitstellung in Render.\n\n## Lizenz\n\nMIT","name","German","tag","de-DE",{"_27":40,"_35":44,"_37":45},{"_29":41,"_31":42,"_33":43},"A Django-based implementation of the Model Context Protocol (MCP) for managing political preferences and visions for the future.","MCP Server","# Picard MCP Server\n\n## Overview\n\nPicard MCP is a complete memory management system built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) standard. It consists of two main components: an MCP server that provides secure memory storage and retrieval services, and a Django client application that demonstrates how to integrate with the MCP server. The system enables users to store, retrieve, and manage their memories while controlling access permissions, and allows for semantic search and AI-powered queries based on stored memories.\n\n### MCP Compliance\n\nThis implementation follows the Model Context Protocol standard, which allows LLM applications to interact with the server in a standardized way. The MCP server exposes:\n\n- **Resources**: Read-only endpoints that provide data to LLMs (memory content)\n- **Tools**: Functional endpoints that perform actions (memory creation, updates, queries)\n- **Authentication**: OAuth 2.0 implementation for secure access to protected resources\n\n### Key Components\n\n1. **MCP Server**: A FastAPI-based implementation of the Model Context Protocol that provides:\n - OAuth 2.0 authentication and authorization with PKCE support\n - Memory storage with vector embeddings\n - Permission-based memory access control\n - LLM integration for memory-based queries\n\n2. **Django Client**: A web application that demonstrates integration with the MCP server:\n - User registration and authentication\n - OAuth 2.0 client implementation\n - Memory creation, retrieval, and management UI\n - Persona-based querying interface\n\n## System Architecture\n\n### Overall Architecture\n\nThe Picard MCP system follows a client-server architecture with the following components:\n\n1. **MCP Server**: Core backend service that handles memory storage, retrieval, and AI operations\n - Built with FastAPI (FastMCP) for high performance and async support\n - Uses PostgreSQL with pgvector extension for vector storage and semantic search\n - Implements data models for Users, Memories (with vector embeddings), OAuth Clients, and Tokens\n - Uses SQLAlchemy ORM with Alembic migrations for database management\n - Implements OAuth 2.0 for secure authentication and authorization\n - Integrates with OpenAI API for memory embeddings (text-embedding-3-small)\n - Uses LangChain for LLM operations when available\n - Provides both stateful and stateless operation modes\n - Supports streamable HTTP transport for better scalability\n\n2. **Django Client**: Web application that demonstrates integration with the MCP server\n - Provides user registration, authentication, and profile management\n - Implements OAuth 2.0 client for secure communication with the MCP server\n - Offers a user-friendly interface for memory management and querying\n - Uses its own PostgreSQL database separate from the MCP server\n\n3. **Docker Infrastructure**: Containerized deployment for easy setup and scaling\n - Separate containers for MCP server (port 8001), Django client (port 8000), and PostgreSQL databases\n - Configured networking for secure inter-container communication\n - Volume mounting for persistent data storage\n - Compatible with both local Docker deployment and Render cloud deployment\n\n### Authentication Approaches\n\nThe system offers two main authentication approaches:\n\n#### 1. Direct Connect with User Context Token Flow (Recommended)\n\nThis simplified approach allows users to authenticate only once with the Django client, avoiding the need for separate MCP server authentication:\n\n1. **Client Registration**:\n - The Django client registers with the MCP server using the `/api/admin/clients/register` endpoint\n - Registration requires admin authentication and includes client name, redirect URIs, and requested scopes\n - The MCP server issues a UUID-based client ID and cryptographically secure client secret\n - Client credentials should be stored securely and never exposed in client-side code\n\n2. **User Authentication Flow**:\n - User authenticates only with the Django client\n - When the user initiates connection to the MCP server, the Django client makes a server-side request to the MCP's `/api/user-tokens/user-token` endpoint\n - The request includes:\n - Client credentials (client_id and client_secret)\n - User information (username and email)\n - Option to create user if not exists\n - The MCP server verifies client credentials and either finds or creates a corresponding user\n - MCP server issues access and refresh tokens for the user\n - Django client securely stores these tokens and uses them for API requests\n\n3. **API Access**:\n - Client includes the access token in the Authorization header (`Authorization: Bearer {token}`) for all API requests\n - MCP server validates the token signature, expiration, and audience claims\n - MCP server enforces scope-based permissions for each endpoint\n - When the access token expires, client uses the refresh token to obtain a new one\n\n4. **Security Features**:\n - Only confidential clients can use this method, providing server-to-server security\n - Client credentials are verified for each token request\n - Tokens are blacklisted after use to prevent replay attacks\n - Refresh tokens use rotation: each use generates a new refresh token and invalidates the old one\n\n#### 2. Standard OAuth 2.0 Authorization Code Flow with PKCE (Legacy)\n\nThe system also supports the standard OAuth 2.0 Authorization Code flow with PKCE for enhanced security, following RFC 6749 and RFC 7636 standards. This approach requires users to authenticate with both the client and the MCP server:\n\n1. **Authorization Flow**:\n - User initiates login through the Django client\n - Client generates a cryptographically secure random `state` parameter for CSRF protection\n - Client generates a random PKCE `code_verifier` and derives `code_challenge` using SHA-256\n - Client redirects to MCP server's `/authorize` endpoint with:\n - `response_type=code`\n - `client_id` (UUID format)\n - `redirect_uri`\n - `scope` (space-separated list, e.g., `memories:read memories:write`)\n - `state` (for CSRF protection)\n - PKCE parameters (`code_challenge` and `code_challenge_method=S256`)\n - MCP server authenticates the user (if not already authenticated)\n - MCP server validates all parameters and redirects back to the client with a short-lived authorization code\n\n2. **Token Exchange**:\n - Client verifies the returned `state` parameter matches the one sent in the authorization request\n - Client exchanges the authorization code for access and refresh tokens via `/token` endpoint\n - MCP server issues a JWT access token, refresh token, expiration time, and granted scopes\n\n3. **API Access**:\n - Same as in the Direct Connect approach\n\n### Database Models\n\nThe MCP Server uses SQLAlchemy ORM with the following key models:\n\n1. **User Model**:\n - Stores user information with email, username, and hashed password\n - Includes boolean flags for account status (is_active, is_superuser)\n - Linked to memories through one-to-many relationship\n\n2. **Memory Model with Vector Storage**:\n - Uses pgvector extension to store and query vector embeddings (1536 dimensions)\n - Supports text content with optional encryption\n - Includes permission controls (private/public)\n - Supports expiration dates for time-limited memories\n - Associated with users through foreign key relationship\n\n3. **OAuth Models**:\n - **OAuthClient**: Stores client application details, including client_id, client_secret, redirect URIs, and authorized scopes\n - **AuthorizationCode**: Manages temporary authorization codes with PKCE support\n - **Token**: Stores access and refresh tokens with expiration tracking\n\nThe system uses Alembic for database migrations, ensuring schema versioning and easy updates.\n\n### Memory Management System\n\nThe core functionality of Picard MCP revolves around memory management with the following components:\n\n1. **Memory Storage**:\n - Memories are stored as text with associated metadata\n - Vector embeddings (using text-embedding-3-small model) enable semantic search capabilities\n - Permissions control who can access each memory\n - Timestamps track creation, modification, and expiration\n - Memory text is encrypted at rest while metadata remains searchable\n - All identifiers use UUID format instead of sequential integers for scalability\n - Each memory is converted to a vector embedding using OpenAI's embedding model\n - Embeddings enable semantic search and similarity matching\n - PostgreSQL with pgvector extension provides efficient vector storage and retrieval\n\n2. **Permission Management**:\n - Each memory has a permission level (private or public)\n - Private memories are only accessible to the owner\n - Public memories can be accessed by other users for persona queries\n - System is designed to be extensible for future permission types (e.g., for statistical/aggregated use)\n - Shared memories can be accessed by specific users or groups\n - Permissions can be modified by the memory owner at any time\n\n3. **Memory Retrieval**:\n - Users can retrieve their own memories with filtering and sorting options\n - Semantic search allows finding memories based on meaning, not just keywords\n - Vector similarity (cosine) enables finding related memories across the database\n - Top-N most similar memories are returned based on query relevance\n - Permission checks ensure users only access authorized memories\n\n4. **LLM Integration**:\n - Memories can be used as context for LLM queries\n - Users can create personas based on their public memories\n - Other users can query these personas to get responses informed by the memories\n - The system handles context management and prompt engineering automatically\n\n## Key Features\n\n### MCP Server Features\n\n- **OAuth 2.0 Authentication**:\n - Authorization Code flow with PKCE for enhanced security\n - Scope-based permission system (`memories:read`, `memories:write`, `memories:admin`)\n - Token management with refresh token support\n - Client registration and management\n\n- **Memory Management**:\n - Create, read, update, and delete memories\n - Vector embedding for semantic search\n - Permission-based access control\n - Batch operations for efficient memory management\n\n- **User Management**:\n - User registration and authentication\n - Profile management and settings\n - Activity tracking and analytics\n - Admin controls for system management\n\n- **AI Integration**:\n - OpenAI API integration for embeddings and LLM queries\n - Persona creation based on user memories\n - Context-aware query processing\n - Customizable AI parameters and settings\n\n### Django Client Features\n\n- **User Interface**:\n - Clean, responsive design for desktop and mobile\n - Intuitive memory management interface\n - Advanced search and filtering options\n - Persona creation and query interface\n\n- **OAuth Client Implementation**:\n - Secure token storage and management\n - Automatic token refresh\n - Scope-based feature availability\n - Error handling and recovery\n\n- **Memory Tools**:\n - Memory creation with rich text support\n - Batch import and export\n - Permission management interface\n - Tagging and categorization\n\n## MCP Interface\n\n### MCP Resources\n\n- **Memory Resource**: `memories://{memory_id}`\n - Returns the content of a specific memory with permission checks\n - Parameters: memory_id (UUID)\n - Response: Memory content with metadata\n\n- **User Memories Resource**: `users://{user_id}/memories`\n - Returns a list of memories for a specific user with permission checks\n - Parameters: user_id (UUID), optional filters\n - Response: List of memory summaries\n\n### MCP Tools\n\n- **Submit Memory Tool**: Creates a new memory\n - Parameters: text (string), permission (string)\n - Returns: Created memory details with UUID\n\n- **Update Memory Tool**: Updates an existing memory\n - Parameters: memory_id (UUID), text (string)\n - Returns: Updated memory details\n\n- **Delete Memory Tool**: Deletes a memory\n - Parameters: memory_id (UUID)\n - Returns: Success confirmation\n\n- **Query Memory Tool**: Performs semantic search on memories\n - Parameters: query (string), limit (integer)\n - Returns: List of relevant memories\n\n- **Query User**: Queries a user's persona based on memories\n - Parameters: user_id (UUID), query (string)\n - Returns: Response based on user's memories\n\n## API Endpoints\n\n### OAuth Endpoints\n\n- **Client Registration**: `/register`\n - Method: POST\n - Description: Register a new OAuth client\n - Request: Client details (ID, secret, redirect URIs, scopes)\n - Response: Client credentials and registration information\n\n- **Authorization**: `/authorize`\n - Method: GET\n - Description: Initiate OAuth authorization flow\n - Parameters: response_type, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method\n - Response: Redirects to client with authorization code\n\n- **Token Exchange**: `/token`\n - Method: POST\n - Description: Exchange authorization code for tokens\n - Request: grant_type, code, redirect_uri, client_id, client_secret, code_verifier\n - Response: Access token, refresh token, expiration, and scope information\n\n### Memory Endpoints\n\n- **Get Memories**: `/api/tools` (tool: `get_memories`)\n - Method: POST\n - Description: Retrieve memories with optional filtering\n - Authentication: Bearer token\n - Request: Optional filter parameters (user_id, permission, expiration status)\n - Response: List of memories accessible to the user\n - Example Request:\n ```json\n {\n \"tool\": \"get_memories\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"private\"\n }\n }\n ```\n\n- **Submit Memory**: `/api/tools` (tool: `submit_memory`)\n - Method: POST\n - Description: Create a new memory\n - Authentication: Bearer token\n - Request: Memory text, permission level, and expiration date (ISO 8601 format, e.g., \"2025-12-31T23:59:59Z\")\n - Response: Created memory details including UUID identifier\n - Example Request:\n ```json\n {\n \"tool\": \"submit_memory\",\n \"data\": {\n \"text\": \"This is my memory content\",\n \"permission\": \"private\"\n }\n }\n ```\n\n- **Retrieve Memories**: `/api/tools` (tool: `retrieve_memories`)\n - Method: POST\n - Description: Get all memories for the authenticated user\n - Authentication: Bearer token\n - Response: List of memory objects with UUID identifiers\n - Example Request:\n ```json\n {\n \"tool\": \"retrieve_memories\",\n \"data\": {}\n }\n ```\n\n- **Update Memory**: `/api/tools` (tool: `update_memory`)\n - Method: POST\n - Description: Update an existing memory\n - Authentication: Bearer token\n - Request: Memory ID, updated content, and optionally updated expiration date (ISO 8601 format)\n - Response: Updated memory details\n - Example Request:\n ```json\n {\n \"tool\": \"update_memory\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"text\": \"Updated memory content\",\n \"expiration_date\": \"2026-01-01T00:00:00Z\"\n }\n }\n ```\n\n- **Modify Permissions**: `/api/tools` (tool: `modify_permissions`)\n - Method: POST\n - Description: Update memory permission level\n - Authentication: Bearer token\n - Request: Memory UUID and new permission level\n - Response: Updated memory details\n - Example Request:\n ```json\n {\n \"tool\": \"modify_permissions\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"public\"\n }\n }\n ```\n\n- **Query User**: `/api/tools` (tool: `query_user`)\n - Method: POST\n - Description: Query a user's persona based on memories (public for other users, public+private for self)\n - Authentication: Bearer token\n - Request: User UUID and query prompt\n - Response: JSON containing non-expired memories, either all valid memories or top-N most similar to query\n - Response: AI-generated response based on user's memories\n - Example Request:\n ```json\n {\n \"tool\": \"query_user\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"prompt\": \"What are your thoughts on artificial intelligence?\"\n }\n }\n ```\n\n## Setup and Deployment\n\n### Prerequisites\n\n- Docker and Docker Compose\n- Python 3.10+\n- OpenAI API key\n\n### Complete Setup Guide\n\n1. Clone the repository:\n ```bash\n git clone https://github.com/yourusername/picard_mcp.git\n cd picard_mcp\n ```\n\n2. Create environment files for both components:\n ```bash\n # For MCP server\n cp mcp_server/.env.example mcp_server/.env\n \n # For Django client\n cp django_client/.env.example django_client/.env\n ```\n\n3. Edit the environment files to set your configuration:\n - In `mcp_server/.env`: Set your database credentials, OpenAI API key, and admin credentials\n - In `django_client/.env`: Set your database credentials and OAuth settings\n\n4. Start the services using Docker Compose:\n ```bash\n docker-compose up -d\n ```\n This will start the following services:\n - `db-mcp`: PostgreSQL database for the MCP server\n - `db-django`: PostgreSQL database for the Django client\n - `mcp_server`: MCP server running on http://localhost:8001\n - `django_client`: Django client running on http://localhost:8000\n\n5. Create an admin user for the MCP server:\n ```bash\n docker-compose exec mcp_server python scripts/create_admin_user.py\n ```\n This will create an admin user with the credentials specified in your environment variables.\n\n6. Register the Django client with the MCP server:\n ```bash\n docker-compose exec django_client python register_oauth_client.py\n ```\n This will register the Django client with the MCP server and update the Django client's `.env` file with the client credentials.\n\n7. Access the applications:\n - MCP Server: http://localhost:8001\n - Django Client: http://localhost:8000\n\n8. Create a user account in the Django client and start using the application.\n\n### Initial Testing\n\nTo verify your setup is working correctly, run the following tests:\n\n1. **MCP Server Tests**:\n ```bash\n docker-compose exec mcp_server python -m pytest\n ```\n This will run all the unit tests for the MCP server, including OAuth endpoints, admin functionality, and memory management.\n\n2. **Django Client Tests**:\n ```bash\n docker-compose exec django_client python manage.py test\n ```\n This will test the Django client's integration with the MCP server.\n\n3. **Manual Testing**:\n - Create a user account in the Django client at http://localhost:8000/register\n - Log in and connect to the MCP server via OAuth\n - Create, retrieve, and manage memories\n - Test the semantic search functionality\n\n## Security Considerations\n\n### Data Protection\n\n- Memory text content is encrypted at rest using Python's Fernet symmetric encryption (AES-128 in CBC mode with PKCS7 padding) while metadata remains searchable\n- Personal identifiable information (PII) is protected through text field encryption\n- Access tokens have a 1-hour expiration time to limit exposure\n- Refresh tokens are long-lived but use rotation: each use generates a new refresh token and invalidates the old one\n- OAuth tokens are securely stored in the Django client's PostgreSQL database\n\n### UUID Usage\n\nAll identifiers in the system use UUID v4 format instead of sequential integers for several reasons:\n\n1. **Security**: UUIDs don't expose system information or record counts\n2. **Scalability**: UUIDs can be generated without database coordination, enabling distributed systems\n3. **Non-guessability**: UUIDs are practically impossible to guess, preventing enumeration attacks\n4. **Consistency**: Using UUIDs throughout the system simplifies integration with other services\n\nAll IDs in the API (user_id, memory_id, client_id, etc.) must be in UUID format.\n\n### OAuth Best Practices\n\n- All OAuth communication must use HTTPS in production environments\n- Authorization codes are single-use and short-lived (max 5 minutes)\n- PKCE is required for all clients, even confidential ones, for defense in depth\n- Refresh tokens are long-lived but can be revoked by users or administrators\n- The system maintains a token blacklist for revoked tokens\n\n## Documentation\n\n### API Documentation\n\nThe MCP server includes Swagger/OpenAPI documentation for all endpoints:\n\n- Access the Swagger UI at `/docs` when the server is running\n- The OpenAPI specification is available at `/openapi.json`\n- All API endpoints are fully documented with request/response schemas and examples\n\n### Additional Documentation Files\n\n- **TESTING.md**: Comprehensive guide to testing the application\n - Describes all implemented tests and their purposes\n - Instructions for running tests locally and in CI/CD\n - Documents test coverage and identifies areas needing additional testing\n\n- **DEBUGGING.md**: Tracks issues and their resolutions\n - Logs known bugs that have not yet been fixed\n - Documents previously solved bugs and their solutions\n - Provides troubleshooting guidance for common issues\n\n- **PLANNING.md**: Tracks the breakdown of tasks required to implement the site\n - Lists tasks and subtasks required to implement the site\n - Documents if a task has been completed with a checkbox\n\n## Deployment\n\nThis project includes a `docker-compose.yml` for local development and `render.yaml` blueprint for deploying to Render. The same codebase works both locally in Docker containers and when deployed to Render cloud services.\n\n### MCP Server Deployment\n\n1. **Docker Deployment** (recommended for production):\n ```bash\n docker-compose up -d\n ```\n \n The Docker Compose configuration includes:\n - Network configuration for inter-container communication\n - Volume mounts for persistent data storage\n - Environment variable configuration from .env files\n - Port mappings (8000 for Django client, 8001 for MCP server)\n - Health checks for service dependencies\n\n2. **Render Cloud Deployment**:\n Use the included `render.yaml` blueprint to deploy to Render.\n\n## License\n\nMIT","English","en-US",{"_27":47,"_35":51,"_37":52},{"_29":48,"_31":49,"_33":50},"Una implementación basada en Django del Protocolo de Contexto Modelo (MCP) para gestionar preferencias políticas y visiones para el futuro.","Servidor MCP","# Servidor MCP de Picard\n\n## Descripción general\n\nPicard MCP es un sistema completo de gestión de memoria basado en el estándar del [Protocolo de Contexto de Modelo (MCP)](https://modelcontextprotocol.io) . 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.\n\n### Cumplimiento de MCP\n\nEsta 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:\n\n* **Recursos** : puntos finales de solo lectura que proporcionan datos a los LLM (contenido de memoria)\n* **Herramientas** : puntos finales funcionales que realizan acciones (creación de memoria, actualizaciones, consultas)\n* **Autenticación** : implementación de OAuth 2.0 para acceso seguro a recursos protegidos\n\n### Componentes clave\n\n1. **Servidor MCP** : una implementación basada en FastAPI del Protocolo de contexto de modelo que proporciona:\n\n * Autenticación y autorización OAuth 2.0 con compatibilidad con PKCE\n * Almacenamiento de memoria con incrustaciones vectoriales\n * Control de acceso a memoria basado en permisos\n * Integración de LLM para consultas basadas en memoria\n\n2. **Cliente Django** : una aplicación web que demuestra la integración con el servidor MCP:\n\n * Registro y autenticación de usuarios\n * Implementación del cliente OAuth 2.0\n * Interfaz de usuario de creación, recuperación y gestión de memoria\n * Interfaz de consulta basada en personas\n\n## Arquitectura del sistema\n\n### Arquitectura general\n\nEl sistema Picard MCP sigue una arquitectura cliente-servidor con los siguientes componentes:\n\n1. **Servidor MCP** : servicio central de backend que gestiona el almacenamiento de memoria, la recuperación y las operaciones de IA\n\n * Creado con FastAPI (FastMCP) para un alto rendimiento y compatibilidad asincrónica\n * Utiliza PostgreSQL con extensión pgvector para almacenamiento de vectores y búsqueda semántica\n * Implementa modelos de datos para usuarios, memorias (con incrustaciones vectoriales), clientes OAuth y tokens\n * Utiliza SQLAlchemy ORM con migraciones de Alembic para la gestión de bases de datos\n * Implementa OAuth 2.0 para autenticación y autorización seguras\n * Se integra con la API de OpenAI para incrustaciones de memoria (text-embedding-3-small)\n * Utiliza LangChain para operaciones LLM cuando está disponible\n * Proporciona modos de operación con estado y sin estado\n * Admite transporte HTTP transmitible para una mejor escalabilidad\n\n2. **Cliente Django** : aplicación web que demuestra la integración con el servidor MCP\n\n * Proporciona registro de usuarios, autenticación y gestión de perfiles.\n * Implementa el cliente OAuth 2.0 para una comunicación segura con el servidor MCP\n * Ofrece una interfaz fácil de usar para la gestión y consulta de memoria.\n * Utiliza su propia base de datos PostgreSQL separada del servidor MCP\n\n3. **Infraestructura Docker** : Implementación en contenedores para una fácil configuración y escalabilidad\n\n * Contenedores separados para el servidor MCP (puerto 8001), el cliente Django (puerto 8000) y las bases de datos PostgreSQL\n * Redes configuradas para una comunicación segura entre contenedores\n * Montaje de volumen para almacenamiento de datos persistentes\n * Compatible tanto con la implementación local de Docker como con la implementación en la nube de Render\n\n### Enfoques de autenticación\n\nEl sistema ofrece dos enfoques principales de autenticación:\n\n#### 1. Conexión directa con el flujo de tokens de contexto de usuario (recomendado)\n\nEste 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:\n\n1. **Registro de cliente** :\n\n * El cliente Django se registra en el servidor MCP utilizando el punto final `/api/admin/clients/register`\n * El registro requiere autenticación de administrador e incluye el nombre del cliente, las URI de redireccionamiento y los alcances solicitados.\n * El servidor MCP emite un ID de cliente basado en UUID y un secreto de cliente criptográficamente seguro\n * Las credenciales del cliente deben almacenarse de forma segura y nunca exponerse en el código del lado del cliente.\n\n2. **Flujo de autenticación de usuario** :\n\n * El usuario se autentica únicamente con el cliente Django\n * 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\n * La solicitud incluye:\n * Credenciales del cliente (client\\_id y client\\_secret)\n * Información del usuario (nombre de usuario y correo electrónico)\n * Opción para crear usuario si no existe\n * El servidor MCP verifica las credenciales del cliente y encuentra o crea un usuario correspondiente.\n * El servidor MCP emite tokens de acceso y actualización para el usuario\n * El cliente de Django almacena de forma segura estos tokens y los utiliza para solicitudes de API\n\n3. **Acceso API** :\n\n * El cliente incluye el token de acceso en el encabezado de autorización ( `Authorization: Bearer {token}` ) para todas las solicitudes de API\n * El servidor MCP valida la firma del token, la expiración y las reclamaciones de audiencia.\n * El servidor MCP aplica permisos basados en el alcance para cada punto final\n * Cuando el token de acceso expira, el cliente utiliza el token de actualización para obtener uno nuevo\n\n4. **Características de seguridad** :\n\n * Sólo los clientes confidenciales pueden utilizar este método, lo que proporciona seguridad de servidor a servidor.\n * Las credenciales del cliente se verifican para cada solicitud de token\n * Los tokens se incluyen en la lista negra después de su uso para evitar ataques de repetición.\n * Rotación de uso de tokens de actualización: cada uso genera un nuevo token de actualización e invalida el anterior\n\n#### 2. Flujo de código de autorización estándar de OAuth 2.0 con PKCE (heredado)\n\nEl 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:\n\n1. **Flujo de autorización** :\n\n * El usuario inicia el inicio de sesión a través del cliente Django\n * El cliente genera un parámetro `state` aleatorio criptográficamente seguro para la protección CSRF\n * El cliente genera un `code_verifier` PKCE aleatorio y deriva `code_challenge` utilizando SHA-256\n * El cliente redirecciona al punto final `/authorize` del servidor MCP con:\n * `response_type=code`\n * `client_id` (formato UUID)\n * `redirect_uri`\n * `scope` (lista separada por espacios, p. ej., `memories:read memories:write` )\n * `state` (para protección CSRF)\n * Parámetros PKCE ( `code_challenge` y `code_challenge_method=S256` )\n * El servidor MCP autentica al usuario (si aún no está autenticado)\n * El servidor MCP valida todos los parámetros y redirecciona al cliente con un código de autorización de corta duración.\n\n2. **Intercambio de tokens** :\n\n * El cliente verifica que el parámetro `state` devuelto coincida con el enviado en la solicitud de autorización\n * El cliente intercambia el código de autorización para acceder y actualizar tokens a través del punto final `/token`\n * El servidor MCP emite un token de acceso JWT, un token de actualización, un tiempo de expiración y alcances otorgados\n\n3. **Acceso API** :\n\n * Igual que en el enfoque de Conexión Directa\n\n### Modelos de bases de datos\n\nEl servidor MCP utiliza SQLAlchemy ORM con los siguientes modelos clave:\n\n1. **Modelo de usuario** :\n\n * Almacena información del usuario con correo electrónico, nombre de usuario y contraseña cifrada.\n * Incluye indicadores booleanos para el estado de la cuenta (is\\_active, is\\_superuser)\n * Vinculado a los recuerdos a través de una relación de uno a muchos\n\n2. **Modelo de memoria con almacenamiento vectorial** :\n\n * Utiliza la extensión pgvector para almacenar y consultar incrustaciones de vectores (1536 dimensiones)\n * Admite contenido de texto con cifrado opcional\n * Incluye controles de permisos (privados/públicos)\n * Admite fechas de vencimiento para memorias con límite de tiempo\n * Asociado con los usuarios a través de una relación de clave externa\n\n3. **Modelos OAuth** :\n\n * **OAuthClient** : almacena detalles de la aplicación cliente, incluidos client\\_id, client\\_secret, URI de redireccionamiento y ámbitos autorizados\n * **Código de autorización** : administra códigos de autorización temporales con soporte PKCE\n * **Token** : almacena tokens de acceso y actualización con seguimiento de vencimiento\n\nEl sistema utiliza Alembic para las migraciones de bases de datos, lo que garantiza el control de versiones del esquema y actualizaciones fáciles.\n\n### Sistema de gestión de memoria\n\nLa funcionalidad principal de Picard MCP gira en torno a la gestión de memoria con los siguientes componentes:\n\n1. **Almacenamiento de memoria** :\n\n * Los recuerdos se almacenan como texto con metadatos asociados.\n * Las incrustaciones vectoriales (que utilizan el modelo text-embedding-3-small) habilitan capacidades de búsqueda semántica\n * Los permisos controlan quién puede acceder a cada memoria\n * Las marcas de tiempo rastrean la creación, modificación y vencimiento\n * El texto de la memoria se cifra en reposo mientras que los metadatos siguen siendo buscables\n * Todos los identificadores utilizan el formato UUID en lugar de números enteros secuenciales para mayor escalabilidad.\n * Cada memoria se convierte en una incrustación vectorial utilizando el modelo de incrustación de OpenAI\n * Las incrustaciones permiten la búsqueda semántica y la coincidencia de similitudes\n * PostgreSQL con la extensión pgvector proporciona un almacenamiento y recuperación de vectores eficiente\n\n2. **Gestión de permisos** :\n\n * Cada memoria tiene un nivel de permiso (privado o público)\n * Los recuerdos privados sólo son accesibles al propietario.\n * Otros usuarios pueden acceder a las memorias públicas para realizar consultas personales.\n * El sistema está diseñado para ser extensible para futuros tipos de permisos (por ejemplo, para uso estadístico/agregado).\n * Los recuerdos compartidos pueden ser accedidos por usuarios o grupos específicos\n * El propietario de la memoria puede modificar los permisos en cualquier momento.\n\n3. **Recuperación de memoria** :\n\n * Los usuarios pueden recuperar sus propios recuerdos con opciones de filtrado y clasificación.\n * La búsqueda semántica permite encontrar recuerdos basándose en el significado, no solo en palabras clave.\n * La similitud vectorial (coseno) permite encontrar memorias relacionadas en la base de datos\n * Se devuelven los N recuerdos más similares según la relevancia de la consulta\n * Las comprobaciones de permisos garantizan que los usuarios solo accedan a las memorias autorizadas\n\n4. **Integración LLM** :\n\n * Los recuerdos se pueden utilizar como contexto para las consultas LLM\n * Los usuarios pueden crear personajes basados en sus recuerdos públicos.\n * Otros usuarios pueden consultar a estas personas para obtener respuestas basadas en los recuerdos.\n * El sistema gestiona automáticamente la gestión del contexto y la ingeniería de indicaciones.\n\n## Características principales\n\n### Características del servidor MCP\n\n* **Autenticación OAuth 2.0** :\n\n * Flujo de código de autorización con PKCE para una mayor seguridad\n * Sistema de permisos basado en alcance ( `memories:read` , `memories:write` , `memories:admin` )\n * Gestión de tokens con soporte para tokens de actualización\n * Registro y gestión de clientes\n\n* **Gestión de memoria** :\n\n * Crear, leer, actualizar y eliminar recuerdos\n * Incorporación de vectores para búsqueda semántica\n * Control de acceso basado en permisos\n * Operaciones por lotes para una gestión eficiente de la memoria\n\n* **Gestión de usuarios** :\n\n * Registro y autenticación de usuarios\n * Gestión y configuración de perfiles\n * Seguimiento y análisis de actividades\n * Controles de administración para la gestión del sistema\n\n* **Integración de IA** :\n\n * Integración de API de OpenAI para incrustaciones y consultas LLM\n * Creación de personajes basada en los recuerdos del usuario\n * Procesamiento de consultas según el contexto\n * Parámetros y configuraciones de IA personalizables\n\n### Características del cliente Django\n\n* **Interfaz de usuario** :\n\n * Diseño limpio y responsivo para computadoras de escritorio y dispositivos móviles.\n * Interfaz intuitiva de gestión de memoria\n * Opciones avanzadas de búsqueda y filtrado\n * Interfaz de creación y consulta de personajes\n\n* **Implementación del cliente OAuth** :\n\n * Almacenamiento y gestión seguros de tokens\n * Actualización automática del token\n * Disponibilidad de funciones según el alcance\n * Manejo y recuperación de errores\n\n* **Herramientas de memoria** :\n\n * Creación de memoria con soporte de texto enriquecido\n * Importación y exportación por lotes\n * Interfaz de gestión de permisos\n * Etiquetado y categorización\n\n## Interfaz MCP\n\n### Recursos de MCP\n\n* **Recurso de memoria** : `memories://{memory_id}`\n\n * Devuelve el contenido de una memoria específica con comprobaciones de permisos\n * Parámetros: memory\\_id (UUID)\n * Respuesta: Contenido de memoria con metadatos\n\n* **Recurso de memorias de usuario** : `users://{user_id}/memories`\n\n * Devuelve una lista de recuerdos para un usuario específico con comprobaciones de permisos\n * Parámetros: user\\_id (UUID), filtros opcionales\n * Respuesta: Lista de resúmenes de memoria\n\n### Herramientas MCP\n\n* **Herramienta de envío de memoria** : crea una nueva memoria\n\n * Parámetros: texto (cadena), permiso (cadena)\n * Devuelve: Detalles de la memoria creada con UUID\n\n* **Herramienta de actualización de memoria** : actualiza una memoria existente\n\n * Parámetros: memory\\_id (UUID), texto (cadena)\n * Devoluciones: Detalles de memoria actualizados\n\n* **Herramienta Eliminar memoria** : elimina una memoria\n\n * Parámetros: memory\\_id (UUID)\n * Devoluciones: Confirmación de éxito\n\n* **Herramienta de consulta de memoria** : realiza búsquedas semánticas en las memorias\n\n * Parámetros: consulta (cadena), límite (entero)\n * Devoluciones: Lista de recuerdos relevantes\n\n* **Consulta de usuario** : consulta la personalidad de un usuario basándose en recuerdos\n\n * Parámetros: user\\_id (UUID), consulta (cadena)\n * Devoluciones: Respuesta basada en los recuerdos del usuario\n\n## Puntos finales de API\n\n### Puntos finales de OAuth\n\n* **Registro de cliente** : `/register`\n\n * Método: POST\n * Descripción: Registrar un nuevo cliente OAuth\n * Solicitud: Detalles del cliente (ID, secreto, URI de redireccionamiento, alcances)\n * Respuesta: Credenciales del cliente e información de registro\n\n* **Autorización** : `/authorize`\n\n * Método: GET\n * Descripción: Iniciar el flujo de autorización OAuth\n * 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\n * Respuesta: Redirecciona al cliente con código de autorización\n\n* **Intercambio de tokens** : `/token`\n\n * Método: POST\n * Descripción: Código de autorización de intercambio de tokens\n * Solicitud: tipo\\_concesión, código, uri\\_redireccionamiento, id\\_cliente, secreto\\_cliente, verificador\\_código\n * Respuesta: Token de acceso, token de actualización, vencimiento e información de alcance\n\n### Puntos finales de memoria\n\n* **Obtener memorias** : `/api/tools` (herramienta: `get_memories` )\n\n * Método: POST\n\n * Descripción: Recupera recuerdos con filtrado opcional\n\n * Autenticación: Token de portador\n\n * Solicitud: parámetros de filtro opcionales (id de usuario, permiso, estado de expiración)\n\n * Respuesta: Lista de memorias accesibles al usuario\n\n * Ejemplo de solicitud:\n\n ```json\n {\n \"tool\": \"get_memories\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **Enviar memoria** : `/api/tools` (herramienta: `submit_memory` )\n\n * Método: POST\n\n * Descripción: Crea una nueva memoria\n\n * Autenticación: Token de portador\n\n * Solicitud: Texto de memoria, nivel de permiso y fecha de vencimiento (formato ISO 8601, p. ej., \"2025-12-31T23:59:59Z\")\n\n * Respuesta: Se crearon detalles de la memoria, incluido el identificador UUID\n\n * Ejemplo de solicitud:\n\n ```json\n {\n \"tool\": \"submit_memory\",\n \"data\": {\n \"text\": \"This is my memory content\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **Recuperar recuerdos** : `/api/tools` (herramienta: `retrieve_memories` )\n\n * Método: POST\n\n * Descripción: Obtener todos los recuerdos del usuario autenticado\n\n * Autenticación: Token de portador\n\n * Respuesta: Lista de objetos de memoria con identificadores UUID\n\n * Ejemplo de solicitud:\n\n ```json\n {\n \"tool\": \"retrieve_memories\",\n \"data\": {}\n }\n ```\n\n* **Actualizar memoria** : `/api/tools` (herramienta: `update_memory` )\n\n * Método: POST\n\n * Descripción: Actualizar una memoria existente\n\n * Autenticación: Token de portador\n\n * Solicitud: ID de memoria, contenido actualizado y fecha de vencimiento actualizada opcionalmente (formato ISO 8601)\n\n * Respuesta: Detalles de memoria actualizados\n\n * Ejemplo de solicitud:\n\n ```json\n {\n \"tool\": \"update_memory\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"text\": \"Updated memory content\",\n \"expiration_date\": \"2026-01-01T00:00:00Z\"\n }\n }\n ```\n\n* **Modificar permisos** : `/api/tools` (herramienta: `modify_permissions` )\n\n * Método: POST\n\n * Descripción: Actualizar el nivel de permiso de memoria\n\n * Autenticación: Token de portador\n\n * Solicitud: UUID de memoria y nuevo nivel de permiso\n\n * Respuesta: Detalles de memoria actualizados\n\n * Ejemplo de solicitud:\n\n ```json\n {\n \"tool\": \"modify_permissions\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"public\"\n }\n }\n ```\n\n* **Consulta de usuario** : `/api/tools` (herramienta: `query_user` )\n\n * Método: POST\n\n * Descripción: Consulta la personalidad de un usuario basándose en recuerdos (públicos para otros usuarios, públicos+privados para uno mismo)\n\n * Autenticación: Token de portador\n\n * Solicitud: UUID del usuario y solicitud de consulta\n\n * Respuesta: JSON que contiene memorias no vencidas, ya sean todas las memorias válidas o las N más similares a la consulta\n\n * Respuesta: Respuesta generada por IA basada en los recuerdos del usuario.\n\n * Ejemplo de solicitud:\n\n ```json\n {\n \"tool\": \"query_user\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"prompt\": \"What are your thoughts on artificial intelligence?\"\n }\n }\n ```\n\n## Configuración e implementación\n\n### Prerrequisitos\n\n* Docker y Docker Compose\n* Python 3.10+\n* Clave API de OpenAI\n\n### Guía de instalación completa\n\n1. Clonar el repositorio:\n\n ```bash\n git clone https://github.com/yourusername/picard_mcp.git\n cd picard_mcp\n ```\n\n2. Cree archivos de entorno para ambos componentes:\n\n ```bash\n # For MCP server\n cp mcp_server/.env.example mcp_server/.env\n\n # For Django client\n cp django_client/.env.example django_client/.env\n ```\n\n3. Edite los archivos de entorno para establecer su configuración:\n\n * En `mcp_server/.env` : configure sus credenciales de base de datos, la clave de API de OpenAI y las credenciales de administrador\n * En `django_client/.env` : configure las credenciales de su base de datos y la configuración de OAuth\n\n4. Inicie los servicios usando Docker Compose:\n\n ```bash\n docker-compose up -d\n ```\n\n Esto iniciará los siguientes servicios:\n\n * `db-mcp` : base de datos PostgreSQL para el servidor MCP\n * `db-django` : base de datos PostgreSQL para el cliente Django\n * `mcp_server` : servidor MCP que se ejecuta en \n * `django_client` : cliente de Django que se ejecuta en \n\n5. Cree un usuario administrador para el servidor MCP:\n\n ```bash\n docker-compose exec mcp_server python scripts/create_admin_user.py\n ```\n\n Esto creará un usuario administrador con las credenciales especificadas en sus variables de entorno.\n\n6. Registra el cliente Django con el servidor MCP:\n\n ```bash\n docker-compose exec django_client python register_oauth_client.py\n ```\n\n Esto registrará el cliente Django con el servidor MCP y actualizará el archivo `.env` del cliente Django con las credenciales del cliente.\n\n7. Acceder a las aplicaciones:\n\n * Servidor MCP: \n * Cliente Django: \n\n8. Cree una cuenta de usuario en el cliente Django y comience a utilizar la aplicación.\n\n### Pruebas iniciales\n\nPara verificar que su configuración funciona correctamente, ejecute las siguientes pruebas:\n\n1. **Pruebas del servidor MCP** :\n\n ```bash\n docker-compose exec mcp_server python -m pytest\n ```\n\n 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.\n\n2. **Pruebas del cliente de Django** :\n\n ```bash\n docker-compose exec django_client python manage.py test\n ```\n\n Esto probará la integración del cliente Django con el servidor MCP.\n\n3. **Pruebas manuales** :\n\n * Cree una cuenta de usuario en el cliente Django en \n * Inicie sesión y conéctese al servidor MCP a través de OAuth\n * Crea, recupera y gestiona recuerdos\n * Pruebe la funcionalidad de búsqueda semántica\n\n## Consideraciones de seguridad\n\n### Protección de datos\n\n* 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.\n* La información de identificación personal (PII) está protegida mediante el cifrado del campo de texto\n* Los tokens de acceso tienen un tiempo de vencimiento de 1 hora para limitar la exposición.\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.\n* Los tokens OAuth se almacenan de forma segura en la base de datos PostgreSQL del cliente Django\n\n### Uso de UUID\n\nTodos los identificadores del sistema utilizan el formato UUID v4 en lugar de números enteros secuenciales por varias razones:\n\n1. **Seguridad** : Los UUID no exponen información del sistema ni registran recuentos\n2. **Escalabilidad** : Los UUID se pueden generar sin coordinación de bases de datos, lo que permite sistemas distribuidos.\n3. **Imposibilidad de adivinar** : los UUID son prácticamente imposibles de adivinar, lo que evita ataques de enumeración.\n4. **Coherencia** : el uso de UUID en todo el sistema simplifica la integración con otros servicios\n\nTodos los ID en la API (user\\_id, memory\\_id, client\\_id, etc.) deben estar en formato UUID.\n\n### Mejores prácticas de OAuth\n\n* Toda comunicación OAuth debe utilizar HTTPS en entornos de producción\n* Los códigos de autorización son de un solo uso y de corta duración (máximo 5 minutos).\n* PKCE es necesario para todos los clientes, incluso los confidenciales, para una defensa en profundidad.\n* Los tokens de actualización tienen una larga duración, pero los usuarios o administradores pueden revocarlos.\n* El sistema mantiene una lista negra de tokens revocados\n\n## Documentación\n\n### Documentación de la API\n\nEl servidor MCP incluye documentación Swagger/OpenAPI para todos los puntos finales:\n\n* Acceda a la interfaz de usuario de Swagger en `/docs` cuando el servidor esté en ejecución\n* La especificación OpenAPI está disponible en `/openapi.json`\n* Todos los puntos finales de la API están completamente documentados con esquemas de solicitud/respuesta y ejemplos.\n\n### Archivos de documentación adicional\n\n* **TESTING.md** : Guía completa para probar la aplicación\n\n * Describe todas las pruebas implementadas y sus propósitos.\n * Instrucciones para ejecutar pruebas localmente y en CI/CD\n * Documenta la cobertura de las pruebas e identifica áreas que necesitan pruebas adicionales\n\n* **DEBUGGING.md** : Realiza un seguimiento de los problemas y sus resoluciones\n\n * Registra errores conocidos que aún no se han solucionado\n * Documenta errores resueltos previamente y sus soluciones.\n * Proporciona orientación para la resolución de problemas comunes.\n\n* **PLANNING.md** : Realiza un seguimiento del desglose de las tareas necesarias para implementar el sitio\n\n * Enumera las tareas y subtareas necesarias para implementar el sitio\n * Documenta si una tarea se ha completado con una casilla de verificación\n\n## Despliegue\n\nEste 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.\n\n### Implementación del servidor MCP\n\n1. **Implementación de Docker** (recomendado para producción):\n\n ```bash\n docker-compose up -d\n ```\n\n La configuración de Docker Compose incluye:\n\n * Configuración de red para la comunicación entre contenedores\n * Montajes de volumen para almacenamiento de datos persistentes\n * Configuración de variables de entorno desde archivos .env\n * Mapeos de puertos (8000 para el cliente Django, 8001 para el servidor MCP)\n * Comprobaciones de estado de las dependencias del servicio\n\n2. **Implementación de Render Cloud** : use el plano `render.yaml` incluido para implementar en Render.\n\n## Licencia\n\nInstituto Tecnológico de Massachusetts (MIT)","Spanish","es-ES",{"_27":54,"_35":58,"_37":59},{"_29":55,"_31":56,"_33":57},"政治的な好みと将来のビジョンを管理するための Model Context Protocol (MCP) の Django ベースの実装。","MCPサーバー","# Picard MCP サーバー\n\n## 概要\n\nPicard MCPは[、モデルコンテキストプロトコル（MCP）](https://modelcontextprotocol.io)標準に基づいて構築された完全なメモリ管理システムです。セキュアなメモリ保存および取得サービスを提供するMCPサーバーと、MCPサーバーとの統合方法を示すDjangoクライアントアプリケーションの2つの主要コンポーネントで構成されています。このシステムにより、ユーザーはアクセス権限を制御しながらメモリを保存、取得、管理することができ、保存されたメモリに基づくセマンティック検索やAIを活用したクエリを実行できます。\n\n### MCPコンプライアンス\n\nこの実装は、LLMアプリケーションが標準化された方法でサーバーとやり取りできるようにするモデルコンテキストプロトコル標準に準拠しています。MCPサーバーは以下を公開します。\n\n* **リソース**: LLMにデータを提供する読み取り専用エンドポイント（メモリコンテンツ）\n* **ツール**: アクション（メモリの作成、更新、クエリ）を実行する機能エンドポイント\n* **認証**: 保護されたリソースへの安全なアクセスのための OAuth 2.0 実装\n\n### 主要コンポーネント\n\n1. **MCP サーバー**: 次の機能を提供するモデルコンテキストプロトコルの FastAPI ベースの実装。\n\n * PKCEサポートによるOAuth 2.0認証と認可\n * ベクトル埋め込みによるメモリストレージ\n * 許可ベースのメモリアクセス制御\n * メモリベースのクエリのためのLLM統合\n\n2. **Django クライアント**: MCP サーバーとの統合を示す Web アプリケーション:\n\n * ユーザー登録と認証\n * OAuth 2.0 クライアント実装\n * メモリの作成、取得、管理UI\n * ペルソナベースのクエリインターフェース\n\n## システムアーキテクチャ\n\n### 全体的なアーキテクチャ\n\nPicard MCP システムは、次のコンポーネントを持つクライアントサーバーアーキテクチャに従います。\n\n1. **MCP サーバー**: メモリの保存、取得、AI 操作を処理するコアバックエンドサービス\n\n * 高性能と非同期サポートを実現するFastAPI（FastMCP）を搭載\n * ベクトルストレージとセマンティック検索のために、pgvector拡張機能を備えたPostgreSQLを使用します。\n * ユーザー、メモリ（ベクトル埋め込み付き）、OAuth クライアント、トークンのデータモデルを実装します。\n * データベース管理にはSQLAlchemy ORMとAlembicマイグレーションを使用します\n * 安全な認証と認可のためにOAuth 2.0を実装\n * メモリ埋め込み用の OpenAI API と統合します (text-embedding-3-small)\n * 利用可能な場合は LangChain を LLM 操作に使用します\n * ステートフルとステートレスの両方の動作モードを提供\n * スケーラビリティ向上のため、ストリーミング可能な HTTP トランスポートをサポート\n\n2. **Django クライアント**: MCP サーバーとの統合を示す Web アプリケーション\n\n * ユーザー登録、認証、プロファイル管理を提供します\n * MCP サーバーとの安全な通信のために OAuth 2.0 クライアントを実装します\n * メモリ管理とクエリのためのユーザーフレンドリーなインターフェースを提供します\n * MCPサーバーとは別に独自のPostgreSQLデータベースを使用する\n\n3. **Docker インフラストラクチャ**: コンテナ化されたデプロイメントにより、セットアップとスケーリングが簡単\n\n * MCP サーバー (ポート 8001)、Django クライアント (ポート 8000)、および PostgreSQL データベース用の個別のコンテナ\n * 安全なコンテナ間通信のためのネットワーク構成\n * 永続的なデータストレージ用のボリュームマウント\n * ローカル Docker デプロイメントと Render クラウドデプロイメントの両方に対応\n\n### 認証アプローチ\n\nシステムでは、主に 2 つの認証方法を提供しています。\n\n#### 1. ユーザーコンテキストトークンフローを使用した直接接続（推奨）\n\nこの簡略化されたアプローチにより、ユーザーは Django クライアントで 1 回だけ認証することができ、個別の MCP サーバー認証が必要なくなります。\n\n1. **クライアント登録**:\n\n * Djangoクライアントは`/api/admin/clients/register`エンドポイントを使用してMCPサーバーに登録します。\n * 登録には管理者認証が必要で、クライアント名、リダイレクトURI、要求されたスコープが含まれます。\n * MCPサーバーはUUIDベースのクライアントIDと暗号化されたクライアントシークレットを発行します。\n * クライアントの資格情報は安全に保存され、クライアント側のコードで公開されないようにする必要があります。\n\n2. **ユーザー認証フロー**:\n\n * ユーザーはDjangoクライアントでのみ認証されます\n * ユーザーがMCPサーバーへの接続を開始すると、DjangoクライアントはMCPの`/api/user-tokens/user-token`エンドポイントにサーバー側のリクエストを送信します。\n * リクエストには以下が含まれます:\n * クライアント資格情報（client\\_id と client\\_secret）\n * ユーザー情報（ユーザー名とメールアドレス）\n * 存在しない場合にユーザーを作成するオプション\n * MCPサーバーはクライアントの資格情報を検証し、対応するユーザーを見つけるか作成します。\n * MCPサーバーはユーザーにアクセストークンとリフレッシュトークンを発行します\n * Djangoクライアントはこれらのトークンを安全に保存し、APIリクエストに使用します。\n\n3. **APIアクセス**:\n\n * クライアントは、すべてのAPIリクエストのAuthorizationヘッダー（ `Authorization: Bearer {token}` ）にアクセストークンを含めます。\n * MCPサーバーはトークンの署名、有効期限、およびオーディエンスクレームを検証します。\n * MCPサーバーは各エンドポイントに対してスコープベースの権限を適用します\n * アクセストークンの有効期限が切れると、クライアントはリフレッシュトークンを使用して新しいトークンを取得します。\n\n4. **セキュリティ機能**:\n\n * 機密クライアントのみがこのメソッドを使用できるため、サーバー間のセキュリティが確保されます。\n * クライアントの資格情報はトークンリクエストごとに検証されます\n * リプレイ攻撃を防ぐために、トークンは使用後にブラックリストに登録されます。\n * リフレッシュトークンはローテーションを使用します。使用するたびに新しいリフレッシュトークンが生成され、古いものは無効になります。\n\n#### 2. PKCE を使用した標準 OAuth 2.0 認可コードフロー（レガシー）\n\nシステムは、RFC 6749およびRFC 7636標準に準拠した、PKCEを使用した標準OAuth 2.0認可コードフローもサポートしており、セキュリティを強化しています。このアプローチでは、ユーザーはクライアントとMCPサーバーの両方で認証を行う必要があります。\n\n1. **承認フロー**:\n\n * ユーザーはDjangoクライアントを通じてログインを開始する\n * クライアントはCSRF保護のために暗号的に安全なランダム`state`パラメータを生成する\n * クライアントはランダムなPKCE `code_verifier`を生成し、SHA-256を使用して`code_challenge`を導出します。\n * クライアントは次のように MCP サーバーの`/authorize`エンドポイントにリダイレクトします。\n * `response_type=code`\n * `client_id` (UUID形式)\n * `redirect_uri`\n * `scope` （スペース区切りのリスト、例： `memories:read memories:write` ）\n * `state` （CSRF保護のため）\n * PKCEパラメータ（ `code_challenge`および`code_challenge_method=S256` ）\n * MCP サーバーがユーザーを認証します (まだ認証されていない場合)\n * MCPサーバーはすべてのパラメータを検証し、短命の認証コードでクライアントにリダイレクトします。\n\n2. **トークン交換**:\n\n * クライアントは返された`state`パラメータが認可リクエストで送信されたものと一致することを確認します。\n * クライアントは`/token`エンドポイント経由でアクセストークンとリフレッシュトークンの認証コードを交換します。\n * MCPサーバーはJWTアクセストークン、リフレッシュトークン、有効期限、および許可されたスコープを発行します。\n\n3. **APIアクセス**:\n\n * ダイレクトコネクトアプローチと同じ\n\n### データベースモデル\n\nMCP サーバーは、次の主要モデルで SQLAlchemy ORM を使用します。\n\n1. **ユーザーモデル**:\n\n * メールアドレス、ユーザー名、ハッシュ化されたパスワードなどのユーザー情報を保存します\n * アカウントステータスのブールフラグ（is\\_active、is\\_superuser）が含まれます\n * 1対多の関係を通じて記憶にリンク\n\n2. **ベクトルストレージを備えたメモリモデル**:\n\n * pgvector拡張機能を使用してベクトル埋め込み（1536次元）を保存およびクエリします。\n * オプションの暗号化によるテキストコンテンツをサポート\n * 権限制御（プライベート/パブリック）が含まれます\n * 期間限定のメモリの有効期限をサポート\n * 外部キー関係を通じてユーザーに関連付けられる\n\n3. **OAuth モデル**:\n\n * **OAuthClient** : client\\_id、client\\_secret、リダイレクトURI、承認済みスコープなどのクライアントアプリケーションの詳細を保存します。\n * **AuthorizationCode** : PKCE サポートによる一時認証コードを管理します\n * **トークン**: 有効期限追跡機能付きでアクセストークンとリフレッシュトークンを保存します\n\nこのシステムでは、データベースの移行に Alembic を使用し、スキーマのバージョン管理と簡単な更新を保証します。\n\n### メモリ管理システム\n\nPicard MCP のコア機能は、次のコンポーネントによるメモリ管理を中心に展開されます。\n\n1. **メモリストレージ**:\n\n * 記憶は関連するメタデータとともにテキストとして保存されます\n * ベクトル埋め込み（テキスト埋め込み3小モデルを使用）によりセマンティック検索機能が有効になります\n * 権限は各メモリに誰がアクセスできるかを制御します\n * タイムスタンプは作成、変更、有効期限を追跡します\n * メモリテキストは保存時に暗号化されますが、メタデータは検索可能なままです\n * すべての識別子は、スケーラビリティのために連続した整数ではなくUUID形式を使用します。\n * 各メモリはOpenAIの埋め込みモデルを使用してベクトル埋め込みに変換されます。\n * 埋め込みによりセマンティック検索と類似性マッチングが可能\n * pgvector拡張機能を備えたPostgreSQLは、効率的なベクトルの保存と取得を提供します。\n\n2. **権限管理**:\n\n * 各メモリには権限レベル（プライベートまたはパブリック）があります\n * プライベートな記憶は所有者のみがアクセスできます\n * 公開メモリは他のユーザーがペルソナクエリのためにアクセスできます\n * システムは、将来の許可タイプ（例：統計/集計使用）に合わせて拡張できるように設計されています。\n * 共有メモリは特定のユーザーまたはグループがアクセスできます\n * 権限はメモリ所有者によっていつでも変更できます\n\n3. **記憶の想起**：\n\n * ユーザーはフィルタリングや並べ替えのオプションを使って自分の思い出を検索できる\n * セマンティック検索では、キーワードだけでなく意味に基づいて記憶を見つけることができます\n * ベクトル類似度（コサイン）により、データベース全体で関連する記憶を見つけることができます。\n * クエリの関連性に基づいて、最も類似した上位N個のメモリが返されます。\n * 権限チェックにより、ユーザーは許可されたメモリのみにアクセスできます\n\n4. **LLM統合**:\n\n * メモリはLLMクエリのコンテキストとして使用できます\n * ユーザーは公開された記憶に基づいてペルソナを作成できます\n * 他のユーザーはこれらのペルソナに問い合わせて、記憶に基づいた回答を得ることができます。\n * システムはコンテキスト管理と迅速なエンジニアリングを自動的に処理します。\n\n## 主な特徴\n\n### MCP サーバーの機能\n\n* **OAuth 2.0認証**:\n\n * セキュリティ強化のためのPKCEによる認証コードフロー\n * スコープベースの権限システム ( `memories:read` 、 `memories:write` 、 `memories:admin` )\n * リフレッシュトークンをサポートするトークン管理\n * クライアントの登録と管理\n\n* **メモリ管理**:\n\n * 思い出を作成、読み取り、更新、削除する\n * セマンティック検索のためのベクトル埋め込み\n * 許可ベースのアクセス制御\n * 効率的なメモリ管理のためのバッチ操作\n\n* **ユーザー管理**:\n\n * ユーザー登録と認証\n * プロフィール管理と設定\n * アクティビティの追跡と分析\n * システム管理のための管理者コントロール\n\n* **AI統合**：\n\n * 埋め込みとLLMクエリのためのOpenAI API統合\n * ユーザーの記憶に基づいたペルソナ作成\n * コンテキスト認識クエリ処理\n * カスタマイズ可能なAIパラメータと設定\n\n### Djangoクライアントの機能\n\n* **ユーザーインターフェース**:\n\n * デスクトップとモバイル向けのクリーンでレスポンシブなデザイン\n * 直感的なメモリ管理インターフェース\n * 高度な検索とフィルタリングオプション\n * ペルソナ作成とクエリインターフェース\n\n* **OAuth クライアント実装**:\n\n * 安全なトークンの保管と管理\n * 自動トークン更新\n * スコープベースの機能の可用性\n * エラー処理と回復\n\n* **メモリツール**:\n\n * リッチテキストサポートによるメモリ作成\n * 一括インポートとエクスポート\n * 権限管理インターフェース\n * タグ付けと分類\n\n## MCPインターフェース\n\n### MCPリソース\n\n* **メモリリソース**: `memories://{memory_id}`\n\n * 権限チェック付きで特定のメモリの内容を返します\n * パラメータ:memory\\_id (UUID)\n * 応答: メタデータを含むメモリコンテンツ\n\n* **ユーザーメモリーリソース**: `users://{user_id}/memories`\n\n * 権限チェックを行った特定のユーザーの思い出のリストを返します\n * パラメータ: user\\_id (UUID)、オプションのフィルタ\n * 応答: メモリ概要のリスト\n\n### MCPツール\n\n* **メモリツールを送信**: 新しいメモリを作成します\n\n * パラメータ: テキスト (文字列)、権限 (文字列)\n * 戻り値: UUIDで作成されたメモリの詳細\n\n* **メモリ更新ツール**: 既存のメモリを更新します\n\n * パラメータ:memory\\_id (UUID)、text (文字列)\n * 戻り値: 更新されたメモリの詳細\n\n* **メモリ削除ツール**: メモリを削除します\n\n * パラメータ:memory\\_id (UUID)\n * 戻り値: 成功確認\n\n* **クエリメモリツール**：記憶の意味的検索を実行する\n\n * パラメータ: クエリ (文字列)、制限 (整数)\n * 戻り値: 関連するメモリのリスト\n\n* **ユーザーのクエリ**: 記憶に基づいてユーザーのペルソナを照会します\n\n * パラメータ: user\\_id (UUID)、query (文字列)\n * 戻り値: ユーザーの記憶に基づいた応答\n\n## APIエンドポイント\n\n### OAuthエンドポイント\n\n* **クライアント登録**: `/register`\n\n * メソッド: POST\n * 説明: 新しいOAuthクライアントを登録する\n * リクエスト: クライアントの詳細 (ID、シークレット、リダイレクト URI、スコープ)\n * 回答: クライアントの資格情報と登録情報\n\n* **承認**: `/authorize`\n\n * メソッド: GET\n * 説明: OAuth 認証フローを開始する\n * パラメータ: response\\_type、client\\_id、redirect\\_uri、scope、state、code\\_challenge、code\\_challenge\\_method\n * レスポンス: 認証コードを使用してクライアントにリダイレクトします\n\n* **トークン交換**: `/token`\n\n * メソッド: POST\n * 説明: 認証コードをトークンと交換する\n * リクエスト: grant\\_type、code、redirect\\_uri、client\\_id、client\\_secret、code\\_verifier\n * レスポンス: アクセストークン、リフレッシュトークン、有効期限、スコープ情報\n\n### メモリエンドポイント\n\n* **思い出を取得**: `/api/tools` (ツール: `get_memories` )\n\n * メソッド: POST\n\n * 説明: オプションのフィルタリングを使用して思い出を検索します\n\n * 認証: ベアラートークン\n\n * リクエスト: オプションのフィルターパラメータ (user\\_id、権限、有効期限ステータス)\n\n * 応答: ユーザーがアクセスできるメモリのリスト\n\n * リクエスト例:\n\n ```json\n {\n \"tool\": \"get_memories\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **メモリの送信**: `/api/tools` (ツール: `submit_memory` )\n\n * メソッド: POST\n\n * 説明: 新しいメモリを作成する\n\n * 認証: ベアラートークン\n\n * リクエスト: メモリテキスト、権限レベル、有効期限 (ISO 8601 形式、例: \"2025-12-31T23:59:59Z\")\n\n * 応答: UUID識別子を含む作成されたメモリの詳細\n\n * リクエスト例:\n\n ```json\n {\n \"tool\": \"submit_memory\",\n \"data\": {\n \"text\": \"This is my memory content\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **思い出の取得**: `/api/tools` (ツール: `retrieve_memories` )\n\n * メソッド: POST\n\n * 説明: 認証されたユーザーのすべてのメモリを取得します\n\n * 認証: ベアラートークン\n\n * 応答: UUID識別子を持つメモリオブジェクトのリスト\n\n * リクエスト例:\n\n ```json\n {\n \"tool\": \"retrieve_memories\",\n \"data\": {}\n }\n ```\n\n* **メモリの更新**: `/api/tools` (ツール: `update_memory` )\n\n * メソッド: POST\n\n * 説明: 既存のメモリを更新する\n\n * 認証: ベアラートークン\n\n * リクエスト: メモリ ID、更新されたコンテンツ、およびオプションで更新された有効期限 (ISO 8601 形式)\n\n * 応答: メモリの詳細を更新しました\n\n * リクエスト例:\n\n ```json\n {\n \"tool\": \"update_memory\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"text\": \"Updated memory content\",\n \"expiration_date\": \"2026-01-01T00:00:00Z\"\n }\n }\n ```\n\n* **権限の変更**: `/api/tools` (ツール: `modify_permissions` )\n\n * メソッド: POST\n\n * 説明: メモリの権限レベルを更新する\n\n * 認証: ベアラートークン\n\n * リクエスト: メモリUUIDと新しい権限レベル\n\n * 応答: メモリの詳細を更新しました\n\n * リクエスト例:\n\n ```json\n {\n \"tool\": \"modify_permissions\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"public\"\n }\n }\n ```\n\n* **クエリユーザー**: `/api/tools` (ツール: `query_user` )\n\n * メソッド: POST\n\n * 説明: 思い出に基づいてユーザーのペルソナを照会します (他のユーザーには公開、自分には公開+非公開)\n\n * 認証: ベアラートークン\n\n * リクエスト: ユーザーUUIDとクエリプロンプト\n\n * レスポンス: 期限切れでないメモリ（すべての有効なメモリまたはクエリに最も類似する上位Nのメモリ）を含むJSON\n\n * 応答: ユーザーの記憶に基づいて AI が生成した応答\n\n * リクエスト例:\n\n ```json\n {\n \"tool\": \"query_user\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"prompt\": \"What are your thoughts on artificial intelligence?\"\n }\n }\n ```\n\n## セットアップと展開\n\n### 前提条件\n\n* Docker と Docker Compose\n* Python 3.10以上\n* OpenAI APIキー\n\n### 完全なセットアップガイド\n\n1. リポジトリをクローンします。\n\n ```bash\n git clone https://github.com/yourusername/picard_mcp.git\n cd picard_mcp\n ```\n\n2. 両方のコンポーネントの環境ファイルを作成します。\n\n ```bash\n # For MCP server\n cp mcp_server/.env.example mcp_server/.env\n\n # For Django client\n cp django_client/.env.example django_client/.env\n ```\n\n3. 環境ファイルを編集して構成を設定します。\n\n * `mcp_server/.env`で、データベースの資格情報、OpenAI API キー、管理者の資格情報を設定します。\n * `django_client/.env`でデータベースの認証情報とOAuth設定を設定します\n\n4. Docker Compose を使用してサービスを開始します。\n\n ```bash\n docker-compose up -d\n ```\n\n これにより、次のサービスが開始されます。\n\n * `db-mcp` : MCP サーバー用の PostgreSQL データベース\n * `db-django` : Django クライアント用の PostgreSQL データベース\n * `mcp_server` : で実行されている MCP サーバー\n * `django_client` : で実行されている Django クライアント\n\n5. MCP サーバーの管理者ユーザーを作成します。\n\n ```bash\n docker-compose exec mcp_server python scripts/create_admin_user.py\n ```\n\n これにより、環境変数で指定された資格情報を持つ管理者ユーザーが作成されます。\n\n6. Django クライアントを MCP サーバーに登録します。\n\n ```bash\n docker-compose exec django_client python register_oauth_client.py\n ```\n\n これにより、Django クライアントが MCP サーバーに登録され、Django クライアントの`.env`ファイルがクライアントの資格情報で更新されます。\n\n7. アプリケーションにアクセスします。\n\n * MCP サーバー: \n * Django クライアント: \n\n8. Django クライアントでユーザーアカウントを作成し、アプリケーションの使用を開始します。\n\n### 初期テスト\n\nセットアップが正しく動作していることを確認するには、次のテストを実行します。\n\n1. **MCP サーバーテスト**:\n\n ```bash\n docker-compose exec mcp_server python -m pytest\n ```\n\n これにより、OAuth エンドポイント、管理機能、メモリ管理など、MCP サーバーのすべての単体テストが実行されます。\n\n2. **Django クライアントテスト**:\n\n ```bash\n docker-compose exec django_client python manage.py test\n ```\n\n これにより、Django クライアントと MCP サーバーの統合がテストされます。\n\n3. **手動テスト**:\n\n * Djangoクライアントでにユーザーアカウントを作成します。\n * OAuth経由でMCPサーバーにログインして接続する\n * 思い出を作成、取得、管理する\n * セマンティック検索機能をテストする\n\n## セキュリティに関する考慮事項\n\n### データ保護\n\n* メモリテキストコンテンツはPythonのFernet対称暗号化（PKCS7パディング付きCBCモードのAES-128）を使用して保存時に暗号化されますが、メタデータは検索可能です。\n* 個人を特定できる情報（PII）はテキストフィールドの暗号化によって保護されます\n* アクセストークンには、露出を制限するために1時間の有効期限があります。\n* リフレッシュトークンは長期間有効ですが、ローテーションを使用します。使用するたびに新しいリフレッシュトークンが生成され、古いトークンは無効になります。\n* OAuthトークンはDjangoクライアントのPostgreSQLデータベースに安全に保存されます。\n\n### UUIDの使用法\n\nシステム内のすべての識別子は、いくつかの理由により、連続した整数ではなく UUID v4 形式を使用します。\n\n1. **セキュリティ**: UUIDはシステム情報やレコード数を公開しません\n2. **スケーラビリティ**: UUIDはデータベース調整なしで生成できるため、分散システムが可能になります。\n3. **推測不可能**: UUIDは推測することが事実上不可能であり、列挙攻撃を防止します。\n4. **一貫性**: システム全体でUUIDを使用すると、他のサービスとの統合が簡単になります。\n\nAPI 内のすべての ID (user\\_id、memory\\_id、client\\_id など) は UUID 形式である必要があります。\n\n### OAuth のベストプラクティス\n\n* 実稼働環境では、すべての OAuth 通信に HTTPS を使用する必要があります。\n* 認証コードは1回限り有効で、有効期間は短い（最大5分）\n* 多層防御のため、すべてのクライアント（機密クライアントも含む）にPKCEが必要です。\n* リフレッシュトークンは長期間有効ですが、ユーザーまたは管理者によって取り消される可能性があります。\n* システムは失効したトークンのブラックリストを維持します\n\n## ドキュメント\n\n### APIドキュメント\n\nMCP サーバーには、すべてのエンドポイントの Swagger/OpenAPI ドキュメントが含まれています。\n\n* サーバーが実行中のときに`/docs`で Swagger UI にアクセスします。\n* OpenAPI仕様は`/openapi.json`で入手可能です。\n* すべてのAPIエンドポイントは、リクエスト/レスポンススキーマと例とともに完全に文書化されています。\n\n### 追加のドキュメントファイル\n\n* **TESTING.md** : アプリケーションをテストするための包括的なガイド\n\n * 実装されたすべてのテストとその目的を説明します\n * ローカルおよび CI/CD でテストを実行する手順\n * テスト範囲を文書化し、追加テストが必要な領域を特定します\n\n* **DEBUGGING.md** : 問題とその解決策を追跡します\n\n * まだ修正されていない既知のバグを記録します\n * 以前に解決されたバグとその解決策を文書化する\n * 一般的な問題に対するトラブルシューティングのガイダンスを提供します\n\n* **PLANNING.md** : サイトの実装に必要なタスクの内訳を追跡します\n\n * サイトの実装に必要なタスクとサブタスクをリストします\n * タスクが完了したかどうかをチェックボックスで記録します\n\n## 展開\n\nこのプロジェクトには、ローカル開発用の`docker-compose.yml`と、Render へのデプロイ用の`render.yaml`ブループリントが含まれています。同じコードベースが、Docker コンテナ内のローカル環境でも、Render クラウドサービスへのデプロイでも動作します。\n\n### MCP サーバーの展開\n\n1. **Docker デプロイメント**(本番環境に推奨):\n\n ```bash\n docker-compose up -d\n ```\n\n Docker Compose 構成には以下が含まれます。\n\n * コンテナ間通信のためのネットワーク構成\n * 永続的なデータストレージ用のボリュームマウント\n * .env ファイルからの環境変数の設定\n * ポートマッピング（Django クライアントの場合は 8000、MCP サーバーの場合は 8001）\n * サービス依存関係のヘルスチェック\n\n2. **Render クラウドデプロイメント**: 付属の`render.yaml`ブループリントを使用して Render にデプロイします。\n\n## ライセンス\n\nマサチューセッツ工科大学","Japanese","ja-JP",{"_27":61,"_35":65,"_37":66},{"_29":62,"_31":63,"_33":64},"정치적 선호도와 미래에 대한 비전을 관리하기 위한 모델 컨텍스트 프로토콜(MCP)의 Django 기반 구현입니다.","MCP 서버","# 피카르드 MCP 서버\n\n## 개요\n\nPicard MCP는 [모델 컨텍스트 프로토콜(MCP)](https://modelcontextprotocol.io) 표준을 기반으로 구축된 완전한 메모리 관리 시스템입니다. 이 시스템은 두 가지 주요 구성 요소로 구성됩니다. 안전한 메모리 저장 및 검색 서비스를 제공하는 MCP 서버와 MCP 서버와의 통합 방법을 보여주는 Django 클라이언트 애플리케이션입니다. 이 시스템을 통해 사용자는 접근 권한을 제어하면서 메모리를 저장, 검색 및 관리할 수 있으며, 저장된 메모리를 기반으로 의미론적 검색 및 AI 기반 쿼리를 수행할 수 있습니다.\n\n### MCP 준수\n\n이 구현은 LLM 애플리케이션이 표준화된 방식으로 서버와 상호 작용할 수 있도록 하는 모델 컨텍스트 프로토콜(MCP) 표준을 따릅니다. MCP 서버는 다음을 제공합니다.\n\n* **리소스** : LLM에 데이터를 제공하는 읽기 전용 엔드포인트(메모리 콘텐츠)\n* **도구** : 작업(메모리 생성, 업데이트, 쿼리)을 수행하는 기능적 엔드포인트\n* **인증** : 보호된 리소스에 대한 보안 액세스를 위한 OAuth 2.0 구현\n\n### 주요 구성 요소\n\n1. **MCP 서버** : 다음을 제공하는 모델 컨텍스트 프로토콜의 FastAPI 기반 구현:\n\n * PKCE 지원을 통한 OAuth 2.0 인증 및 권한 부여\n * 벡터 임베딩을 사용한 메모리 저장\n * 권한 기반 메모리 액세스 제어\n * 메모리 기반 쿼리를 위한 LLM 통합\n\n2. **Django 클라이언트** : MCP 서버와의 통합을 보여주는 웹 애플리케이션입니다.\n\n * 사용자 등록 및 인증\n * OAuth 2.0 클라이언트 구현\n * 메모리 생성, 검색 및 관리 UI\n * 페르소나 기반 쿼리 인터페이스\n\n## 시스템 아키텍처\n\n### 전체 아키텍처\n\nPicard MCP 시스템은 다음 구성 요소로 구성된 클라이언트-서버 아키텍처를 따릅니다.\n\n1. **MCP 서버** : 메모리 저장, 검색 및 AI 작업을 처리하는 핵심 백엔드 서비스\n\n * 고성능 및 비동기 지원을 위해 FastAPI(FastMCP)로 구축됨\n * 벡터 저장 및 의미 검색을 위해 pgvector 확장 기능이 있는 PostgreSQL을 사용합니다.\n * 사용자, 메모리(벡터 임베딩 포함), OAuth 클라이언트 및 토큰에 대한 데이터 모델을 구현합니다.\n * 데이터베이스 관리를 위해 Alembic 마이그레이션과 함께 SQLAlchemy ORM을 사용합니다.\n * 안전한 인증 및 권한 부여를 위해 OAuth 2.0을 구현합니다.\n * 메모리 임베딩을 위한 OpenAI API와 통합(text-embedding-3-small)\n * 사용 가능한 경우 LLM 작업에 LangChain을 사용합니다.\n * 상태 저장 및 상태 비저장 운영 모드를 모두 제공합니다.\n * 더 나은 확장성을 위해 스트리밍 가능한 HTTP 전송을 지원합니다.\n\n2. **Django 클라이언트** : MCP 서버와의 통합을 보여주는 웹 애플리케이션\n\n * 사용자 등록, 인증 및 프로필 관리를 제공합니다.\n * MCP 서버와의 보안 통신을 위해 OAuth 2.0 클라이언트를 구현합니다.\n * 메모리 관리 및 쿼리를 위한 사용자 친화적인 인터페이스를 제공합니다.\n * MCP 서버와 별도로 자체 PostgreSQL 데이터베이스를 사용합니다.\n\n3. **Docker Infrastructure** : 간편한 설정 및 확장을 위한 컨테이너화된 배포\n\n * MCP 서버(포트 8001), Django 클라이언트(포트 8000) 및 PostgreSQL 데이터베이스에 대한 별도의 컨테이너\n * 안전한 컨테이너 간 통신을 위한 네트워킹 구성\n * 영구 데이터 저장을 위한 볼륨 마운팅\n * 로컬 Docker 배포와 Render 클라우드 배포 모두와 호환 가능\n\n### 인증 접근 방식\n\n이 시스템은 두 가지 주요 인증 방법을 제공합니다.\n\n#### 1. 사용자 컨텍스트 토큰 흐름을 통한 직접 연결(권장)\n\n이 간소화된 접근 방식을 사용하면 사용자는 Django 클라이언트에서 한 번만 인증하면 되므로 별도의 MCP 서버 인증이 필요하지 않습니다.\n\n1. **고객 등록** :\n\n * Django 클라이언트는 `/api/admin/clients/register` 엔드포인트를 사용하여 MCP 서버에 등록합니다.\n * 등록에는 관리자 인증이 필요하며 클라이언트 이름, 리디렉션 URI 및 요청 범위가 포함됩니다.\n * MCP 서버는 UUID 기반 클라이언트 ID와 암호학적으로 안전한 클라이언트 비밀번호를 발급합니다.\n * 클라이언트 자격 증명은 안전하게 저장되어야 하며 클라이언트 측 코드에 노출되어서는 안 됩니다.\n\n2. **사용자 인증 흐름** :\n\n * 사용자는 Django 클라이언트로만 인증합니다.\n * 사용자가 MCP 서버에 연결을 시작하면 Django 클라이언트는 MCP의 `/api/user-tokens/user-token` 엔드포인트에 서버 측 요청을 합니다.\n * 요청에는 다음이 포함됩니다.\n * 클라이언트 자격 증명(client\\_id 및 client\\_secret)\n * 사용자 정보(사용자 이름 및 이메일)\n * 존재하지 않는 경우 사용자를 생성하는 옵션\n * MCP 서버는 클라이언트 자격 증명을 확인하고 해당 사용자를 찾거나 생성합니다.\n * MCP 서버는 사용자에게 액세스 토큰과 새로 고침 토큰을 발급합니다.\n * Django 클라이언트는 이러한 토큰을 안전하게 저장하고 API 요청에 사용합니다.\n\n3. **API 접근** :\n\n * 클라이언트는 모든 API 요청에 대해 Authorization 헤더( `Authorization: Bearer {token}` )에 액세스 토큰을 포함합니다.\n * MCP 서버는 토큰 서명, 만료 및 대상자 클레임을 검증합니다.\n * MCP 서버는 각 엔드포인트에 대해 범위 기반 권한을 적용합니다.\n * 액세스 토큰이 만료되면 클라이언트는 새로 고침 토큰을 사용하여 새 토큰을 얻습니다.\n\n4. **보안 기능** :\n\n * 이 방법은 기밀 클라이언트만 사용할 수 있으므로 서버 간 보안이 제공됩니다.\n * 각 토큰 요청에 대해 클라이언트 자격 증명이 검증됩니다.\n * 재생 공격을 방지하기 위해 토큰은 사용 후 블랙리스트에 등록됩니다.\n * 새로 고침 토큰은 회전을 사용합니다. 사용할 때마다 새 새로 고침 토큰이 생성되고 이전 토큰은 무효화됩니다.\n\n#### 2. PKCE를 사용한 표준 OAuth 2.0 인증 코드 흐름(레거시)\n\n이 시스템은 또한 RFC 6749 및 RFC 7636 표준을 준수하여 보안 강화를 위해 PKCE를 포함한 표준 OAuth 2.0 인증 코드 흐름을 지원합니다. 이 접근 방식을 사용하려면 사용자가 클라이언트와 MCP 서버 모두에서 인증해야 합니다.\n\n1. **승인 흐름** :\n\n * 사용자는 Django 클라이언트를 통해 로그인을 시작합니다.\n * 클라이언트는 CSRF 보호를 위해 암호화된 난수 `state` 매개변수를 생성합니다.\n * 클라이언트는 임의의 PKCE `code_verifier` 생성하고 SHA-256을 사용하여 `code_challenge` 도출합니다.\n * 클라이언트는 다음을 사용하여 MCP 서버의 `/authorize` 엔드포인트로 리디렉션합니다.\n * `response_type=code`\n * `client_id` (UUID 형식)\n * `redirect_uri`\n * `scope` (공백으로 구분된 목록, 예: `memories:read memories:write` )\n * `state` (CSRF 보호용)\n * PKCE 매개변수( `code_challenge` 및 `code_challenge_method=S256` )\n * MCP 서버는 사용자를 인증합니다(아직 인증되지 않은 경우)\n * MCP 서버는 모든 매개변수를 검증하고 단기 승인 코드와 함께 클라이언트로 다시 리디렉션합니다.\n\n2. **토큰 교환** :\n\n * 클라이언트는 반환된 `state` 매개변수가 권한 부여 요청에서 전송된 매개변수와 일치하는지 확인합니다.\n * 클라이언트는 `/token` 엔드포인트를 통해 액세스 및 새로 고침 토큰에 대한 승인 코드를 교환합니다.\n * MCP 서버는 JWT 액세스 토큰, 새로 고침 토큰, 만료 시간 및 부여된 범위를 발급합니다.\n\n3. **API 접근** :\n\n * Direct Connect 접근 방식과 동일\n\n### 데이터베이스 모델\n\nMCP 서버는 다음과 같은 주요 모델을 갖춘 SQLAlchemy ORM을 사용합니다.\n\n1. **사용자 모델** :\n\n * 이메일, 사용자 이름 및 해시된 비밀번호와 함께 사용자 정보를 저장합니다.\n * 계정 상태에 대한 부울 플래그(is\\_active, is\\_superuser)가 포함됩니다.\n * 일대다 관계를 통해 기억과 연결됨\n\n2. **벡터 저장을 통한 메모리 모델** :\n\n * pgvector 확장을 사용하여 벡터 임베딩(1536차원)을 저장하고 쿼리합니다.\n * 선택적 암호화를 통해 텍스트 콘텐츠를 지원합니다.\n * 권한 제어(비공개/공개) 포함\n * 시간 제한이 있는 메모리의 만료 날짜를 지원합니다.\n * 외래 키 관계를 통해 사용자와 연결됨\n\n3. **OAuth 모델** :\n\n * **OAuthClient** : client\\_id, client\\_secret, 리디렉션 URI, 권한 범위를 포함한 클라이언트 애플리케이션 세부 정보를 저장합니다.\n * **AuthorizationCode** : PKCE 지원을 통해 임시 승인 코드를 관리합니다.\n * **토큰** : 만료 추적 기능이 있는 액세스 및 새로 고침 토큰을 저장합니다.\n\n이 시스템은 Alembic을 사용하여 데이터베이스 마이그레이션을 수행하고 스키마 버전 관리와 손쉬운 업데이트를 보장합니다.\n\n### 메모리 관리 시스템\n\nPicard MCP의 핵심 기능은 다음 구성 요소를 사용한 메모리 관리를 중심으로 이루어집니다.\n\n1. **메모리 저장** :\n\n * 메모리는 연관된 메타데이터와 함께 텍스트로 저장됩니다.\n * 벡터 임베딩(텍스트 임베딩 3-소형 모델 사용)을 통해 의미 검색 기능이 활성화됩니다.\n * 권한은 각 메모리에 누가 액세스할 수 있는지 제어합니다.\n * 타임스탬프는 생성, 수정 및 만료를 추적합니다.\n * 메모리 텍스트는 저장 시 암호화되지만 메타데이터는 검색 가능합니다.\n * 모든 식별자는 확장성을 위해 순차적 정수 대신 UUID 형식을 사용합니다.\n * 각 메모리는 OpenAI의 임베딩 모델을 사용하여 벡터 임베딩으로 변환됩니다.\n * 임베딩을 사용하면 의미 검색 및 유사성 일치가 가능합니다.\n * pgvector 확장 기능을 갖춘 PostgreSQL은 효율적인 벡터 저장 및 검색을 제공합니다.\n\n2. **권한 관리** :\n\n * 각 메모리에는 권한 수준(비공개 또는 공개)이 있습니다.\n * 개인 기억은 소유자만이 접근할 수 있습니다.\n * 공개 메모리는 다른 사용자가 페르소나 쿼리를 위해 액세스할 수 있습니다.\n * 시스템은 향후 권한 유형(예: 통계/집계 사용)에 대해 확장 가능하도록 설계되었습니다.\n * 공유 메모리는 특정 사용자 또는 그룹이 액세스할 수 있습니다.\n * 메모리 소유자는 언제든지 권한을 수정할 수 있습니다.\n\n3. **기억 회복** :\n\n * 사용자는 필터링 및 정렬 옵션을 사용하여 자신의 메모리를 검색할 수 있습니다.\n * 의미 검색을 통해 키워드뿐만 아니라 의미에 기반한 기억을 찾을 수 있습니다.\n * 벡터 유사성(코사인)을 통해 데이터베이스 전체에서 관련 메모리를 찾을 수 있습니다.\n * 쿼리 관련성에 따라 가장 유사한 상위 N개의 메모리가 반환됩니다.\n * 권한 검사를 통해 사용자는 승인된 메모리에만 액세스할 수 있습니다.\n\n4. **LLM 통합** :\n\n * 메모리는 LLM 쿼리의 컨텍스트로 사용될 수 있습니다.\n * 사용자는 공개 기억을 기반으로 페르소나를 생성할 수 있습니다.\n * 다른 사용자는 이러한 페르소나를 쿼리하여 기억을 통해 응답을 얻을 수 있습니다.\n * 시스템은 컨텍스트 관리 및 신속한 엔지니어링을 자동으로 처리합니다.\n\n## 주요 특징\n\n### MCP 서버 기능\n\n* **OAuth 2.0 인증** :\n\n * 보안 강화를 위한 PKCE를 사용한 승인 코드 흐름\n * 범위 기반 권한 시스템( `memories:read` , `memories:write` , `memories:admin` )\n * 새로고침 토큰 지원을 통한 토큰 관리\n * 클라이언트 등록 및 관리\n\n* **메모리 관리** :\n\n * 추억을 만들고, 읽고, 업데이트하고, 삭제하세요\n * 의미 검색을 위한 벡터 임베딩\n * 권한 기반 액세스 제어\n * 효율적인 메모리 관리를 위한 일괄 작업\n\n* **사용자 관리** :\n\n * 사용자 등록 및 인증\n * 프로필 관리 및 설정\n * 활동 추적 및 분석\n * 시스템 관리를 위한 관리자 제어\n\n* **AI 통합** :\n\n * 임베딩 및 LLM 쿼리를 위한 OpenAI API 통합\n * 사용자 기억 기반 페르소나 생성\n * 컨텍스트 인식 쿼리 처리\n * 사용자 정의 가능한 AI 매개변수 및 설정\n\n### Django 클라이언트 기능\n\n* **사용자 인터페이스** :\n\n * 데스크톱과 모바일에 적합한 깔끔하고 반응성 있는 디자인\n * 직관적인 메모리 관리 인터페이스\n * 고급 검색 및 필터링 옵션\n * 페르소나 생성 및 쿼리 인터페이스\n\n* **OAuth 클라이언트 구현** :\n\n * 안전한 토큰 저장 및 관리\n * 자동 토큰 새로 고침\n * 범위 기반 기능 가용성\n * 오류 처리 및 복구\n\n* **메모리 도구** :\n\n * 리치 텍스트 지원을 통한 메모리 생성\n * 일괄 가져오기 및 내보내기\n * 권한 관리 인터페이스\n * 태그 지정 및 분류\n\n## MCP 인터페이스\n\n### MCP 리소스\n\n* **메모리 리소스** : `memories://{memory_id}`\n\n * 권한 검사를 통해 특정 메모리의 내용을 반환합니다.\n * 매개변수: memory\\_id(UUID)\n * 응답: 메타데이터가 포함된 메모리 콘텐츠\n\n* **사용자 메모리 리소스** : `users://{user_id}/memories`\n\n * 권한 검사를 통해 특정 사용자에 대한 메모리 목록을 반환합니다.\n * 매개변수: user\\_id(UUID), 선택적 필터\n * 응답: 기억 요약 목록\n\n### MCP 도구\n\n* **메모리 도구 제출** : 새로운 메모리를 만듭니다\n\n * 매개변수: 텍스트(문자열), 권한(문자열)\n * 반환: UUID로 생성된 메모리 세부 정보\n\n* **메모리 업데이트 도구** : 기존 메모리를 업데이트합니다.\n\n * 매개변수: memory\\_id(UUID), text(문자열)\n * 반환: 업데이트된 메모리 세부 정보\n\n* **메모리 삭제 도구** : 메모리를 삭제합니다\n\n * 매개변수: memory\\_id(UUID)\n * 반환: 성공 확인\n\n* **쿼리 메모리 도구** : 메모리에 대한 의미 검색을 수행합니다.\n\n * 매개변수: 쿼리(문자열), 제한(정수)\n * 반환: 관련 메모리 목록\n\n* **사용자 쿼리** : 메모리를 기반으로 사용자의 페르소나를 쿼리합니다.\n\n * 매개변수: user\\_id(UUID), query(문자열)\n * 반환: 사용자의 기억에 기반한 응답\n\n## API 엔드포인트\n\n### OAuth 엔드포인트\n\n* **클라이언트 등록** : `/register`\n\n * 방법: POST\n * 설명: 새로운 OAuth 클라이언트 등록\n * 요청: 클라이언트 세부 정보(ID, 비밀번호, 리디렉션 URI, 범위)\n * 응답: 클라이언트 자격 증명 및 등록 정보\n\n* **권한 부여** : `/authorize`\n\n * 방법: GET\n * 설명: OAuth 권한 부여 흐름 시작\n * 매개변수: response\\_type, client\\_id, redirect\\_uri, scope, state, code\\_challenge, code\\_challenge\\_method\n * 응답: 승인 코드를 사용하여 클라이언트로 리디렉션합니다.\n\n* **토큰 교환** : `/token`\n\n * 방법: POST\n * 설명: 토큰에 대한 승인 코드 교환\n * 요청: grant\\_type, code, redirect\\_uri, client\\_id, client\\_secret, code\\_verifier\n * 응답: 액세스 토큰, 새로 고침 토큰, 만료 및 범위 정보\n\n### 메모리 엔드포인트\n\n* **메모리 가져오기** : `/api/tools` (도구: `get_memories` )\n\n * 방법: POST\n\n * 설명: 선택적 필터링을 사용하여 메모리 검색\n\n * 인증: 베어러 토큰\n\n * 요청: 선택적 필터 매개변수(user\\_id, 권한, 만료 상태)\n\n * 응답: 사용자가 접근 가능한 메모리 목록\n\n * 요청 예시:\n\n 지엑스피1\n\n* **메모리 제출** : `/api/tools` (도구: `submit_memory` )\n\n * 방법: POST\n\n * 설명: 새로운 추억을 만들어 보세요\n\n * 인증: 베어러 토큰\n\n * 요청: 메모리 텍스트, 권한 수준 및 만료 날짜(ISO 8601 형식, 예: \"2025-12-31T23:59:59Z\")\n\n * 응답: UUID 식별자를 포함한 메모리 세부 정보가 생성되었습니다.\n\n * 요청 예시:\n\n ```json\n {\n \"tool\": \"submit_memory\",\n \"data\": {\n \"text\": \"This is my memory content\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **기억 검색** : `/api/tools` (도구: `retrieve_memories` )\n\n * 방법: POST\n\n * 설명: 인증된 사용자에 대한 모든 메모리를 가져옵니다.\n\n * 인증: 베어러 토큰\n\n * 응답: UUID 식별자가 있는 메모리 객체 목록\n\n * 요청 예시:\n\n ```json\n {\n \"tool\": \"retrieve_memories\",\n \"data\": {}\n }\n ```\n\n* **메모리 업데이트** : `/api/tools` (도구: `update_memory` )\n\n * 방법: POST\n\n * 설명: 기존 메모리 업데이트\n\n * 인증: 베어러 토큰\n\n * 요청: 메모리 ID, 업데이트된 콘텐츠 및 선택적으로 업데이트된 만료 날짜(ISO 8601 형식)\n\n * 응답: 메모리 세부 정보가 업데이트되었습니다.\n\n * 요청 예시:\n\n ```json\n {\n \"tool\": \"update_memory\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"text\": \"Updated memory content\",\n \"expiration_date\": \"2026-01-01T00:00:00Z\"\n }\n }\n ```\n\n* **권한 수정** : `/api/tools` (도구: `modify_permissions` )\n\n * 방법: POST\n\n * 설명: 메모리 권한 수준 업데이트\n\n * 인증: 베어러 토큰\n\n * 요청: 메모리 UUID 및 새로운 권한 수준\n\n * 응답: 메모리 세부 정보가 업데이트되었습니다.\n\n * 요청 예시:\n\n ```json\n {\n \"tool\": \"modify_permissions\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"public\"\n }\n }\n ```\n\n* **쿼리 사용자** : `/api/tools` (도구: `query_user` )\n\n * 방법: POST\n\n * 설명: 메모리를 기반으로 사용자의 페르소나를 쿼리합니다(다른 사용자의 경우 공개, 자신의 경우 공개+비공개)\n\n * 인증: 베어러 토큰\n\n * 요청: 사용자 UUID 및 쿼리 프롬프트\n\n * 응답: 만료되지 않은 메모리를 포함하는 JSON(모든 유효한 메모리 또는 쿼리와 가장 유사한 상위 N개 메모리)\n\n * 응답: 사용자의 기억을 기반으로 AI가 생성하는 응답\n\n * 요청 예시:\n\n ```json\n {\n \"tool\": \"query_user\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"prompt\": \"What are your thoughts on artificial intelligence?\"\n }\n }\n ```\n\n## 설정 및 배포\n\n### 필수 조건\n\n* Docker와 Docker Compose\n* 파이썬 3.10+\n* OpenAI API 키\n\n### 전체 설정 가이드\n\n1. 저장소를 복제합니다.\n\n ```bash\n git clone https://github.com/yourusername/picard_mcp.git\n cd picard_mcp\n ```\n\n2. 두 구성 요소에 대한 환경 파일을 만듭니다.\n\n ```bash\n # For MCP server\n cp mcp_server/.env.example mcp_server/.env\n\n # For Django client\n cp django_client/.env.example django_client/.env\n ```\n\n3. 구성을 설정하려면 환경 파일을 편집하세요.\n\n * `mcp_server/.env` 에서: 데이터베이스 자격 증명, OpenAI API 키 및 관리자 자격 증명을 설정합니다.\n * `django_client/.env` 에서: 데이터베이스 자격 증명과 OAuth 설정을 설정합니다.\n\n4. Docker Compose를 사용하여 서비스를 시작합니다.\n\n ```bash\n docker-compose up -d\n ```\n\n 그러면 다음 서비스가 시작됩니다.\n\n * `db-mcp` : MCP 서버용 PostgreSQL 데이터베이스\n * `db-django` : Django 클라이언트용 PostgreSQL 데이터베이스\n * `mcp_server` : 에서 실행되는 MCP 서버\n * `django_client` : 에서 실행되는 Django 클라이언트\n\n5. MCP 서버에 대한 관리자 사용자를 만듭니다.\n\n ```bash\n docker-compose exec mcp_server python scripts/create_admin_user.py\n ```\n\n 이렇게 하면 환경 변수에 지정된 자격 증명을 사용하는 관리자 사용자가 생성됩니다.\n\n6. Django 클라이언트를 MCP 서버에 등록합니다.\n\n ```bash\n docker-compose exec django_client python register_oauth_client.py\n ```\n\n 이렇게 하면 Django 클라이언트가 MCP 서버에 등록되고 Django 클라이언트의 `.env` 파일이 클라이언트 자격 증명으로 업데이트됩니다.\n\n7. 애플리케이션에 접속하세요:\n\n * MCP 서버: \n * Django 클라이언트: \n\n8. Django 클라이언트에서 사용자 계정을 만들고 애플리케이션 사용을 시작하세요.\n\n### 초기 테스트\n\n설정이 올바르게 작동하는지 확인하려면 다음 테스트를 실행하세요.\n\n1. **MCP 서버 테스트** :\n\n ```bash\n docker-compose exec mcp_server python -m pytest\n ```\n\n 이렇게 하면 OAuth 엔드포인트, 관리 기능, 메모리 관리를 포함하여 MCP 서버에 대한 모든 단위 테스트가 실행됩니다.\n\n2. **Django 클라이언트 테스트** :\n\n ```bash\n docker-compose exec django_client python manage.py test\n ```\n\n 이는 Django 클라이언트와 MCP 서버의 통합을 테스트합니다.\n\n3. **수동 테스트** :\n\n * 에서 Django 클라이언트에 사용자 계정을 만듭니다.\n * OAuth를 통해 MCP 서버에 로그인하고 연결합니다.\n * 추억을 만들고, 검색하고, 관리하세요\n * 의미 검색 기능을 테스트하세요\n\n## 보안 고려 사항\n\n### 데이터 보호\n\n* 메모리 텍스트 콘텐츠는 PKCS7 패딩이 있는 CBC 모드에서 AES-128을 사용하여 Python의 Fernet 대칭 암호화를 사용하여 암호화되며 메타데이터는 검색 가능한 상태로 유지됩니다.\n* 개인 식별 정보(PII)는 텍스트 필드 암호화를 통해 보호됩니다.\n* 액세스 토큰은 노출을 제한하기 위해 1시간의 만료 시간을 갖습니다.\n* 새로 고침 토큰은 수명이 길지만 회전을 사용합니다. 사용할 때마다 새 새로 고침 토큰이 생성되고 이전 토큰은 무효화됩니다.\n* OAuth 토큰은 Django 클라이언트의 PostgreSQL 데이터베이스에 안전하게 저장됩니다.\n\n### UUID 사용\n\n시스템의 모든 식별자는 여러 가지 이유로 순차적인 정수 대신 UUID v4 형식을 사용합니다.\n\n1. **보안** : UUID는 시스템 정보나 레코드 수를 노출하지 않습니다.\n2. **확장성** : 데이터베이스 조정 없이 UUID를 생성할 수 있으므로 분산 시스템이 가능합니다.\n3. **추측 불가능** : UUID는 사실상 추측이 불가능하므로 열거형 공격이 방지됩니다.\n4. **일관성** : 시스템 전체에서 UUID를 사용하면 다른 서비스와의 통합이 간소화됩니다.\n\nAPI의 모든 ID(user\\_id, memory\\_id, client\\_id 등)는 UUID 형식이어야 합니다.\n\n### OAuth 모범 사례\n\n* 모든 OAuth 통신은 프로덕션 환경에서 HTTPS를 사용해야 합니다.\n* 승인 코드는 한 번만 사용 가능하며 유효 기간이 짧습니다(최대 5분).\n* PKCE는 심층 방어를 위해 기밀 클라이언트를 포함한 모든 클라이언트에게 필요합니다.\n* 새로 고침 토큰은 장기적으로 유효하지만 사용자 또는 관리자가 취소할 수 있습니다.\n* 시스템은 취소된 토큰에 대한 토큰 블랙리스트를 유지합니다.\n\n## 선적 서류 비치\n\n### API 문서\n\nMCP 서버에는 모든 엔드포인트에 대한 Swagger/OpenAPI 문서가 포함되어 있습니다.\n\n* 서버가 실행 중일 때 `/docs` 에서 Swagger UI에 액세스합니다.\n* OpenAPI 사양은 `/openapi.json` 에서 확인할 수 있습니다.\n* 모든 API 엔드포인트는 요청/응답 스키마와 예제를 통해 완전히 문서화됩니다.\n\n### 추가 문서 파일\n\n* **TESTING.md** : 애플리케이션 테스트를 위한 포괄적인 가이드\n\n * 구현된 모든 테스트와 그 목적을 설명합니다.\n * 로컬 및 CI/CD에서 테스트를 실행하기 위한 지침\n * 문서 테스트 범위를 확인하고 추가 테스트가 필요한 영역을 식별합니다.\n\n* **DEBUGGING.md** : 문제와 해결 방법을 추적합니다.\n\n * 아직 수정되지 않은 알려진 버그를 기록합니다.\n * 이전에 해결된 버그와 그 해결책을 문서화합니다.\n * 일반적인 문제에 대한 문제 해결 지침을 제공합니다.\n\n* **PLANNING.md** : 사이트 구현에 필요한 작업의 세부 내용을 추적합니다.\n\n * 사이트를 구현하는 데 필요한 작업 및 하위 작업을 나열합니다.\n * 체크박스로 작업이 완료되었는지 문서화합니다.\n\n## 전개\n\n이 프로젝트에는 로컬 개발을 위한 `docker-compose.yml` 과 Render에 배포하기 위한 `render.yaml` 청사진이 포함되어 있습니다. 동일한 코드베이스가 Docker 컨테이너에서 로컬로 실행되며 Render 클라우드 서비스에 배포될 때도 작동합니다.\n\n### MCP 서버 배포\n\n1. **Docker 배포** (프로덕션에 권장):\n\n ```bash\n docker-compose up -d\n ```\n\n Docker Compose 구성에는 다음이 포함됩니다.\n\n * 컨테이너 간 통신을 위한 네트워크 구성\n * 영구 데이터 저장을 위한 볼륨 마운트\n * .env 파일에서 환경 변수 구성\n * 포트 매핑(Django 클라이언트의 경우 8000, MCP 서버의 경우 8001)\n * 서비스 종속성에 대한 상태 점검\n\n2. **Render Cloud 배포** : 포함된 `render.yaml` 블루프린트를 사용하여 Render에 배포합니다.\n\n## 특허\n\nMIT","Korean","ko-KR",{"_27":68,"_35":72,"_37":73},{"_29":69,"_31":70,"_33":71},"Реализация протокола контекста модели (MCP) на базе Django для управления политическими предпочтениями и видением будущего.","MCP-сервер","# Пикард MCP Сервер\n\n## Обзор\n\nPicard MCP — это полноценная система управления памятью, построенная на стандарте [Model Context Protocol (MCP)](https://modelcontextprotocol.io) . Она состоит из двух основных компонентов: сервера MCP, который предоставляет безопасные службы хранения и извлечения памяти, и клиентского приложения Django, которое демонстрирует, как интегрироваться с сервером MCP. Система позволяет пользователям хранить, извлекать и управлять своими воспоминаниями, контролируя разрешения на доступ, а также позволяет выполнять семантический поиск и запросы на основе ИИ на основе сохраненных воспоминаний.\n\n### Соответствие MCP\n\nЭта реализация следует стандарту Model Context Protocol, который позволяет приложениям LLM взаимодействовать с сервером стандартизированным образом. Сервер MCP предоставляет:\n\n* **Ресурсы** : конечные точки только для чтения, которые предоставляют данные LLM (содержимое памяти)\n* **Инструменты** : функциональные конечные точки, которые выполняют действия (создание памяти, обновления, запросы)\n* **Аутентификация** : реализация OAuth 2.0 для безопасного доступа к защищенным ресурсам\n\n### Ключевые компоненты\n\n1. **MCP Server** : реализация протокола контекста модели на базе FastAPI, которая обеспечивает:\n\n * Аутентификация и авторизация OAuth 2.0 с поддержкой PKCE\n * Хранилище памяти с векторными вложениями\n * Контроль доступа к памяти на основе разрешений\n * Интеграция LLM для запросов на основе памяти\n\n2. **Клиент Django** : веб-приложение, демонстрирующее интеграцию с сервером MCP:\n\n * Регистрация и аутентификация пользователя\n * Реализация клиента OAuth 2.0\n * Пользовательский интерфейс создания, извлечения и управления памятью\n * Интерфейс запросов на основе персоны\n\n## Архитектура системы\n\n### Общая архитектура\n\nСистема Picard MCP имеет архитектуру клиент-сервер и включает в себя следующие компоненты:\n\n1. **MCP Server** : основная внутренняя служба, которая управляет хранением памяти, извлечением данных и операциями ИИ.\n\n * Создан с использованием FastAPI (FastMCP) для высокой производительности и асинхронной поддержки\n * Использует PostgreSQL с расширением pgvector для векторного хранения и семантического поиска\n * Реализует модели данных для пользователей, воспоминаний (с векторными вложениями), клиентов OAuth и токенов.\n * Использует SQLAlchemy ORM с миграциями Alembic для управления базами данных\n * Реализует OAuth 2.0 для безопасной аутентификации и авторизации\n * Интегрируется с API OpenAI для встраивания памяти (text-embedding-3-small)\n * Использует LangChain для операций LLM, если доступно\n * Обеспечивает как режимы работы с сохранением состояния, так и режимы работы без сохранения состояния\n * Поддерживает потоковую передачу HTTP для лучшей масштабируемости\n\n2. **Django Client** : веб-приложение, демонстрирующее интеграцию с сервером MCP\n\n * Обеспечивает регистрацию пользователей, аутентификацию и управление профилями\n * Реализует клиент OAuth 2.0 для безопасного взаимодействия с сервером MCP\n * Предлагает удобный интерфейс для управления памятью и выполнения запросов.\n * Использует собственную базу данных PostgreSQL, отдельную от сервера MCP\n\n3. **Инфраструктура Docker** : контейнерное развертывание для легкой настройки и масштабирования\n\n * Отдельные контейнеры для сервера MCP (порт 8001), клиента Django (порт 8000) и баз данных PostgreSQL\n * Настроенная сеть для безопасной связи между контейнерами\n * Монтирование тома для постоянного хранения данных\n * Совместимо как с локальным развертыванием Docker, так и с развертыванием облака Render.\n\n### Подходы к аутентификации\n\nСистема предлагает два основных подхода к аутентификации:\n\n#### 1. Прямое подключение к потоку маркеров контекста пользователя (рекомендуется)\n\nЭтот упрощенный подход позволяет пользователям проходить аутентификацию только один раз с помощью клиента Django, избегая необходимости в отдельной аутентификации на сервере MCP:\n\n1. **Регистрация клиента** :\n\n * Клиент Django регистрируется на сервере MCP, используя конечную точку `/api/admin/clients/register`\n * Регистрация требует аутентификации администратора и включает имя клиента, URI перенаправления и запрошенные области действия.\n * Сервер MCP выдает клиентский идентификатор на основе UUID и криптографически защищенный клиентский секрет\n * Учетные данные клиента должны храниться в безопасности и никогда не раскрываться в клиентском коде.\n\n2. **Процесс аутентификации пользователя** :\n\n * Пользователь аутентифицируется только с помощью клиента Django\n * Когда пользователь инициирует подключение к серверу MCP, клиент Django отправляет запрос на стороне сервера к конечной точке MCP `/api/user-tokens/user-token`\n * Запрос включает в себя:\n * Учетные данные клиента (client\\_id и client\\_secret)\n * Информация о пользователе (имя пользователя и адрес электронной почты)\n * Возможность создания пользователя, если он не существует\n * Сервер MCP проверяет учетные данные клиента и либо находит, либо создает соответствующего пользователя.\n * Сервер MCP выдает токены доступа и обновления для пользователя\n * Клиент Django надежно хранит эти токены и использует их для запросов API.\n\n3. **API-доступ** :\n\n * Клиент включает токен доступа в заголовок Authorization ( `Authorization: Bearer {token}` ) для всех запросов API.\n * Сервер MCP проверяет подпись токена, срок действия и заявления аудитории\n * Сервер MCP применяет разрешения на основе области действия для каждой конечной точки\n * Когда срок действия токена доступа истекает, клиент использует токен обновления для получения нового.\n\n4. **Функции безопасности** :\n\n * Только конфиденциальные клиенты могут использовать этот метод, обеспечивая безопасность на уровне сервер-сервер.\n * Учетные данные клиента проверяются для каждого запроса токена.\n * Токены заносятся в черный список после использования для предотвращения атак повторного воспроизведения.\n * Токены обновления используют ротацию: каждое использование генерирует новый токен обновления и делает старый недействительным.\n\n#### 2. Стандартный поток кода авторизации OAuth 2.0 с PKCE (устаревший)\n\nСистема также поддерживает стандартный поток кода авторизации OAuth 2.0 с PKCE для повышения безопасности в соответствии со стандартами RFC 6749 и RFC 7636. Этот подход требует от пользователей аутентификации как на клиенте, так и на сервере MCP:\n\n1. **Поток авторизации** :\n\n * Пользователь инициирует вход через клиент Django\n * Клиент генерирует криптографически безопасный случайный параметр `state` для защиты от CSRF\n * Клиент генерирует случайный PKCE `code_verifier` и выводит `code_challenge` с помощью SHA-256\n * Клиент перенаправляется на конечную точку `/authorize` сервера MCP с помощью:\n * `response_type=code`\n * `client_id` (формат UUID)\n * `redirect_uri`\n * `scope` (список, разделенный пробелами, например, `memories:read memories:write` )\n * `state` (для защиты от CSRF)\n * Параметры PKCE ( `code_challenge` и `code_challenge_method=S256` )\n * Сервер MCP аутентифицирует пользователя (если он еще не аутентифицирован)\n * Сервер MCP проверяет все параметры и перенаправляет обратно клиенту с кратковременным кодом авторизации.\n\n2. **Обмен токенами** :\n\n * Клиент проверяет, соответствует ли возвращаемый параметр `state` параметру, отправленному в запросе авторизации.\n * Клиент обменивается кодом авторизации на токены доступа и обновления через конечную точку `/token`\n * Сервер MCP выдает токен доступа JWT, токен обновления, время истечения срока действия и предоставленные области действия\n\n3. **API-доступ** :\n\n * То же, что и в подходе Direct Connect\n\n### Модели баз данных\n\nСервер MCP использует SQLAlchemy ORM со следующими ключевыми моделями:\n\n1. **Модель пользователя** :\n\n * Сохраняет информацию о пользователе с адресом электронной почты, именем пользователя и хешированным паролем.\n * Включает логические флаги для статуса учетной записи (is\\_active, is\\_superuser)\n * Связано с воспоминаниями через отношение «один ко многим»\n\n2. **Модель памяти с векторным хранением** :\n\n * Использует расширение pgvector для хранения и запроса векторных вложений (1536 измерений)\n * Поддерживает текстовый контент с возможностью шифрования.\n * Включает элементы управления разрешениями (частные/публичные)\n * Поддерживает даты истечения срока действия для ограниченных по времени воспоминаний\n * Связан с пользователями через связь внешнего ключа\n\n3. **Модели OAuth** :\n\n * **OAuthClient** : хранит данные клиентского приложения, включая client\\_id, client\\_secret, URI перенаправления и авторизованные области действия.\n * **AuthorizationCode** : управляет временными кодами авторизации с поддержкой PKCE.\n * **Токен** : хранит токены доступа и обновления с отслеживанием срока действия.\n\nСистема использует Alembic для миграции баз данных, обеспечивая управление версиями схем и простоту обновлений.\n\n### Система управления памятью\n\nОсновная функциональность Picard MCP сосредоточена вокруг управления памятью с помощью следующих компонентов:\n\n1. **Память хранения** :\n\n * Воспоминания хранятся в виде текста с соответствующими метаданными.\n * Векторные вложения (с использованием модели text-embedding-3-small) обеспечивают возможности семантического поиска\n * Разрешения контролируют, кто может получить доступ к каждому воспоминанию.\n * Временные метки отслеживают создание, изменение и истечение срока действия\n * Текст памяти шифруется при хранении, а метаданные остаются доступными для поиска\n * Все идентификаторы используют формат UUID вместо последовательных целых чисел для масштабируемости.\n * Каждая память преобразуется в векторное вложение с использованием модели вложения OpenAI.\n * Встраивание позволяет осуществлять семантический поиск и сопоставление сходств\n * PostgreSQL с расширением pgvector обеспечивает эффективное хранение и извлечение векторов\n\n2. **Управление разрешениями** :\n\n * Каждое воспоминание имеет уровень доступа (частный или публичный)\n * Личные воспоминания доступны только владельцу.\n * Публичные воспоминания могут быть доступны другим пользователям для запросов персон.\n * Система разработана с возможностью расширения для будущих типов разрешений (например, для статистического/агрегированного использования)\n * Доступ к общим воспоминаниям могут получить определенные пользователи или группы.\n * Владелец памяти может изменить разрешения в любое время.\n\n3. **Восстановление памяти** :\n\n * Пользователи могут извлекать собственные воспоминания с помощью функций фильтрации и сортировки.\n * Семантический поиск позволяет находить воспоминания на основе смысла, а не только ключевых слов.\n * Вектор сходства (косинус) позволяет находить связанные воспоминания в базе данных.\n * Возвращаются первые N наиболее похожих воспоминаний на основе релевантности запроса\n * Проверка разрешений гарантирует, что пользователи имеют доступ только к авторизованным воспоминаниям.\n\n4. **Интеграция LLM** :\n\n * Воспоминания могут использоваться в качестве контекста для запросов LLM.\n * Пользователи могут создавать персоны на основе своих публичных воспоминаний.\n * Другие пользователи могут запрашивать эти персоны, чтобы получать ответы, основанные на воспоминаниях.\n * Система автоматически управляет контекстным управлением и выполняет инжиниринг подсказок.\n\n## Основные характеристики\n\n### Возможности сервера MCP\n\n* **Аутентификация OAuth 2.0** :\n\n * Поток кода авторизации с PKCE для повышения безопасности\n * Система разрешений на основе области действия ( `memories:read` , `memories:write` , `memories:admin` )\n * Управление токенами с поддержкой обновления токенов\n * Регистрация и управление клиентами\n\n* **Управление памятью** :\n\n * Создавайте, читайте, обновляйте и удаляйте воспоминания\n * Встраивание векторов для семантического поиска\n * Контроль доступа на основе разрешений\n * Пакетные операции для эффективного управления памятью\n\n* **Управление пользователями** :\n\n * Регистрация и аутентификация пользователя\n * Управление профилем и настройки\n * Отслеживание активности и аналитика\n * Административные элементы управления системой\n\n* **Интеграция ИИ** :\n\n * Интеграция API OpenAI для встраивания и запросов LLM\n * Создание персоны на основе воспоминаний пользователя\n * Обработка запросов с учетом контекста\n * Настраиваемые параметры и настройки ИИ\n\n### Возможности клиента Django\n\n* **Пользовательский интерфейс** :\n\n * Чистый, адаптивный дизайн для настольных компьютеров и мобильных устройств\n * Интуитивно понятный интерфейс управления памятью\n * Расширенные возможности поиска и фильтрации\n * Интерфейс создания персоны и запросов\n\n* **Реализация клиента OAuth** :\n\n * Безопасное хранение и управление токенами\n * Автоматическое обновление токена\n * Доступность функций на основе области применения\n * Обработка ошибок и восстановление\n\n* **Инструменты памяти** :\n\n * Создание памяти с поддержкой форматированного текста\n * Пакетный импорт и экспорт\n * Интерфейс управления разрешениями\n * Тегирование и категоризация\n\n## Интерфейс МКП\n\n### Ресурсы МКП\n\n* **Ресурс памяти** : `memories://{memory_id}`\n\n * Возвращает содержимое определенной памяти с проверкой разрешений.\n * Параметры: memory\\_id (UUID)\n * Ответ: Содержимое памяти с метаданными\n\n* **Ресурс воспоминаний пользователя** : `users://{user_id}/memories`\n\n * Возвращает список воспоминаний для определенного пользователя с проверкой разрешений.\n * Параметры: user\\_id (UUID), необязательные фильтры\n * Ответ: Список сводок памяти\n\n### Инструменты МКП\n\n* **Инструмент «Отправить память»** : создает новое воспоминание\n\n * Параметры: текст (строка), разрешение (строка)\n * Возвращает: Созданные данные памяти с UUID\n\n* **Инструмент обновления памяти** : обновляет существующую память.\n\n * Параметры: memory\\_id (UUID), текст (строка)\n * Возвращает: обновленные данные памяти.\n\n* **Инструмент удаления памяти** : удаляет память.\n\n * Параметры: memory\\_id (UUID)\n * Возврат: Подтверждение успеха\n\n* **Инструмент запроса памяти** : выполняет семантический поиск в воспоминаниях.\n\n * Параметры: запрос (строка), предел (целое число)\n * Возвращает: Список соответствующих воспоминаний.\n\n* **Запрос пользователя** : запрашивает личность пользователя на основе воспоминаний.\n\n * Параметры: user\\_id (UUID), запрос (строка)\n * Возвращает: ответ, основанный на воспоминаниях пользователя.\n\n## Конечные точки API\n\n### Конечные точки OAuth\n\n* **Регистрация клиента** : `/register`\n\n * Метод: ПОСТ\n * Описание: Регистрация нового клиента OAuth.\n * Запрос: данные клиента (идентификатор, секрет, URI перенаправления, области действия)\n * Ответ: Учетные данные клиента и регистрационная информация\n\n* **Авторизация** : `/authorize`\n\n * Метод: ПОЛУЧИТЬ\n * Описание: Инициировать процесс авторизации OAuth\n * Параметры: response\\_type, client\\_id, redirect\\_uri, scope, state, code\\_challenge, code\\_challenge\\_method\n * Ответ: Перенаправляет клиенту с кодом авторизации\n\n* **Обмен токенами** : `/token`\n\n * Метод: ПОСТ\n * Описание: Обмен кода авторизации на токены\n * Запрос: grant\\_type, code, redirect\\_uri, client\\_id, client\\_secret, code\\_verifier\n * Ответ: токен доступа, токен обновления, срок действия и информация о области действия\n\n### Конечные точки памяти\n\n* **Получить воспоминания** : `/api/tools` (инструмент: `get_memories` )\n\n * Метод: ПОСТ\n\n * Описание: Извлечение воспоминаний с возможностью фильтрации.\n\n * Аутентификация: токен на предъявителя\n\n * Запрос: Необязательные параметры фильтра (user\\_id, разрешение, срок действия)\n\n * Ответ: Список воспоминаний, доступных пользователю.\n\n * Пример запроса:\n\n ```json\n {\n \"tool\": \"get_memories\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **Отправить память** : `/api/tools` (инструмент: `submit_memory` )\n\n * Метод: ПОСТ\n\n * Описание: Создайте новое воспоминание.\n\n * Аутентификация: токен на предъявителя\n\n * Запрос: текст памяти, уровень разрешения и дата истечения срока действия (формат ISO 8601, например, «2025-12-31T23:59:59Z»)\n\n * Ответ: Созданные данные памяти, включая идентификатор UUID.\n\n * Пример запроса:\n\n ```json\n {\n \"tool\": \"submit_memory\",\n \"data\": {\n \"text\": \"This is my memory content\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **Извлечь воспоминания** : `/api/tools` (инструмент: `retrieve_memories` )\n\n * Метод: ПОСТ\n\n * Описание: Получить все воспоминания для аутентифицированного пользователя.\n\n * Аутентификация: токен на предъявителя\n\n * Ответ: Список объектов памяти с идентификаторами UUID\n\n * Пример запроса:\n\n ```json\n {\n \"tool\": \"retrieve_memories\",\n \"data\": {}\n }\n ```\n\n* **Обновление памяти** : `/api/tools` (инструмент: `update_memory` )\n\n * Метод: ПОСТ\n\n * Описание: Обновление существующей памяти.\n\n * Аутентификация: токен на предъявителя\n\n * Запрос: идентификатор памяти, обновленное содержимое и опционально обновленная дата истечения срока действия (формат ISO 8601)\n\n * Ответ: Обновленные данные памяти.\n\n * Пример запроса:\n\n ```json\n {\n \"tool\": \"update_memory\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"text\": \"Updated memory content\",\n \"expiration_date\": \"2026-01-01T00:00:00Z\"\n }\n }\n ```\n\n* **Изменить разрешения** : `/api/tools` (инструмент: `modify_permissions` )\n\n * Метод: ПОСТ\n\n * Описание: Обновление уровня разрешений памяти.\n\n * Аутентификация: токен на предъявителя\n\n * Запрос: UUID памяти и новый уровень разрешений\n\n * Ответ: Обновленные данные памяти.\n\n * Пример запроса:\n\n ```json\n {\n \"tool\": \"modify_permissions\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"public\"\n }\n }\n ```\n\n* **Запрос пользователя** : `/api/tools` (tool: `query_user` )\n\n * Метод: ПОСТ\n\n * Описание: Запрос персоны пользователя на основе воспоминаний (публичная для других пользователей, публичная+личная для себя)\n\n * Аутентификация: токен на предъявителя\n\n * Запрос: UUID пользователя и запрос запроса\n\n * Ответ: JSON, содержащий неистекшие воспоминания, либо все действительные воспоминания, либо первые N наиболее похожих на запрос\n\n * Ответ: ответ, сгенерированный искусственным интеллектом на основе воспоминаний пользователя.\n\n * Пример запроса:\n\n ```json\n {\n \"tool\": \"query_user\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"prompt\": \"What are your thoughts on artificial intelligence?\"\n }\n }\n ```\n\n## Настройка и развертывание\n\n### Предпосылки\n\n* Docker и Docker Compose\n* Питон 3.10+\n* API-ключ OpenAI\n\n### Полное руководство по настройке\n\n1. Клонируйте репозиторий:\n\n ```bash\n git clone https://github.com/yourusername/picard_mcp.git\n cd picard_mcp\n ```\n\n2. Создайте файлы среды для обоих компонентов:\n\n ```bash\n # For MCP server\n cp mcp_server/.env.example mcp_server/.env\n\n # For Django client\n cp django_client/.env.example django_client/.env\n ```\n\n3. Отредактируйте файлы среды, чтобы задать свою конфигурацию:\n\n * В `mcp_server/.env` : задайте учетные данные базы данных, ключ API OpenAI и учетные данные администратора.\n * В `django_client/.env` : установите учетные данные базы данных и настройки OAuth.\n\n4. Запустите службы с помощью Docker Compose:\n\n ```bash\n docker-compose up -d\n ```\n\n Это запустит следующие службы:\n\n * `db-mcp` : База данных PostgreSQL для сервера MCP\n * `db-django` : База данных PostgreSQL для клиента Django\n * `mcp_server` : MCP-сервер, работающий на \n * `django_client` : Клиент Django, работающий на \n\n5. Создайте пользователя-администратора для сервера MCP:\n\n ```bash\n docker-compose exec mcp_server python scripts/create_admin_user.py\n ```\n\n Это создаст пользователя-администратора с учетными данными, указанными в переменных среды.\n\n6. Зарегистрируйте клиент Django на сервере MCP:\n\n ```bash\n docker-compose exec django_client python register_oauth_client.py\n ```\n\n Это зарегистрирует клиент Django на сервере MCP и обновит файл `.env` клиента Django с использованием учетных данных клиента.\n\n7. Доступ к приложениям:\n\n * MCP-сервер: \n * Клиент Django: \n\n8. Создайте учетную запись пользователя в клиенте Django и начните использовать приложение.\n\n### Первоначальное тестирование\n\nЧтобы проверить правильность работы вашей настройки, выполните следующие тесты:\n\n1. **Тесты сервера MCP** :\n\n ```bash\n docker-compose exec mcp_server python -m pytest\n ```\n\n Это запустит все модульные тесты для сервера MCP, включая конечные точки OAuth, функции администрирования и управление памятью.\n\n2. **Тесты клиента Django** :\n\n ```bash\n docker-compose exec django_client python manage.py test\n ```\n\n Это позволит протестировать интеграцию клиента Django с сервером MCP.\n\n3. **Ручное тестирование** :\n\n * Создайте учетную запись пользователя в клиенте Django по адресу \n * Авторизуйтесь и подключитесь к серверу MCP через OAuth\n * Создавайте, извлекайте и управляйте воспоминаниями\n * Тестирование функциональности семантического поиска\n\n## Соображения безопасности\n\n### Защита данных\n\n* Содержимое текстовой памяти шифруется при хранении с помощью симметричного шифрования Python Fernet (AES-128 в режиме CBC с дополнением PKCS7), при этом метаданные остаются доступными для поиска.\n* Персональные данные (PII) защищены с помощью шифрования текстовых полей.\n* Срок действия токенов доступа составляет 1 час, что позволяет ограничить риск\n* Токены обновления долговечны, но используют ротацию: каждое использование генерирует новый токен обновления и делает старый недействительным.\n* Токены OAuth надежно хранятся в базе данных PostgreSQL клиента Django.\n\n### Использование UUID\n\nВсе идентификаторы в системе используют формат UUID v4 вместо последовательных целых чисел по нескольким причинам:\n\n1. **Безопасность** : UUID не раскрывают системную информацию или количество записей.\n2. **Масштабируемость** : универсальные уникальные идентификаторы (UUID) могут генерироваться без координации с базой данных, что позволяет использовать распределенные системы.\n3. **Невозможность угадывания** : UUID практически невозможно угадать, что предотвращает атаки методом перечисления.\n4. **Согласованность** : использование UUID во всей системе упрощает интеграцию с другими службами.\n\nВсе идентификаторы в API (user\\_id, memory\\_id, client\\_id и т. д.) должны быть в формате UUID.\n\n### Лучшие практики OAuth\n\n* Все коммуникации OAuth должны использовать HTTPS в производственных средах.\n* Коды авторизации являются одноразовыми и имеют короткий срок действия (максимум 5 минут).\n* PKCE требуется для всех клиентов, даже конфиденциальных, для глубокой защиты\n* Токены обновления долговечны, но могут быть отозваны пользователями или администраторами.\n* Система ведет черный список токенов для отозванных токенов.\n\n## Документация\n\n### API-документация\n\nСервер MCP включает документацию Swagger/OpenAPI для всех конечных точек:\n\n* Доступ к пользовательскому интерфейсу Swagger по адресу `/docs` при работающем сервере.\n* Спецификация OpenAPI доступна по адресу `/openapi.json`\n* Все конечные точки API полностью документированы со схемами запросов/ответов и примерами.\n\n### Дополнительные файлы документации\n\n* **TESTING.md** : Полное руководство по тестированию приложения\n\n * Описывает все реализованные тесты и их цели\n * Инструкции по запуску тестов локально и в CI/CD\n * Документирует охват тестированием и определяет области, требующие дополнительного тестирования.\n\n* **DEBUGGING.md** : отслеживает проблемы и их решения\n\n * Регистрирует известные ошибки, которые еще не исправлены.\n * Документы ранее решенных ошибок и их решения\n * Предоставляет руководство по устранению распространенных неполадок\n\n* **PLANNING.md** : Отслеживает распределение задач, необходимых для реализации сайта.\n\n * Перечисляет задачи и подзадачи, необходимые для реализации сайта\n * Документирует, выполнено ли задание, с помощью флажка\n\n## Развертывание\n\nЭтот проект включает `docker-compose.yml` для локальной разработки и `render.yaml` для развертывания в Render. Та же кодовая база работает как локально в контейнерах Docker, так и при развертывании в облачных сервисах Render.\n\n### Развертывание сервера MCP\n\n1. **Развертывание Docker** (рекомендуется для производства):\n\n ```bash\n docker-compose up -d\n ```\n\n Конфигурация Docker Compose включает в себя:\n\n * Конфигурация сети для межконтейнерной связи\n * Монтирование томов для постоянного хранения данных\n * Конфигурация переменных среды из файлов .env\n * Сопоставление портов (8000 для клиента Django, 8001 для сервера MCP)\n * Проверки работоспособности зависимостей служб\n\n2. **Развертывание Render Cloud** : используйте прилагаемый проект `render.yaml` для развертывания в Render.\n\n## Лицензия\n\nМассачусетский технологический институт","Russian","ru-RU",{"_27":75,"_35":79,"_37":80},{"_29":76,"_31":77,"_33":78},"基于 Django 的模型上下文协议 (MCP) 实现，用于管理政治偏好和未来愿景。","MCP 服务器","# Picard MCP 服务器\n\n## 概述\n\nPicard MCP 是一个基于[模型上下文协议 (MCP)](https://modelcontextprotocol.io)标准构建的完整内存管理系统。它由两个主要组件组成：一个提供安全内存存储和检索服务的 MCP 服务器，以及一个演示如何与 MCP 服务器集成的 Django 客户端应用程序。该系统允许用户在控制访问权限的同时存储、检索和管理他们的内存，并允许基于存储的内存进行语义搜索和 AI 查询。\n\n### MCP 合规性\n\n此实现遵循模型上下文协议 (MCP) 标准，该标准允许 LLM 应用程序以标准化方式与服务器交互。MCP 服务器公开：\n\n* **资源**：向 LLM 提供数据（内存内容）的只读端点\n* **工具**：执行操作的功能端点（内存创建、更新、查询）\n* **身份验证**：OAuth 2.0 实现，用于安全访问受保护的资源\n\n### 关键组件\n\n1. **MCP 服务器**：基于 FastAPI 的模型上下文协议实现，提供以下功能：\n\n * 支持 PKCE 的 OAuth 2.0 身份验证和授权\n * 带有向量嵌入的内存存储\n * 基于权限的内存访问控制\n * 基于内存的查询的 LLM 集成\n\n2. **Django 客户端**：演示与 MCP 服务器集成的 Web 应用程序：\n\n * 用户注册和身份验证\n * OAuth 2.0客户端实现\n * 内存创建、检索和管理 UI\n * 基于角色的查询界面\n\n## 系统架构\n\n### 总体架构\n\nPicard MCP 系统遵循客户端-服务器架构，具有以下组件：\n\n1. **MCP 服务器**：处理内存存储、检索和 AI 操作的核心后端服务\n\n * 采用 FastAPI（FastMCP）构建，提供高性能和异步支持\n * 使用带有 pgvector 扩展的 PostgreSQL 进行向量存储和语义搜索\n * 为用户、记忆（带有向量嵌入）、OAuth 客户端和令牌实现数据模型\n * 使用 SQLAlchemy ORM 和 Alembic 迁移进行数据库管理\n * 实施 OAuth 2.0 以实现安全身份验证和授权\n * 与 OpenAI API 集成以实现记忆嵌入 (text-embedding-3-small)\n * 在可用的情况下使用 LangChain 进行 LLM 操作\n * 提供有状态和无状态操作模式\n * 支持流式 HTTP 传输，以实现更好的可扩展性\n\n2. **Django 客户端**：演示与 MCP 服务器集成的 Web 应用程序\n\n * 提供用户注册、身份验证和配置文件管理\n * 实现 OAuth 2.0 客户端与 MCP 服务器进行安全通信\n * 提供用户友好的内存管理和查询界面\n * 使用独立于 MCP 服务器的 PostgreSQL 数据库\n\n3. **Docker 基础设施**：容器化部署，易于设置和扩展\n\n * MCP 服务器（端口 8001）、Django 客户端（端口 8000）和 PostgreSQL 数据库的独立容器\n * 配置网络以实现安全的容器间通信\n * 用于持久数据存储的卷安装\n * 兼容本地 Docker 部署和渲染云部署\n\n### 身份验证方法\n\n该系统提供两种主要的身份验证方法：\n\n#### 1. 直接连接用户上下文令牌流程（推荐）\n\n这种简化的方法允许用户仅使用 Django 客户端进行一次身份验证，从而避免了单独的 MCP 服务器身份验证：\n\n1. **客户注册**：\n\n * Django 客户端使用`/api/admin/clients/register`端点向 MCP 服务器注册\n * 注册需要管理员身份验证，包括客户端名称、重定向 URI 和请求的范围\n * MCP 服务器发布基于 UUID 的客户端 ID 和加密安全的客户端密钥\n * 客户端凭据应安全存储，并且永远不会在客户端代码中暴露\n\n2. **用户身份验证流程**：\n\n * 用户仅通过 Django 客户端进行身份验证\n * 当用户发起与 MCP 服务器的连接时，Django 客户端会向 MCP 的`/api/user-tokens/user-token`端点发出服务器端请求\n * 该请求包括：\n * 客户端凭证（client\\_id 和 client\\_secret）\n * 用户信息（用户名和电子邮件）\n * 如果不存在则创建用户的选项\n * MCP 服务器验证客户端凭据并查找或创建相应的用户\n * MCP 服务器为用户发放访问和刷新令牌\n * Django 客户端安全地存储这些令牌并将其用于 API 请求\n\n3. **API访问**：\n\n * 客户端在所有 API 请求的授权标头中包含访问令牌（ `Authorization: Bearer {token}` ）\n * MCP 服务器验证令牌签名、有效期和受众声明\n * MCP 服务器为每个端点强制执行基于范围的权限\n * 当访问令牌过期时，客户端使用刷新令牌获取新的访问令牌\n\n4. **安全功能**：\n\n * 只有机密客户端才能使用此方法，从而提供服务器到服务器的安全性\n * 针对每个令牌请求验证客户端凭据\n * 令牌使用后会被列入黑名单，以防止重放攻击\n * 刷新令牌使用轮换：每次使用都会生成一个新的刷新令牌并使旧令牌无效\n\n#### 2. 使用 PKCE 的标准 OAuth 2.0 授权码流程（遗留）\n\n该系统还支持带有 PKCE 的标准 OAuth 2.0 授权码流程，以增强安全性，遵循 RFC 6749 和 RFC 7636 标准。此方法要求用户同时在客户端和 MCP 服务器上进行身份验证：\n\n1. **授权流程**：\n\n * 用户通过 Django 客户端发起登录\n * 客户端生成加密安全的随机`state`参数以进行 CSRF 保护\n * 客户端生成随机 PKCE `code_verifier`并使用 SHA-256 派生`code_challenge`\n * 客户端重定向到 MCP 服务器的`/authorize`端点：\n * `response_type=code`\n * `client_id` （UUID格式）\n * `redirect_uri`\n * `scope` （以空格分隔的列表，例如， `memories:read memories:write` ）\n * `state` （用于 CSRF 保护）\n * PKCE 参数（ `code_challenge`和`code_challenge_method=S256` ）\n * MCP 服务器对用户进行身份验证（如果尚未进行身份验证）\n * MCP 服务器验证所有参数，并使用短期授权码重定向回客户端\n\n2. **代币兑换**：\n\n * 客户端验证返回的`state`参数与授权请求中发送的状态参数匹配\n * 客户端通过`/token`端点交换访问和刷新令牌的授权码\n * MCP 服务器发出 JWT 访问令牌、刷新令牌、到期时间和授予范围\n\n3. **API访问**：\n\n * 与直接连接方法相同\n\n### 数据库模型\n\nMCP 服务器使用 SQLAlchemy ORM 及其以下关键模型：\n\n1. **用户模型**：\n\n * 使用电子邮件、用户名和散列密码存储用户信息\n * 包括帐户状态的布尔标志（is\\_active、is\\_superuser）\n * 通过一对多关系链接到记忆\n\n2. **具有向量存储的内存模型**：\n\n * 使用 pgvector 扩展来存储和查询向量嵌入（1536 维）\n * 支持可选加密的文本内容\n * 包括权限控制（私人/公共）\n * 支持限时记忆的到期日期\n * 通过外键关系与用户关联\n\n3. **OAuth 模型**：\n\n * **OAuthClient** ：存储客户端应用程序详细信息，包括 client\\_id、client\\_secret、重定向 URI 和授权范围\n * **AuthorizationCode** ：使用 PKCE 支持管理临时授权码\n * **令牌**：存储访问和刷新令牌，并跟踪到期时间\n\n该系统使用 Alembic 进行数据库迁移，确保模式版本控制和轻松更新。\n\n### 内存管理系统\n\nPicard MCP 的核心功能围绕内存管理，包含以下组件：\n\n1. **内存存储**：\n\n * 记忆以文本形式存储，并附带相关元数据\n * 向量嵌入（使用 text-embedding-3-small 模型）支持语义搜索功能\n * 权限控制谁可以访问每个内存\n * 时间戳跟踪创建、修改和到期\n * 内存文本处于静态加密状态，但元数据仍可搜索\n * 所有标识符均使用 UUID 格式，而不是连续整数，以实现可扩展性\n * 使用 OpenAI 的嵌入模型将每个记忆转换为向量嵌入\n * 嵌入支持语义搜索和相似性匹配\n * 带有 pgvector 扩展的 PostgreSQL 提供高效的向量存储和检索\n\n2. **权限管理**：\n\n * 每个内存都有一个权限级别（私有或公共）\n * 私人记忆只有主人才能访问\n * 其他用户可以访问公共记忆以进行角色查询\n * 系统设计为可扩展以适应未来的权限类型（例如，用于统计/汇总用途）\n * 特定用户或群组可以访问共享记忆\n * 内存所有者可以随时修改权限\n\n3. **记忆检索**：\n\n * 用户可以通过筛选和排序选项检索自己的记忆\n * 语义搜索允许根据含义（而不仅仅是关键词）查找记忆\n * 向量相似度（余弦）可以在数据库中找到相关的记忆\n * 根据查询相关性返回 Top-N 最相似的记忆\n * 权限检查确保用户只能访问授权的记忆\n\n4. **LLM 集成**：\n\n * 记忆可以用作 LLM 查询的上下文\n * 用户可以根据自己的公开记忆创建角色\n * 其他用户可以查询这些角色，以获得记忆中的信息\n * 系统自动处理上下文管理和提示工程\n\n## 主要特点\n\n### MCP 服务器功能\n\n* **OAuth 2.0身份验证**：\n\n * 授权码流与 PKCE 配合使用，增强安全性\n * 基于范围的权限系统（ `memories:read` 、 `memories:write` 、 `memories:admin` ）\n * 支持刷新令牌的令牌管理\n * 客户注册和管理\n\n* **内存管理**：\n\n * 创建、读取、更新和删除记忆\n * 用于语义搜索的向量嵌入\n * 基于权限的访问控制\n * 批量操作以实现高效的内存管理\n\n* **用户管理**：\n\n * 用户注册和身份验证\n * 配置文件管理和设置\n * 活动追踪和分析\n * 系统管理的管理员控制\n\n* **人工智能集成**：\n\n * 用于嵌入和 LLM 查询的 OpenAI API 集成\n * 根据用户记忆创建角色\n * 上下文感知查询处理\n * 可定制的 AI 参数和设置\n\n### Django 客户端功能\n\n* **用户界面**：\n\n * 简洁、响应迅速的桌面和移动设备设计\n * 直观的内存管理界面\n * 高级搜索和过滤选项\n * 角色创建和查询界面\n\n* **OAuth客户端实现**：\n\n * 安全令牌存储和管理\n * 自动令牌刷新\n * 基于范围的功能可用性\n * 错误处理和恢复\n\n* **记忆工具**：\n\n * 创建具有富文本支持的内存\n * 批量导入导出\n * 权限管理接口\n * 标记和分类\n\n## MCP 接口\n\n### MCP 资源\n\n* **内存资源**： `memories://{memory_id}`\n\n * 返回具有权限检查的特定内存的内容\n * 参数：memory\\_id（UUID）\n * 响应：带有元数据的内存内容\n\n* **用户回忆资源**： `users://{user_id}/memories`\n\n * 返回具有权限检查的特定用户的记忆列表\n * 参数：user\\_id（UUID），可选过滤器\n * 响应：内存摘要列表\n\n### MCP 工具\n\n* **提交记忆工具**：创建新记忆\n\n * 参数：文本（字符串）、权限（字符串）\n * 返回：使用 UUID 创建的内存详细信息\n\n* **更新记忆工具**：更新现有记忆\n\n * 参数：memory\\_id（UUID）、text（字符串）\n * 返回：更新的内存详细信息\n\n* **删除记忆工具**：删除记忆\n\n * 参数：memory\\_id（UUID）\n * 返回：成功确认\n\n* **查询记忆工具**：对记忆进行语义搜索\n\n * 参数：查询（字符串）、限制（整数）\n * 返回：相关记忆列表\n\n* **查询用户**：根据记忆查询用户的角色\n\n * 参数：user\\_id（UUID）、query（字符串）\n * 返回：基于用户记忆的响应\n\n## API 端点\n\n### OAuth 端点\n\n* **客户注册**： `/register`\n\n * 方法：POST\n * 描述：注册一个新的 OAuth 客户端\n * 请求：客户端详细信息（ID、密钥、重定向 URI、范围）\n * 响应：客户端凭证和注册信息\n\n* **授权**： `/authorize`\n\n * 方法：GET\n * 描述：启动 OAuth 授权流程\n * 参数：response\\_type、client\\_id、redirect\\_uri、scope、state、code\\_challenge、code\\_challenge\\_method\n * 响应：使用授权码重定向到客户端\n\n* **代币兑换**： `/token`\n\n * 方法：POST\n * 描述：用授权码兑换令牌\n * 请求：grant\\_type、code、redirect\\_uri、client\\_id、client\\_secret、code\\_verifier\n * 响应：访问令牌、刷新令牌、到期日期和范围信息\n\n### 内存端点\n\n* **获取记忆**： `/api/tools` （工具： `get_memories` ）\n\n * 方法：POST\n\n * 描述：使用可选的筛选功能检索记忆\n\n * 身份验证：持有者令牌\n\n * 请求：可选的过滤参数（user\\_id、权限、过期状态）\n\n * 响应：用户可访问的记忆列表\n\n * 示例请求：\n\n ```json\n {\n \"tool\": \"get_memories\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **提交内存**： `/api/tools` （工具： `submit_memory` ）\n\n * 方法：POST\n\n * 描述：创建新的记忆\n\n * 身份验证：持有者令牌\n\n * 请求：内存文本、权限级别和到期日期（ISO 8601 格式，例如“2025-12-31T23:59:59Z”）\n\n * 响应：已创建内存详细信息，包括 UUID 标识符\n\n * 示例请求：\n\n ```json\n {\n \"tool\": \"submit_memory\",\n \"data\": {\n \"text\": \"This is my memory content\",\n \"permission\": \"private\"\n }\n }\n ```\n\n* **检索记忆**： `/api/tools` （工具： `retrieve_memories` ）\n\n * 方法：POST\n\n * 描述：获取已认证用户的所有记忆\n\n * 身份验证：持有者令牌\n\n * 响应：具有 UUID 标识符的内存对象列表\n\n * 示例请求：\n\n ```json\n {\n \"tool\": \"retrieve_memories\",\n \"data\": {}\n }\n ```\n\n* **更新内存**： `/api/tools` （工具： `update_memory` ）\n\n * 方法：POST\n\n * 描述：更新现有内存\n\n * 身份验证：持有者令牌\n\n * 请求：内存 ID、更新内容以及可选更新的到期日期（ISO 8601 格式）\n\n * 响应：更新了内存详细信息\n\n * 示例请求：\n\n ```json\n {\n \"tool\": \"update_memory\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"text\": \"Updated memory content\",\n \"expiration_date\": \"2026-01-01T00:00:00Z\"\n }\n }\n ```\n\n* **修改权限**： `/api/tools` （工具： `modify_permissions` ）\n\n * 方法：POST\n\n * 描述：更新内存权限级别\n\n * 身份验证：持有者令牌\n\n * 请求：内存UUID和新的权限级别\n\n * 响应：更新了内存详细信息\n\n * 示例请求：\n\n ```json\n {\n \"tool\": \"modify_permissions\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"public\"\n }\n }\n ```\n\n* **查询用户**： `/api/tools` （工具： `query_user` ）\n\n * 方法：POST\n\n * 描述：根据记忆查询用户的角色（对其他用户公开，对自己公开+私人）\n\n * 身份验证：持有者令牌\n\n * 请求：用户UUID和查询提示\n\n * 响应：包含未过期记忆的 JSON，可以是所有有效记忆，也可以是与查询最相似的前 N 个记忆\n\n * 响应：基于用户记忆的人工智能生成的响应\n\n * 示例请求：\n\n ```json\n {\n \"tool\": \"query_user\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"prompt\": \"What are your thoughts on artificial intelligence?\"\n }\n }\n ```\n\n## 设置和部署\n\n### 先决条件\n\n* Docker 和 Docker Compose\n* Python 3.10+\n* OpenAI API 密钥\n\n### 完整的安装指南\n\n1. 克隆存储库：\n\n ```bash\n git clone https://github.com/yourusername/picard_mcp.git\n cd picard_mcp\n ```\n\n2. 为两个组件创建环境文件：\n\n ```bash\n # For MCP server\n cp mcp_server/.env.example mcp_server/.env\n\n # For Django client\n cp django_client/.env.example django_client/.env\n ```\n\n3. 编辑环境文件来设置您的配置：\n\n * 在`mcp_server/.env`中：设置数据库凭据、OpenAI API 密钥和管理员凭据\n * 在`django_client/.env`中：设置数据库凭据和 OAuth 设置\n\n4. 使用 Docker Compose 启动服务：\n\n ```bash\n docker-compose up -d\n ```\n\n 这将启动以下服务：\n\n * `db-mcp` ：MCP 服务器的 PostgreSQL 数据库\n * `db-django` ：Django 客户端的 PostgreSQL 数据库\n * `mcp_server` ：运行于[http://localhost:8001 的](http://localhost:8001)MCP 服务器\n * `django_client` ：在上运行的 Django 客户端\n\n5. 为 MCP 服务器创建管理员用户：\n\n ```bash\n docker-compose exec mcp_server python scripts/create_admin_user.py\n ```\n\n 这将创建一个具有环境变量中指定的凭据的管理员用户。\n\n6. 将 Django 客户端注册到 MCP 服务器：\n\n ```bash\n docker-compose exec django_client python register_oauth_client.py\n ```\n\n 这将向 MCP 服务器注册 Django 客户端，并使用客户端凭据更新 Django 客户端的`.env`文件。\n\n7. 访问应用程序：\n\n * MCP 服务器： \n * Django 客户端： \n\n8. 在 Django 客户端中创建用户帐户并开始使用该应用程序。\n\n### 初步测试\n\n要验证您的设置是否正常工作，请运行以下测试：\n\n1. **MCP 服务器测试**：\n\n ```bash\n docker-compose exec mcp_server python -m pytest\n ```\n\n 这将运行 MCP 服务器的所有单元测试，包括 OAuth 端点、管理功能和内存管理。\n\n2. **Django 客户端测试**：\n\n ```bash\n docker-compose exec django_client python manage.py test\n ```\n\n 这将测试 Django 客户端与 MCP 服务器的集成。\n\n3. **手动测试**：\n\n * 在 Django 客户端的中创建用户帐户\n * 通过 OAuth 登录并连接到 MCP 服务器\n * 创建、检索和管理记忆\n * 测试语义搜索功能\n\n## 安全注意事项\n\n### 数据保护\n\n* 内存文本内容使用 Python 的 Fernet 对称加密（CBC 模式下的 AES-128 和 PKCS7 填充）进行静态加密，同时元数据仍然可搜索\n* 个人身份信息 (PII) 通过文本字段加密进行保护\n* 访问令牌的有效期为 1 小时，以限制暴露\n* 刷新令牌是长期有效的，但使用轮换：每次使用都会生成一个新的刷新令牌并使旧令牌无效\n* OAuth 令牌安全地存储在 Django 客户端的 PostgreSQL 数据库中\n\n### UUID 用法\n\n系统中的所有标识符都使用 UUID v4 格式而不是连续整数，原因如下：\n\n1. **安全性**：UUID 不会暴露系统信息或记录计数\n2. **可扩展性**：无需数据库协调即可生成 UUID，从而实现分布式系统\n3. **不可猜测性**：UUID 几乎不可能被猜测，从而防止枚举攻击\n4. **一致性**：在整个系统中使用 UUID 简化了与其他服务的集成\n\nAPI 中的所有 ID（user\\_id、memory\\_id、client\\_id 等）都必须是 UUID 格式。\n\n### OAuth最佳实践\n\n* 在生产环境中，所有 OAuth 通信都必须使用 HTTPS\n* 授权码是一次性的，并且有效期很短（最多 5 分钟）\n* 所有客户端（甚至是机密客户端）都需要 PKCE 才能进行纵深防御\n* 刷新令牌有效期较长，但可以被用户或管理员撤销\n* 系统维护已撤销令牌的黑名单\n\n## 文档\n\n### API 文档\n\nMCP 服务器包含所有端点的 Swagger/OpenAPI 文档：\n\n* 当服务器运行时，访问`/docs`上的 Swagger UI\n* OpenAPI 规范可在`/openapi.json`中找到\n* 所有 API 端点均有完整记录，包括请求/响应模式和示例\n\n### 附加文档文件\n\n* **TESTING.md** ：应用程序测试的综合指南\n\n * 描述所有实施的测试及其目的\n * 在本地和 CI/CD 中运行测试的说明\n * 记录测试覆盖范围并确定需要额外测试的区域\n\n* **DEBUGGING.md** ：跟踪问题及其解决方案\n\n * 记录尚未修复的已知错误\n * 记录之前解决的 bug 及其解决方案\n * 提供常见问题的故障排除指导\n\n* **PLANNING.md** ：跟踪实施网站所需的任务细分\n\n * 列出实施网站所需的任务和子任务\n * 使用复选框记录任务是否已完成\n\n## 部署\n\n该项目包含用于本地开发的`docker-compose.yml`文件和用于部署到 Render 的`render.yaml`蓝图。相同的代码库既可以在本地 Docker 容器中运行，也可以部署到 Render 云服务中运行。\n\n### MCP 服务器部署\n\n1. **Docker 部署**（推荐用于生产）：\n\n ```bash\n docker-compose up -d\n ```\n\n Docker Compose 配置包括：\n\n * 容器间通信的网络配置\n * 用于持久数据存储的卷挂载\n * .env 文件中的环境变量配置\n * 端口映射（Django 客户端为 8000，MCP 服务器为 8001）\n * 服务依赖关系的健康检查\n\n2. **渲染云部署**：使用包含的`render.yaml`蓝图部署到渲染。\n\n## 执照\n\n麻省理工学院","Chinese","zh-CN","githubUser","locale",{"_84":85,"_13":86,"_93":41,"_94":41,"_31":42,"_16":95,"_96":97,"_151":152,"_159":-5,"_160":-5,"_161":162,"_199":200,"_204":-5,"_104":186,"_205":190,"_107":206,"_207":208},"addedAt","2025-05-15T05:00:39.103267Z",[87,88,89,90,91,92],"category:knowledge-and-memory","category:vector-databases","category:rag-systems","environment:local","hosting:remote-capable","language:python","descriptionMarkdown","descriptionPlainText",6683,"integrations",[98,109,116,123,130,137,144],{"_99":100,"_29":106,"_107":108},"brand",{"_101":102,"_35":103,"_104":105},"logoSvgPath","M11.146 0h3.924v18.166c-2.013.382-3.491.535-5.096.535-4.791 0-7.288-2.166-7.288-6.32 0-4.002 2.65-6.6 6.753-6.6.637 0 1.121.05 1.707.203zm0 9.143a3.894 3.894 0 00-1.325-.204c-1.988 0-3.134 1.223-3.134 3.365 0 2.09 1.096 3.236 3.109 3.236.433 0 .79-.025 1.35-.102V9.142zM21.314 6.06v9.098c0 3.134-.229 4.638-.917 5.937-.637 1.249-1.478 2.039-3.211 2.905l-3.644-1.733c1.733-.815 2.574-1.53 3.109-2.625.561-1.121.739-2.421.739-5.835V6.059h3.924zM17.39.021h3.924v4.026H17.39z","Django","slug","django","Built on the Django framework for web application development, providing the foundation for the MCP server's functionality including user authentication, admin interface, and database interactions.","uid","l0re4z2pbc",{"_99":110,"_29":114,"_107":115},{"_101":111,"_35":112,"_104":113},"M13.983 11.078h2.119a.186.186 0 00.186-.185V9.006a.186.186 0 00-.186-.186h-2.119a.185.185 0 00-.185.185v1.888c0 .102.083.185.185.185m-2.954-5.43h2.118a.186.186 0 00.186-.186V3.574a.186.186 0 00-.186-.185h-2.118a.185.185 0 00-.185.185v1.888c0 .102.082.185.185.185m0 2.716h2.118a.187.187 0 00.186-.186V6.29a.186.186 0 00-.186-.185h-2.118a.185.185 0 00-.185.185v1.887c0 .102.082.185.185.186m-2.93 0h2.12a.186.186 0 00.184-.186V6.29a.185.185 0 00-.185-.185H8.1a.185.185 0 00-.185.185v1.887c0 .102.083.185.185.186m-2.964 0h2.119a.186.186 0 00.185-.186V6.29a.185.185 0 00-.185-.185H5.136a.186.186 0 00-.186.185v1.887c0 .102.084.185.186.186m5.893 2.715h2.118a.186.186 0 00.186-.185V9.006a.186.186 0 00-.186-.186h-2.118a.185.185 0 00-.185.185v1.888c0 .102.082.185.185.185m-2.93 0h2.12a.185.185 0 00.184-.185V9.006a.185.185 0 00-.184-.186h-2.12a.185.185 0 00-.184.185v1.888c0 .102.083.185.185.185m-2.964 0h2.119a.185.185 0 00.185-.185V9.006a.185.185 0 00-.184-.186h-2.12a.186.186 0 00-.186.186v1.887c0 .102.084.185.186.185m-2.92 0h2.12a.185.185 0 00.184-.185V9.006a.185.185 0 00-.184-.186h-2.12a.185.185 0 00-.184.185v1.888c0 .102.082.185.185.185M23.763 9.89c-.065-.051-.672-.51-1.954-.51-.338.001-.676.03-1.01.087-.248-1.7-1.653-2.53-1.716-2.566l-.344-.199-.226.327c-.284.438-.49.922-.612 1.43-.23.97-.09 1.882.403 2.661-.595.332-1.55.413-1.744.42H.751a.751.751 0 00-.75.748 11.376 11.376 0 00.692 4.062c.545 1.428 1.355 2.48 2.41 3.124 1.18.723 3.1 1.137 5.275 1.137.983.003 1.963-.086 2.93-.266a12.248 12.248 0 003.823-1.389c.98-.567 1.86-1.288 2.61-2.136 1.252-1.418 1.998-2.997 2.553-4.4h.221c1.372 0 2.215-.549 2.68-1.009.309-.293.55-.65.707-1.046l.098-.288Z","Docker","docker","Supports containerized deployment using Docker and Docker Compose, enabling consistent and isolated execution across different environments.","x21cpapovj",{"_99":117,"_29":121,"_107":122},{"_101":118,"_35":119,"_104":120},"M24 0v24H0V0h24ZM10.933 15.89H6.84v5.52h4.198v-.93H7.955v-1.503h2.77v-.93h-2.77v-1.224h2.978v-.934Zm2.146 0h-1.084v5.52h1.035v-3.6l2.226 3.6h1.118v-5.52h-1.036v3.686l-2.259-3.687Zm5.117 0h-1.208l1.973 5.52h1.19l1.976-5.52h-1.182l-1.352 4.085-1.397-4.086ZM5.4 19.68H3.72v1.68H5.4v-1.68Z",".ENV","dotenv","Uses .env files for configuration management, allowing customization of server settings through environment variables.","n8v2qxjsp0",{"_99":124,"_29":128,"_107":129},{"_101":125,"_35":126,"_104":127},"M23.546 10.93L13.067.452c-.604-.603-1.582-.603-2.188 0L8.708 2.627l2.76 2.76c.645-.215 1.379-.07 1.889.441.516.515.658 1.258.438 1.9l2.658 2.66c.645-.223 1.387-.078 1.9.435.721.72.721 1.884 0 2.604-.719.719-1.881.719-2.6 0-.539-.541-.674-1.337-.404-1.996L12.86 8.955v6.525c.176.086.342.203.488.348.713.721.713 1.883 0 2.6-.719.721-1.889.721-2.609 0-.719-.719-.719-1.879 0-2.598.182-.18.387-.316.605-.406V8.835c-.217-.091-.424-.222-.6-.401-.545-.545-.676-1.342-.396-2.009L7.636 3.7.45 10.881c-.6.605-.6 1.584 0 2.189l10.48 10.477c.604.604 1.582.604 2.186 0l10.43-10.43c.605-.603.605-1.582 0-2.187","Git","git","Integrates with Git for version control and deployment, providing instructions for cloning the repository as part of the setup process.","aoh9xoqps0",{"_99":131,"_29":135,"_107":136},{"_101":132,"_35":133,"_104":134},"M2.6152 0v.8867h3.8399V0zm5.0215 0v.8867h3.8418V0zm4.957 0v.8867h3.8418V0zm4.9356 0v.8867h3.8418V0zM2.4473 1.8945a.935.935 0 0 0-.9356.9356c0 .517.4185.9375.9356.9375h19.1054c.5171 0 .9356-.4204.9356-.9375a.935.935 0 0 0-.9356-.9356zm.168 2.8477V24H6.455V4.7422zm5.0214 0V20.543h3.8418V4.7422zm4.957 0V15.291h3.8497V4.7422zm4.9356 0v6.4941h3.8418V4.7422z","Pytest","pytest","Implements testing with pytest, enabling automated verification of server functionality and ensuring reliability.","0dxyzevp8o",{"_99":138,"_29":142,"_107":143},{"_101":139,"_35":140,"_104":141},"M14.25.18l.9.2.73.26.59.3.45.32.34.34.25.34.16.33.1.3.04.26.02.2-.01.13V8.5l-.05.63-.13.55-.21.46-.26.38-.3.31-.33.25-.35.19-.35.14-.33.1-.3.07-.26.04-.21.02H8.77l-.69.05-.59.14-.5.22-.41.27-.33.32-.27.35-.2.36-.15.37-.1.35-.07.32-.04.27-.02.21v3.06H3.17l-.21-.03-.28-.07-.32-.12-.35-.18-.36-.26-.36-.36-.35-.46-.32-.59-.28-.73-.21-.88-.14-1.05-.05-1.23.06-1.22.16-1.04.24-.87.32-.71.36-.57.4-.44.42-.33.42-.24.4-.16.36-.1.32-.05.24-.01h.16l.06.01h8.16v-.83H6.18l-.01-2.75-.02-.37.05-.34.11-.31.17-.28.25-.26.31-.23.38-.2.44-.18.51-.15.58-.12.64-.1.71-.06.77-.04.84-.02 1.27.05zm-6.3 1.98l-.23.33-.08.41.08.41.23.34.33.22.41.09.41-.09.33-.22.23-.34.08-.41-.08-.41-.23-.33-.33-.22-.41-.09-.41.09zm13.09 3.95l.28.06.32.12.35.18.36.27.36.35.35.47.32.59.28.73.21.88.14 1.04.05 1.23-.06 1.23-.16 1.04-.24.86-.32.71-.36.57-.4.45-.42.33-.42.24-.4.16-.36.09-.32.05-.24.02-.16-.01h-8.22v.82h5.84l.01 2.76.02.36-.05.34-.11.31-.17.29-.25.25-.31.24-.38.2-.44.17-.51.15-.58.13-.64.09-.71.07-.77.04-.84.01-1.27-.04-1.07-.14-.9-.2-.73-.25-.59-.3-.45-.33-.34-.34-.25-.34-.16-.33-.1-.3-.04-.25-.02-.2.01-.13v-5.34l.05-.64.13-.54.21-.46.26-.38.3-.32.33-.24.35-.2.35-.14.33-.1.3-.06.26-.04.21-.02.13-.01h5.84l.69-.05.59-.14.5-.21.41-.28.33-.32.27-.35.2-.36.15-.36.1-.35.07-.32.04-.28.02-.21V6.07h2.09l.14.01zm-6.47 14.25l-.23.33-.08.41.08.41.23.33.33.23.41.08.41-.08.33-.23.23-.33.08-.41-.08-.41-.23-.33-.33-.23-.41-.08-.41.08z","Python","python","Built with Python programming language, requiring Python 3.9+ for operation and development.","vlajvlqq70",{"_99":145,"_29":149,"_107":150},{"_101":146,"_35":147,"_104":148},"M12 0C5.383 0 0 5.383 0 12s5.383 12 12 12c6.616 0 12-5.383 12-12S18.616 0 12 0zm0 1.144c5.995 0 10.856 4.86 10.856 10.856 0 5.995-4.86 10.856-10.856 10.856-5.996 0-10.856-4.86-10.856-10.856C1.144 6.004 6.004 1.144 12 1.144zM8.37 5.868a6.707 6.707 0 0 0-.423.005c-.983.056-1.573.517-1.735 1.472-.115.665-.096 1.348-.143 2.017-.013.35-.05.697-.115 1.038-.134.609-.397.798-1.016.83a2.65 2.65 0 0 0-.244.042v1.463c1.126.055 1.278.452 1.37 1.629.033.429-.013.858.015 1.287.018.406.073.808.156 1.2.259 1.075 1.307 1.435 2.575 1.218v-1.283c-.203 0-.383.005-.558 0-.43-.013-.591-.12-.632-.535-.056-.535-.042-1.08-.075-1.62-.064-1.001-.175-1.988-1.153-2.625.503-.37.868-.812.983-1.398.083-.41.134-.821.166-1.237.028-.415-.023-.84.014-1.25.06-.665.102-.937.9-.91.12 0 .235-.017.369-.027v-1.31c-.16 0-.31-.004-.454-.006zm7.593.009a4.247 4.247 0 0 0-.813.06v1.274c.245 0 .434 0 .623.005.328.004.577.13.61.494.032.332.031.669.064 1.006.065.669.101 1.347.217 2.007.102.544.475.95.941 1.283-.817.549-1.057 1.333-1.098 2.215-.023.604-.037 1.213-.069 1.822-.028.554-.222.734-.78.748-.157.004-.31.018-.484.028v1.305c.327 0 .627.019.927 0 .932-.055 1.495-.507 1.68-1.412.078-.498.124-1 .138-1.504.032-.461.028-.927.074-1.384.069-.715.397-1.01 1.112-1.057a.972.972 0 0 0 .199-.046v-1.463c-.12-.014-.204-.027-.291-.032-.536-.023-.804-.203-.937-.71a5.146 5.146 0 0 1-.152-.993c-.037-.618-.033-1.241-.074-1.86-.08-1.192-.794-1.753-1.887-1.786zm-6.89 5.28a.844.844 0 0 0-.083 1.684h.055a.83.83 0 0 0 .877-.78v-.046a.845.845 0 0 0-.83-.858zm2.911 0a.808.808 0 0 0-.834.78c0 .027 0 .05.004.078 0 .503.342.826.859.826.507 0 .826-.332.826-.853-.005-.503-.342-.836-.855-.831zm2.963 0a.861.861 0 0 0-.876.835c0 .47.378.849.849.849h.009c.425.074.853-.337.881-.83.023-.457-.392-.854-.863-.854z","Swagger","swagger","Offers API documentation through Swagger UI, providing interactive exploration of the available API endpoints and operations.","wacwfdw6qq","namespace",{"_153":154,"_104":158},"owner",{"_155":156},"githubAccount",{"_157":158},"login","hburgoyne","readmeMarkdown","redditPostExternalId","repository",{"_163":164,"_171":172,"_176":177,"_194":-5,"_195":196,"_197":-5,"_198":-5},"argumentsJsonSchema",{"_165":166,"_167":168,"_169":170},"properties",{},"required",[],"type","object","githubProject",{"_33":173,"_174":175},"# Picard MCP Server\n\n## Overview\n\nPicard MCP is a complete memory management system built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) standard. It consists of two main components: an MCP server that provides secure memory storage and retrieval services, and a Django client application that demonstrates how to integrate with the MCP server. The system enables users to store, retrieve, and manage their memories while controlling access permissions, and allows for semantic search and AI-powered queries based on stored memories.\n\n### MCP Compliance\n\nThis implementation follows the Model Context Protocol standard, which allows LLM applications to interact with the server in a standardized way. The MCP server exposes:\n\n- **Resources**: Read-only endpoints that provide data to LLMs (memory content)\n- **Tools**: Functional endpoints that perform actions (memory creation, updates, queries)\n- **Authentication**: OAuth 2.0 implementation for secure access to protected resources\n\n### Key Components\n\n1. **MCP Server**: A FastAPI-based implementation of the Model Context Protocol that provides:\n - ✅ OAuth 2.0 authentication and authorization with PKCE support\n - ✅ Memory storage with PostgreSQL and pgvector extension\n - ✅ Permission-based memory access control (private/public)\n - ✅ Vector embeddings for semantic search using OpenAI's text-embedding-3-small model\n - 🔄 LLM integration for memory-based queries (framework ready, advanced features planned)\n\n2. **Django Client**: A web application that demonstrates integration with the MCP server:\n - User registration and authentication\n - OAuth 2.0 client implementation\n - Memory creation, retrieval, and management UI\n - Persona-based querying interface\n\n## System Architecture\n\n### Overall Architecture\n\nThe Picard MCP system follows a client-server architecture with the following components:\n\n1. **MCP Server**: Core backend service that handles memory storage, retrieval, and AI operations\n - Built with FastAPI (FastMCP) for high performance and async support\n - Uses PostgreSQL with pgvector extension for vector storage and semantic search\n - Implements data models for Users, Memories (with vector embeddings), OAuth Clients, and Tokens\n - Uses SQLAlchemy ORM with Alembic migrations for database management\n - Implements OAuth 2.0 for secure authentication and authorization\n - Integrates with OpenAI API for memory embeddings (text-embedding-3-small)\n - Uses LangChain for LLM operations when available\n - Provides both stateful and stateless operation modes\n - Supports streamable HTTP transport for better scalability\n\n2. **Django Client**: Web application that demonstrates integration with the MCP server\n - Provides user registration, authentication, and profile management\n - Implements OAuth 2.0 client for secure communication with the MCP server\n - Offers a user-friendly interface for memory management and querying\n - Uses its own PostgreSQL database separate from the MCP server\n\n3. **Docker Infrastructure**: Containerized deployment for easy setup and scaling\n - Separate containers for MCP server (port 8001), Django client (port 8000), and PostgreSQL databases\n - Configured networking for secure inter-container communication\n - Volume mounting for persistent data storage\n - Compatible with both local Docker deployment and Render cloud deployment\n\n### Authentication Approaches\n\nThe system offers two main authentication approaches:\n\n#### 1. Direct Connect with User Context Token Flow (Recommended)\n\nThis simplified approach allows users to authenticate only once with the Django client, avoiding the need for separate MCP server authentication:\n\n1. **Client Registration**:\n - The Django client registers with the MCP server using the `/api/admin/clients/register` endpoint\n - Registration requires admin authentication and includes client name, redirect URIs, and requested scopes\n - The MCP server issues a UUID-based client ID and cryptographically secure client secret\n - Client credentials should be stored securely and never exposed in client-side code\n\n2. **User Authentication Flow**:\n - User authenticates only with the Django client\n - When the user initiates connection to the MCP server, the Django client makes a server-side request to the MCP's `/api/user-tokens/user-token` endpoint\n - The request includes:\n - Client credentials (client_id and client_secret)\n - User information (username and email)\n - Option to create user if not exists\n - The MCP server verifies client credentials and either finds or creates a corresponding user\n - MCP server issues access and refresh tokens for the user\n - Django client securely stores these tokens and uses them for API requests\n\n3. **API Access**:\n - Client includes the access token in the Authorization header (`Authorization: Bearer {token}`) for all API requests\n - MCP server validates the token signature, expiration, and audience claims\n - MCP server enforces scope-based permissions for each endpoint\n - When the access token expires, client uses the refresh token to obtain a new one\n\n4. **Security Features**:\n - Only confidential clients can use this method, providing server-to-server security\n - Client credentials are verified for each token request\n - Tokens are blacklisted after use to prevent replay attacks\n - Refresh tokens use rotation: each use generates a new refresh token and invalidates the old one\n\n#### 2. Standard OAuth 2.0 Authorization Code Flow with PKCE (Legacy)\n\nThe system also supports the standard OAuth 2.0 Authorization Code flow with PKCE for enhanced security, following RFC 6749 and RFC 7636 standards. This approach requires users to authenticate with both the client and the MCP server:\n\n1. **Authorization Flow**:\n - User initiates login through the Django client\n - Client generates a cryptographically secure random `state` parameter for CSRF protection\n - Client generates a random PKCE `code_verifier` and derives `code_challenge` using SHA-256\n - Client redirects to MCP server's `/authorize` endpoint with:\n - `response_type=code`\n - `client_id` (UUID format)\n - `redirect_uri`\n - `scope` (space-separated list, e.g., `memories:read memories:write`)\n - `state` (for CSRF protection)\n - PKCE parameters (`code_challenge` and `code_challenge_method=S256`)\n - MCP server authenticates the user (if not already authenticated)\n - MCP server validates all parameters and redirects back to the client with a short-lived authorization code\n\n2. **Token Exchange**:\n - Client verifies the returned `state` parameter matches the one sent in the authorization request\n - Client exchanges the authorization code for access and refresh tokens via `/token` endpoint\n - MCP server issues a JWT access token, refresh token, expiration time, and granted scopes\n\n3. **API Access**:\n - Same as in the Direct Connect approach\n\n### Database Models\n\nThe MCP Server uses SQLAlchemy ORM with the following key models:\n\n1. **User Model**:\n - Stores user information with email, username, and hashed password\n - Includes boolean flags for account status (is_active, is_superuser)\n - Linked to memories through one-to-many relationship\n\n2. **Memory Model with Vector Storage**:\n - Uses pgvector extension to store and query vector embeddings (1536 dimensions)\n - Supports text content with optional encryption\n - Includes permission controls (private/public)\n - Supports expiration dates for time-limited memories\n - Associated with users through foreign key relationship\n\n3. **OAuth Models**:\n - **OAuthClient**: Stores client application details, including client_id, client_secret, redirect URIs, and authorized scopes\n - **AuthorizationCode**: Manages temporary authorization codes with PKCE support\n - **Token**: Stores access and refresh tokens with expiration tracking\n\nThe system uses Alembic for database migrations, ensuring schema versioning and easy updates.\n\n### Memory Management System\n\nThe core functionality of Picard MCP revolves around memory management with the following components:\n\n1. **Memory Storage**:\n - Memories are stored as text with associated metadata\n - Vector embeddings (using text-embedding-3-small model) enable semantic search capabilities\n - Permissions control who can access each memory\n - Timestamps track creation, modification, and expiration\n - Memory text is encrypted at rest while metadata remains searchable\n - All identifiers use UUID format instead of sequential integers for scalability\n - Each memory is converted to a vector embedding using OpenAI's embedding model\n - Embeddings enable semantic search and similarity matching\n - PostgreSQL with pgvector extension provides efficient vector storage and retrieval\n\n2. **Permission Management**:\n - Each memory has a permission level (private or public)\n - Private memories are only accessible to the owner\n - Public memories can be accessed by other users for persona queries\n - System is designed to be extensible for future permission types (e.g., for statistical/aggregated use)\n - Shared memories can be accessed by specific users or groups\n - Permissions can be modified by the memory owner at any time\n\n3. **Memory Retrieval**:\n - ✅ Users can retrieve their own memories with filtering and sorting options\n - ✅ Semantic search for finding memories based on meaning using vector embeddings\n - ✅ Vector similarity (cosine) for finding related memories using pgvector\n - ✅ Top-N most similar memories based on query relevance with configurable similarity threshold\n - ✅ Permission checks ensure users only access authorized memories\n\n4. **LLM Integration**:\n - Memories can be used as context for LLM queries\n - Users can create personas based on their public memories\n - Other users can query these personas to get responses informed by the memories\n - The system handles context management and prompt engineering automatically\n\n## Key Features\n\n### MCP Server Features\n\n- **OAuth 2.0 Authentication**:\n - Authorization Code flow with PKCE for enhanced security\n - Scope-based permission system (`memories:read`, `memories:write`, `memories:admin`)\n - Token management with refresh token support\n - Client registration and management\n\n- **Memory Management**:\n - Create, read, update, and delete memories\n - Vector embedding for semantic search\n - Permission-based access control\n - Batch operations for efficient memory management\n\n- **User Management**:\n - User registration and authentication\n - Profile management and settings\n - Activity tracking and analytics\n - Admin controls for system management\n\n- **✅ AI Integration**:\n - ✅ OpenAI API integration (v1.x) for embeddings using text-embedding-3-small model\n - ✅ Automatic vector embedding generation for all memories (1536 dimensions)\n - ✅ Semantic search using pgvector cosine similarity\n - ✅ Asynchronous embedding generation with strict error handling\n - 📋 Persona creation framework based on user memories (planned)\n - 📋 Context-aware query processing architecture (planned)\n\n### Django Client Features\n\n- **User Interface**:\n - Clean, responsive design for desktop and mobile\n - Intuitive memory management interface\n - Advanced search and filtering options\n - Persona creation and query interface\n\n- **OAuth Client Implementation**:\n - Secure token storage and management\n - Automatic token refresh\n - Scope-based feature availability\n - Error handling and recovery\n\n- **Memory Tools**:\n - Memory creation with rich text support\n - Batch import and export\n - Permission management interface\n - Tagging and categorization\n\n## MCP Interface\n\n### MCP Resources\n\n- **Memory Resource**: `memories://{memory_id}`\n - Returns the content of a specific memory with permission checks\n - Parameters: memory_id (UUID)\n - Response: Memory content with metadata\n\n- **User Memories Resource**: `users://{user_id}/memories`\n - Returns a list of memories for a specific user with permission checks\n - Parameters: user_id (UUID), optional filters\n - Response: List of memory summaries\n\n### MCP Tools\n\n- **Submit Memory Tool**: Creates a new memory\n - Parameters: text (string), permission (string)\n - Returns: Created memory details with UUID\n\n- **Update Memory Tool**: Updates an existing memory\n - Parameters: memory_id (UUID), text (string)\n - Returns: Updated memory details\n\n- **Delete Memory Tool**: Deletes a memory\n - Parameters: memory_id (UUID)\n - Returns: Success confirmation\n\n- **Query Memory Tool**: Performs semantic search on memories\n - Parameters: query (string), limit (integer), similarity_threshold (float), permission_filter (string)\n - Returns: List of relevant memories ordered by similarity score\n - Uses: OpenAI embeddings and pgvector cosine similarity\n\n- **Query User**: Queries a user's persona based on memories\n - Parameters: user_id (UUID), query (string)\n - Returns: Response based on user's memories\n\n## API Endpoints\n\n### OAuth Endpoints\n\n- **Client Registration**: `/register`\n - Method: POST\n - Description: Register a new OAuth client\n - Request: Client details (ID, secret, redirect URIs, scopes)\n - Response: Client credentials and registration information\n\n- **Authorization**: `/authorize`\n - Method: GET\n - Description: Initiate OAuth authorization flow\n - Parameters: response_type, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method\n - Response: Redirects to client with authorization code\n\n- **Token Exchange**: `/token`\n - Method: POST\n - Description: Exchange authorization code for tokens\n - Request: grant_type, code, redirect_uri, client_id, client_secret, code_verifier\n - Response: Access token, refresh token, expiration, and scope information\n\n### Memory Endpoints\n\n- **Get Memories**: `/api/tools` (tool: `get_memories`)\n - Method: POST\n - Description: Retrieve memories with optional filtering\n - Authentication: Bearer token\n - Request: Optional filter parameters (user_id, permission, expiration status)\n - Response: List of memories accessible to the user\n - Example Request:\n ```json\n {\n \"tool\": \"get_memories\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"private\"\n }\n }\n ```\n\n- **Submit Memory**: `/api/tools` (tool: `submit_memory`)\n - Method: POST\n - Description: Create a new memory\n - Authentication: Bearer token\n - Request: Memory text, permission level, and expiration date (ISO 8601 format, e.g., \"2025-12-31T23:59:59Z\")\n - Response: Created memory details including UUID identifier\n - Example Request:\n ```json\n {\n \"tool\": \"submit_memory\",\n \"data\": {\n \"text\": \"This is my memory content\",\n \"permission\": \"private\"\n }\n }\n ```\n\n- **Retrieve Memories**: `/api/tools` (tool: `retrieve_memories`)\n - Method: POST\n - Description: Get all memories for the authenticated user\n - Authentication: Bearer token\n - Response: List of memory objects with UUID identifiers\n - Example Request:\n ```json\n {\n \"tool\": \"retrieve_memories\",\n \"data\": {}\n }\n ```\n\n- **Update Memory**: `/api/tools` (tool: `update_memory`)\n - Method: POST\n - Description: Update an existing memory\n - Authentication: Bearer token\n - Request: Memory ID, updated content, and optionally updated expiration date (ISO 8601 format)\n - Response: Updated memory details\n - Example Request:\n ```json\n {\n \"tool\": \"update_memory\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"text\": \"Updated memory content\",\n \"expiration_date\": \"2026-01-01T00:00:00Z\"\n }\n }\n ```\n\n- **Modify Permissions**: `/api/tools` (tool: `modify_permissions`)\n - Method: POST\n - Description: Update memory permission level\n - Authentication: Bearer token\n - Request: Memory UUID and new permission level\n - Response: Updated memory details\n - Example Request:\n ```json\n {\n \"tool\": \"modify_permissions\",\n \"data\": {\n \"memory_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"permission\": \"public\"\n }\n }\n ```\n\n- **Query Memory**: `/api/tools` (tool: `query_memory`)\n - Method: POST\n - Description: Perform semantic search on user's memories using vector embeddings\n - Authentication: Bearer token\n - Request: Search query and optional parameters in the data field\n - Response: List of memories ordered by similarity score\n - Example Request:\n ```json\n {\n \"tool\": \"query_memory\",\n \"data\": {\n \"query\": \"artificial intelligence thoughts\",\n \"limit\": 10,\n \"similarity_threshold\": 0.5,\n \"permission_filter\": \"private\"\n }\n }\n ```\n - Example Response:\n ```json\n {\n \"data\": {\n \"memories\": [\n {\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"text\": \"I think AI will revolutionize how we work...\",\n \"permission\": \"private\",\n \"similarity\": 0.85,\n \"created_at\": \"2024-01-15T10:30:00Z\",\n \"updated_at\": \"2024-01-15T10:30:00Z\"\n }\n ]\n }\n }\n ```\n\n- **Query User**: `/api/tools` (tool: `query_user`)\n - Method: POST\n - Description: Query a user's persona based on memories (public for other users, public+private for self)\n - Authentication: Bearer token\n - Request: User UUID and query prompt\n - Response: JSON containing non-expired memories, either all valid memories or top-N most similar to query\n - Response: AI-generated response based on user's memories\n - Example Request:\n ```json\n {\n \"tool\": \"query_user\",\n \"data\": {\n \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"prompt\": \"What are your thoughts on artificial intelligence?\"\n }\n }\n ```\n\n## Setup and Deployment\n\n### Prerequisites\n\n- Docker and Docker Compose\n- Python 3.10+\n- OpenAI API key\n\n### Complete Setup Guide\n\n1. Clone the repository:\n ```bash\n git clone https://github.com/yourusername/picard_mcp.git\n cd picard_mcp\n ```\n\n2. Create environment files for both components:\n ```bash\n # For MCP server\n cp mcp_server/.env.example mcp_server/.env\n \n # For Django client\n cp django_client/.env.example django_client/.env\n ```\n\n3. Edit the environment files to set your configuration:\n - In `mcp_server/.env`: Set your database credentials, OpenAI API key, and admin credentials\n - In `django_client/.env`: Set your database credentials and OAuth settings\n\n4. Start the services using Docker Compose:\n ```bash\n docker-compose up -d\n ```\n This will start the following services:\n - `db-mcp`: PostgreSQL database for the MCP server\n - `db-django`: PostgreSQL database for the Django client\n - `mcp_server`: MCP server running on http://localhost:8001\n - `django_client`: Django client running on http://localhost:8000\n\n5. Create an admin user for the MCP server:\n ```bash\n docker-compose exec mcp_server python scripts/create_admin_user.py\n ```\n This will create an admin user with the credentials specified in your environment variables.\n\n6. Register the Django client with the MCP server:\n ```bash\n docker-compose exec django_client python register_oauth_client.py\n ```\n This will register the Django client with the MCP server and update the Django client's `.env` file with the client credentials.\n\n7. Access the applications:\n - MCP Server: http://localhost:8001\n - Django Client: http://localhost:8000\n\n8. Create a user account in the Django client and start using the application.\n\n### Initial Testing\n\nTo verify your setup is working correctly, run the following tests:\n\n1. **MCP Server Tests**:\n ```bash\n docker-compose exec mcp_server python -m pytest\n ```\n This will run all the unit tests for the MCP server, including OAuth endpoints, admin functionality, and memory management.\n\n2. **Django Client Tests**:\n ```bash\n docker-compose exec django_client python manage.py test\n ```\n This will test the Django client's integration with the MCP server.\n\n3. **Manual Testing**:\n - Create a user account in the Django client at http://localhost:8000/register\n - Log in and connect to the MCP server via OAuth\n - Create, retrieve, and manage memories\n - Test the semantic search functionality\n\n## Security Considerations\n\n### Data Protection\n\n- Memory text content is encrypted at rest using Python's Fernet symmetric encryption (AES-128 in CBC mode with PKCS7 padding) while metadata remains searchable\n- Personal identifiable information (PII) is protected through text field encryption\n- Access tokens have a 1-hour expiration time to limit exposure\n- Refresh tokens are long-lived but use rotation: each use generates a new refresh token and invalidates the old one\n- OAuth tokens are securely stored in the Django client's PostgreSQL database\n\n### UUID Usage\n\nAll identifiers in the system use UUID v4 format instead of sequential integers for several reasons:\n\n1. **Security**: UUIDs don't expose system information or record counts\n2. **Scalability**: UUIDs can be generated without database coordination, enabling distributed systems\n3. **Non-guessability**: UUIDs are practically impossible to guess, preventing enumeration attacks\n4. **Consistency**: Using UUIDs throughout the system simplifies integration with other services\n\nAll IDs in the API (user_id, memory_id, client_id, etc.) must be in UUID format.\n\n### OAuth Best Practices\n\n- All OAuth communication must use HTTPS in production environments\n- Authorization codes are single-use and short-lived (max 5 minutes)\n- PKCE is required for all clients, even confidential ones, for defense in depth\n- Refresh tokens are long-lived but can be revoked by users or administrators\n- The system maintains a token blacklist for revoked tokens\n\n## Documentation\n\n### API Documentation\n\nThe MCP server includes Swagger/OpenAPI documentation for all endpoints:\n\n- Access the Swagger UI at `/docs` when the server is running\n- The OpenAPI specification is available at `/openapi.json`\n- All API endpoints are fully documented with request/response schemas and examples\n\n### Additional Documentation Files\n\n- **TESTING.md**: Comprehensive guide to testing the application\n - Describes all implemented tests and their purposes\n - Instructions for running tests locally and in CI/CD\n - Documents test coverage and identifies areas needing additional testing\n\n- **DEBUGGING.md**: Tracks issues and their resolutions\n - Logs known bugs that have not yet been fixed\n - Documents previously solved bugs and their solutions\n - Provides troubleshooting guidance for common issues\n\n- **PLANNING.md**: Tracks the breakdown of tasks required to implement the site\n - Lists tasks and subtasks required to implement the site\n - Documents if a task has been completed with a checkbox\n\n## Deployment\n\nThis project includes a `docker-compose.yml` for local development and `render.yaml` blueprint for deploying to Render. The same codebase works both locally in Docker containers and when deployed to Render cloud services.\n\n### MCP Server Deployment\n\n1. **Docker Deployment** (recommended for production):\n ```bash\n docker-compose up -d\n ```\n \n The Docker Compose configuration includes:\n - Network configuration for inter-container communication\n - Volume mounts for persistent data storage\n - Environment variable configuration from .env files\n - Port mappings (8000 for Django client, 8001 for MCP server)\n - Health checks for service dependencies\n\n2. **Render Cloud Deployment**:\n Use the included `render.yaml` blueprint to deploy to Render.\n\n## License\n\nMIT","url","https://github.com/hburgoyne/picard_mcp","githubRepository",{"_178":179,"_180":181,"_182":183,"_16":184,"_185":140,"_35":186,"_153":187,"_189":190,"_191":-5,"_192":193},"defaultBranch","main","fullName","hburgoyne/picard_mcp","githubTreeId",330741,13458,"language","picard_mcp",{"_157":158,"_107":188},"u9VtoIlkNX","recentStargazers",0,"spdxLicense","stargazers",1,"glamaJson","inspectable",false,"npmPackage","supportedPlatforms","scores",{"_201":-5,"_202":-5,"_203":-5},"license","quality","security","simpleIcon","toolCount","fchlnmt6nz","updatedAt","2025-10-01T19:37:46.342673Z","meta",[211,214,216,223,226,228,231,234,237,240,243,245,248,251,253,255,257,259,261],{"_212":213},"title","MCP Server | Glama",{"_215":41,"_35":29},"content",{"_217":218,"_219":220,"_221":222},"href","https://glama.ai/mcp/servers/@hburgoyne/picard_mcp","rel","canonical","tagName","link",{"_215":42,"_224":225},"property","og:title",{"_215":41,"_224":227},"og:description",{"_215":229,"_224":230},"https://glama.ai/logo.png","og:logo",{"_215":232,"_224":233},"https://glama.ai/mcp/servers/@hburgoyne/picard_mcp/og-image","og:image",{"_215":235,"_224":236},"630","og:image:height",{"_215":238,"_224":239},"1200","og:image:width",{"_215":241,"_224":242},"website","og:type",{"_215":218,"_224":244},"og:url",{"_215":246,"_224":247},"Glama – MCP Hosting Platform","og:site_name",{"_215":249,"_35":250},"summary_large_image","twitter:card",{"_215":246,"_35":252},"twitter:title",{"_215":41,"_35":254},"twitter:description",{"_215":232,"_35":256},"twitter:image",{"_215":235,"_35":258},"twitter:image:height",{"_215":238,"_35":260},"twitter:image:width",{"_262":263},"script:ld+json",{"_264":265,"_266":267},"@context","http://schema.org","@graph",[268],{"_264":269,"_270":271,"_272":273},"https://schema.org","@type","BreadcrumbList","itemListElement",[274,280,284,288],{"_270":275,"_276":277,"_35":278,"_279":193},"ListItem","item","/","Glama","position",{"_270":275,"_276":281,"_35":282,"_279":283},"/mcp","MCP",2,{"_270":275,"_276":285,"_35":286,"_279":287},"/mcp/servers","Servers",3,{"_270":275,"_276":289,"_35":42,"_279":290},"/mcp/servers/@hburgoyne/picard_mcp",4,"visitorIsMaintainer","routes/_public/mcp/servers/~namespace/~slug/_pages/_explorer/blob/~commit/~/_route",{"_294":295,"_27":301,"_329":330,"_209":344,"_341":368,"_369":370},"blob",{"_215":296,"_297":298,"_299":300},"requests==2.31.0\nselenium==4.16.0\npytest==7.3.1\nwebdriver-manager==4.0.1\n","fileName","requirements.txt","size",73,{"_84":85,"_13":302,"_93":41,"_94":41,"_31":42,"_16":95,"_96":303,"_151":318,"_159":-5,"_160":-5,"_161":321,"_199":328,"_204":-5,"_104":186,"_205":190,"_107":206,"_207":208},[87,88,89,90,91,92],[304,306,308,310,312,314,316],{"_99":305,"_29":106,"_107":108},{"_101":102,"_35":103,"_104":105},{"_99":307,"_29":114,"_107":115},{"_101":111,"_35":112,"_104":113},{"_99":309,"_29":121,"_107":122},{"_101":118,"_35":119,"_104":120},{"_99":311,"_29":128,"_107":129},{"_101":125,"_35":126,"_104":127},{"_99":313,"_29":135,"_107":136},{"_101":132,"_35":133,"_104":134},{"_99":315,"_29":142,"_107":143},{"_101":139,"_35":140,"_104":141},{"_99":317,"_29":149,"_107":150},{"_101":146,"_35":147,"_104":148},{"_153":319,"_104":158},{"_155":320},{"_157":158},{"_163":322,"_171":325,"_176":326,"_194":-5,"_195":196,"_197":-5,"_198":-5},{"_165":323,"_167":324,"_169":170},{},[],{"_33":173,"_174":175},{"_178":179,"_180":181,"_182":183,"_16":184,"_185":140,"_35":186,"_153":327,"_189":190,"_191":-5,"_192":193},{"_157":158,"_107":188},{"_201":-5,"_202":-5,"_203":-5},"member",{"_331":332,"_335":336,"_337":338,"_182":339,"_340":196,"_341":298,"_342":343,"_299":300,"_169":294},"commit",{"_333":334},"sha","a6c8acee6a0e1c123e20d82395b56e1effac748f","contentStoredObjectPointerId",472173,"fullPath","tests/requirements.txt",330740,"indexable","path","safeToDisplayAsText",true,[345,347,349,351,353,354,355,357,358,359,360,361,362,363,364,365,366,367],{"_212":346},"requirements.txt | MCP Server | Glama",{"_215":348,"_35":29},"Enterprise-grade security, privacy, and features like agents, MCP, prompt templates, and more.",{"_217":350,"_219":220,"_221":222},"https://glama.ai/mcp/servers/@hburgoyne/picard_mcp/blob/a6c8acee6a0e1c123e20d82395b56e1effac748f/tests",{"_215":352,"_224":225},"requirements.txt | MCP Server",{"_215":348,"_224":227},{"_215":229,"_224":230},{"_215":356,"_224":233},"https://glama.ai/generated-images/og?title=requirements.txt+%7C+MCP+Server",{"_215":235,"_224":236},{"_215":238,"_224":239},{"_215":241,"_224":242},{"_215":350,"_224":244},{"_215":246,"_224":247},{"_215":249,"_35":250},{"_215":246,"_35":252},{"_215":348,"_35":254},{"_215":356,"_35":256},{"_215":235,"_35":258},{"_215":238,"_35":260},"tests","treeMembers",[371,375,377],{"_331":372,"_337":373,"_341":374,"_169":294},{"_333":334},"tests/README.md","README.md",{"_331":376,"_337":338,"_341":298,"_169":294},{"_333":334},{"_331":378,"_337":379,"_341":380,"_169":294},{"_333":334},"tests/test_oauth_integration.py","test_oauth_integration.py","actionData","errors"]

MCP directory API