ZeroDB MCP服务器v2.2.0

](https://www.npmjs.com/package/ainative-zerodb-mcp-server) ](https://www.npmjs.com/package/ainative-zerodb-mcp-server) ![license](https://github.com/AINative-Studio/ainative-zerodb-mcp-server/blob/main/LICENSE) ![test coverage](https://github.com/AINative-Studio/ainative-zerodb-mcp-server)

企业级模型上下文协议（MCP）服务器，为人工智能代理提供对ZeroDB矢量搜索、量子压缩、PostgreSQL、NoSQL操作和持久内存的完全访问。

🆕 v2.2.0的新增功能

3个新的嵌入工具 -免费嵌入生成 zerodb_generate_embeddings, zerodb_embed_and_store, zerodb_semantic_search
多维支持 -使用384、768、1024或1536维向量
免费模型 -BAAI/bg-small/base/alarge-en-v1.5（无API成本！）
151测试通过 -全面TDD测试套件的覆盖率为80.76%
看嵌入式_工具\_ GUIDE.md 获取完整的文档

主要特点

69完成操作 -API全面覆盖所有ZeroDB功能+新的嵌入工具
向量搜索 -基于384/768/1024/1536维嵌入的语义相似度搜索
免费嵌入 -使用BAAI BGE模型生成嵌入（无OpenAI成本！）
量子压缩 -使用量子算法的高级矢量压缩
PostgreSQL操作 -完整的SQL查询执行、模式管理、备份和统计
NoSQL表 -结构化数据的灵活表操作
文件存储 -安全的文件上传、下载和管理
事件系统 -支持发布/订阅的事件驱动架构
项目管理 -多租户项目隔离和管理
RLHF集成 -从人类反馈收集中强化学习
管理工具 -系统监控、优化和健康检查
企业安全 -JWT身份验证，自动令牌更新+SQL注入预防
90%+测试覆盖率 -生产可靠性综合测试套件

______________________________________________________________________

安装

NPM全球安装

npm install -g ainative-zerodb-mcp-server

NPX（无需安装）

npx ainative-zerodb-mcp-server

需求

Node.js>=18.0.0
NPM>=9.0.0
具有API证书的ZeroDB帐户（见下文）

______________________________________________________________________

入门指南

步骤1:创建您的ZeroDB帐户

在使用MCP服务器之前，您需要一个ZeroDB帐户和项目。

选项A：通过网络注册（推荐）

访问： https://api.ainative.studio/docs

点击“注册用户”端点
使用“试用”功能
输入您的电子邮件、密码和用户名

选项B：通过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"
  }'

答复：

{
  "email": "your-email@example.com",
  "id": "user-uuid-here",
  "username": "yourname"
}

第二步：创建项目

注册后，创建一个项目以获得您的 PROJECT_ID:

# 1. Login to get your access token
curl -X POST 'https://api.ainative.studio/v1/public/auth/login-json' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "your-email@example.com",
    "password": "YourSecurePassword123!"
  }'

答复：

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

答复：

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

保存此项目ID！ 您需要它来配置MCP。

______________________________________________________________________

快速开始

步骤3：配置Claude桌面

添加到您的Claude Desktop配置文件中：

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

{
  "mcpServers": {
    "zerodb": {
      "command": "npx",
      "args": ["ainative-zerodb-mcp-server"],
      "env": {
        "ZERODB_API_URL": "https://api.ainative.studio",
        "ZERODB_PROJECT_ID": "your-project-id-here",
        "ZERODB_USERNAME": "your-email@example.com",
        "ZERODB_PASSWORD": "your-password",
        "MCP_CONTEXT_WINDOW": "8192",
        "MCP_RETENTION_DAYS": "30"
      }
    }
  }
}

步骤4:重新启动克劳德桌面

保存配置后，重新启动Claude Desktop以激活MCP服务器。

第五步：测试你的第一次手术

在Claude Desktop中，尝试：

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

