Ainative Zerodb Mcp Server

ZeroDB MCP Server v2.3.2

[npm version] [npm downloads] [license] [test coverage]

Enterprise-grade Model Context Protocol (MCP) server providing full access to ZeroDB's vector search, quantum compression, PostgreSQL, NoSQL operations, and persistent memory for AI agents.

What's New in v2.3.2

• Auth endpoint fix — login uses /v1/auth/login with email field (was broken in v2.2.0)
• Execute endpoint fix — all MCP operations route through /v1/public/mcp (was dead endpoint)
• PostgreSQL endpoint fix — all 7 postgres management paths corrected
• Test env isolation fix — 151/151 tests passing with proper env var cleanup
• 3 Embedding Tools (from v2.2.0) — zerodb_generate_embeddings, zerodb_embed_and_store, zerodb_semantic_search
• Multi-Dimension Support — 384, 768, 1024, or 1536 dimension vectors
• Free Models — BAAI/bge-small/base/large-en-v1.5 (no API costs)
• See EMBEDDING_TOOLS_GUIDE.md for complete documentation

Key Features

• 70+ Complete Operations - Full API coverage across all ZeroDB capabilities including embedding tools
• Vector Search - Semantic similarity search with 384/768/1024/1536-dimensional embeddings
• Free Embeddings - Generate embeddings with BAAI BGE models (no OpenAI costs!)
• Quantum Compression - Advanced vector compression using quantum algorithms
• PostgreSQL Operations - Full SQL query execution, schema management, backups, and statistics
• NoSQL Tables - Flexible table operations for structured data
• File Storage - Secure file upload, download, and management
• Event System - Event-driven architecture with pub/sub support
• Project Management - Multi-tenant project isolation and management
• RLHF Integration - Reinforcement Learning from Human Feedback collection
• Admin Tools - System monitoring, optimization, and health checks
• Enterprise Security - JWT authentication with automatic token renewal + SQL injection prevention
• 90%+ Test Coverage - Comprehensive test suite for production reliability

Table of Contents

• Installation
• Quick Start
• API Reference
  • Memory Operations (3)
  • Vector Operations (10)
  • Quantum Operations (6)
  • Table/NoSQL Operations (8)
  • File Operations (6)
  • Event Operations (5)
  • Project Operations (7)
  • RLHF Operations (10)
  • Admin Operations (5)
  • PostgreSQL Operations (6)
• Configuration
• Examples
• Migration Guide
• Troubleshooting
• Contributing
• License

Installation

NPM Global Installation

npm install -g ainative-zerodb-mcp-server

NPX (No Installation Required)

npx ainative-zerodb-mcp-server

Requirements

• Node.js >= 18.0.0
• NPM >= 9.0.0
• ZeroDB account with API credentials (see below)

Getting Started

Step 1: Create Your ZeroDB Account

Before using the MCP server, you need a ZeroDB account and project.

Option A: Register via Web (Recommended)

Visit: https://api.ainative.studio/docs

1. Click on "Register User" endpoint
2. Use the "Try it out" feature
3. Enter your email, password, and username

Option B: Register via API

curl -X POST 'https://api.ainative.studio/v1/public/auth/register' \  -H 'Content-Type: application/json' \  -d '{    "email": "[email protected]",    "password": "YourSecurePassword123!",    "username": "yourname"  }'

Response:

{  "email": "[email protected]",  "id": "user-uuid-here",  "username": "yourname"}

Step 2: Create a Project

After registration, create a project to get your PROJECT_ID:

# 1. Login to get your access tokencurl -X POST 'https://api.ainative.studio/v1/auth/login' \  -H 'Content-Type: application/json' \  -d '{    "email": "[email protected]",    "password": "YourSecurePassword123!"  }'

Response:

{  "access_token": "eyJhbGc...",  "token_type": "bearer",  "expires_in": 1800}

# 2. Create a project using your tokencurl -X POST 'https://api.ainative.studio/v1/public/projects' \  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \  -H 'Content-Type: application/json' \  -d '{    "name": "My ZeroDB MCP Project",    "description": "Project for Claude Desktop MCP integration"  }'

Response:

{  "id": "550e8400-e29b-41d4-a716-446655440000",  "name": "My ZeroDB MCP Project",  "status": "ACTIVE",  ...}

Save this Project ID! You'll need it for the MCP configuration.

Quick Start

Step 3: Configure Claude Desktop

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{  "mcpServers": {    "zerodb": {      "command": "npx",      "args": ["ainative-zerodb-mcp-server"],      "env": {        "ZERODB_API_URL": "https://api.ainative.studio",        "ZERODB_PROJECT_ID": "your-project-id-here",        "ZERODB_API_KEY": "your-api-key",        "MCP_CONTEXT_WINDOW": "8192",        "MCP_RETENTION_DAYS": "30"      }    }  }}

Step 4: Restart Claude Desktop

After saving the configuration, restart Claude Desktop to activate the MCP server.

Step 5: Test Your First Operation

In Claude Desktop, try:

Store a memory: "This is my first ZeroDB memory entry"

Claude will use the zerodb_store_memory tool to persist this information.

API Reference

All 60 operations are organized into 9 categories. Each operation is exposed as an MCP tool that Claude can invoke.

Memory Operations

1. zerodb_store_memory

Store agent memory in ZeroDB for persistent context across sessions.

Parameters:

• content (string, required) - Memory content to store
• role (string, required) - Message role: "user", "assistant", or "system"
• session_id (string, optional) - Session identifier (auto-generated if not provided)
• agent_id (string, optional) - Agent identifier (auto-generated if not provided)
• metadata (object, optional) - Additional metadata

Returns:

{  "memory_id": "uuid",  "created_at": "2025-10-14T12:00:00Z"}

Example:

{  "content": "User prefers dark mode and TypeScript",  "role": "system",  "metadata": {    "category": "preferences"  }}

2. zerodb_search_memory

Search agent memory using semantic similarity.

Parameters:

• query (string, required) - Search query
• session_id (string, optional) - Filter by session
• agent_id (string, optional) - Filter by agent
• role (string, optional) - Filter by role
• limit (number, optional) - Max results (default: 10)

Returns:

{  "memories": [    {      "memory_id": "uuid",      "content": "string",      "role": "user|assistant|system",      "created_at": "timestamp",      "similarity_score": 0.95    }  ]}

Example:

{  "query": "What were the user's preferences?",  "limit": 5}

3. zerodb_get_context

Get agent context window for current session, optimized for token limits.

Parameters:

• session_id (string, required) - Session identifier
• agent_id (string, optional) - Agent identifier
• max_tokens (number, optional) - Max tokens in context (default: 8192)

Returns:

{  "session_id": "uuid",  "agent_id": "uuid",  "total_tokens": 1024,  "memory_count": 15,  "messages": [    {      "role": "user",      "content": "string",      "timestamp": "2025-10-14T12:00:00Z"    }  ]}

Example:

{  "session_id": "session-123",  "max_tokens": 4096}

Vector Operations

4. zerodb_store_vector

Store vector embedding with metadata (exactly 1536 dimensions).

Parameters:

• vector_embedding (array[number], required) - 1536-dimensional vector
• document (string, required) - Source document text
• metadata (object, optional) - Document metadata
• namespace (string, optional) - Vector namespace (default: "windsurf")

Returns:

{  "vector_id": "uuid",  "namespace": "windsurf"}

