🧠 SuiAgentic

SuiAgentic es una aplicación basada en FastAPI para la incrustación de documentos y la recuperación semántica, impulsada por la base de datos vectorial Qdrant. Permite convertir documentos (desde URL o archivos locales) en incrustaciones, almacenarlos eficientemente y recuperar contenido relevante mediante consultas en lenguaje natural. Está diseñada para ser compatible con herramientas optimizadas con IA como Cursor, Copilot, Claude y otros clientes compatibles con MCP.

¿Por qué SuiAgentic? Muchas organizaciones necesitan integrar el contexto de documentos internos (p. ej., PRD, especificaciones de diseño, wikis) en las herramientas que utilizan los desarrolladores y los profesionales del conocimiento. Sin embargo, consolidar documentos de diversas fuentes en una base de conocimiento centralizada y con capacidad de búsqueda es complejo y fragmentado.

SuiAgentic soluciona este problema proporcionando un servidor de contexto centralizado que ingiere, fragmenta, integra e indexa su contenido, poniéndolo a disposición mediante una API REST sencilla y una interfaz web. También puede utilizarse como servidor MCP para agentes de IA.

🚀 Características principales Incorporación de documentos: extrae contenido de las URL (con o sin autenticación), lo divide en fragmentos, genera incorporaciones y las almacena en Qdrant.

Búsqueda semántica: consulte su base de conocimientos con lenguaje natural y recupere fragmentos o documentos relevantes.

Interfaz web: interfaz web fácil de usar para integrar y realizar búsquedas.

API REST: totalmente accesible a través de puntos finales HTTP para automatización o integración.

Servidor MCP listo: úselo con clientes compatibles con MCP como Cursor, Copilot, Claude, etc.

Soporte de autenticación: admite autenticación básica y token de portador para documentos protegidos.

⚙️ Inicio rápido

1. Clonar el repositorio

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

2. Configurar el entorno de Python

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

3. Instalar dependencias

pip install -r requirements.txt

4. Cree un archivo .env (o utilice el archivo .env.example proporcionado)

QDRANT_URL=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION_NAME=documents

5. Iniciar Qdrant (Base de datos vectorial)

Usando Docker:

docker run -p 6333:6333 qdrant/qdrant

O usando el script auxiliar:

./runqdrant.sh

6. Ejecutar la aplicación Agentic

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

Visita http://localhost:8000

Interfaz web y API

Interfaz web:

• / - Hogar

• /embed — Incrustar documentos a través de la interfaz de usuario

• /retrieve — Interfaz de usuario de búsqueda semántica

🔍 PUBLICAR /recuperar

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

🌍Incrustar desde URL

URL públicas:

• Simplemente proporcione la URL a través de la API o la UI; no se necesita autenticación.

🤖Usándolo como servidor MCP

Para utilizar sui como servidor MCP:

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

Herramientas para subir documentos

Este directorio contiene herramientas para cargar documentos en masa a su base de datos SuiAgentic Qdrant.

Herramientas disponibles

1. upload_folder.py - Un script simple para cargar archivos PDF desde una carpeta

2. upload_documents.py : un script avanzado para cargar archivos PDF, DOCX y TXT con más opciones

Related MCP server: Qdrant MCP Server

Prerrequisitos

• Python 3.8+

• Aplicación SuiAgentic instalada y configurada

• Servidor Qdrant ejecutándose localmente o accesible a través de la red

• Dependencias requeridas instaladas (PyPDF2, python-docx)

Uso básico

Subir archivos PDF desde una carpeta

# 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"

Carga avanzada de documentos

# 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

Qué hacen estas herramientas

1. Buscar documentos compatibles en la carpeta especificada

2. Extraer el contenido del texto de cada documento

3. Dividir el texto en fragmentos manejables

4. Generar incrustaciones de 3072 dimensiones para cada fragmento

5. Almacenar fragmentos e incrustaciones en Qdrant

6. Realizar un seguimiento de los metadatos de cada documento

Argumentos de la línea de comandos

carpeta_de_carga.py

• folder - Ruta a la carpeta que contiene los archivos PDF

• --prefix - Prefijo para agregar a los nombres de los documentos

subir_documentos.py

• folder - Ruta a la carpeta que contiene los documentos

• --prefix - Prefijo para agregar a los nombres de los documentos

• --recursive - Busca archivos recursivamente en subcarpetas

• --collection - Nombre de la colección de Qdrant a utilizar

• --tag - Agrega etiquetas de metadatos a los documentos (se puede usar varias veces: --tag key=value )

Ejemplos

Organizar documentos por proyecto

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

Categorizar documentos

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

Solución de problemas

• Si encuentra errores de memoria con documentos grandes, intente dividirlos en archivos más pequeños

• Para grandes colecciones de documentos, considere procesarlos en lotes más pequeños

• Verifique la salida del registro para detectar cualquier error durante el procesamiento

🪪 Licencia

Con licencia Apache 2.0.