克劳德将使用 zerodb_store_memory 用于保存此信息的工具。

______________________________________________________________________

API 参考

所有60项行动分为9类。每个操作都公开为Claude可以调用的MCP工具。

内存操作

1. `zerodb_store_memory`

将代理内存存储在ZeroDB中，以实现会话间的持久上下文。

参数：

content （字符串，必填）-要存储的内存内容
role （字符串，必填）-消息角色： "user", "assistant"，或 "system"
session_id （字符串，可选）-会话标识符（如果未提供，则自动生成）
agent_id （字符串，可选）-代理标识符（如果未提供，则自动生成）
metadata （对象，可选）-其他元数据

退货：

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

例子：

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

2. `zerodb_search_memory`

使用语义相似性搜索代理内存。

参数：

query （字符串，必填）-搜索查询
session_id （字符串，可选）-按会话筛选
agent_id （字符串，可选）-按代理筛选
role （字符串，可选）-按角色筛选
limit （数字，可选）-最大结果（默认值：10）

退货：

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

例子：

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

3. `zerodb_get_context`

获取当前会话的代理上下文窗口，针对令牌限制进行了优化。

参数：

session_id （字符串，必填）-会话标识符
agent_id （字符串，可选）-代理标识符
max_tokens （数字，可选）-上下文中的最大令牌数（默认值：8192）

退货：

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

例子：

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

______________________________________________________________________

向量运算

4. `zerodb_store_vector`

存储带有元数据的向量嵌入（精确到1536维）。

参数：

vector_embedding （数组\[数字\]，必填）-1536维向量
document （字符串，必填）-源文档文本
metadata （对象，可选）-文档元数据
namespace （字符串，可选）-矢量命名空间（默认值：“windsurf”）

退货：

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

例子：

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

批量追加销售多个矢量以提高性能。

参数：

vectors （array，必填）-矢量对象数组

- vector_embedding （数组\[数字\]，必填）-1536维向量 - document （字符串，必填）-源文档 - metadata （对象，可选）-文档元数据

namespace （字符串，可选）-矢量命名空间

退货：

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

例子：

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

6. `zerodb_search_vectors`

使用语义相似性搜索向量。

参数：

query_vector （数组\[数字\]，必填）-1536维查询向量
namespace （字符串，可选）-矢量命名空间
limit （数字，可选）-最大结果（默认值：10）
threshold （数字，可选）-相似性阈值0-1（默认值：0.7）

退货：

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

例子：

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

7. `zerodb_delete_vector`

按ID删除特定向量。

参数：

vector_id （字符串，必填）-要删除的矢量UUID

退货：

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

例子：

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

8. `zerodb_get_vector`

按ID检索特定矢量。

参数：

vector_id （字符串，必填）-要检索的矢量UUID

退货：

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

例子：

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

9. `zerodb_list_vectors`

列出具有分页和过滤功能的向量。

参数：

namespace （字符串，可选）-按命名空间筛选
limit （数字，可选）-每页结果（默认值：50）
offset （数字，可选）-分页偏移量（默认值：0）

退货：

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

例子：

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

10. `zerodb_vector_stats`

获取有关矢量存储的统计信息。

参数：

namespace （字符串，可选）-按命名空间筛选

退货：

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

例子：

{
  "namespace": "windsurf"
}

11. `zerodb_create_vector_index`

创建矢量搜索索引以提高性能。

参数：

namespace （字符串，必填）-要索引的命名空间
index_type （字符串，可选）-索引类型：“ivfflat”或“hnsw”（默认值：“hnsw”）
params （对象，可选）-索引特定参数

退货：

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

例子：

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

12. `zerodb_optimize_vectors`

优化向量存储和索引。

参数：

namespace （字符串，可选）-要优化的命名空间

退货：

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

例子：

{
  "namespace": "windsurf"
}

13. `zerodb_export_vectors`

将矢量导出为外部格式。

参数：