Example:

{  "vector_embedding": [0.1, 0.2, ..., 0.9], // 1536 values  "document": "This is the source text",  "metadata": {    "source": "documentation",    "page": 42  }}

5. zerodb_batch_upsert_vectors

Batch upsert multiple vectors for improved performance.

Parameters:

• vectors (array, required) - Array of vector objects
  • vector_embedding (array[number], required) - 1536-dimensional vector
  • document (string, required) - Source document
  • metadata (object, optional) - Document metadata
• namespace (string, optional) - Vector namespace

Returns:

{  "success_count": 100,  "failed_count": 0,  "vector_ids": ["uuid1", "uuid2", ...]}

Example:

{  "vectors": [    {      "vector_embedding": [...],      "document": "Document 1",      "metadata": {"index": 1}    },    {      "vector_embedding": [...],      "document": "Document 2",      "metadata": {"index": 2}    }  ],  "namespace": "knowledge-base"}

6. zerodb_search_vectors

Search vectors using semantic similarity.

Parameters:

• query_vector (array[number], required) - 1536-dimensional query vector
• namespace (string, optional) - Vector namespace
• limit (number, optional) - Max results (default: 10)
• threshold (number, optional) - Similarity threshold 0-1 (default: 0.7)

Returns:

{  "vectors": [    {      "vector_id": "uuid",      "document": "string",      "similarity_score": 0.95,      "metadata": {}    }  ]}

Example:

{  "query_vector": [...], // 1536 values  "namespace": "windsurf",  "limit": 20,  "threshold": 0.8}

7. zerodb_delete_vector

Delete a specific vector by ID.

Parameters:

• vector_id (string, required) - Vector UUID to delete

Returns:

{  "success": true,  "deleted_id": "uuid"}

Example:

{  "vector_id": "123e4567-e89b-12d3-a456-426614174000"}

8. zerodb_get_vector

Retrieve a specific vector by ID.

Parameters:

• vector_id (string, required) - Vector UUID to retrieve

Returns:

{  "vector_id": "uuid",  "vector_embedding": [...],  "document": "string",  "metadata": {},  "created_at": "timestamp"}

Example:

{  "vector_id": "123e4567-e89b-12d3-a456-426614174000"}

9. zerodb_list_vectors

List vectors with pagination and filtering.

Parameters:

• namespace (string, optional) - Filter by namespace
• limit (number, optional) - Results per page (default: 50)
• offset (number, optional) - Pagination offset (default: 0)

Returns:

{  "vectors": [...],  "total_count": 1000,  "limit": 50,  "offset": 0}

Example:

{  "namespace": "windsurf",  "limit": 100,  "offset": 200}

10. zerodb_vector_stats

Get statistics about vector storage.

Parameters:

• namespace (string, optional) - Filter by namespace

Returns:

{  "total_vectors": 10000,  "namespaces": {    "windsurf": 5000,    "default": 5000  },  "storage_bytes": 1048576,  "avg_dimension": 1536}

Example:

{  "namespace": "windsurf"}

11. zerodb_create_vector_index

Create a vector search index for improved performance.

Parameters:

• namespace (string, required) - Namespace to index
• index_type (string, optional) - Index type: "ivfflat" or "hnsw" (default: "hnsw")
• params (object, optional) - Index-specific parameters

Returns:

{  "index_id": "uuid",  "namespace": "windsurf",  "index_type": "hnsw",  "status": "created"}

Example:

{  "namespace": "windsurf",  "index_type": "hnsw",  "params": {    "m": 16,    "ef_construction": 200  }}

12. zerodb_optimize_vectors

Optimize vector storage and indexes.

Parameters:

• namespace (string, optional) - Namespace to optimize

Returns:

{  "optimized": true,  "space_saved_bytes": 102400,  "duration_ms": 1500}

Example:

{  "namespace": "windsurf"}

13. zerodb_export_vectors

Export vectors to external format.

Parameters:

• namespace (string, required) - Namespace to export
• format (string, optional) - Export format: "json" or "csv" (default: "json")
• include_embeddings (boolean, optional) - Include vector data (default: false)

Returns:

{  "export_id": "uuid",  "download_url": "https://...",  "expires_at": "timestamp"}

Example:

{  "namespace": "windsurf",  "format": "json",  "include_embeddings": true}

Quantum Operations

14. zerodb_quantum_compress

Compress vector using quantum algorithms for reduced storage.

Parameters:

• vector_embedding (array[number], required) - 1536-dimensional vector to compress
• compression_ratio (number, optional) - Target ratio 0-1 (default: 0.5)
• algorithm (string, optional) - Algorithm: "qaoa" or "vqe" (default: "qaoa")

Returns:

{  "compressed_vector": [...],  "original_dimensions": 1536,  "compressed_dimensions": 768,  "compression_ratio": 0.5,  "fidelity_score": 0.98}

Example:

{  "vector_embedding": [...],  "compression_ratio": 0.6,  "algorithm": "qaoa"}

15. zerodb_quantum_decompress

Decompress quantum-compressed vector.

Parameters:

• compressed_vector (array[number], required) - Compressed vector data
• original_dimensions (number, required) - Original dimension count

Returns:

{  "decompressed_vector": [...],  "dimensions": 1536,  "reconstruction_error": 0.02}

Example:

{  "compressed_vector": [...],  "original_dimensions": 1536}

16. zerodb_quantum_hybrid_search

Perform hybrid search using quantum-enhanced similarity.

Parameters:

• query_vector (array[number], required) - 1536-dimensional query
• namespace (string, optional) - Vector namespace
• limit (number, optional) - Max results (default: 10)
• quantum_weight (number, optional) - Quantum influence 0-1 (default: 0.5)

Returns:

{  "vectors": [    {      "vector_id": "uuid",      "document": "string",      "similarity_score": 0.96,      "quantum_score": 0.94,      "hybrid_score": 0.95    }  ]}

Example:

{  "query_vector": [...],  "namespace": "windsurf",  "limit": 10,  "quantum_weight": 0.7}

17. zerodb_quantum_optimize

Optimize vector space using quantum optimization.

Parameters:

• namespace (string, required) - Namespace to optimize
• optimization_target (string, optional) - "storage" or "search_speed" (default: "storage")

Returns:

{  "optimized": true,  "improvement_percentage": 35.5,  "duration_ms": 5000}

Example:

{  "namespace": "windsurf",  "optimization_target": "search_speed"}

18. zerodb_quantum_feature_map

Generate quantum feature map for vector.

Parameters:

• vector_embedding (array[number], required) - 1536-dimensional vector
• feature_map_type (string, optional) - "zz" or "pauli" (default: "zz")

Returns:

{  "feature_map": [...],  "quantum_circuit_depth": 10,  "qubit_count": 12}

Example:

{  "vector_embedding": [...],  "feature_map_type": "pauli"}

19. zerodb_quantum_kernel

Compute quantum kernel similarity between vectors.

Parameters:

• vector_a (array[number], required) - First 1536-dimensional vector
• vector_b (array[number], required) - Second 1536-dimensional vector
• kernel_type (string, optional) - "linear" or "rbf" (default: "rbf")

Returns:

{  "kernel_similarity": 0.92,  "quantum_advantage": 0.15,  "computation_time_ms": 45}

Example:

{  "vector_a": [...],  "vector_b": [...],  "kernel_type": "rbf"}

Table/NoSQL Operations

20. zerodb_create_table

Create a new NoSQL table with schema.

Parameters:

• table_name (string, required) - Table name
• schema (object, required) - JSON schema definition
• description (string, optional) - Table description

Returns:

{  "table_id": "uuid",  "table_name": "string",  "created_at": "timestamp"}

Example:

{  "table_name": "user_profiles",  "schema": {    "user_id": "uuid",    "name": "string",    "email": "string",    "created_at": "timestamp"  },  "description": "User profile information"}

21. zerodb_list_tables

List all tables in project.

Parameters:

• limit (number, optional) - Results per page (default: 50)
• offset (number, optional) - Pagination offset (default: 0)

Returns:

{  "tables": [    {      "table_id": "uuid",      "table_name": "string",      "row_count": 1000,      "created_at": "timestamp"    }  ],  "total_count": 10}

Example:

{  "limit": 100,  "offset": 0}

22. zerodb_get_table

Get table details and schema.

Parameters:

• table_id (string, required) - Table UUID

Returns:

{  "table_id": "uuid",  "table_name": "string",  "schema": {},  "row_count": 1000,  "created_at": "timestamp"}

Example:

{  "table_id": "123e4567-e89b-12d3-a456-426614174000"}

23. zerodb_delete_table

Delete a table and all its data.

Parameters:

• table_id (string, required) - Table UUID to delete

Returns:

{  "success": true,  "deleted_id": "uuid",  "rows_deleted": 1000}

Example:

{  "table_id": "123e4567-e89b-12d3-a456-426614174000"}

24. zerodb_insert_rows

Insert rows into table.

Parameters:

• table_id (string, required) - Table UUID
• rows (array, required) - Array of row objects

Returns:

{  "inserted_count": 100,  "row_ids": ["uuid1", "uuid2", ...]}

Example:

{  "table_id": "123e4567-e89b-12d3-a456-426614174000",  "rows": [    {      "user_id": "user-1",      "name": "John Doe",      "email": "[email protected]"    },    {      "user_id": "user-2",      "name": "Jane Smith",      "email": "[email protected]"    }  ]}

25. zerodb_query_rows

Query table rows with filters.

Parameters:

• table_id (string, required) - Table UUID
• filters (object, optional) - Query filters
• limit (number, optional) - Max results (default: 50)
• offset (number, optional) - Pagination offset (default: 0)

Returns:

{  "rows": [...],  "total_count": 1000,  "limit": 50,  "offset": 0}

Example:

{  "table_id": "123e4567-e89b-12d3-a456-426614174000",  "filters": {    "email": {      "$contains": "@example.com"    }  },  "limit": 100}

26. zerodb_update_rows

Update rows in table.

Parameters:

• table_id (string, required) - Table UUID
• filters (object, required) - Row selection filters
• updates (object, required) - Fields to update

Returns:

{  "updated_count": 50,  "row_ids": ["uuid1", "uuid2", ...]}

Example:

{  "table_id": "123e4567-e89b-12d3-a456-426614174000",  "filters": {    "user_id": "user-1"  },  "updates": {    "email": "[email protected]"  }}

27. zerodb_delete_rows

Delete rows from table.

Parameters:

• table_id (string, required) - Table UUID
• filters (object, required) - Row selection filters

Returns:

{  "deleted_count": 25,  "row_ids": ["uuid1", "uuid2", ...]}

Example:

{  "table_id": "123e4567-e89b-12d3-a456-426614174000",  "filters": {    "created_at": {      "$lt": "2025-01-01"    }  }}

File Operations

28. zerodb_upload_file

Upload file to ZeroDB storage.

Parameters:

• file_name (string, required) - File name
• file_data (string, required) - Base64-encoded file data
• content_type (string, optional) - MIME type
• metadata (object, optional) - File metadata

Returns:

{  "file_id": "uuid",  "file_name": "string",  "size_bytes": 1024,  "upload_url": "string"}

Example:

{  "file_name": "document.pdf",  "file_data": "base64encodeddata...",  "content_type": "application/pdf",  "metadata": {    "category": "documentation"  }}

29. zerodb_download_file

Download file from ZeroDB storage.

Parameters:

• file_id (string, required) - File UUID

Returns:

{  "file_id": "uuid",  "file_name": "string",  "file_data": "base64encodeddata...",  "content_type": "string",  "size_bytes": 1024}

Example:

{  "file_id": "123e4567-e89b-12d3-a456-426614174000"}

30. zerodb_list_files

List files with pagination.

Parameters:

• limit (number, optional) - Results per page (default: 50)
• offset (number, optional) - Pagination offset (default: 0)
• content_type (string, optional) - Filter by MIME type

Returns:

{  "files": [    {      "file_id": "uuid",      "file_name": "string",      "size_bytes": 1024,      "content_type": "string",      "created_at": "timestamp"    }  ],  "total_count": 100}

Example:

{  "limit": 100,  "content_type": "application/pdf"}

31. zerodb_delete_file

Delete file from storage.

Parameters:

• file_id (string, required) - File UUID to delete

Returns:

{  "success": true,  "deleted_id": "uuid"}

Example:

{  "file_id": "123e4567-e89b-12d3-a456-426614174000"}

32. zerodb_get_file_metadata

Get file metadata without downloading.

Parameters:

• file_id (string, required) - File UUID

Returns:

{  "file_id": "uuid",  "file_name": "string",  "size_bytes": 1024,  "content_type": "string",  "metadata": {},  "created_at": "timestamp"}

Example:

{  "file_id": "123e4567-e89b-12d3-a456-426614174000"}

33. zerodb_generate_presigned_url

Generate temporary download URL.

Parameters:

• file_id (string, required) - File UUID
• expiry_seconds (number, optional) - URL validity (default: 3600)

Returns:

{  "file_id": "uuid",  "presigned_url": "https://...",  "expires_at": "timestamp"}

Example:

{  "file_id": "123e4567-e89b-12d3-a456-426614174000",  "expiry_seconds": 7200}

Event Operations

34. zerodb_create_event

Create a new event in the event system.

Parameters:

• event_type (string, required) - Event type identifier
• event_data (object, required) - Event payload
• metadata (object, optional) - Event metadata

Returns:

{  "event_id": "uuid",  "event_type": "string",  "created_at": "timestamp"}

Example:

{  "event_type": "user.signup",  "event_data": {    "user_id": "user-123",    "email": "[email protected]"  },  "metadata": {    "source": "web"  }}

35. zerodb_list_events

List events with filtering and pagination.

Parameters:

• event_type (string, optional) - Filter by event type
• start_date (string, optional) - Filter by start date (ISO 8601)
• end_date (string, optional) - Filter by end date (ISO 8601)
• limit (number, optional) - Results per page (default: 50)
• offset (number, optional) - Pagination offset (default: 0)

Returns:

{  "events": [    {      "event_id": "uuid",      "event_type": "string",      "event_data": {},      "created_at": "timestamp"    }  ],  "total_count": 1000}

Example:

{  "event_type": "user.signup",  "start_date": "2025-10-01T00:00:00Z",  "limit": 100}

36. zerodb_get_event

Get specific event by ID.

Parameters:

• event_id (string, required) - Event UUID

Returns:

{  "event_id": "uuid",  "event_type": "string",  "event_data": {},  "metadata": {},  "created_at": "timestamp"}

Example:

{  "event_id": "123e4567-e89b-12d3-a456-426614174000"}

37. zerodb_subscribe_events

Subscribe to event stream (WebSocket).

Parameters:

• event_types (array[string], required) - Event types to subscribe to
• filters (object, optional) - Additional filters

Returns:

{  "subscription_id": "uuid",  "event_types": ["user.signup", "user.login"],  "websocket_url": "wss://..."}

Example:

{  "event_types": ["user.signup", "user.login"],  "filters": {    "source": "web"  }}

38. zerodb_event_stats

Get event statistics and analytics.

Parameters:

• event_type (string, optional) - Filter by event type
• start_date (string, optional) - Start date (ISO 8601)
• end_date (string, optional) - End date (ISO 8601)
• group_by (string, optional) - Group by: "hour", "day", "week" (default: "day")

Returns:

{  "total_events": 10000,  "event_types": {    "user.signup": 1000,    "user.login": 9000  },  "timeline": [    {      "date": "2025-10-14",      "count": 500    }  ]}

Example:

{  "start_date": "2025-10-01T00:00:00Z",  "end_date": "2025-10-14T23:59:59Z",  "group_by": "day"}

Project Operations

39. zerodb_create_project

Create a new ZeroDB project.

Parameters:

• project_name (string, required) - Project name
• description (string, optional) - Project description
• settings (object, optional) - Project settings

Returns:

{  "project_id": "uuid",  "project_name": "string",  "created_at": "timestamp"}

Example:

{  "project_name": "My AI Application",  "description": "Vector search for customer support",  "settings": {    "retention_days": 90  }}

40. zerodb_get_project

Get project details.

Parameters:

• project_id (string, required) - Project UUID

Returns:

{  "project_id": "uuid",  "project_name": "string",  "description": "string",  "settings": {},  "created_at": "timestamp"}

Example:

{  "project_id": "123e4567-e89b-12d3-a456-426614174000"}

41. zerodb_list_projects

List all accessible projects.

Parameters:

• limit (number, optional) - Results per page (default: 50)
• offset (number, optional) - Pagination offset (default: 0)

Returns:

{  "projects": [    {      "project_id": "uuid",      "project_name": "string",      "created_at": "timestamp"    }  ],  "total_count": 10}

Example:

{  "limit": 100}

42. zerodb_update_project

Update project settings.

Parameters:

• project_id (string, required) - Project UUID
• project_name (string, optional) - New project name
• description (string, optional) - New description
• settings (object, optional) - Updated settings

Returns:

{  "project_id": "uuid",  "updated_fields": ["project_name", "settings"],  "updated_at": "timestamp"}

Example:

{  "project_id": "123e4567-e89b-12d3-a456-426614174000",  "settings": {    "retention_days": 120  }}

43. zerodb_delete_project

Delete a project and all its data.

Parameters:

• project_id (string, required) - Project UUID to delete
• confirm (boolean, required) - Must be true to confirm deletion

Returns:

{  "success": true,  "deleted_id": "uuid",  "deleted_at": "timestamp"}

Example:

{  "project_id": "123e4567-e89b-12d3-a456-426614174000",  "confirm": true}

44. zerodb_get_project_stats

Get project usage statistics.

Parameters:

• project_id (string, required) - Project UUID
• start_date (string, optional) - Start date (ISO 8601)
• end_date (string, optional) - End date (ISO 8601)

Returns:

{  "project_id": "uuid",  "vector_count": 10000,  "memory_count": 5000,  "table_count": 10,  "file_count": 100,  "storage_bytes": 10485760,  "api_calls": 50000}

Example:

{  "project_id": "123e4567-e89b-12d3-a456-426614174000",  "start_date": "2025-10-01T00:00:00Z"}

45. zerodb_enable_database

Enable database features for project.

Parameters:

• project_id (string, required) - Project UUID
• features (array[string], required) - Features to enable: ["vectors", "tables", "files", "events"]

Returns:

{  "project_id": "uuid",  "enabled_features": ["vectors", "tables"],  "enabled_at": "timestamp"}

Example:

{  "project_id": "123e4567-e89b-12d3-a456-426614174000",  "features": ["vectors", "tables", "files"]}

RLHF Operations

46. zerodb_rlhf_interaction

Collect user interaction for RLHF training.

Parameters:

• session_id (string, required) - Session identifier
• user_input (string, required) - User's input
• agent_response (string, required) - Agent's response
• feedback_score (number, optional) - User rating 1-5
• metadata (object, optional) - Additional context

Returns:

{  "interaction_id": "uuid",  "collected_at": "timestamp"}

Example:

{  "session_id": "session-123",  "user_input": "How do I reset my password?",  "agent_response": "You can reset your password by...",  "feedback_score": 5,  "metadata": {    "model": "claude-3-sonnet",    "response_time_ms": 1200  }}

47. zerodb_rlhf_agent_feedback

Collect feedback about agent performance.

Parameters:

• agent_id (string, required) - Agent identifier
• session_id (string, required) - Session identifier
• feedback_type (string, required) - "positive" or "negative"
• feedback_text (string, optional) - Detailed feedback
• metrics (object, optional) - Performance metrics

Returns:

{  "feedback_id": "uuid",  "collected_at": "timestamp"}

Example:

{  "agent_id": "agent-123",  "session_id": "session-123",  "feedback_type": "positive",  "feedback_text": "Very helpful and accurate responses",  "metrics": {    "accuracy": 0.95,    "helpfulness": 0.9  }}

48. zerodb_rlhf_workflow

Collect feedback about workflow completion.

Parameters:

• workflow_id (string, required) - Workflow identifier
• session_id (string, required) - Session identifier
• completed (boolean, required) - Workflow completion status
• duration_ms (number, optional) - Workflow duration
• feedback (object, optional) - Workflow feedback

Returns:

{  "workflow_feedback_id": "uuid",  "collected_at": "timestamp"}

Example:

{  "workflow_id": "workflow-123",  "session_id": "session-123",  "completed": true,  "duration_ms": 5000,  "feedback": {    "ease_of_use": 5,    "effectiveness": 4  }}

49. zerodb_rlhf_error

Collect error reports for model improvement.

Parameters:

• session_id (string, required) - Session identifier
• error_type (string, required) - Error category
• error_message (string, required) - Error description
• context (object, optional) - Error context
• user_impact (string, optional) - Impact level: "low", "medium", "high"

Returns:

{  "error_report_id": "uuid",  "collected_at": "timestamp"}

Example:

{  "session_id": "session-123",  "error_type": "hallucination",  "error_message": "Agent provided incorrect information about product pricing",  "context": {    "user_query": "What is the price?",    "agent_response": "The price is $50"  },  "user_impact": "high"}

50. zerodb_rlhf_status

Get RLHF collection status.

Parameters:

• session_id (string, optional) - Filter by session
• start_date (string, optional) - Start date (ISO 8601)
• end_date (string, optional) - End date (ISO 8601)

Returns:

{  "total_interactions": 1000,  "avg_feedback_score": 4.2,  "positive_feedback": 850,  "negative_feedback": 150,  "collection_rate": 0.85}

Example:

{  "start_date": "2025-10-01T00:00:00Z",  "end_date": "2025-10-14T23:59:59Z"}

51. zerodb_rlhf_summary

Get RLHF analytics summary.

Parameters:

• group_by (string, optional) - Group by: "agent", "workflow", "session" (default: "agent")
• start_date (string, optional) - Start date (ISO 8601)
• end_date (string, optional) - End date (ISO 8601)

Returns:

{  "summary": [    {      "group_id": "agent-123",      "interaction_count": 500,      "avg_score": 4.5,      "improvement_trend": 0.15    }  ]}

Example:

{  "group_by": "agent",  "start_date": "2025-10-01T00:00:00Z"}

52. zerodb_rlhf_start

Start RLHF collection for session.

Parameters:

• session_id (string, required) - Session identifier
• collection_config (object, optional) - Collection settings

Returns:

{  "session_id": "uuid",  "collection_started": true,  "started_at": "timestamp"}

Example:

{  "session_id": "session-123",  "collection_config": {    "collect_all_interactions": true,    "require_explicit_feedback": false  }}

53. zerodb_rlhf_stop

Stop RLHF collection for session.

Parameters:

• session_id (string, required) - Session identifier

Returns:

{  "session_id": "uuid",  "collection_stopped": true,  "stopped_at": "timestamp",  "total_collected": 50}

Example:

{  "session_id": "session-123"}

54. zerodb_rlhf_session

Get all interactions for a session.

Parameters:

• session_id (string, required) - Session identifier
• limit (number, optional) - Max results (default: 100)

Returns:

{  "session_id": "uuid",  "interactions": [    {      "interaction_id": "uuid",      "user_input": "string",      "agent_response": "string",      "feedback_score": 5,      "timestamp": "timestamp"    }  ],  "total_count": 50}

Example:

{  "session_id": "session-123",  "limit": 200}

55. zerodb_rlhf_broadcast

Broadcast RLHF event to subscribers.

Parameters:

• event_type (string, required) - Event type
• event_data (object, required) - Event payload
• target_sessions (array[string], optional) - Target session IDs

Returns:

{  "broadcast_id": "uuid",  "recipients": 10,  "broadcasted_at": "timestamp"}

Example:

{  "event_type": "feedback.requested",  "event_data": {    "interaction_id": "interaction-123",    "question": "Was this response helpful?"  },  "target_sessions": ["session-1", "session-2"]}

Admin Operations

56. zerodb_admin_system_stats

Get system-wide statistics (requires admin role).

Parameters:

• include_details (boolean, optional) - Include detailed metrics (default: false)

Returns:

{  "total_projects": 100,  "total_users": 500,  "total_vectors": 1000000,  "total_storage_bytes": 10737418240,  "active_sessions": 50,  "api_calls_24h": 100000,  "avg_response_time_ms": 150}

Example:

{  "include_details": true}

57. zerodb_admin_list_projects

List all projects in system (requires admin role).

Parameters:

• user_id (string, optional) - Filter by user
• limit (number, optional) - Results per page (default: 100)
• offset (number, optional) - Pagination offset (default: 0)

Returns:

{  "projects": [    {      "project_id": "uuid",      "project_name": "string",      "user_id": "uuid",      "created_at": "timestamp",      "storage_bytes": 1048576    }  ],  "total_count": 100}

Example:

{  "limit": 500}

58. zerodb_admin_user_usage

Get user usage statistics (requires admin role).

Parameters:

• user_id (string, required) - User UUID
• start_date (string, optional) - Start date (ISO 8601)
• end_date (string, optional) - End date (ISO 8601)

Returns:

{  "user_id": "uuid",  "project_count": 5,  "vector_count": 10000,  "storage_bytes": 10485760,  "api_calls": 50000,  "cost_estimate_usd": 25.50}

Example:

{  "user_id": "user-123",  "start_date": "2025-10-01T00:00:00Z"}

59. zerodb_admin_health

Get system health status (requires admin role).

Parameters:

• None

Returns:

{  "status": "healthy",  "database": "connected",  "storage": "healthy",  "quantum_service": "operational",  "cache": "healthy",  "uptime_seconds": 86400,  "last_check": "timestamp"}

Example:

{}

60. zerodb_admin_optimize

Optimize database and storage (requires admin role).

Parameters:

• optimization_type (string, required) - "vacuum", "reindex", or "all"
• tables (array[string], optional) - Specific tables to optimize

Returns:

{  "optimized": true,  "optimization_type": "all",  "duration_ms": 30000,  "space_freed_bytes": 1048576,  "improvements": {    "query_performance": 0.25,    "storage_efficiency": 0.15  }}

Example:

{  "optimization_type": "all"}

PostgreSQL Operations

Dedicated PostgreSQL database operations for advanced SQL workloads.

61. zerodb_postgres_query

Execute SQL query on your provisioned PostgreSQL instance with comprehensive security validations.

Parameters:

• sql (string, required) - SQL query to execute
• params (array[string], optional) - Query parameters for prepared statements
• read_only (boolean, optional) - Enforce read-only mode (SELECT only), default: false
• timeout_seconds (number, optional) - Query timeout in seconds, default: 30
• max_rows (number, optional) - Maximum rows to return, default: 1000

Returns:

{  "query_id": "q_abc123",  "query_type": "SELECT",  "rows_returned": 10,  "rows_affected": 0,  "execution_time_ms": 45.2,  "columns": ["id", "name", "email"],  "rows": [{"id": 1, "name": "User", "email": "[email protected]"}],  "success": true}

Security Features:

• SQL injection prevention (blocks DROP DATABASE, TRUNCATE, etc.)
• Query timeout enforcement
• Read-only mode support
• Parameter sanitization
• Execution history tracking

Example:

{  "sql": "SELECT * FROM users WHERE created_at > $1 LIMIT 10",  "params": ["2025-01-01"],  "read_only": true,  "timeout_seconds": 30}

62. zerodb_postgres_schema_info

Get detailed database schema information including tables, columns, indexes, and constraints.

Parameters:

• table_name (string, optional) - Specific table to inspect (omit for all tables)
• include_indexes (boolean, optional) - Include index information, default: true
• include_constraints (boolean, optional) - Include constraint information, default: true
• include_stats (boolean, optional) - Include table statistics, default: false

Returns:

{  "schema": "public",  "total_tables": 5,  "database_size_mb": 150.5,  "tables": [    {      "table_name": "users",      "columns": [        {"name": "id", "type": "INTEGER", "nullable": false, "primary_key": true},        {"name": "email", "type": "VARCHAR(255)", "nullable": false, "unique": true}      ],      "indexes": [        {"name": "users_pkey", "columns": ["id"], "unique": true},        {"name": "users_email_idx", "columns": ["email"], "unique": true}      ],      "row_count": 1000,      "size_mb": 25.5    }  ]}

Example:

{  "table_name": "users",  "include_indexes": true,  "include_constraints": true}

63. zerodb_postgres_create_table

Create a new table with complete schema definition including columns, constraints, and indexes.

Parameters:

• table_name (string, required) - Name of the table to create
• columns (array, required) - Column definitions
  • name (string, required) - Column name
  • type (string, required) - Column type (e.g., "VARCHAR(255)", "INTEGER", "TIMESTAMP")
  • nullable (boolean, optional) - Allow NULL values, default: true
  • primary_key (boolean, optional) - Is primary key, default: false
  • unique (boolean, optional) - Unique constraint, default: false
  • default (string, optional) - Default value
• indexes (array, optional) - Index definitions
  • name (string, optional) - Index name (auto-generated if not provided)
  • columns (array[string], required) - Columns to index
  • unique (boolean, optional) - Unique index, default: false
• if_not_exists (boolean, optional) - Only create if table doesn't exist, default: true

Returns:

{  "table_name": "products",  "created": true,  "columns_count": 5,  "indexes_created": 2,  "indexes": [    {"index_name": "products_sku_idx", "success": true},    {"index_name": "products_name_idx", "success": true}  ]}

Example:

{  "table_name": "products",  "columns": [    {"name": "id", "type": "SERIAL", "primary_key": true},    {"name": "sku", "type": "VARCHAR(50)", "nullable": false, "unique": true},    {"name": "name", "type": "VARCHAR(255)", "nullable": false},    {"name": "price", "type": "DECIMAL(10,2)", "nullable": false},    {"name": "created_at", "type": "TIMESTAMP", "default": "NOW()"}  ],  "indexes": [    {"columns": ["sku"], "unique": true},    {"columns": ["name"]}  ]}

64. zerodb_postgres_backup

Trigger a PostgreSQL backup job with configurable options.

Parameters:

• backup_type (string, optional) - "full" or "incremental", default: "full"
• retention_days (number, optional) - Backup retention in days, default: 7
• compression (boolean, optional) - Compress backup, default: true
• include_schema (boolean, optional) - Include schema definition, default: true
• include_data (boolean, optional) - Include table data, default: true

Returns:

{  "backup_id": "backup_xyz789",  "backup_type": "full",  "status": "initiated",  "estimated_size_mb": 250.0,  "retention_days": 7,  "created_at": "2025-12-07T18:00:00Z"}

Example:

{  "backup_type": "full",  "retention_days": 30,  "compression": true}

65. zerodb_postgres_restore

Restore PostgreSQL database from a backup.

Parameters:

• backup_id (string, required) - Backup ID to restore from
• restore_type (string, optional) - "full", "schema_only", or "data_only", default: "full"
• target_database (string, optional) - Restore to different database name
• confirm_overwrite (boolean, required) - Must be true to confirm overwrite of existing data

Returns:

{  "restore_id": "restore_abc123",  "backup_id": "backup_xyz789",  "status": "in_progress",  "estimated_time_minutes": 5,  "started_at": "2025-12-07T18:05:00Z"}

Security:

• Requires explicit confirm_overwrite: true to prevent accidental data loss
• Logs all restore operations for audit trail

Example:

{  "backup_id": "backup_xyz789",  "restore_type": "full",  "confirm_overwrite": true}

66. zerodb_postgres_stats

Get comprehensive PostgreSQL database statistics including performance metrics.

Parameters:

• include_connections (boolean, optional) - Include connection statistics, default: true
• include_queries (boolean, optional) - Include query performance stats, default: true
• include_storage (boolean, optional) - Include storage statistics, default: true
• include_replication (boolean, optional) - Include replication stats, default: false
• time_range (string, optional) - "hour", "day", "week", or "month", default: "day"

Returns:

{  "project_id": "proj_123",  "database_size_mb": 150.5,  "table_count": 25,  "active_connections": 5,  "max_connections": 100,  "queries_per_second": 120.5,  "cache_hit_ratio": 0.95,  "avg_query_time_ms": 15.2,  "cpu_usage_percent": 25.0,  "memory_usage_percent": 40.0,  "replication_lag_ms": null}

Example:

{  "include_connections": true,  "include_queries": true,  "include_storage": true,  "time_range": "day"}

Knowledge Graph Operations

Entity/relationship graph on top of your ZeroDB memories — create entities, link them, walk the graph, and run hybrid vector+graph search. Requires a core backend version that includes the graph_* MCP operations (AINative-Studio/core#8341); an older backend returns an "operation not recognized" error for these four tools.

zerodb_graph_upsert_entity

Create or update a knowledge graph entity. If an entity with the same canonical_name + entity_type already exists, its aliases are merged and memory_count is incremented instead of creating a duplicate.

Parameters:

• canonical_name (string, required) - Entity canonical name
• entity_type (string, required) - Entity type, e.g. person, org, tech, concept
• aliases (array[string], optional) - Known aliases for the entity
• properties (object, optional) - Arbitrary entity properties
• project_id (string, optional) - When provided, entity_type is checked against that project's ontology; a warning (not a block) is returned if it is not in the allowed list

Returns:

{  "id": "ent_abc123",  "canonical_name": "Alice Johnson",  "entity_type": "person",  "aliases": ["Alice"],  "properties": { "role": "engineer" },  "memory_count": 1,  "status": "created"}

zerodb_graph_create_edge

Create or strengthen a directed edge (relationship) between two entities that already exist in the graph. Does not create the entities — use zerodb_graph_upsert_entity first.

Parameters:

• source_name (string, required) - Source entity canonical name (must already exist)
• target_name (string, required) - Target entity canonical name (must already exist)
• predicate (string, required) - Relationship type, e.g. works_at, located_in, depends_on
• confidence (number, optional) - Edge confidence 0.0-1.0, default: 0.8
• properties (object, optional) - Arbitrary edge properties

Example:

{  "source_name": "Alice Johnson",  "target_name": "Acme Corp",  "predicate": "works_at",  "confidence": 0.9}

zerodb_graph_traverse

Multi-hop traversal of the knowledge graph starting from an entity. Returns nodes, edges, and paths discovered within max_hops.

Parameters:

• entity (string, required) - Entity name or ID to start traversal from
• max_hops (number, optional) - Maximum traversal depth (1-5), default: 3
• predicates (array[string], optional) - Only follow edges with these predicate types
• min_confidence (number, optional) - Minimum edge confidence to follow, default: 0.0
• as_of (string, optional) - ISO timestamp — only return edges valid at this point in time

Example:

{  "entity": "Alice Johnson",  "max_hops": 2}

zerodb_graph_rag_search

GraphRAG hybrid search — blends vector similarity with knowledge graph proximity. graph_weight=0.0 behaves like pure vector search; graph_weight=1.0 is pure graph proximity ranking; the default 0.3 blends both.

Parameters:

• query (string, required) - Search query text
• limit (number, optional) - Maximum results to return, default: 10
• graph_weight (number, optional) - Blend factor: 0=pure vector, 1=pure graph proximity, default: 0.3
• max_hops (number, optional) - Maximum graph traversal depth for the graph-proximity component, default: 2

Example:

{  "query": "pricing strategy",  "limit": 5,  "graph_weight": 0.5}

zerodb_graph_list_entities

List knowledge graph entities for the current user, optionally filtered by entity type, paginated by memory_count descending.

Parameters:

• entity_type (string, optional) - Filter by entity type, e.g. person, org, tech, concept
• limit (number, optional) - Max results, default: 50
• offset (number, optional) - Pagination offset, default: 0

zerodb_graph_neighbors

Get the direct (1-hop) neighbors of an entity, with relationship and entity metadata. Bounded to a single hop — use zerodb_graph_traverse for a deeper walk.

Parameters:

• entity_name (string, required) - Entity name to find neighbors of (must already exist)
• limit (number, optional) - Max neighbors to return, default: 50

zerodb_graph_stats

Graph analytics for the current user: node count, edge count, density, entity-type and predicate distributions, and top entities by connectivity. No parameters.

zerodb_graph_merge_entities

Merge duplicate entities into a canonical entity, moving all edges and aliases from the merge targets and deleting the duplicates. Destructive — cannot be undone.

Parameters:

• canonical (string, required) - Canonical entity name to keep
• merge (array[string], required) - Entity names to merge into the canonical entity and delete

zerodb_graph_ontology_get

Get the ontology (allowed entity types, predicates per type, constraints) for a project. Returns a not-found error if no ontology is defined yet.

Parameters:

• project_id (string, required) - Project UUID

zerodb_graph_ontology_upsert

Create or update a project's ontology. Version is auto-incremented on update.

Parameters:

• project_id (string, required) - Project UUID
• entity_types (array[string], required) - Allowed entity types for this project
• predicates (object, optional) - Allowed predicates per entity type, e.g. {"customer": {"places": "order"}}
• constraints (object, optional) - Optional additional constraints

zerodb_graph_ontology_infer

Infer a candidate ontology from existing graph data by analyzing entity-type and predicate frequency. When project_id is given, also returns a diff against that project's current ontology.

Parameters:

• min_entity_count (number, optional) - Minimum entity-type occurrences to suggest it, default: 3
• min_predicate_count (number, optional) - Minimum predicate occurrences to suggest it, default: 2
• project_id (string, optional) - Project UUID to diff against

zerodb_graph_ontology_suggestions

Human-readable, actionable suggestions for improving a project's ontology (reclassify generic-typed entities, missing predicates, undeclared entity types).

Parameters:

• project_id (string, optional) - Project UUID to scope suggestions to

zerodb_graph_contradictions_list

List contradictions: edges superseded because a newer edge contradicted an existing relationship on the same (source, predicate) pair.

Parameters:

• limit (number, optional) - Max contradictions to return, default: 50

zerodb_graph_contradictions_resolve

Resolve a contradiction on a superseded edge found via zerodb_graph_contradictions_list.

Parameters:

• edge_id (string, required) - UUID of the superseded (old) edge to resolve
• action (string, required) - One of accept_new (no-op, keeps current state), keep_both (restores the old edge), reject_new (deletes the new edge and restores the old one)

zerodb_graph_centrality

Entities ranked by degree centrality (total/in/out degree, hub score, critical-node flag). Requires the graph.compute_centrality background task to have run at least once — returns an empty list otherwise.

Parameters:

• entity_type (string, optional) - Filter by entity type
• limit (number, optional) - Max entities to return, default: 50
• critical_only (boolean, optional) - Only return entities flagged as critical infrastructure nodes, default: false

zerodb_graph_export

Export the knowledge graph as JSON (nodes + edges, D3/Cytoscape-compatible). For GEXF (Gephi), use the underlying HTTP export route directly.

Parameters:

• entity_type (string, optional) - Filter by entity type
• limit (number, optional) - Max entities to export, default: 5000
• min_confidence (number, optional) - Minimum edge confidence to include, default: 0.0

Configuration

Environment Variables

All configuration is done through environment variables. Set these in your MCP server configuration.

* Either ZERODB_API_KEY or both ZERODB_USERNAME and ZERODB_PASSWORD must be provided.

Authentication

The MCP server supports two authentication methods:

API Key (Recommended)

Set ZERODB_API_KEY in your environment. The API key is used as a static Bearer token for all requests -- no login flow, no token renewal needed.

Username/Password (Legacy)

Set ZERODB_USERNAME and ZERODB_PASSWORD. The server authenticates on startup, stores the JWT in memory, and automatically renews it every 25 minutes (tokens expire after 30 minutes). Use zerodb_renew_token to manually renew if needed.

Backward compatibility: If you have ZERODB_USERNAME/ZERODB_PASSWORD configured, it will continue to work. We recommend migrating to API key auth for simplicity and security.

Security Best Practices

1. Use API keys instead of passwords: API keys don't require plaintext password storage
2. Store credentials securely: Use environment variables, never hardcode
3. Use project-specific credentials: Create separate projects for different applications
4. Rotate API keys regularly: Regenerate keys every 90 days
5. Monitor API usage: Check for unusual activity in project stats

Examples

Example 1: Building a Knowledge Base

// 1. Create a project for your knowledge baseconst project = await zerodb_create_project({  project_name: "Product Documentation KB",  description: "Searchable product documentation"});
// 2. Upload documentation filesconst file = await zerodb_upload_file({  file_name: "user_guide.pdf",  file_data: "base64data...",  content_type: "application/pdf"});
// 3. Store vectors for semantic search// (Assume you've generated embeddings from the documentation)const vector = await zerodb_store_vector({  vector_embedding: [...], // 1536-dimensional vector  document: "How to reset your password: Navigate to Settings...",  metadata: {    source: "user_guide.pdf",    page: 15  }});
// 4. Search the knowledge baseconst results = await zerodb_search_vectors({  query_vector: [...], // User query embedding  limit: 5,  threshold: 0.75});

Example 2: Agent Memory with Context

// 1. Store conversation in memoryawait zerodb_store_memory({  content: "User wants to book a flight to Paris",  role: "user",  session_id: "session-123"});
await zerodb_store_memory({  content: "I'll help you book a flight to Paris. What dates?",  role: "assistant",  session_id: "session-123"});
// 2. Later in the conversation, get contextconst context = await zerodb_get_context({  session_id: "session-123",  max_tokens: 4096});
// Context includes all previous messages, token-optimized

Example 3: RLHF Data Collection

// 1. Start RLHF collection for sessionawait zerodb_rlhf_start({  session_id: "session-456",  collection_config: {    collect_all_interactions: true  }});
// 2. Collect interactions during conversationawait zerodb_rlhf_interaction({  session_id: "session-456",  user_input: "What's the weather like?",  agent_response: "I don't have access to real-time weather data",  feedback_score: 3,  metadata: {    model: "claude-3-sonnet",    response_time_ms: 800  }});
// 3. Collect error reportsawait zerodb_rlhf_error({  session_id: "session-456",  error_type: "capability_limitation",  error_message: "Agent cannot access real-time data",  user_impact: "medium"});
// 4. Get RLHF summaryconst summary = await zerodb_rlhf_summary({  group_by: "session",  start_date: "2025-10-14T00:00:00Z"});

Example 4: Quantum-Enhanced Search

// 1. Store vectors with quantum compressionconst compressed = await zerodb_quantum_compress({  vector_embedding: [...], // Original 1536 dimensions  compression_ratio: 0.5,  algorithm: "qaoa"});
// Store compressed versionawait zerodb_store_vector({  vector_embedding: compressed.compressed_vector,  document: "Product description...",  metadata: {    compressed: true,    original_dimensions: 1536  }});
// 2. Perform quantum hybrid searchconst results = await zerodb_quantum_hybrid_search({  query_vector: [...],  quantum_weight: 0.7, // Higher weight for quantum similarity  limit: 10});
// Results include both classical and quantum similarity scores

Example 5: NoSQL Data Management

// 1. Create a table for user profilesconst table = await zerodb_create_table({  table_name: "user_profiles",  schema: {    user_id: "uuid",    name: "string",    email: "string",    preferences: "json",    created_at: "timestamp"  }});
// 2. Insert user dataawait zerodb_insert_rows({  table_id: table.table_id,  rows: [    {      user_id: "user-1",      name: "Alice Smith",      email: "[email protected]",      preferences: { theme: "dark", language: "en" }    }  ]});
// 3. Query usersconst users = await zerodb_query_rows({  table_id: table.table_id,  filters: {    email: { $contains: "@example.com" }  }});
// 4. Update preferencesawait zerodb_update_rows({  table_id: table.table_id,  filters: { user_id: "user-1" },  updates: {    preferences: { theme: "light", language: "en" }  }});

Example 6: Error Handling

// All operations return structured responses with error handlingtry {  const result = await zerodb_store_vector({    vector_embedding: [...],    document: "Sample text"  });
  if (result.isError) {    console.error("Operation failed:", result.content[0].text);    // Handle error appropriately  } else {    console.log("Success:", result.content[0].text);  }} catch (error) {  // Handle unexpected errors  console.error("Unexpected error:", error.message);}

Migration Guide

Migrating from Password Auth to API Key Auth

Password auth (ZERODB_USERNAME/ZERODB_PASSWORD) is deprecated and will be removed in v3.0. The server will print a deprecation warning on startup if password auth is detected.

Step 1: Get Your API Key

1. Go to https://ainative.studio/settings
2. Navigate to the API Keys section
3. Click Create API Key
4. Copy the key (it starts with zdb_)

Step 2: Update Your Configuration

Old config (deprecated):

{  "mcpServers": {    "zerodb": {      "command": "npx",      "args": ["ainative-zerodb-mcp-server"],      "env": {        "ZERODB_API_URL": "https://api.ainative.studio",        "ZERODB_PROJECT_ID": "your-project-id",        "ZERODB_USERNAME": "[email protected]",        "ZERODB_PASSWORD": "YourPassword123!"      }    }  }}

New config (recommended):

{  "mcpServers": {    "zerodb": {      "command": "npx",      "args": ["ainative-zerodb-mcp-server"],      "env": {        "ZERODB_API_URL": "https://api.ainative.studio",        "ZERODB_PROJECT_ID": "your-project-id",        "ZERODB_API_KEY": "zdb_your-api-key-here"      }    }  }}

Why Switch?

• No plaintext passwords — API keys don't require storing your account password
• No token renewal — API keys are used directly as Bearer tokens, no login/refresh flow
• Revocable — Rotate or revoke individual keys without changing your password
• Scoped — Future support for project-scoped and read-only keys

Migrating from v1.x to v2.0.0

Breaking Changes

1. API Endpoint Consolidation

   • v1.x: Direct API calls to various endpoints
   • v2.0: All operations go through unified MCP execute endpoint

   Impact: No code changes needed if using MCP tools

2. Tool Naming Convention

   • v1.x: Some tools lacked zerodb_ prefix
   • v2.0: All tools prefixed with zerodb_

   Migration:

   javascript

   // Old (v1.x)store_memory(...) → zerodb_store_memory(...)search_memory(...) → zerodb_search_memory(...)
   // New (v2.0)zerodb_store_memory(...) // Consistent prefix

3. Parameter Changes

   • Memory operations: memory_metadata → metadata
   • Vector operations: vector_metadata → metadata

   Migration:

   javascript

   // Old (v1.x){  content: "...",  memory_metadata: { key: "value" }}
   // New (v2.0){  content: "...",  metadata: { key: "value" }}

4. New Required Environment Variables

   • ZERODB_PROJECT_ID is now required (was optional in v1.x)

   Migration: Add to your config:

   json

   {  "env": {    "ZERODB_PROJECT_ID": "your-project-id"  }}

New Features Available

1. 54 New Operations - Full API coverage beyond memory and vector operations
2. Quantum Compression - Reduce vector storage by up to 50%
3. NoSQL Tables - Structured data storage and queries
4. File Management - Upload and manage files
5. Event System - Event-driven architecture support
6. RLHF Collection - Built-in feedback collection for model training
7. Admin Tools - System monitoring and optimization

Migration Steps

1. Update Package

   bash

   npm update ainative-zerodb-mcp-server# ornpm install -g [email protected]

2. Update Configuration

   • Add ZERODB_PROJECT_ID to environment variables
   • Update any custom tool names to include zerodb_ prefix

3. Test Existing Functionality

   • All v1.x operations remain compatible
   • Test memory and vector operations still work

4. Gradually Adopt New Features

   • Start with new features that provide immediate value
   • Refer to API Reference for new operation documentation

Backward Compatibility

• All v1.x operations are supported in v2.0
• Existing data and projects are fully compatible
• No data migration required

Troubleshooting

Common Issues

1. Authentication Failed

Error: Authentication failed: Invalid credentials

Solutions:

• If using API key: verify ZERODB_API_KEY is correct and not expired
• If using username/password: verify ZERODB_USERNAME and ZERODB_PASSWORD are correct
• Check that your account is active
• Try manual token renewal: zerodb_renew_token (username/password auth only)

2. Project Not Found

Error: Project not found: [project-id]

Solutions:

• Verify ZERODB_PROJECT_ID is correct
• List your projects: zerodb_list_projects
• Create a new project: zerodb_create_project

3. Vector Dimension Mismatch

Error: vector must have exactly 1536 dimensions, got 768

Solutions:

• Ensure you're using OpenAI's text-embedding-3-small (1536 dimensions)
• Or use text-embedding-ada-002 (1536 dimensions)
• Do not use text-embedding-3-large (3072 dimensions)

4. Token Expired

Error: Token expired or invalid

Solutions:

• The server should auto-renew tokens every 25 minutes
• Manually renew: zerodb_renew_token
• Check server logs for renewal errors

5. Rate Limiting

Error: Rate limit exceeded

Solutions:

• Reduce request frequency
• Use batch operations where available
• Contact support for rate limit increases

Debug Logging

Enable verbose logging by checking stderr output:

# The MCP server logs to stderr# In Claude Desktop, check: ~/Library/Logs/Claude/mcp*.log

Log messages include:

• Token renewal attempts and status
• API call details (operation, params)
• Error messages with full context

Getting Help

1. Documentation: https://docs.ainative.studio/zerodb
2. GitHub Issues: https://github.com/AINative-Studio/ainative-zerodb-mcp-server/issues
3. Email Support: [email protected]
4. Discord Community: https://discord.gg/ainative

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repositorygit clone https://github.com/AINative-Studio/ainative-zerodb-mcp-server.gitcd ainative-zerodb-mcp-server
# Install dependenciesnpm install
# Run testsnpm test
# Lint codenpm run lint
# Run security auditnpm run security:audit

Testing

# Run tests with coveragenpm test
# Watch mode for developmentnpm run test:watch
# CI modenpm run test:ci

Code Quality

• 90%+ test coverage required
• ESLint for code style
• No high/critical npm vulnerabilities
• All tests must pass before PR merge

License

MIT License - see LICENSE file for details.

Changelog

v2.0.0 (2025-10-14)

Breaking Changes:

• All operations now require ZERODB_PROJECT_ID environment variable
• Unified API endpoint for all operations
• Consistent zerodb_ prefix for all tool names

New Features:

• Added 54 new operations (total 60)
• Quantum vector compression and optimization
• NoSQL table operations
• File storage and management
• Event-driven architecture support
• RLHF feedback collection
• Admin system monitoring and optimization
• 90%+ test coverage
• Automatic token renewal

Improvements:

• Better error handling and messages
• Improved documentation
• Enhanced security
• Performance optimizations

v1.0.7 (2025-10-01)

• Initial public release
• Basic memory and vector operations
• Claude Desktop integration

Built with ❤️ by AINative Studio

Powered by ZeroDB - Enterprise Vector Search for AI