Zero-Vector MCP

Um servidor de banco de dados vetorial de alto desempenho para gerenciamento de memória de persona de IA.

GitHub
10
Experimente este MCPPatrocinado

Documentação

Zero-Vector MCP: Sistema de Memória de Persona de IA e Banco de Dados Vetorial

Um sistema completo de gerenciamento de memória de persona de IA que combina um servidor de banco de dados vetorial de alto desempenho com uma interface Model Context Protocol (MCP) para integração perfeita com ferramentas de desenvolvimento de IA como o Cline.

🔗 Repositório GitHub: https://github.com/MushroomFleet/zero-vector-MCP

🎯 Visão Geral

O Zero-Vector MCP fornece uma solução pronta para produção para gerenciamento de personas de IA e busca por similaridade vetorial, com:

  • Banco de Dados Vetorial de Alto Desempenho — Tempos de consulta abaixo de 50ms com capacidade para 349k+ vetores
  • Gerenciamento de Memória de Persona de IA — Armazenamento de memória com consciência de contexto e busca semântica
  • Integração MCP — Integração perfeita com ferramentas de IA através do Model Context Protocol
  • Arquitetura Pronta para Produção — Recursos abrangentes de segurança, monitoramento e escalabilidade

🏗️ Arquitetura do 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

🚀 Início Rápido

Pré-requisitos

  • Node.js 18.0.0 ou superior
  • 2GB+ de RAM disponível (recomendado)
  • Git

Instalação

# 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

Teste Rápido

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

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

📚 Documentação dos Componentes

Este sistema consiste em dois componentes principais, cada um com documentação detalhada:

🗄️ Servidor Zero-Vector

Localização: zero-vector/README.md

O servidor central do banco de dados vetorial, fornecendo:

  • Armazenamento vetorial de alto desempenho e busca por similaridade
  • API RESTful para operações vetoriais
  • Persistência de metadados com SQLite
  • Middleware de autenticação e segurança
  • Monitoramento em tempo real e verificações de saúde

🔌 Servidor MCP

Localização: MCP/README.md

A interface Model Context Protocol, fornecendo:

  • 13 ferramentas especializadas para gerenciamento de personas e memória
  • Integração perfeita com ferramentas de desenvolvimento de IA
  • Tratamento abrangente de erros e validação
  • Registro estruturado e monitoramento de desempenho

✨ Principais Recursos

Desempenho do Banco de Dados Vetorial

  • Eficiência de Memória: Armazenamento otimizado de 2GB suportando 349.525+ vetores
  • Busca de Alta Velocidade: Tempos de consulta abaixo de 50ms com similaridade de cosseno
  • Arquitetura Escalável: Design em três camadas com monitoramento abrangente
  • Múltiplas Métricas: Similaridade por cosseno, euclidiana e produto escalar

Gerenciamento de Personas de IA

  • Criação de Personas: Personas de IA configuráveis com configurações de comportamento personalizadas
  • Armazenamento de Memória: Memória com consciência de contexto e pontuação de importância
  • Busca Semântica: Encontre memórias relevantes usando similaridade vetorial
  • Histórico de Conversas: Rastreamento e recuperação completos de conversas
  • Limpeza de Memória: Limpeza automatizada de memórias antigas ou de baixa importância

Ferramentas de Integração MCP

  • Ferramentas de Persona: create_persona, list_personas, get_persona, update_persona, delete_persona
  • Ferramentas de Memória: add_memory, search_persona_memories, add_conversation, get_conversation_history, cleanup_persona_memories
  • Ferramentas Utilitárias: get_system_health, get_persona_stats, test_connection

Recursos de Segurança e Produção

  • Autenticação por Chave de API: Geração segura de chaves com permissões baseadas em papéis
  • Limitação de Taxa: Limitação de taxa em múltiplas camadas (global, por chave, por endpoint)
  • Validação de Entrada: Validação e sanitização abrangentes de solicitações
  • Registro Estruturado: Registro baseado em Winston com métricas de desempenho
  • Monitoramento de Saúde: Múltiplos endpoints de verificação de saúde para diferentes necessidades de monitoramento

🎮 Casos de Uso

Memória de Assistente 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
});

Busca por Similaridade Vetorial

// 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
  })
});

Integração com o 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"
      }
    }
  }
}

🛠️ Desenvolvimento

Estrutura do Projeto

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

Configuração de Desenvolvimento

# 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

Configuração de Ambiente

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 Desempenho

  • Armazenamento Vetorial: ~6MB por 1000 vetores (1536 dimensões)
  • Desempenho de Busca: <50ms para corpus de 10.000+ vetores
  • Eficiência de Memória: 99,9% de utilização do espaço de buffer alocado
  • Taxa de Transferência: Taxa de inserção de 1000+ vetores/segundo
  • Capacidade: 349.525 vetores em configuração de 2GB

🔒 Recursos de Segurança

  • Autenticação: Autenticação baseada em chave de API com geração segura
  • Autorização: Controle de acesso baseado em papéis com permissões granulares
  • Limitação de Taxa: Múltiplas camadas de limitação de taxa (global, por chave, por endpoint)
  • Validação de Entrada: Validação e sanitização abrangentes de solicitações
  • Cabeçalhos de Segurança: Implementação Helmet.js com políticas CSP
  • Registro de Auditoria: Trilha de auditoria completa para todas as operações

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça suas alterações
  4. Adicione testes para novas funcionalidades
  5. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  6. Envie para o branch (git push origin feature/amazing-feature)
  7. Abra um Pull Request

Diretrizes de Desenvolvimento

  • Siga o estilo e os padrões de código existentes
  • Adicione testes abrangentes para novos recursos
  • Atualize a documentação para quaisquer alterações de API
  • Garanta que todos os testes passem antes de enviar o PR
  • Inclua considerações de desempenho para operações vetoriais

📄 Licença

Este projeto está licenciado sob a Licença MIT — consulte o arquivo LICENSE para obter detalhes.

🆘 Suporte

Documentação

  • Banco de Dados Vetorial: Consulte zero-vector/README.md para documentação detalhada do servidor
  • Servidor MCP: Consulte MCP/README.md para documentação de configuração e ferramentas do MCP

Solução de Problemas

Problemas de Conexão:

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

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

Problemas Comuns:

  • Certifique-se de que o Node.js 18+ está instalado
  • Verifique a configuração da chave de API no arquivo de configuração do MCP .env
  • Verifique se o servidor Zero-Vector está em execução antes de iniciar o servidor MCP
  • Garanta alocação de memória suficiente (2GB+ recomendado)

Obtendo Ajuda

  • GitHub Issues: Relate bugs e solicitações de recursos
  • Discussões: Faça perguntas e compartilhe ideias
  • Wiki: Documentação adicional e exemplos

Zero-Vector MCP — Gerenciamento de memória de persona de IA pronto para produção com busca vetorial de alto desempenho

Veja Também