namespace （字符串，必填）-要导出的命名空间
format （字符串，可选）-导出格式：“json”或“csv”（默认为“json”）
include_embeddings （布尔值，可选）-包含向量数据（默认值：false）

退货：

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

例子：

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

______________________________________________________________________

量子操作

14. `zerodb_quantum_compress`

使用量子算法压缩向量以减少存储。

参数：

vector_embedding （数组\[number\]，必填）-要压缩的1536维向量
compression_ratio （数字，可选）-目标比率0-1（默认值：0.5）
algorithm （字符串，可选）-算法：“qaoa”或“vqe”（默认值：“qaaa”）

退货：

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

例子：

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

15. `zerodb_quantum_decompress`

对量子压缩向量进行解压缩。

参数：

compressed_vector （数组\[number\]，必填）-压缩向量数据
original_dimensions （数字，必填）-原始尺寸计数

退货：

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

例子：

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

16. `zerodb_quantum_hybrid_search`

使用量子增强相似性进行混合搜索。

参数：

query_vector （数组\[数字\]，必填）-1536维查询
namespace （字符串，可选）-矢量命名空间
limit （数字，可选）-最大结果（默认值：10）
quantum_weight （数字，可选）-量子影响0-1（默认值：0.5）

退货：

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

例子：

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

17. `zerodb_quantum_optimize`

使用量子优化优化向量空间。

参数：

namespace （字符串，必填）-要优化的命名空间
optimization_target （字符串，可选）-“存储”或“search_speed”（默认值：“存储”）

退货：

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

例子：

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

18. `zerodb_quantum_feature_map`

为矢量生成量子特征图。

参数：

vector_embedding （数组\[数字\]，必填）-1536维向量
feature_map_type （字符串，可选）-“zz”或“pauli”（默认值：“zz“）

退货：

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

例子：

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

19. `zerodb_quantum_kernel`

计算向量之间的量子核相似性。

参数：

vector_a （数组\[数字\]，必填）-第一个1536维向量
vector_b （数组\[数字\]，必填）-第二个1536维向量
kernel_type （字符串，可选）-“线性”或“rbf”（默认值：“rbf”）

退货：

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

例子：

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

______________________________________________________________________

表/NoSQL操作

20. `zerodb_create_table`

使用模式创建一个新的NoSQL表。

参数：

table_name （字符串，必填）-表名
schema （对象，必填）-JSON模式定义
description （字符串，可选）-表描述

退货：

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

例子：

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

21. `zerodb_list_tables`

列出项目中的所有表。

参数：

limit （数字，可选）-每页结果（默认值：50）
offset （数字，可选）-分页偏移量（默认值：0）

退货：

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

例子：

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

22. `zerodb_get_table`

获取表详细信息和架构。

参数：

table_id （字符串，必填）-表UUID

退货：

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

例子：

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

23. `zerodb_delete_table`

删除表及其所有数据。

参数：

table_id （字符串，必填）-要删除的表UUID

退货：

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

例子：

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

24. `zerodb_insert_rows`

将行插入表中。

参数：

table_id （字符串，必填）-表UUID
rows （array，必填）-行对象数组

退货：

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

例子：

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

使用筛选器查询表行。

参数：

table_id （字符串，必填）-表UUID
filters （对象，可选）-查询筛选器
limit （数字，可选）-最大结果（默认值：50）
offset （数字，可选）-分页偏移量（默认值：0）

退货：

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

例子：

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

26. `zerodb_update_rows`

更新表中的行。

参数：

table_id （字符串，必填）-表UUID
filters （对象，必填）-行选择过滤器
updates （对象，必填）-要更新的字段

退货：

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

例子：

{
  "table_id": "123e4567-e89b-12d3-a456-426614174000",
  "filters": {
    "user_id": "user-1"
  },
  "updates": {
    "email": "newemail@example.com"
  }
}

27. `zerodb_delete_rows`

从表中删除行。

参数：

