Zero-Vector MCP

Un servidor de base de datos vectorial de alto rendimiento para la gestión de memoria de personajes de IA.

GitHub
10
Prueba este MCPPatrocinado

Documentación

Zero-Vector MCP: Sistema de Memoria de Persona de IA y Base de Datos Vectorial

Un sistema completo de gestión de memoria de persona de IA que combina un servidor de base de datos vectorial de alto rendimiento con una interfaz de Protocolo de Contexto de Modelo (MCP) para una integración perfecta con herramientas de desarrollo de IA como Cline.

🔗 Repositorio de GitHub: https://github.com/MushroomFleet/zero-vector-MCP

🎯 Descripción General

Zero-Vector MCP proporciona una solución lista para producción para la gestión de personas de IA y búsqueda de similitud vectorial, con las siguientes características:

  • Base de Datos Vectorial de Alto Rendimiento - Tiempos de consulta inferiores a 50 ms con capacidad para más de 349k vectores
  • Gestión de Memoria de Persona de IA - Almacenamiento de memoria consciente del contexto con búsqueda semántica
  • Integración MCP - Integración perfecta con herramientas de IA mediante el Protocolo de Contexto de Modelo
  • Arquitectura Lista para Producción - Características integrales de seguridad, monitoreo y escalabilidad

🏗️ Arquitectura del Sistema

graph TB
    subgraph "AI Development Environment"
        A[Cline AI Assistant] --> B[MCP Client]
    end
    
    subgraph "Zero-Vector MCP System"
        B --> C[MCP Server]
        C --> D[Zero-Vector API]
        D --> E[Vector Database]
        D --> F[SQLite Metadata]
        
        subgraph "Core Services"
            G[Persona Manager]
            H[Memory Service]
            I[Embedding Service]
        end
        
        D --> G
        D --> H
        D --> I
    end
    
    subgraph "External Services"
        J[OpenAI Embeddings]
        K[Local Transformers]
    end
    
    I --> J
    I --> K
    
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style E fill:#e8f5e8
    style G fill:#fff3e0
    style H fill:#fff3e0
    style I fill:#fff3e0

🚀 Inicio Rápido

Requisitos Previos

  • Node.js 18.0.0 o superior
  • 2GB+ de RAM disponible (recomendado)
  • Git

Instalación

# Clone the repository
git clone https://github.com/MushroomFleet/zero-vector-MCP.git
cd zero-vector-MCP

# 1. Set up the Zero-Vector server
cd zero-vector/server
npm install
npm run setup:database
npm run generate:api-key  # Generate API key for MCP
cp env.example .env  # Add your Open AI API key
npm start

# 2. Set up the MCP server (in a new terminal)
cd MCP
npm install
cp env.example .env
# Edit .env with your Zero-Vector server URL and API key
npm start

Prueba Rápida

# Test the vector database
curl http://localhost:3000/health

# Test MCP server connection
cd MCP
npm run test:connection

📚 Documentación de Componentes

Este sistema consta de dos componentes principales, cada uno con documentación detallada:

🗄️ Servidor Zero-Vector

Ubicación: zero-vector/README.md

El servidor de base de datos vectorial principal que proporciona:

  • Almacenamiento vectorial de alto rendimiento y búsqueda de similitud
  • API RESTful para operaciones vectoriales
  • Persistencia de metadatos SQLite
  • Middleware de autenticación y seguridad
  • Monitoreo en tiempo real y verificaciones de salud

🔌 Servidor MCP

Ubicación: MCP/README.md

La interfaz del Protocolo de Contexto de Modelo que proporciona:

  • 13 herramientas especializadas para la gestión de personas y memoria
  • Integración perfecta con herramientas de desarrollo de IA
  • Manejo integral de errores y validación
  • Registro estructurado y monitoreo de rendimiento

✨ Características Clave

Rendimiento de la Base de Datos Vectorial

  • Eficiencia de Memoria: Almacenamiento optimizado de 2GB que soporta 349,525+ vectores
  • Búsqueda de Alta Velocidad: Tiempos de consulta inferiores a 50 ms con similitud de coseno
  • Arquitectura Escalable: Diseño de tres niveles con monitoreo integral
  • Múltiples Métricas: Similitud de coseno, euclidiana y producto punto

Gestión de Persona de IA

  • Creación de Personas: Personas de IA configurables con configuraciones de comportamiento personalizadas
  • Almacenamiento de Memoria: Memoria consciente del contexto con puntuación de importancia
  • Búsqueda Semántica: Encuentre recuerdos relevantes usando similitud vectorial
  • Historial de Conversaciones: Seguimiento y recuperación completa de conversaciones
  • Limpieza de Memoria: Limpieza automatizada de recuerdos antiguos o de baja importancia

Herramientas de Integración MCP

  • Herramientas de Persona: create_persona, list_personas, get_persona, update_persona, delete_persona
  • Herramientas de Memoria: add_memory, search_persona_memories, add_conversation, get_conversation_history, cleanup_persona_memories
  • Herramientas de Utilidad: get_system_health, get_persona_stats, test_connection

Características de Seguridad y Producción

  • Autenticación por Clave API: Generación segura de claves con permisos basados en roles
  • Limitación de Tasa: Limitación de tasa de múltiples niveles (global, por clave, por endpoint)
  • Validación de Entrada: Validación y saneamiento integral de solicitudes
  • Registro Estructurado: Registro basado en Winston con métricas de rendimiento
  • Monitoreo de Salud: Múltiples endpoints de verificación de salud para diferentes necesidades de monitoreo

