Skillget

zero-vector-MCP

mcp
Security Audit
Warn
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 9 GitHub stars
Code Warn
  • network request — Outbound network request in MCP/package-lock.json
  • network request — Outbound network request in MCP/package.json
  • network request — Outbound network request in MCP/src/apiClient.js
  • process.env — Environment variable access in MCP/src/config.js
  • network request — Outbound network request in zero-vector/package.json
Permissions Pass
  • Permissions — No dangerous permissions requested
Purpose
This tool is a Model Context Protocol (MCP) server that provides a local vector database and AI persona memory management system. It is designed to store, retrieve, and search context for AI development tools using vector similarity.

Security Assessment
Overall risk: Medium. The server makes multiple outbound network requests, which aligns with its architecture of relying on external embedding services like OpenAI. It accesses environment variables (`process.env`) to securely load API keys and server configurations, which is standard practice. No hardcoded secrets were detected, and the tool does not request dangerous operating system permissions or execute arbitrary shell commands. However, because it acts as a local API server and handles external network traffic, developers should properly secure their `.env` files and ensure the server is not exposed to the public internet.

Quality Assessment
The project has a solid foundation, utilizing the permissive MIT license and featuring a highly detailed, comprehensive README. It is under active development, with its last push occurring today. The primary concern is its extremely low community visibility. With only 9 GitHub stars, the codebase lacks the broader peer review, testing, and community trust that come with more widely adopted open-source projects.

Verdict
Use with caution — the code appears safe and follows standard practices, but its low community adoption means it hasn't been battle-tested at scale.
SUMMARY

MCP server for deterministic procedural generation — seed-based world building, terrain & content systems

README.md

Zero-Vector MCP: AI Persona Memory & Vector Database System

A complete AI persona memory management system combining a high-performance vector database server with a Model Context Protocol (MCP) interface for seamless integration with AI development tools like Cline.

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

🎯 Overview

Zero-Vector MCP provides a production-ready solution for AI persona management and vector similarity search, featuring:

  • High-Performance Vector Database - Sub-50ms query times with 349k+ vector capacity
  • AI Persona Memory Management - Context-aware memory storage with semantic search
  • MCP Integration - Seamless integration with AI tools through Model Context Protocol
  • Production-Ready Architecture - Comprehensive security, monitoring, and scalability features

🏗️ System Architecture

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

🚀 Quick Start

Prerequisites

  • Node.js 18.0.0 or higher
  • 2GB+ available RAM (recommended)
  • Git

Installation

# 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

Quick Test

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

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

📚 Component Documentation

This system consists of two main components, each with detailed documentation:

🗄️ Zero-Vector Server

Location: zero-vector/README.md

The core vector database server providing:

  • High-performance vector storage and similarity search
  • RESTful API for vector operations
  • SQLite metadata persistence
  • Authentication and security middleware
  • Real-time monitoring and health checks

🔌 MCP Server

Location: MCP/README.md

The Model Context Protocol interface providing:

  • 13 specialized tools for persona and memory management
  • Seamless integration with AI development tools
  • Comprehensive error handling and validation
  • Structured logging and performance monitoring

✨ Key Features

Vector Database Performance

  • Memory Efficiency: 2GB optimized storage supporting 349,525+ vectors
  • High-Speed Search: Sub-50ms query times with cosine similarity
  • Scalable Architecture: Three-tier design with comprehensive monitoring
  • Multiple Metrics: Cosine, Euclidean, and dot product similarity

AI Persona Management

  • Persona Creation: Configurable AI personas with custom behavior settings
  • Memory Storage: Context-aware memory with importance scoring
  • Semantic Search: Find relevant memories using vector similarity
  • Conversation History: Complete conversation tracking and retrieval
  • Memory Cleanup: Automated cleanup of old or low-importance memories

MCP Integration Tools

  • Persona Tools: create_persona, list_personas, get_persona, update_persona, delete_persona
  • Memory Tools: add_memory, search_persona_memories, add_conversation, get_conversation_history, cleanup_persona_memories
  • Utility Tools: get_system_health, get_persona_stats, test_connection

Security & Production Features

  • API Key Authentication: Secure key generation with role-based permissions
  • Rate Limiting: Multi-tier rate limiting (global, per-key, per-endpoint)
  • Input Validation: Comprehensive request validation and sanitization
  • Structured Logging: Winston-based logging with performance metrics
  • Health Monitoring: Multiple health check endpoints for different monitoring needs

🎮 Use Cases

AI Assistant Memory

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

Vector Similarity Search

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

Integration with 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"
      }
    }
  }
}

🛠️ Development

Project Structure

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

Development Setup

# 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

Environment Configuration

Zero-Vector Server:

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

MCP Server:

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

📊 Performance Characteristics

  • Vector Storage: ~6MB per 1000 vectors (1536 dimensions)
  • Search Performance: <50ms for 10,000+ vector corpus
  • Memory Efficiency: 99.9% utilization of allocated buffer space
  • Throughput: 1000+ vectors/second insertion rate
  • Capacity: 349,525 vectors in 2GB configuration

🔒 Security Features

  • Authentication: API key-based authentication with secure generation
  • Authorization: Role-based access control with granular permissions
  • Rate Limiting: Multiple rate limiting layers (global, per-key, per-endpoint)
  • Input Validation: Comprehensive request validation and sanitization
  • Security Headers: Helmet.js implementation with CSP policies
  • Audit Logging: Complete audit trail for all operations

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for new functionality
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Development Guidelines

  • Follow existing code style and patterns
  • Add comprehensive tests for new features
  • Update documentation for any API changes
  • Ensure all tests pass before submitting PR
  • Include performance considerations for vector operations

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Documentation

Troubleshooting

Connection Issues:

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

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

Common Issues:

  • Ensure Node.js 18+ is installed
  • Verify API key configuration in MCP .env file
  • Check Zero-Vector server is running before starting MCP server
  • Ensure sufficient memory allocation (2GB+ recommended)

Getting Help

  • GitHub Issues: Report bugs and feature requests
  • Discussions: Ask questions and share ideas
  • Wiki: Additional documentation and examples

Zero-Vector MCP - Production-ready AI persona memory management with high-performance vector search

See Also

Reviews (0)

No results found