table_id （字符串，必填）-表UUID
filters （对象，必填）-行选择过滤器

退货：

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

例子：

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

______________________________________________________________________

文件操作

28. `zerodb_upload_file`

将文件上传到ZeroDB存储。

参数：

file_name （字符串，必填）-文件名
file_data （字符串，必填）-Base64编码文件数据
content_type （字符串，可选）-MIME类型
metadata （对象，可选）-文件元数据

退货：

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

例子：

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

29. `zerodb_download_file`

从ZeroDB存储中下载文件。

参数：

file_id （字符串，必填）-文件UUID

退货：

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

例子：

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

30. `zerodb_list_files`

列出带分页的文件。

参数：

limit （数字，可选）-每页结果（默认值：50）
offset （数字，可选）-分页偏移量（默认值：0）
content_type （字符串，可选）-按MIME类型筛选

退货：

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

例子：

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

31. `zerodb_delete_file`

从存储中删除文件。

参数：

file_id （字符串，必填）-要删除的文件UUID

退货：

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

例子：

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

32. `zerodb_get_file_metadata`

无需下载即可获取文件元数据。

参数：

file_id （字符串，必填）-文件UUID

退货：

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

例子：

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

33. `zerodb_generate_presigned_url`

生成临时下载URL。

参数：

file_id （字符串，必填）-文件UUID
expiry_seconds （数字，可选）-URL有效性（默认值：3600）

退货：

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

例子：

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

______________________________________________________________________

活动操作

34. `zerodb_create_event`

在事件系统中创建新事件。

参数：

event_type （字符串，必填）-事件类型标识符
event_data （对象，必填）-事件有效载荷
metadata （对象，可选）-事件元数据

退货：

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

例子：

{
  "event_type": "user.signup",
  "event_data": {
    "user_id": "user-123",
    "email": "user@example.com"
  },
  "metadata": {
    "source": "web"
  }
}

35. `zerodb_list_events`

列出具有筛选和分页功能的事件。

参数：

event_type （字符串，可选）-按事件类型筛选
start_date （字符串，可选）-按开始日期筛选（ISO 8601）
end_date （字符串，可选）-按结束日期筛选（ISO 8601）
limit （数字，可选）-每页结果（默认值：50）
offset （数字，可选）-分页偏移量（默认值：0）

退货：

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

例子：

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

36. `zerodb_get_event`

按ID获取特定事件。

参数：

event_id （字符串，必填）-事件UUID

退货：

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

例子：

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

37. `zerodb_subscribe_events`

订阅事件流（WebSocket）。

参数：

event_types （array\[string\]，必填）-要订阅的事件类型
filters （对象，可选）-其他过滤器

退货：

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

例子：

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

38. `zerodb_event_stats`

获取事件统计和分析。

参数：

event_type （字符串，可选）-按事件类型筛选
start_date （字符串，可选）-开始日期（ISO 8601）
end_date （字符串，可选）-结束日期（ISO 8601）
group_by （字符串，可选）-分组方式：“小时”、“天”、“周”（默认值：“天”）

退货：

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

例子：

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

______________________________________________________________________

项目运营

39. `zerodb_create_project`

创建一个新的ZeroDB项目。

参数：

project_name （字符串，必填）-项目名称
description （字符串，可选）-项目描述
settings （对象，可选）-项目设置

退货：

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

例子：

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

40. `zerodb_get_project`

获取项目详细信息。

参数：

project_id （字符串，必填）-项目UUID

退货：

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

例子：

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

41. `zerodb_list_projects`

列出所有可访问的项目。

参数：

limit （数字，可选）-每页结果（默认值：50）
offset （数字，可选）-分页偏移量（默认值：0）

退货：

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

例子：

{
  "limit": 100
}

42. `zerodb_update_project`

更新项目设置。

参数：

project_id （字符串，必填）-项目UUID
project_name （字符串，可选）-新项目名称
description （字符串，可选）-新描述
settings （对象，可选）-更新设置

