ZeroDB MCP Server v2.0.8

npm version npm downloads license test coverage

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

Key Features

60 Complete Operations - Full API coverage across all ZeroDB capabilities
Vector Search - Semantic similarity search with 1536-dimensional embeddings
Quantum Compression - Advanced vector compression using quantum algorithms
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
90%+ Test Coverage - Comprehensive test suite for production reliability

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

Click on "Register User" endpoint
Use the "Try it out" feature
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": "your-email@example.com", "password": "YourSecurePassword123!", "username": "yourname" }'

Response:

{ "email": "your-email@example.com", "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 token curl -X POST 'https://api.ainative.studio/v1/public/auth/login-json' \ -H 'Content-Type: application/json' \ -d '{ "username": "your-email@example.com", "password": "YourSecurePassword123!" }'

Response:

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

# 2. Create a project using your token curl -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_USERNAME": "your-email@example.com", "ZERODB_PASSWORD": "your-password", "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": "john@example.com" }, { "user_id": "user-2", "name": "Jane Smith", "email": "jane@example.com" } ] }

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": "newemail@example.com" } }

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": "user@example.com" }, "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" }

Configuration

Environment Variables

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

Variable	Required	Default	Description
`ZERODB_API_URL`	No	`https://api.ainative.studio`	ZeroDB API base URL
`ZERODB_PROJECT_ID`	Yes	-	Your ZeroDB project ID
`ZERODB_USERNAME`	Yes	-	Your ZeroDB account email
`ZERODB_PASSWORD`	Yes	-	Your ZeroDB account password
`ZERODB_API_TOKEN`	No	-	Pre-existing API token (optional, will be auto-generated)
`MCP_CONTEXT_WINDOW`	No	`8192`	Maximum tokens in context window
`MCP_RETENTION_DAYS`	No	`30`	Memory retention period in days

Authentication

The MCP server uses JWT authentication with automatic token renewal:

Initial Authentication: On startup, the server authenticates using username/password
Token Storage: Access token is stored in memory
Automatic Renewal: Token is automatically renewed every 25 minutes (tokens expire after 30 minutes)
Manual Renewal: Use zerodb_renew_token to manually renew if needed

Security Best Practices

Store credentials securely: Use environment variables, never hardcode
Use project-specific credentials: Create separate projects for different applications
Rotate passwords regularly: Change passwords every 90 days
Monitor API usage: Check for unusual activity in project stats
Limit token scope: Use project-specific tokens when possible

Examples

Example 1: Building a Knowledge Base

// 1. Create a project for your knowledge base const project = await zerodb_create_project({ project_name: "Product Documentation KB", description: "Searchable product documentation" }); // 2. Upload documentation files const 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 base const 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 memory await 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 context const 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 session await zerodb_rlhf_start({ session_id: "session-456", collection_config: { collect_all_interactions: true } }); // 2. Collect interactions during conversation await 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 reports await 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 summary const 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 compression const compressed = await zerodb_quantum_compress({ vector_embedding: [...], // Original 1536 dimensions compression_ratio: 0.5, algorithm: "qaoa" }); // Store compressed version await zerodb_store_vector({ vector_embedding: compressed.compressed_vector, document: "Product description...", metadata: { compressed: true, original_dimensions: 1536 } }); // 2. Perform quantum hybrid search const 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 profiles const 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 data await zerodb_insert_rows({ table_id: table.table_id, rows: [ { user_id: "user-1", name: "Alice Smith", email: "alice@example.com", preferences: { theme: "dark", language: "en" } } ] }); // 3. Query users const users = await zerodb_query_rows({ table_id: table.table_id, filters: { email: { $contains: "@example.com" } } }); // 4. Update preferences await 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 handling try { 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 v1.x to v2.0.0

Breaking Changes

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
Tool Naming Convention
- v1.x: Some tools lacked zerodb_ prefix
- v2.0: All tools prefixed with zerodb_
Migration:
// Old (v1.x) store_memory(...) → zerodb_store_memory(...) search_memory(...) → zerodb_search_memory(...) // New (v2.0) zerodb_store_memory(...) // Consistent prefix
Parameter Changes
- Memory operations: memory_metadata → metadata
- Vector operations: vector_metadata → metadata
Migration:
// Old (v1.x) { content: "...", memory_metadata: { key: "value" } } // New (v2.0) { content: "...", metadata: { key: "value" } }
New Required Environment Variables
- ZERODB_PROJECT_ID is now required (was optional in v1.x)
Migration: Add to your config:
{ "env": { "ZERODB_PROJECT_ID": "your-project-id" } }

New Features Available

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

Migration Steps

Update Package
npm update ainative-zerodb-mcp-server # or npm install -g ainative-zerodb-mcp-server@2.0.0
Update Configuration
- Add ZERODB_PROJECT_ID to environment variables
- Update any custom tool names to include zerodb_ prefix
Test Existing Functionality
- All v1.x operations remain compatible
- Test memory and vector operations still work
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:

Verify ZERODB_USERNAME and ZERODB_PASSWORD are correct
Check that your account is active
Try manual token renewal: zerodb_renew_token

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

Documentation: https://docs.ainative.studio/zerodb
GitHub Issues: https://github.com/AINative-Studio/ainative-zerodb-mcp-server/issues
Email Support: support@ainative.studio
Discord Community: https://discord.gg/ainative

Contributing

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

Development Setup

# Clone repository git clone https://github.com/AINative-Studio/ainative-zerodb-mcp-server.git cd ainative-zerodb-mcp-server # Install dependencies npm install # Run tests npm test # Lint code npm run lint # Run security audit npm run security:audit

Testing

# Run tests with coverage npm test # Watch mode for development npm run test:watch # CI mode npm 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

ZeroDB MCP Server v2.0.8

Key Features

Table of Contents

Installation

NPM Global Installation

NPX (No Installation Required)

Requirements

Getting Started

Step 1: Create Your ZeroDB Account

Option A: Register via Web (Recommended)

Option B: Register via API

Step 2: Create a Project

Quick Start

Step 3: Configure Claude Desktop

Step 4: Restart Claude Desktop

Step 5: Test Your First Operation

API Reference

Memory Operations

1. zerodb_store_memory

2. zerodb_search_memory

3. zerodb_get_context

Vector Operations

4. zerodb_store_vector

5. zerodb_batch_upsert_vectors

6. zerodb_search_vectors

7. zerodb_delete_vector

8. zerodb_get_vector

9. zerodb_list_vectors

10. zerodb_vector_stats

11. zerodb_create_vector_index

12. zerodb_optimize_vectors

13. zerodb_export_vectors

Quantum Operations

14. zerodb_quantum_compress

15. zerodb_quantum_decompress

16. zerodb_quantum_hybrid_search

17. zerodb_quantum_optimize

18. zerodb_quantum_feature_map

19. zerodb_quantum_kernel

Table/NoSQL Operations

20. zerodb_create_table

21. zerodb_list_tables

22. zerodb_get_table

23. zerodb_delete_table

24. zerodb_insert_rows

25. zerodb_query_rows

26. zerodb_update_rows

27. zerodb_delete_rows

File Operations

28. zerodb_upload_file

29. zerodb_download_file

30. zerodb_list_files

31. zerodb_delete_file

32. zerodb_get_file_metadata

33. zerodb_generate_presigned_url

Event Operations

34. zerodb_create_event

35. zerodb_list_events

36. zerodb_get_event

37. zerodb_subscribe_events

38. zerodb_event_stats

Project Operations

39. zerodb_create_project

40. zerodb_get_project

41. zerodb_list_projects

42. zerodb_update_project

43. zerodb_delete_project

44. zerodb_get_project_stats

45. zerodb_enable_database

RLHF Operations

46. zerodb_rlhf_interaction

47. zerodb_rlhf_agent_feedback

48. zerodb_rlhf_workflow

49. zerodb_rlhf_error

50. zerodb_rlhf_status

51. zerodb_rlhf_summary

52. zerodb_rlhf_start

53. zerodb_rlhf_stop

54. zerodb_rlhf_session

55. zerodb_rlhf_broadcast

1. `zerodb_store_memory`

2. `zerodb_search_memory`

3. `zerodb_get_context`

4. `zerodb_store_vector`

5. `zerodb_batch_upsert_vectors`

6. `zerodb_search_vectors`

7. `zerodb_delete_vector`

8. `zerodb_get_vector`

9. `zerodb_list_vectors`

10. `zerodb_vector_stats`

11. `zerodb_create_vector_index`

12. `zerodb_optimize_vectors`

13. `zerodb_export_vectors`

14. `zerodb_quantum_compress`

15. `zerodb_quantum_decompress`

16. `zerodb_quantum_hybrid_search`

17. `zerodb_quantum_optimize`

18. `zerodb_quantum_feature_map`

19. `zerodb_quantum_kernel`

20. `zerodb_create_table`

21. `zerodb_list_tables`

22. `zerodb_get_table`

23. `zerodb_delete_table`

24. `zerodb_insert_rows`

25. `zerodb_query_rows`

26. `zerodb_update_rows`

27. `zerodb_delete_rows`

28. `zerodb_upload_file`

29. `zerodb_download_file`

30. `zerodb_list_files`

31. `zerodb_delete_file`

32. `zerodb_get_file_metadata`

33. `zerodb_generate_presigned_url`

34. `zerodb_create_event`

35. `zerodb_list_events`

36. `zerodb_get_event`

37. `zerodb_subscribe_events`

38. `zerodb_event_stats`

39. `zerodb_create_project`

40. `zerodb_get_project`

41. `zerodb_list_projects`

42. `zerodb_update_project`

43. `zerodb_delete_project`

44. `zerodb_get_project_stats`

45. `zerodb_enable_database`

46. `zerodb_rlhf_interaction`

47. `zerodb_rlhf_agent_feedback`

48. `zerodb_rlhf_workflow`

49. `zerodb_rlhf_error`

50. `zerodb_rlhf_status`

51. `zerodb_rlhf_summary`

52. `zerodb_rlhf_start`

53. `zerodb_rlhf_stop`

54. `zerodb_rlhf_session`

55. `zerodb_rlhf_broadcast`

56. `zerodb_admin_system_stats`

57. `zerodb_admin_list_projects`

58. `zerodb_admin_user_usage`

59. `zerodb_admin_health`

60. `zerodb_admin_optimize`