Name: ZeroDB MCP 服务器
Author: AINative-Studio

使用说明

ZeroDB MCP Server v2.3.2

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

Installation
Quick Start
API Reference
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

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/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "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_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": "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"
}

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

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_API_KEY`	Recommended	-	Your ZeroDB API key (preferred auth method)
`ZERODB_USERNAME`	No*	-	DEPRECATED — Your ZeroDB account email. Switch to `ZERODB_API_KEY`. Will be removed in v3.0.
`ZERODB_PASSWORD`	No*	-	DEPRECATED — Your ZeroDB account password. Switch to `ZERODB_API_KEY`. Will be removed in v3.0.
`ZERODB_API_TOKEN`	No	-	Legacy alias for `ZERODB_API_KEY`
`MCP_CONTEXT_WINDOW`	No	`8192`	Maximum tokens in context window
`MCP_RETENTION_DAYS`	No	`30`	Memory retention period in days

* 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

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

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

Go to https://ainative.studio/settings
Navigate to the API Keys section
Click Create API Key
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": "your-email@example.com",
        "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

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:

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

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

使用说明

ZeroDB MCP Server v2.3.2

What's New in v2.3.2

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

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`

61. `zerodb_postgres_query`

62. `zerodb_postgres_schema_info`

63. `zerodb_postgres_create_table`

64. `zerodb_postgres_backup`

65. `zerodb_postgres_restore`

66. `zerodb_postgres_stats`

`zerodb_graph_upsert_entity`

`zerodb_graph_create_edge`

`zerodb_graph_traverse`

`zerodb_graph_rag_search`

`zerodb_graph_list_entities`

`zerodb_graph_neighbors`

`zerodb_graph_stats`

`zerodb_graph_merge_entities`

`zerodb_graph_ontology_get`

`zerodb_graph_ontology_upsert`

`zerodb_graph_ontology_infer`

`zerodb_graph_ontology_suggestions`

`zerodb_graph_contradictions_list`

`zerodb_graph_contradictions_resolve`