退货：

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

例子：

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

43. `zerodb_delete_project`

删除项目及其所有数据。

参数：

project_id （字符串，必填）-要删除的项目UUID
confirm （boolean，必填）-必须为true才能确认删除

退货：

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

例子：

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

44. `zerodb_get_project_stats`

获取项目使用统计信息。

参数：

project_id （字符串，必填）-项目UUID
start_date （字符串，可选）-开始日期（ISO 8601）
end_date （字符串，可选）-结束日期（ISO 8601）

退货：

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

例子：

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

45. `zerodb_enable_database`

为项目启用数据库功能。

参数：

project_id （字符串，必填）-项目UUID
features （array\[string\]，必填）-要启用的功能：\[“向量”、“表”、“文件”、“事件”\]

退货：

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

例子：

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

______________________________________________________________________

RLHF操作

46. `zerodb_rlhf_interaction`

收集RLHF训练的用户交互。

参数：

session_id （字符串，必填）-会话标识符
user_input （字符串，必填）-用户输入
agent_response （字符串，必填）-代理的响应
feedback_score （数字，可选）-用户评分1-5
metadata （对象，可选）-附加上下文

退货：

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

例子：

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

收集有关代理绩效的反馈。

参数：

agent_id （字符串，必填）-代理标识符
session_id （字符串，必填）-会话标识符
feedback_type （字符串，必填）-“正”或“负”
feedback_text （字符串，可选）-详细反馈
metrics （对象，可选）-性能指标

退货：

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

例子：

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

收集有关工作流程完成情况的反馈。

参数：

workflow_id （字符串，必填）-工作流标识符
session_id （字符串，必填）-会话标识符
completed （布尔值，必填）-工作流完成状态
duration_ms （数字，可选）-工作流持续时间
feedback （对象，可选）-工作流反馈

退货：

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

例子：

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

49. `zerodb_rlhf_error`

收集错误报告以改进模型。

参数：

session_id （字符串，必填）-会话标识符
error_type （字符串，必填）-错误类别
error_message （字符串，必填）-错误描述
context （对象，可选）-错误上下文
user_impact （字符串，可选）-影响级别：“低”、“中”、“高”

退货：

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

例子：

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

获取RLHF收集状态。

参数：

session_id （字符串，可选）-按会话筛选
start_date （字符串，可选）-开始日期（ISO 8601）
end_date （字符串，可选）-结束日期（ISO 8601）

退货：

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

例子：

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

51. `zerodb_rlhf_summary`

获取RLHF分析摘要。

参数：

group_by （字符串，可选）-分组方式：“代理”、“工作流”、“会话”（默认：“代理“）
start_date （字符串，可选）-开始日期（ISO 8601）
end_date （字符串，可选）-结束日期（ISO 8601）

退货：

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

例子：

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

52. `zerodb_rlhf_start`

启动会话的RLHF收集。

参数：

session_id （字符串，必填）-会话标识符
collection_config （对象，可选）-收藏设置

退货：

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

例子：

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

53. `zerodb_rlhf_stop`

停止会话的RLHF收集。

参数：

session_id （字符串，必填）-会话标识符

退货：

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

例子：

{
  "session_id": "session-123"
}

54. `zerodb_rlhf_session`

获取会话的所有交互。

参数：

session_id （字符串，必填）-会话标识符
limit （数字，可选）-最大结果（默认值：100）

退货：

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

例子：

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

55. `zerodb_rlhf_broadcast`

向订阅者广播RLHF事件。

参数：

event_type （字符串，必填）-事件类型
event_data （对象，必填）-事件有效载荷
target_sessions （array\[string\]，可选）-目标会话ID

退货：

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

例子：

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

______________________________________________________________________

管理操作

56. `zerodb_admin_system_stats`

获取系统范围的统计数据（需要管理员角色）。

参数：

include_details （布尔值，可选）-包括详细指标（默认值：false）

