Connapse

Tus agentes de IA olvidan todo entre sesiones. Connapse soluciona eso.

Cada vez que inicias una nueva conversación, tu agente de IA comienza desde cero: sin memoria de investigaciones pasadas, sin acceso a tus documentos, sin conocimiento acumulado. Connapse es un backend de conocimiento de código abierto que proporciona a los agentes memoria persistente y buscable. Sube documentos o apúntalo a tus buckets existentes de Amazon S3, contenedores de Azure Blob Storage o sistemas de archivos locales. Los agentes consultan y construyen su propio corpus de investigación a través de 11 herramientas MCP, API REST o CLI. Aislado en contenedores, búsqueda híbrida (vectorial + palabras clave), autohospedado y privado. Despliega en 60 segundos con Docker. Construido sobre .NET 10.

Los agentes de IA consultan tu base de conocimiento a través del servidor MCP, recibiendo respuestas estructuradas con citas de fuentes de tus documentos.

Cambia los proveedores de embedding, ajusta los parámetros de fragmentación y configura la búsqueda: todo en tiempo de ejecución, sin reiniciar.

📦 Inicio rápido

git clone https://github.com/Destrayon/Connapse.git && cd Connapse && docker-compose up -d
# Open http://localhost:5001

Requisitos previos

• Docker y Docker Compose

• .NET 10 SDK (para desarrollo)

• (Opcional) Ollama para embeddings locales

Ejecutar con Docker Compose

# Clone the repository
git clone https://github.com/Destrayon/Connapse.git
cd Connapse

# Set required auth environment variables (or use a .env file)
export CONNAPSE_ADMIN_EMAIL=admin@example.com
export CONNAPSE_ADMIN_PASSWORD=YourSecurePassword123!
export Identity__Jwt__Secret=$(openssl rand -base64 64)

# Start all services (PostgreSQL, MinIO, Web App)
docker-compose up -d

# Open http://localhost:5001 — log in with the admin credentials above

La primera ejecución hará lo siguiente:

1. Descargará las imágenes de Docker (~2-5 minutos)

2. Inicializará PostgreSQL con la extensión pgvector y ejecutará las migraciones de EF Core

3. Creará los buckets de MinIO

4. Sembrará la cuenta de administrador (desde variables de entorno) e iniciará la aplicación web

Configuración de desarrollo

# Start infrastructure only (database + object storage)
docker-compose up -d postgres minio

# Run the web app locally
dotnet run --project src/Connapse.Web

# Run all tests
dotnet test

# Run just unit tests
dotnet test --filter "Category=Unit"

Uso de la CLI

Instala la CLI (elige una opción):

# Option A: .NET Global Tool (requires .NET 10)
dotnet tool install -g Connapse.CLI

# Option B: Download native binary from GitHub Releases (no .NET required)
# https://github.com/Destrayon/Connapse/releases

Uso básico:

# Authenticate first
connapse auth login --url https://localhost:5001

# Create a container (project)
connapse container create my-project --description "My knowledge base"

# Upload files
connapse upload ./documents --container my-project

# Search
connapse search "your query" --container my-project

# Update to latest release (--pre to include alpha/pre-release builds)
connapse update
connapse update --pre

Uso con Claude (MCP)

Connapse incluye un servidor de Protocolo de Contexto de Modelo (MCP) para la integración con Claude y cualquier cliente MCP.

Configuración: Crea una clave de API de agente a través de la interfaz web (Configuración → Claves de API de agente) o CLI (connapse auth agent-key create), luego añade el fragmento de configuración para tu cliente:

claude mcp add connapse --transport streamable-http http://localhost:5001/mcp --header "X-Agent-Api-Key: YOUR_API_KEY"

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "connapse": {
      "transport": "streamable-http",
      "url": "http://localhost:5001/mcp",
      "headers": {
        "X-Agent-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Añade a tu .vscode/settings.json (VS Code) o a la configuración MCP de Cursor:

{
  "mcp": {
    "servers": {
      "connapse": {
        "transport": "streamable-http",
        "url": "http://localhost:5001/mcp",
        "headers": {
          "X-Agent-Api-Key": "${input:connapseApiKey}"
        }
      }
    }
  }
}

VS Code solicitará la clave de API en el primer uso.

El servidor MCP expone 11 herramientas:

Referencia completa: Consulta docs/mcp-tools.md para tablas de parámetros, formatos de retorno, casos de error y ejemplos de uso.

Protecciones de escritura: Los contenedores de Amazon S3 y Azure Blob Storage son de solo lectura (sincronizados desde la fuente). Los contenedores del sistema de archivos respetan las banderas de permisos por contenedor. Las herramientas de subida y eliminación devolverán un error para los contenedores que bloqueen las escrituras.

• "Crea un contenedor llamado 'project-research' para mis notas de arquitectura"

• "Sube todos los PDF de mi carpeta de descargas al contenedor project-research"

• "Busca en mi contenedor project-research información sobre estrategias de limitación de tasa"

• "Lista todos los archivos en la carpeta /notes/ de mi contenedor project-research"

• "Obtén el texto completo de distributed-systems-notes.md de project-research"

• "Elimina meeting-2026-03-14.md de project-research y sube esta versión actualizada"

• "Elimina todos los archivos en la carpeta /drafts/ de project-research"

• "¿Cuántos documentos y fragmentos hay en mi contenedor project-research?"

Conexión rechazada en localhost:5001 — Docker no se está ejecutando o hay conflicto de puertos. Comprueba docker compose ps y docker compose logs web.

401 No autorizado / La clave de API no funciona — Verifica la clave en Configuración > Claves de API de agente. Las claves se muestran una vez al crearlas.

Las herramientas no aparecen en Claude — Reinicia tu cliente MCP después de los cambios de configuración. Verifica el endpoint con curl http://localhost:5001/mcp.

Las subidas fallan o se agota el tiempo de espera — Comprueba que el tipo de archivo esté en la lista de permitidos. El tamaño máximo de archivo depende de la configuración del servidor.

La búsqueda no devuelve resultados — Los documentos necesitan tiempo para ser procesados (embeddings) después de la subida. Comprueba las estadísticas del contenedor para ver el progreso.

🚀 Características

• 🗂️ Conocimiento aislado en contenedores — Cada proyecto obtiene su propio índice vectorial, conector de almacenamiento y configuración de búsqueda. Sin contaminación cruzada entre proyectos, equipos o clientes.

• 🔍 Búsqueda híbrida — Similitud vectorial + texto completo de palabras clave con fusión configurable (combinación convexa, DBSF, AutoCut). Obtén resultados que la búsqueda puramente vectorial pierde.

• 🧠 IA multi-proveedor — Cambia entre Ollama, OpenAI, Azure OpenAI y Anthropic tanto para embeddings como para LLM, en tiempo de ejecución, por contenedor, sin reiniciar.

• 🔌 Indexa tu almacenamiento existente — Conecta MinIO, sistema de archivos local (observación de archivos en vivo), Amazon S3 (autenticación IAM) o Azure Blob Storage (identidad administrada). Tus archivos permanecen donde están.

• 🤖 4 superficies de acceso — Interfaz web, API REST, CLI (binarios nativos) y servidor MCP (11 herramientas para Claude). Construido para humanos, scripts y agentes de IA por igual.

• 🔐 Autenticación empresarial — RBAC de varios niveles (Cookie + OAuth 2.1 + PAT + JWT) con AWS IAM Identity Center y vinculación de identidad de Azure AD. Los permisos de la nube son la fuente de verdad.

• 🐳 Despliegue con un comando — Docker Compose con PostgreSQL + pgvector, MinIO y Ollama opcional. Registro de auditoría estructurado y limitación de tasa integrados.

• 📄 Ingesta multiformato: PDF, documentos de Office, Markdown, texto plano: analizados, fragmentados e integrados automáticamente

• ⚡ Procesamiento en tiempo real: Ingesta en segundo plano con actualizaciones de progreso en vivo a través de SignalR

• 🎛️ Configuración en tiempo de ejecución: Cambia la estrategia de fragmentación, el modelo de embedding y los ajustes de búsqueda por contenedor sin reiniciar

• ☁️ Vinculación de identidad en la nube: AWS IAM Identity Center (flujo de autenticación de dispositivo) + Azure AD (OAuth2+PKCE) con cumplimiento de alcance derivado de IAM

• 👥 Acceso solo por invitación: Registro de usuarios controlado por el administrador con cuatro roles (Administrador / Editor / Visor / Agente)

• 🤖 Gestión de agentes: Entidades de agente dedicadas con ciclo de vida de clave de API, permisos con alcance y pistas de auditoría

• 📋 Registro de auditoría: Pista de auditoría estructurada para subidas, eliminaciones, operaciones de contenedor y eventos de autenticación

• 📦 Distribución CLI: Binarios nativos autocontenidos (Windows/Linux/macOS) y herramienta global .NET a través de NuGet

• 🔄 Búsqueda entre modelos: Cambia los modelos de embedding a mitad del proyecto: respaldo automático de Semántico→Híbrido para vectores heredados

🎯 ¿Para quién es Connapse?

• Desarrolladores de agentes de IA que necesitan un backend de conocimiento que sus agentes puedan consultar y construir: sube investigación, cura un corpus y búscalo a través de MCP o API REST

• Equipos de .NET / Azure que desean una plataforma RAG que se ajuste a su stack existente y a su identidad en la nube

• Equipos empresariales que necesitan bases de conocimiento aisladas por proyecto con RBAC adecuado y pistas de auditoría

• Cualquiera que esté cansado de volver a subir archivos: apunta Connapse a tu almacenamiento existente de Amazon S3/Azure Blob Storage/sistema de archivos

Este proyecto está en desarrollo activo (v0.3.2) y acercándose a la preparación para producción.

v0.3.x añade arquitectura de conector en la nube con control de acceso basado en IAM, soporte para embeddings y LLM de múltiples proveedores, vinculación de identidad en la nube (AWS SSO + Azure AD) y limitación de tasa.

• ✅ Autenticación y autorización (v0.2.0)

• ✅ Control de acceso basado en roles (Administrador / Editor / Visor / Agente)

• ✅ Registro de auditoría

• ✅ Vinculación de identidad en la nube — AWS IAM Identity Center + Azure AD OAuth2+PKCE (v0.3.0)

• ✅ Cumplimiento de alcance derivado de IAM — los permisos de la nube son la fuente de verdad (v0.3.0)

• ✅ Limitación de tasa — middleware integrado de ASP.NET Core con políticas por usuario y por IP (v0.3.2)

• ⚠️ Establece un Identity__Jwt__Secret fuerte en producción — consulta la guía de despliegue

Consulta SECURITY.md para conocer la política de seguridad completa.

🏗️ Arquitectura

┌──────────────────────────────────────────────────────────────────────┐
│                         Access Surfaces                              │
│  Web UI (Blazor)  │  REST API  │  CLI  │  MCP Server                │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                       Core Services Layer                            │
│  Document Store  │  Vector Store  │  Search  │  Ingestion           │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                        Connectors Layer                              │
│  MinIO  │  Filesystem  │  Amazon S3  │  Azure Blob Storage          │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                        Infrastructure                                │
│  PostgreSQL+pgvector  │  MinIO (S3)  │  Ollama (optional)           │
└──────────────────────────────────────────────────────────────────────┘

Flujo de datos: Subida → Búsqueda

[Upload] → [Parse] → [Chunk] → [Embed] → [Store] → [Searchable]
              ↓
         [Metadata]
              ↓
        [Document Store]

Objetivo: < 30 segundos desde la subida hasta que sea buscable.

Tecnologías clave:

• Base de datos: PostgreSQL 17 + pgvector para embeddings vectoriales

• Almacenamiento de objetos: Abstracción de almacenamiento administrado: MinIO (compatible con S3) por defecto, anulable por despliegue

• Backend: ASP.NET Core 10 Minimal APIs

• Frontend: Blazor Server (modo interactivo)

• Embeddings: Ollama (por defecto), OpenAI, Azure OpenAI (configurable)

• LLM: Ollama, OpenAI, Azure OpenAI, Anthropic (configurable)

• Búsqueda: Híbrida vectorial + palabras clave con fusión de combinación convexa

• Conectores: Almacenamiento administr