🧠 SuiAgentic

SuiAgentic ist eine FastAPI-basierte Anwendung für die Einbettung von Dokumenten und die semantische Abfrage, basierend auf der Qdrant-Vektordatenbank. Sie ermöglicht die Konvertierung von Dokumenten (aus URLs oder lokalen Dateien) in Einbettungen, deren effiziente Speicherung und den Abruf relevanter Inhalte mithilfe natürlicher Sprachabfragen. Sie unterstützt KI-gestützte Tools wie Cursor, Copilot, Claude und andere MCP-kompatible Clients.

💡 Warum SuiAgentic? Viele Organisationen müssen Kontext aus internen Dokumenten (z. B. PRDs, Design-Spezifikationen, Wikis) in die Tools von Entwicklern und Wissensarbeitern integrieren. Die Konsolidierung von Dokumenten aus verschiedenen Quellen in einer zentralen, durchsuchbaren Wissensdatenbank ist jedoch komplex und fragmentiert.

SuiAgentic löst dieses Problem durch einen zentralen Kontextserver, der Ihre Inhalte aufnimmt, aufteilt, einbettet und indexiert und sie über eine einfache REST-API und Weboberfläche verfügbar macht. Er unterstützt auch die Verwendung als MCP-Server für KI-Agenten.

🚀 Hauptfunktionen: Dokumenteinbettung: Extrahiert Inhalte aus URLs (mit oder ohne Authentifizierung), teilt sie in Blöcke auf, generiert Einbettungen und speichert sie in Qdrant.

Semantische Suche: Fragen Sie Ihre Wissensdatenbank mit natürlicher Sprache ab und rufen Sie relevante Abschnitte oder Dokumente ab.

Web-Benutzeroberfläche: Benutzerfreundliche Weboberfläche zum Einbetten und Suchen.

REST-API: Vollständig zugänglich über HTTP-Endpunkte für Automatisierung oder Integration.

MCP-Server-fähig: Verwenden Sie es mit MCP-kompatiblen Clients wie Cursor, Copilot, Claude usw.

Authentifizierungsunterstützung: Unterstützt Basic Auth und Bearer Token für geschützte Dokumente.

⚙️ Schnellstart

1. Klonen Sie das Repository

git clone https://github.com/AnhQuan2004/mcp_agent.git
cd mcp_agent

2. Python-Umgebung einrichten

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Abhängigkeiten installieren

pip install -r requirements.txt

4. Erstellen Sie eine .env-Datei (oder verwenden Sie das bereitgestellte .env.example).

QDRANT_URL=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION_NAME=documents

5. Starten Sie Qdrant (Vektor-DB)

Docker verwenden:

docker run -p 6333:6333 qdrant/qdrant

Oder mithilfe des Hilfsskripts:

./runqdrant.sh

6. Ausführen der Agentic-App

uvicorn app.main:app --reload
# or:
python run.py

Besuchen Sie http://localhost:8000

🌐 Webschnittstelle und API

Web-Benutzeroberfläche:

• / - Heim

• /embed – Dokumente über die Benutzeroberfläche einbetten

• /retrieve – Semantische Such-UI

🔍 POST /abrufen

{
  "query": "What is the architecture of Sui?",
  "top_k": 5,
  "group_by_doc": true
}

🌍 Einbetten von URLs

Öffentliche URLs:

• Geben Sie einfach die URL über die API oder Benutzeroberfläche an – keine Authentifizierung erforderlich.

🤖 Verwendung als MCP-Server

So verwenden Sie sui als MCP-Server:

{
  "mcpServers": {
    "suiAgentic": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Tools zum Hochladen von Dokumenten

Dieses Verzeichnis enthält Tools zum Massenhochladen von Dokumenten in Ihre SuiAgentic Qdrant-Datenbank.

Verfügbare Tools

1. upload_folder.py - Ein einfaches Skript zum Hochladen von PDF-Dateien aus einem Ordner

2. upload_documents.py – Ein erweitertes Skript zum Hochladen von PDF-, DOCX- und TXT-Dateien mit mehr Optionen

Related MCP server: RagDocs MCP Server

Voraussetzungen

• Python 3.8+

• SuiAgentic-Anwendung installiert und konfiguriert

• Qdrant-Server, der lokal ausgeführt wird oder über das Netzwerk zugänglich ist

• Erforderliche Abhängigkeiten installiert (PyPDF2, python-docx)

Grundlegende Verwendung

PDF-Dateien aus einem Ordner hochladen

# Upload all PDFs from a folder
python upload_folder.py /path/to/pdf/folder

# Upload with a prefix (useful for categorizing documents)
python upload_folder.py /path/to/pdf/folder --prefix "Research Papers"

Erweiterter Dokument-Upload

# Upload all supported documents from a folder and subfolders
python upload_documents.py /path/to/documents --recursive

# Add metadata tags to all documents
python upload_documents.py /path/to/documents --tag category=research --tag project=alpha

# Specify collection name (if not using default)
python upload_documents.py /path/to/documents --collection my_collection

# Complete example with all options
python upload_documents.py /path/to/documents --recursive --prefix "Project X" --tag department=marketing --tag status=final

Was diese Tools leisten

1. Finden Sie unterstützte Dokumente im angegebenen Ordner

2. Extrahieren Sie Textinhalte aus jedem Dokument

3. Teilen Sie Text in überschaubare Abschnitte auf

4. Generieren Sie 3072-dimensionale Einbettungen für jeden Block

5. Speichern Sie Chunks und Einbettungen in Qdrant

6. Verfolgen Sie Metadaten für jedes Dokument

Befehlszeilenargumente

upload_folder.py

• folder - Pfad zum Ordner mit den PDF-Dateien

• --prefix – Präfix, das den Dokumentnamen hinzugefügt werden soll

upload_documents.py

• folder - Pfad zum Ordner mit den Dokumenten

• --prefix – Präfix, das den Dokumentnamen hinzugefügt werden soll

• --recursive – Rekursive Suche nach Dateien in Unterordnern

• --collection – Name der zu verwendenden Qdrant-Sammlung

• --tag – Metadaten-Tags zu Dokumenten hinzufügen (kann mehrfach verwendet werden: --tag key=value )

Beispiele

Dokumente nach Projekt organisieren

python upload_documents.py /path/to/projects/project1 --recursive --prefix "Project 1" --tag project=alpha
python upload_documents.py /path/to/projects/project2 --recursive --prefix "Project 2" --tag project=beta

Dokumente kategorisieren

python upload_documents.py /path/to/contracts --prefix "Legal" --tag department=legal --tag confidential=true
python upload_documents.py /path/to/manuals --prefix "Technical" --tag department=engineering

Fehlerbehebung

• Wenn bei großen Dokumenten Speicherfehler auftreten, versuchen Sie, sie in kleinere Dateien aufzuteilen

• Bei großen Dokumentensammlungen ist die Verarbeitung in kleineren Stapeln zu erwägen.

• Überprüfen Sie die Protokollausgabe auf etwaige Fehler während der Verarbeitung

🪪 Lizenz

Lizenziert unter der Apache-Lizenz 2.0.