退货：

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

例子：

{
  "include_details": true
}

57. `zerodb_admin_list_projects`

列出系统中的所有项目（需要管理员角色）。

参数：

user_id （字符串，可选）-按用户筛选
limit （数字，可选）-每页结果（默认值：100）
offset （数字，可选）-分页偏移量（默认值：0）

退货：

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

例子：

{
  "limit": 500
}

58. `zerodb_admin_user_usage`

获取用户使用统计数据（需要管理员角色）。

参数：

user_id （字符串，必填）-用户UUID
start_date （字符串，可选）-开始日期（ISO 8601）
end_date （字符串，可选）-结束日期（ISO 8601）

退货：

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

例子：

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

59. `zerodb_admin_health`

获取系统健康状态（需要管理员角色）。

参数：

退货：

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

例子：

{}

60. `zerodb_admin_optimize`

优化数据库和存储（需要管理员角色）。

参数：

optimization_type （字符串，必填）-“真空”、“重新索引”或“全部”
tables （array\[string\]，可选）-要优化的特定表

退货：

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

例子：

{
  "optimization_type": "all"
}

______________________________________________________________________

PostgreSQL操作

用于高级SQL工作负载的专用PostgreSQL数据库操作。

61. `zerodb_postgres_query`

在您配置的PostgreSQL实例上执行SQL查询，并进行全面的安全验证。

参数：

sql （字符串，必填）-要执行的SQL查询
params （array\[string\]，可选）-查询已准备语句的参数
read_only （boolean，可选）-强制只读模式（仅限SELECT），默认值：false
timeout_seconds （数字，可选）-查询超时（秒），默认值：30
max_rows （数字，可选）-返回的最大行数，默认值：1000

退货：

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

安全功能：

SQL注入预防（阻止DROP DATABASE、TRUNCATE等）
查询超时强制
只读模式支持
参数净化
执行历史跟踪

例子：

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

获取详细的数据库模式信息，包括表、列、索引和约束。

参数：

table_name （字符串，可选）-要检查的特定表（所有表省略）
include_indexes （布尔值，可选）-包括索引信息，默认值：true
include_constraints （布尔值，可选）-包括约束信息，默认值：true
include_stats （布尔值，可选）-包括表统计信息，默认值：false

退货：

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

例子：

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

63. `zerodb_postgres_create_table`

创建一个新表，其中包含完整的架构定义，包括列、约束和索引。

参数：

table_name （string，必填）-要创建的表的名称
columns （数组，必填）-列定义

- name （字符串，必填）-列名 - type （字符串，必填）-列类型（例如，“VARCHAR（255）”、“INTEGER”、“TIMESTAMP”） - nullable （boolean，可选）-允许NULL值，默认值：true - primary_key （boolean，可选）-是主键，默认值：false - unique （boolean，可选）-唯一约束，默认值：false - default （字符串，可选）-默认值

indexes （数组，可选）-索引定义

- name （字符串，可选）-索引名称（如果未提供，则自动生成） - columns （array\[string\]，必填）-要索引的列 - unique （布尔值，可选）-唯一索引，默认值：false

if_not_exists （boolean，可选）-仅在表不存在时创建，默认值：true

退货：

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

例子：

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

使用可配置选项触发PostgreSQL备份作业。

参数：

backup_type （字符串，可选）-“完整”或“增量”，默认值：“完整”
retention_days （数字，可选）-备份保留天数，默认值：7
compression （布尔值，可选）-压缩备份，默认值：true
include_schema （布尔值，可选）-包括模式定义，默认值：true
include_data （布尔值，可选）-包括表数据，默认值：true

退货：

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

例子：

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

65. `zerodb_postgres_restore`

从备份还原PostgreSQL数据库。

参数：

backup_id （字符串，必填）-要从中还原的备份ID
restore_type （字符串，可选）-“full”、“schema-only”或“data_only”，默认值：“full
target_database （字符串，可选）-还原为不同的数据库名称
confirm_overwrite （boolean，必填）-必须为true才能确认覆盖现有数据

