ZeroDB MCP Server v2.0.8

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

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)
• 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 token
curl -X POST 'https://api.ainative.studio/v1/public/auth/login-json' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "[email protected]",
    "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": "[email protected]",
        "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": "[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"
}

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:

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

Security Best Practices

1. Store credentials securely: Use environment variables, never hardcode
2. Use project-specific credentials: Create separate projects for different applications
3. Rotate passwords regularly: Change passwords every 90 days
4. Monitor API usage: Check for unusual activity in project stats
5. 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: "[email protected]",
      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

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:

   // 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:

   // 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:

   {
     "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

   npm update ainative-zerodb-mcp-server
   # or
   npm 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:

• 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

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 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 AINative Studio

Powered by ZeroDB - Enterprise Vector Search for AI