🎮 Casos de Uso

Memoria de Asistente de IA

// Create a persona for an AI assistant
const persona = await mcpClient.createPersona({
  name: "Technical Assistant",
  description: "Helpful coding assistant with memory",
  systemPrompt: "You are a helpful technical assistant...",
  maxMemorySize: 1000
});

// Add important information to memory
await mcpClient.addMemory({
  personaId: persona.id,
  content: "User prefers TypeScript over JavaScript",
  type: "preference",
  importance: 0.8
});

// Search for relevant memories during conversation
const relevantMemories = await mcpClient.searchPersonaMemories({
  personaId: persona.id,
  query: "coding preferences",
  limit: 5
});

Búsqueda de Similitud Vectorial

// Direct vector operations through the API
const response = await fetch('http://localhost:3000/api/vectors/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify({
    query: [0.1, 0.2, 0.3, /* ... 1536 dimensions */],
    limit: 10,
    threshold: 0.7
  })
});

Integración con Cline

{
  "mcpServers": {
    "zero-vector": {
      "command": "node",
      "args": ["C:/path/to/zero-vector-MCP/MCP/src/index.js"],
      "env": {
        "ZERO_VECTOR_BASE_URL": "http://localhost:3000",
        "ZERO_VECTOR_API_KEY": "your_api_key_here"
      }
    }
  }
}

🛠️ Desarrollo

Estructura del Proyecto

zero-vector-MCP/
├── zero-vector/                 # Vector database server
│   ├── server/                  # Node.js backend
│   │   ├── src/                 # Source code
│   │   ├── scripts/             # Setup scripts
│   │   ├── data/                # Database files
│   │   └── README.md            # Server documentation
│   └── README.md                # Server overview
├── MCP/                         # Model Context Protocol server
│   ├── src/                     # MCP server source
│   │   ├── tools/               # MCP tool implementations
│   │   └── utils/               # Utilities
│   ├── .env.example             # Environment template
│   └── README.md                # MCP documentation
├── DOCS/                        # Internal documentation
└── README.md                    # This file

Configuración de Desarrollo

# Start Zero-Vector server in development mode
cd zero-vector/server
npm run dev

# Start MCP server in development mode (new terminal)
cd MCP
npm run dev

# Run tests
npm test

Configuración de Entorno

Servidor Zero-Vector:

NODE_ENV=development
PORT=3000
MAX_MEMORY_MB=2048
DEFAULT_DIMENSIONS=1536
LOG_LEVEL=info

Servidor MCP:

ZERO_VECTOR_BASE_URL=http://localhost:3000
ZERO_VECTOR_API_KEY=your_api_key_here
MCP_SERVER_NAME=zero-vector-mcp
LOG_LEVEL=info

📊 Características de Rendimiento

  • Almacenamiento Vectorial: ~6MB por 1000 vectores (1536 dimensiones)
  • Rendimiento de Búsqueda: <50ms para corpus de 10,000+ vectores
  • Eficiencia de Memoria: 99.9% de utilización del espacio de búfer asignado
  • Rendimiento: Tasa de inserción de 1000+ vectores/segundo
  • Capacidad: 349,525 vectores en configuración de 2GB

🔒 Características de Seguridad

  • Autenticación: Autenticación basada en clave API con generación segura
  • Autorización: Control de acceso basado en roles con permisos granulares
  • Limitación de Tasa: Múltiples capas de limitación de tasa (global, por clave, por endpoint)
  • Validación de Entrada: Validación y saneamiento integral de solicitudes
  • Encabezados de Seguridad: Implementación de Helmet.js con políticas CSP
  • Registro de Auditoría: Rastro de auditoría completo para todas las operaciones

🤝 Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características (git checkout -b feature/amazing-feature)
  3. Realice sus cambios
  4. Agregue pruebas para la nueva funcionalidad
  5. Confirme sus cambios (git commit -m 'Add amazing feature')
  6. Envíe a la rama (git push origin feature/amazing-feature)
  7. Abra una Solicitud de Extracción

Directrices de Desarrollo

  • Siga el estilo y los patrones de código existentes
  • Agregue pruebas integrales para nuevas características
  • Actualice la documentación para cualquier cambio de API
  • Asegúrese de que todas las pruebas pasen antes de enviar el PR
  • Incluya consideraciones de rendimiento para operaciones vectoriales

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENCIA para más detalles.

🆘 Soporte

Documentación

  • Base de Datos Vectorial: Consulte zero-vector/README.md para documentación detallada del servidor
  • Servidor MCP: Consulte MCP/README.md para documentación de configuración y herramientas de MCP

Solución de Problemas

Problemas de Conexión:

# Check Zero-Vector server health
curl http://localhost:3000/health

# Test MCP server connection
cd MCP && npm run test:connection

Problemas Comunes:

  • Asegúrese de que Node.js 18+ esté instalado
  • Verifique la configuración de la clave API en el archivo MCP .env
  • Verifique que el servidor Zero-Vector esté ejecutándose antes de iniciar el servidor MCP
  • Asegure una asignación de memoria suficiente (2GB+ recomendado)

Obteniendo Ayuda

  • Problemas de GitHub: Reporte errores y solicitudes de características
  • Discusiones: Haga preguntas y comparta ideas
  • Wiki: Documentación adicional y ejemplos

Zero-Vector MCP - Gestión de memoria de persona de IA lista para producción con búsqueda vectorial de alto rendimiento

Ver También