退货：

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

安全：

需要明确 confirm_overwrite: true 防止意外数据丢失
记录所有还原操作以进行审核跟踪

例子：

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

66. `zerodb_postgres_stats`

获取全面的PostgreSQL数据库统计数据，包括性能指标。

参数：

include_connections （布尔值，可选）-包括连接统计信息，默认值：true
include_queries （布尔值，可选）-包括查询性能统计数据，默认值：true
include_storage （布尔值，可选）-包括存储统计信息，默认值：true
include_replication （布尔值，可选）-包括复制统计信息，默认值：false
time_range （字符串，可选）-“小时”、“天”、“周”或“月”，默认值：“天”

退货：

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

例子：

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

______________________________________________________________________

配置

环境变量

所有配置都是通过环境变量完成的。在MCP服务器配置中设置这些。

变量	必填	默认	描述
`ZERODB_API_URL`	没有	`https://api.ainative.studio`	ZeroDB API基础URL
`ZERODB_PROJECT_ID`	是	-	您的ZeroDB项目ID
`ZERODB_USERNAME`	是	-	您的ZeroDB帐户电子邮件
`ZERODB_PASSWORD`	是	-	您的ZeroDB帐户密码
`ZERODB_API_TOKEN`	没有	-	预先存在的API令牌（可选，将自动生成）
`MCP_CONTEXT_WINDOW`	没有	`8192`	上下文窗口中的最大令牌数
`MCP_RETENTION_DAYS`	没有	`30`	记忆保留期（天）

认证

MCP服务器使用带有自动令牌续订的JWT身份验证：

初始身份验证：启动时，服务器使用用户名/密码进行身份验证
令牌存储：访问令牌存储在内存中
自动续订：令牌每25分钟自动续订一次（令牌在30分钟后过期）
手动续订：使用 zerodb_renew_token 如果需要，手动续订

安全最佳实践

安全地存储凭据：使用环境变量，不要硬编码
使用特定于项目的凭据：为不同的应用程序创建单独的项目
定期轮换密码：每90天更改一次密码
监控API使用情况：检查项目统计中的异常活动
限制令牌范围：尽可能使用项目特定的令牌

______________________________________________________________________

示例

示例1：构建知识库

// 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
});

示例2：带有上下文的代理内存

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

示例3:RLHF数据收集

// 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"
});

示例4：量子增强搜索

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

示例5:NoSQL数据管理

// 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" }
  }
});

示例6：错误处理

// 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);
}

______________________________________________________________________

迁移指南

从v1.x迁移到v2.0.0

重大变更

API端点整合

- v1.x：将API直接调用到各个端点 - v2.0：所有操作都通过统一的MCP执行端点

影响：如果使用MCP工具，则不需要更改代码

工具命名约定

- v1.x：缺少一些工具 zerodb_ 前缀 - v2.0：所有前缀为的工具 zerodb_

迁移:

   // Old (v1.x)
   store_memory(...) → zerodb_store_memory(...)
   search_memory(...) → zerodb_search_memory(...)

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

参数变化

- 内存操作: memory_metadata → metadata - 向量运算: vector_metadata → metadata

迁移:

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

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

新的必需环境变量

- ZERODB_PROJECT_ID 现在是必需的（在v1.x中是可选的）

迁移：添加到您的配置中：

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

可用的新功能

54新业务 -API完全覆盖内存和向量运算之外的内容
量子压缩 -将矢量存储减少高达50%
NoSQL表 -结构化数据存储和查询
文件管理 -上传和管理文件
事件系统 -事件驱动架构支持
RLHF收集 -用于模型训练的内置反馈收集
管理工具 -系统监控和优化

迁移步骤

更新程序包

   npm update ainative-zerodb-mcp-server
   # or
   npm install -g ainative-zerodb-mcp-server@2.0.0

