# ZeroDB MCP Server v2.3.2

[![npm version](https://img.shields.io/npm/v/ainative-zerodb-mcp-server.svg)](https://www.npmjs.com/package/ainative-zerodb-mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/ainative-zerodb-mcp-server.svg)](https://www.npmjs.com/package/ainative-zerodb-mcp-server)
[![license](https://img.shields.io/npm/l/ainative-zerodb-mcp-server.svg)](https://github.com/AINative-Studio/ainative-zerodb-mcp-server/blob/main/LICENSE)
[![test coverage](https://img.shields.io/badge/coverage-81%25-brightgreen.svg)](https://github.com/AINative-Studio/ainative-zerodb-mcp-server)

**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](./EMBEDDING_TOOLS_GUIDE.md) for complete documentation**

## Key Features

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

---

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
  - [Memory Operations (3)](#memory-operations)
  - [Vector Operations (10)](#vector-operations)
  - [Quantum Operations (6)](#quantum-operations)
  - [Table/NoSQL Operations (8)](#tablenos-ql-operations)
  - [File Operations (6)](#file-operations)
  - [Event Operations (5)](#event-operations)
  - [Project Operations (7)](#project-operations)
  - [RLHF Operations (10)](#rlhf-operations)
  - [Admin Operations (5)](#admin-operations)
  - [PostgreSQL Operations (6)](#postgresql-operations)
- [Configuration](#configuration)
- [Examples](#examples)
- [Migration Guide](#migration-guide)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

---

## Installation

### NPM Global Installation
```bash
npm install -g ainative-zerodb-mcp-server
```

### NPX (No Installation Required)
```bash
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
```bash
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:**
```json
{
  "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`:

```bash
# 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:**
```json
{
  "access_token": "eyJhbGc...",
  "token_type": "bearer",
  "expires_in": 1800
}
```

```bash
# 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:**
```json
{
  "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`

```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:**
```json
{
  "memory_id": "uuid",
  "created_at": "2025-10-14T12:00:00Z"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "memories": [
    {
      "memory_id": "uuid",
      "content": "string",
      "role": "user|assistant|system",
      "created_at": "timestamp",
      "similarity_score": 0.95
    }
  ]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "session_id": "uuid",
  "agent_id": "uuid",
  "total_tokens": 1024,
  "memory_count": 15,
  "messages": [
    {
      "role": "user",
      "content": "string",
      "timestamp": "2025-10-14T12:00:00Z"
    }
  ]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "vector_id": "uuid",
  "namespace": "windsurf"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "success_count": 100,
  "failed_count": 0,
  "vector_ids": ["uuid1", "uuid2", ...]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "vectors": [
    {
      "vector_id": "uuid",
      "document": "string",
      "similarity_score": 0.95,
      "metadata": {}
    }
  ]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "success": true,
  "deleted_id": "uuid"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "vector_id": "uuid",
  "vector_embedding": [...],
  "document": "string",
  "metadata": {},
  "created_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "vectors": [...],
  "total_count": 1000,
  "limit": 50,
  "offset": 0
}
```

**Example:**
```javascript
{
  "namespace": "windsurf",
  "limit": 100,
  "offset": 200
}
```

#### 10. `zerodb_vector_stats`
Get statistics about vector storage.

**Parameters:**
- `namespace` (string, optional) - Filter by namespace

**Returns:**
```json
{
  "total_vectors": 10000,
  "namespaces": {
    "windsurf": 5000,
    "default": 5000
  },
  "storage_bytes": 1048576,
  "avg_dimension": 1536
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "index_id": "uuid",
  "namespace": "windsurf",
  "index_type": "hnsw",
  "status": "created"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "optimized": true,
  "space_saved_bytes": 102400,
  "duration_ms": 1500
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "export_id": "uuid",
  "download_url": "https://...",
  "expires_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "compressed_vector": [...],
  "original_dimensions": 1536,
  "compressed_dimensions": 768,
  "compression_ratio": 0.5,
  "fidelity_score": 0.98
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "decompressed_vector": [...],
  "dimensions": 1536,
  "reconstruction_error": 0.02
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "vectors": [
    {
      "vector_id": "uuid",
      "document": "string",
      "similarity_score": 0.96,
      "quantum_score": 0.94,
      "hybrid_score": 0.95
    }
  ]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "optimized": true,
  "improvement_percentage": 35.5,
  "duration_ms": 5000
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "feature_map": [...],
  "quantum_circuit_depth": 10,
  "qubit_count": 12
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "kernel_similarity": 0.92,
  "quantum_advantage": 0.15,
  "computation_time_ms": 45
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "table_id": "uuid",
  "table_name": "string",
  "created_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "tables": [
    {
      "table_id": "uuid",
      "table_name": "string",
      "row_count": 1000,
      "created_at": "timestamp"
    }
  ],
  "total_count": 10
}
```

**Example:**
```javascript
{
  "limit": 100,
  "offset": 0
}
```

#### 22. `zerodb_get_table`
Get table details and schema.

**Parameters:**
- `table_id` (string, required) - Table UUID

**Returns:**
```json
{
  "table_id": "uuid",
  "table_name": "string",
  "schema": {},
  "row_count": 1000,
  "created_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "success": true,
  "deleted_id": "uuid",
  "rows_deleted": 1000
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "inserted_count": 100,
  "row_ids": ["uuid1", "uuid2", ...]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "rows": [...],
  "total_count": 1000,
  "limit": 50,
  "offset": 0
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "updated_count": 50,
  "row_ids": ["uuid1", "uuid2", ...]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "deleted_count": 25,
  "row_ids": ["uuid1", "uuid2", ...]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "file_id": "uuid",
  "file_name": "string",
  "size_bytes": 1024,
  "upload_url": "string"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "file_id": "uuid",
  "file_name": "string",
  "file_data": "base64encodeddata...",
  "content_type": "string",
  "size_bytes": 1024
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "files": [
    {
      "file_id": "uuid",
      "file_name": "string",
      "size_bytes": 1024,
      "content_type": "string",
      "created_at": "timestamp"
    }
  ],
  "total_count": 100
}
```

**Example:**
```javascript
{
  "limit": 100,
  "content_type": "application/pdf"
}
```

#### 31. `zerodb_delete_file`
Delete file from storage.

**Parameters:**
- `file_id` (string, required) - File UUID to delete

**Returns:**
```json
{
  "success": true,
  "deleted_id": "uuid"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "file_id": "uuid",
  "file_name": "string",
  "size_bytes": 1024,
  "content_type": "string",
  "metadata": {},
  "created_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "file_id": "uuid",
  "presigned_url": "https://...",
  "expires_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "event_id": "uuid",
  "event_type": "string",
  "created_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "events": [
    {
      "event_id": "uuid",
      "event_type": "string",
      "event_data": {},
      "created_at": "timestamp"
    }
  ],
  "total_count": 1000
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "event_id": "uuid",
  "event_type": "string",
  "event_data": {},
  "metadata": {},
  "created_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "subscription_id": "uuid",
  "event_types": ["user.signup", "user.login"],
  "websocket_url": "wss://..."
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "total_events": 10000,
  "event_types": {
    "user.signup": 1000,
    "user.login": 9000
  },
  "timeline": [
    {
      "date": "2025-10-14",
      "count": 500
    }
  ]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "project_id": "uuid",
  "project_name": "string",
  "created_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "project_id": "uuid",
  "project_name": "string",
  "description": "string",
  "settings": {},
  "created_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "projects": [
    {
      "project_id": "uuid",
      "project_name": "string",
      "created_at": "timestamp"
    }
  ],
  "total_count": 10
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "project_id": "uuid",
  "updated_fields": ["project_name", "settings"],
  "updated_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "success": true,
  "deleted_id": "uuid",
  "deleted_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "project_id": "uuid",
  "vector_count": 10000,
  "memory_count": 5000,
  "table_count": 10,
  "file_count": 100,
  "storage_bytes": 10485760,
  "api_calls": 50000
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "project_id": "uuid",
  "enabled_features": ["vectors", "tables"],
  "enabled_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "interaction_id": "uuid",
  "collected_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "feedback_id": "uuid",
  "collected_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "workflow_feedback_id": "uuid",
  "collected_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "error_report_id": "uuid",
  "collected_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "total_interactions": 1000,
  "avg_feedback_score": 4.2,
  "positive_feedback": 850,
  "negative_feedback": 150,
  "collection_rate": 0.85
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "summary": [
    {
      "group_id": "agent-123",
      "interaction_count": 500,
      "avg_score": 4.5,
      "improvement_trend": 0.15
    }
  ]
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "session_id": "uuid",
  "collection_started": true,
  "started_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "session_id": "uuid",
  "collection_stopped": true,
  "stopped_at": "timestamp",
  "total_collected": 50
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "session_id": "uuid",
  "interactions": [
    {
      "interaction_id": "uuid",
      "user_input": "string",
      "agent_response": "string",
      "feedback_score": 5,
      "timestamp": "timestamp"
    }
  ],
  "total_count": 50
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "broadcast_id": "uuid",
  "recipients": 10,
  "broadcasted_at": "timestamp"
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "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:**
```javascript
{
  "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:**
```json
{
  "projects": [
    {
      "project_id": "uuid",
      "project_name": "string",
      "user_id": "uuid",
      "created_at": "timestamp",
      "storage_bytes": 1048576
    }
  ],
  "total_count": 100
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "user_id": "uuid",
  "project_count": 5,
  "vector_count": 10000,
  "storage_bytes": 10485760,
  "api_calls": 50000,
  "cost_estimate_usd": 25.50
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "status": "healthy",
  "database": "connected",
  "storage": "healthy",
  "quantum_service": "operational",
  "cache": "healthy",
  "uptime_seconds": 86400,
  "last_check": "timestamp"
}
```

**Example:**
```javascript
{}
```

#### 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:**
```json
{
  "optimized": true,
  "optimization_type": "all",
  "duration_ms": 30000,
  "space_freed_bytes": 1048576,
  "improvements": {
    "query_performance": 0.25,
    "storage_efficiency": 0.15
  }
}
```

**Example:**
```javascript
{
  "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:**
```json
{
  "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:**
```javascript
{
  "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:**
```json
{
  "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:**
```javascript
{
  "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:**
```json
{
  "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:**
```javascript
{
  "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:**
```json
{
  "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:**
```javascript
{
  "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:**
```json
{
  "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:**
```javascript
{
  "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:**
```json
{
  "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:**
```javascript
{
  "include_connections": true,
  "include_queries": true,
  "include_storage": true,
  "time_range": "day"
}
```

---

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

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

---

## Examples

### Example 1: Building a Knowledge Base

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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

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

#### Step 2: Update Your Configuration

**Old config (deprecated):**
```json
{
  "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):**
```json
{
  "mcpServers": {
    "zerodb": {
      "command": "npx",
      "args": ["ainative-zerodb-mcp-server"],
      "env": {
        "ZERODB_API_URL": "https://api.ainative.studio",
        "ZERODB_PROJECT_ID": "your-project-id",
        "ZERODB_API_KEY": "zdb_your-api-key-here"
      }
    }
  }
}
```

#### Why Switch?

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

---

### Migrating from v1.x to v2.0.0

#### Breaking Changes

1. **API Endpoint Consolidation**
   - **v1.x**: Direct API calls to various endpoints
   - **v2.0**: All operations go through unified MCP execute endpoint

   **Impact**: No code changes needed if using MCP tools

2. **Tool Naming Convention**
   - **v1.x**: Some tools lacked `zerodb_` prefix
   - **v2.0**: All tools prefixed with `zerodb_`

   **Migration**:
   ```javascript
   // Old (v1.x)
   store_memory(...) → zerodb_store_memory(...)
   search_memory(...) → zerodb_search_memory(...)

   // New (v2.0)
   zerodb_store_memory(...) // Consistent prefix
   ```

3. **Parameter Changes**
   - **Memory operations**: `memory_metadata` → `metadata`
   - **Vector operations**: `vector_metadata` → `metadata`

   **Migration**:
   ```javascript
   // Old (v1.x)
   {
     content: "...",
     memory_metadata: { key: "value" }
   }

   // New (v2.0)
   {
     content: "...",
     metadata: { key: "value" }
   }
   ```

4. **New Required Environment Variables**
   - `ZERODB_PROJECT_ID` is now required (was optional in v1.x)

   **Migration**: Add to your config:
   ```json
   {
     "env": {
       "ZERODB_PROJECT_ID": "your-project-id"
     }
   }
   ```

#### New Features Available

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

#### Migration Steps

1. **Update Package**
   ```bash
   npm update ainative-zerodb-mcp-server
   # or
   npm install -g ainative-zerodb-mcp-server@2.0.0
   ```

2. **Update Configuration**
   - Add `ZERODB_PROJECT_ID` to environment variables
   - Update any custom tool names to include `zerodb_` prefix

3. **Test Existing Functionality**
   - All v1.x operations remain compatible
   - Test memory and vector operations still work

4. **Gradually Adopt New Features**
   - Start with new features that provide immediate value
   - Refer to API Reference for new operation documentation

#### Backward Compatibility

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

---

## Troubleshooting

### Common Issues

#### 1. Authentication Failed

**Error**: `Authentication failed: Invalid credentials`

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

#### 2. Project Not Found

**Error**: `Project not found: [project-id]`

**Solutions**:
- Verify `ZERODB_PROJECT_ID` is correct
- List your projects: `zerodb_list_projects`
- Create a new project: `zerodb_create_project`

#### 3. Vector Dimension Mismatch

**Error**: `vector must have exactly 1536 dimensions, got 768`

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

#### 4. Token Expired

**Error**: `Token expired or invalid`

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

#### 5. Rate Limiting

**Error**: `Rate limit exceeded`

**Solutions**:
- Reduce request frequency
- Use batch operations where available
- Contact support for rate limit increases

### Debug Logging

Enable verbose logging by checking stderr output:

```bash
# 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**: support@ainative.studio
4. **Discord Community**: https://discord.gg/ainative

---

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# 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

```bash
# 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](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](https://ainative.studio)**

**Powered by ZeroDB - Enterprise Vector Search for AI**