更新配置

- 添加 ZERODB_PROJECT_ID 环境变量 - 更新任何自定义工具名称以包括 zerodb_ 前缀

测试现有功能

- 所有v1.x操作保持兼容 - 测试内存和向量操作仍然有效

逐步采用新功能

- 从提供即时价值的新功能开始 - 有关新的操作文档，请参阅API参考资料

向后兼容

v2.0支持所有v1.x操作
现有数据和项目完全兼容
无需数据迁移

______________________________________________________________________

故障排除

常见问题

1.身份验证失败

错误: Authentication failed: Invalid credentials

解决方案:

验证 ZERODB_USERNAME 和 ZERODB_PASSWORD 是正确的
检查您的帐户是否处于活动状态
尝试手动续订令牌： zerodb_renew_token

2.未找到项目

错误: Project not found: [project-id]

解决方案:

验证 ZERODB_PROJECT_ID 是正确的
列出您的项目： zerodb_list_projects
创建新项目： zerodb_create_project

3.矢量维度不匹配

错误: vector must have exactly 1536 dimensions, got 768

解决方案:

确保你正在使用OpenAI text-embedding-3-small （1536个维度）
或使用 text-embedding-ada-002 （1536个维度）
不要使用 text-embedding-3-large （3072个尺寸）

4.令牌已过期

错误: Token expired or invalid

解决方案:

服务器应每25分钟自动续订一次令牌
手动续订： zerodb_renew_token
检查服务器日志中的续订错误

5.费率限制

错误: Rate limit exceeded

解决方案:

降低请求频率
在可用的情况下使用批处理操作
联系支持人员以提高费率限制

调试日志

通过检查stderr输出启用详细日志记录：

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

日志消息包括：

令牌续订尝试和状态
API调用详细信息（操作，参数）
带有完整上下文的错误消息

获取帮助

文档: https://docs.ainative.studio/zerodb
GitHub问题: https://github.com/AINative-Studio/ainative-zerodb-mcp-server/issues
电子邮件支持: support@ainative.studio
不和谐社区: https://discord.gg/ainative

______________________________________________________________________

贡献

我们欢迎捐款！请查看我们的贡献指南了解详情。

开发设置

# 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

测试

# Run tests with coverage
npm test

# Watch mode for development
npm run test:watch

# CI mode
npm run test:ci

代码质量

要求90%以上的测试覆盖率
ESLint代码风格
没有高/关键的npm漏洞
PR合并前必须通过所有测试

______________________________________________________________________

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

______________________________________________________________________

更新日志

v2.0.0（2025-10-14）

重大变更:

现在所有操作都需要 ZERODB_PROJECT_ID 环境变量
用于所有操作的统一API端点
一致的 zerodb_ 所有工具名称的前缀

新功能:

新增54项操作（共60项）
量子矢量压缩与优化
NoSQL表操作
文件存储和管理
事件驱动架构支持
RLHF反馈收集
管理系统监控和优化
90%+测试覆盖率
自动令牌续订

改进:

更好的错误处理和消息
改进文档
增强安全性
性能优化

v1.0.7（2025-10-01）

首次公开发布
基本内存和向量操作
Claude桌面集成

______________________________________________________________________

建于❤️ 通过 AINative工作室

由ZeroDB提供技术支持-人工智能企业矢量搜索

AINative ZeroDB MCP Server

快速接入

详细介绍

ZeroDB MCP服务器v2.2.0

🆕 v2.2.0的新增功能

主要特点

目录

安装

NPM全球安装

NPX（无需安装）

需求

入门指南

步骤1:创建您的ZeroDB帐户

选项A：通过网络注册（推荐）

选项B：通过API注册

第二步：创建项目

快速开始

步骤3：配置Claude桌面

步骤4:重新启动克劳德桌面

第五步：测试你的第一次手术

API 参考

内存操作

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

表/NoSQL操作

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

RLHF操作

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

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`