{"_id":"@ainative/zerodb-mcp-client","name":"@ainative/zerodb-mcp-client","dist-tags":{"latest":"2.3.0"},"versions":{"2.3.0":{"name":"@ainative/zerodb-mcp-client","version":"2.3.0","description":"Production-ready TypeScript/JavaScript client for ZeroDB MCP Bridge","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","build:watch":"tsc --watch","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","prepublishOnly":"npm run build","clean":"rm -rf dist"},"keywords":["zerodb","mcp","vector","database","quantum","semantic-search","embeddings","ai","machine-learning"],"author":{"name":"AINative Studio"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ainative-studio/zerodb-mcp-client.git"},"bugs":{"url":"https://github.com/ainative-studio/zerodb-mcp-client/issues"},"homepage":"https://github.com/ainative-studio/zerodb-mcp-client#readme","dependencies":{"axios":"^1.6.0"},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.48.0","jest":"^29.6.0","ts-jest":"^29.1.0","typescript":"^5.2.0"},"engines":{"node":">=16.0.0"},"_id":"@ainative/zerodb-mcp-client@2.3.0","gitHead":"de4d2b78d4658a66b58ca256fe935557a0b3638f","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-X/nxFRMBnGHhJjXXHMiyvIqLicWsP2fkh6maN5pS0xHdELXSqSK9DwzAErn3Zup6H60Vc5xpYzZVHeB5XgTDBA==","shasum":"2dc4c3281acced06f47c08c05ebbcd05a51727cb","tarball":"https://registry.npmjs.org/@ainative/zerodb-mcp-client/-/zerodb-mcp-client-2.3.0.tgz","fileCount":84,"unpackedSize":186909,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDaM4WmRo41kyIVe1F/rMv3wSUH5OXdBA4loTw0teRzIAiEAsRMOla+rGqLD/HYyGgIXj3P6oHgtQlYIUXNWKwlP2pM="}]},"_npmUser":{"name":"ainative-studio","email":"toby@rely.ventures"},"directories":{},"maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zerodb-mcp-client_2.3.0_1766533601792_0.09620601582961319"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-23T23:46:41.651Z","2.3.0":"2025-12-23T23:46:41.956Z","modified":"2025-12-23T23:46:42.274Z"},"maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"description":"Production-ready TypeScript/JavaScript client for ZeroDB MCP Bridge","homepage":"https://github.com/ainative-studio/zerodb-mcp-client#readme","keywords":["zerodb","mcp","vector","database","quantum","semantic-search","embeddings","ai","machine-learning"],"repository":{"type":"git","url":"git+https://github.com/ainative-studio/zerodb-mcp-client.git"},"author":{"name":"AINative Studio"},"bugs":{"url":"https://github.com/ainative-studio/zerodb-mcp-client/issues"},"license":"MIT","readme":"# ZeroDB MCP Client\n\nProduction-ready TypeScript/JavaScript client for the ZeroDB MCP Bridge API. Provides type-safe access to all ZeroDB capabilities including vector search, quantum operations, NoSQL tables, file storage, events, and more.\n\n[![npm version](https://badge.fury.io/js/%40zerodb%2Fmcp-client.svg)](https://www.npmjs.com/package/@zerodb/mcp-client)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.2-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- **Complete API Coverage**: All 60+ ZeroDB operations supported\n- **Type-Safe**: Full TypeScript support with comprehensive type definitions\n- **Error Handling**: Custom error classes with detailed error information\n- **Retry Logic**: Built-in exponential backoff for transient failures\n- **Authentication**: Support for both API keys and JWT tokens\n- **Rate Limiting**: Automatic rate limit handling with retry-after support\n- **Validation**: Input validation for vectors, UUIDs, and other data\n- **Framework Support**: Works with Node.js, React, Next.js, and other frameworks\n\n## Installation\n\n```bash\nnpm install @zerodb/mcp-client\n```\n\nOr with yarn:\n\n```bash\nyarn add @zerodb/mcp-client\n```\n\n## Quick Start\n\n```typescript\nimport { ZeroDBClient } from '@zerodb/mcp-client';\n\n// Initialize the client\nconst client = new ZeroDBClient({\n  apiKey: 'ZERODB_your_api_key',\n  baseURL: 'https://api.ainative.studio' // optional\n});\n\n// Search vectors\nconst results = await client.vectors.search({\n  project_id: 'your-project-uuid',\n  query_vector: embedding, // 1536-dimensional array\n  limit: 10,\n  threshold: 0.7\n});\n\nconsole.log(`Found ${results.total_count} results`);\n```\n\n## Authentication\n\nThe client supports two authentication methods:\n\n### API Key Authentication\n\n```typescript\nconst client = new ZeroDBClient({\n  apiKey: 'ZERODB_your_api_key'\n});\n```\n\n### JWT Token Authentication\n\n```typescript\nconst client = new ZeroDBClient({\n  jwtToken: 'your_jwt_token'\n});\n```\n\n### Updating Authentication\n\n```typescript\n// Switch to JWT\nclient.setAuthToken('new_jwt_token', 'jwt');\n\n// Switch to API key\nclient.setAuthToken('ZERODB_new_api_key', 'apiKey');\n```\n\n## Configuration Options\n\n```typescript\nconst client = new ZeroDBClient({\n  apiKey: 'ZERODB_your_api_key',      // API key (or use jwtToken)\n  jwtToken: 'your_jwt_token',         // JWT token (alternative to apiKey)\n  baseURL: 'https://api.ainative.studio', // API base URL (optional)\n  timeout: 30000,                     // Request timeout in ms (default: 30000)\n  retryAttempts: 3,                   // Number of retry attempts (default: 3)\n  retryDelay: 1000                    // Initial retry delay in ms (default: 1000)\n});\n```\n\n## API Reference\n\n### Vector Operations\n\n#### Upsert a Vector\n\n```typescript\nconst result = await client.vectors.upsert({\n  project_id: 'project-uuid',\n  embedding: [0.1, 0.2, ...], // 1536 dimensions\n  document: 'This is a sample document',\n  namespace: 'default',\n  metadata: {\n    source: 'api',\n    type: 'article',\n    tags: ['technology', 'ai']\n  }\n});\n// Returns: { vector_id: string, status: string }\n```\n\n#### Batch Upsert Vectors\n\n```typescript\nconst result = await client.vectors.batchUpsert({\n  project_id: 'project-uuid',\n  namespace: 'documents',\n  vectors: [\n    {\n      embedding: [...],\n      document: 'Document 1',\n      metadata: { ... }\n    },\n    {\n      embedding: [...],\n      document: 'Document 2',\n      metadata: { ... }\n    }\n  ]\n});\n// Returns: { vector_ids: string[], success_count: number, error_count: number }\n```\n\n#### Search Vectors\n\n```typescript\nconst results = await client.vectors.search({\n  project_id: 'project-uuid',\n  query_vector: [...], // 1536 dimensions\n  limit: 10,\n  threshold: 0.7,\n  namespace: 'default',\n  metadata_filter: {\n    category: 'technology'\n  }\n});\n// Returns: { vectors: Vector[], total_count: number, search_time_ms: number }\n```\n\n#### Delete a Vector\n\n```typescript\nconst result = await client.vectors.delete('project-uuid', 'vector-id');\n// Returns: { status: string, deleted: boolean }\n```\n\n#### Get Vector by ID\n\n```typescript\nconst vector = await client.vectors.get('project-uuid', 'vector-id');\n// Returns: Vector object with all fields\n```\n\n#### List Vectors\n\n```typescript\nconst vectors = await client.vectors.list({\n  project_id: 'project-uuid',\n  namespace: 'default',\n  limit: 100,\n  offset: 0\n});\n// Returns: Vector[]\n```\n\n#### Vector Statistics\n\n```typescript\nconst stats = await client.vectors.stats('project-uuid');\n// Returns: {\n//   total_vectors: number,\n//   namespaces: Array<{ namespace: string, count: number }>,\n//   storage_bytes: number,\n//   avg_vector_size: number\n// }\n```\n\n#### Create Vector Index\n\n```typescript\nconst index = await client.vectors.createIndex({\n  project_id: 'project-uuid',\n  namespace: 'default',\n  index_type: 'HNSW' // or 'IVF' or 'FLAT'\n});\n// Returns: { index_id: string, estimated_build_time_seconds: number, status: string }\n```\n\n#### Optimize Vector Storage\n\n```typescript\nconst result = await client.vectors.optimize({\n  project_id: 'project-uuid',\n  strategy: 'compression' // or 'deduplication' or 'clustering'\n});\n// Returns: { optimized_vectors: number, storage_saved_bytes: number, optimization_time_ms: number }\n```\n\n#### Export Vectors\n\n```typescript\nconst result = await client.vectors.export({\n  project_id: 'project-uuid',\n  namespace: 'default',\n  format: 'json' // or 'csv' or 'parquet'\n});\n// Returns: { download_url: string, vector_count: number, file_size_bytes: number }\n```\n\n### Quantum Operations\n\n#### Compress Vector\n\n```typescript\nconst result = await client.quantum.compress({\n  project_id: 'project-uuid',\n  embedding: [...],\n  compression_ratio: 0.6,\n  preserve_semantics: true\n});\n// Returns: { compressed_embedding: number[], compression_achieved: number }\n```\n\n#### Decompress Vector\n\n```typescript\nconst result = await client.quantum.decompress({\n  project_id: 'project-uuid',\n  compressed_embedding: [...]\n});\n// Returns: { embedding: number[], quality_score: number }\n```\n\n#### Hybrid Similarity\n\n```typescript\nconst result = await client.quantum.hybridSimilarity({\n  project_id: 'project-uuid',\n  query_vector: [...],\n  candidate_vector: [...],\n  metadata_boost: { relevance: 0.8 }\n});\n// Returns: { similarity_score: number, cosine_component: number, quantum_component: number }\n```\n\n### Table Operations\n\n#### Create Table\n\n```typescript\nconst table = await client.tables.createTable({\n  project_id: 'project-uuid',\n  table_name: 'users',\n  schema: {\n    name: { type: 'string', nullable: false },\n    email: { type: 'string', nullable: false },\n    age: { type: 'number', nullable: true }\n  }\n});\n```\n\n#### Insert Rows\n\n```typescript\nconst result = await client.tables.insertRows({\n  project_id: 'project-uuid',\n  table_name: 'users',\n  rows: [\n    { name: 'John', email: 'john@example.com', age: 30 },\n    { name: 'Jane', email: 'jane@example.com', age: 28 }\n  ]\n});\n```\n\n#### Query Rows\n\n```typescript\nconst result = await client.tables.queryRows({\n  project_id: 'project-uuid',\n  table_name: 'users',\n  filters: { age: { $gte: 25 } },\n  limit: 10,\n  order_by: 'name'\n});\n```\n\n#### Update Rows\n\n```typescript\nconst result = await client.tables.updateRows({\n  project_id: 'project-uuid',\n  table_name: 'users',\n  filters: { email: 'john@example.com' },\n  updates: { age: 31 }\n});\n```\n\n#### Delete Rows\n\n```typescript\nconst result = await client.tables.deleteRows({\n  project_id: 'project-uuid',\n  table_name: 'users',\n  filters: { age: { $lt: 18 } },\n  confirm: true\n});\n```\n\n### File Operations\n\n#### Upload File\n\n```typescript\nconst result = await client.files.uploadBuffer(\n  'project-uuid',\n  'document.pdf',\n  fileBuffer,\n  'application/pdf',\n  { author: 'John Doe' }\n);\n```\n\n#### Download File\n\n```typescript\nconst result = await client.files.download({\n  project_id: 'project-uuid',\n  file_id: 'file-uuid'\n});\nconst content = Buffer.from(result.file_data, 'base64');\n```\n\n#### List Files\n\n```typescript\nconst result = await client.files.list({\n  project_id: 'project-uuid',\n  prefix: 'documents/',\n  limit: 50\n});\n```\n\n#### Delete File\n\n```typescript\nconst result = await client.files.delete({\n  project_id: 'project-uuid',\n  file_id: 'file-uuid'\n});\n```\n\n### Event Operations\n\n#### Create Event\n\n```typescript\nconst result = await client.events.create({\n  project_id: 'project-uuid',\n  event_type: 'user.signup',\n  topic: 'users',\n  payload: { user_id: '123', email: 'user@example.com' },\n  source: 'web-app'\n});\n```\n\n#### List Events\n\n```typescript\nconst result = await client.events.list({\n  project_id: 'project-uuid',\n  topic: 'users',\n  limit: 100\n});\n```\n\n#### Subscribe to Events\n\n```typescript\nconst result = await client.events.subscribe({\n  project_id: 'project-uuid',\n  topic: 'users',\n  webhook_url: 'https://myapp.com/webhooks/events'\n});\n```\n\n### Project Operations\n\n#### Create Project\n\n```typescript\nconst project = await client.projects.create({\n  name: 'My Project',\n  description: 'Project description',\n  tier: 'pro'\n});\n```\n\n#### List Projects\n\n```typescript\nconst result = await client.projects.list();\n```\n\n#### Get Project Stats\n\n```typescript\nconst stats = await client.projects.stats({\n  project_id: 'project-uuid'\n});\n```\n\n#### Delete Project\n\n```typescript\nconst result = await client.projects.delete({\n  project_id: 'project-uuid',\n  confirm: true\n});\n```\n\n### RLHF Operations\n\n#### Collect Interaction\n\n```typescript\nconst result = await client.rlhf.collectInteraction({\n  type: 'click',\n  session_id: 'session-uuid',\n  element_clicked: 'search-button',\n  page_url: '/search'\n});\n```\n\n#### Collect Agent Feedback\n\n```typescript\nconst result = await client.rlhf.collectAgentFeedback({\n  project_id: 'project-uuid',\n  agent_type: 'search-agent',\n  agent_response_id: 'response-uuid',\n  user_rating: 5,\n  feedback_text: 'Very helpful response'\n});\n```\n\n### Admin Operations (Admin Only)\n\n#### System Stats\n\n```typescript\nconst stats = await client.admin.getSystemStats();\n```\n\n#### System Health\n\n```typescript\nconst health = await client.admin.getSystemHealth();\n```\n\n## Error Handling\n\nThe client provides custom error classes for different error scenarios:\n\n```typescript\nimport {\n  ZeroDBError,\n  AuthenticationError,\n  AuthorizationError,\n  RateLimitError,\n  ValidationError,\n  NotFoundError,\n  NetworkError,\n  TimeoutError\n} from '@zerodb/mcp-client';\n\ntry {\n  await client.vectors.search({\n    project_id: 'invalid-uuid',\n    query_vector: embedding,\n    limit: 10\n  });\n} catch (error) {\n  if (error instanceof ValidationError) {\n    console.error('Validation failed:', error.message);\n    console.error('Field errors:', error.errors);\n  } else if (error instanceof AuthenticationError) {\n    console.error('Authentication failed:', error.message);\n  } else if (error instanceof RateLimitError) {\n    console.error('Rate limited. Retry after:', error.retryAfter);\n  } else if (error instanceof NotFoundError) {\n    console.error('Resource not found:', error.message);\n  } else {\n    console.error('Unexpected error:', error);\n  }\n}\n```\n\n## Framework Integration\n\n### React / Next.js\n\n```typescript\nimport { ZeroDBClient } from '@zerodb/mcp-client';\nimport { useState, useEffect } from 'react';\n\nfunction SearchComponent() {\n  const [results, setResults] = useState([]);\n  const client = new ZeroDBClient({ apiKey: process.env.ZERODB_API_KEY });\n\n  const search = async (query: string) => {\n    const embedding = await getEmbedding(query); // Your embedding function\n\n    const results = await client.vectors.search({\n      project_id: process.env.ZERODB_PROJECT_ID,\n      query_vector: embedding,\n      limit: 10\n    });\n\n    setResults(results.vectors);\n  };\n\n  return (\n    <div>\n      <input onChange={(e) => search(e.target.value)} />\n      {results.map(result => (\n        <div key={result.vector_id}>{result.document}</div>\n      ))}\n    </div>\n  );\n}\n```\n\n### Node.js Backend\n\n```typescript\nimport express from 'express';\nimport { ZeroDBClient } from '@zerodb/mcp-client';\n\nconst app = express();\nconst client = new ZeroDBClient({\n  apiKey: process.env.ZERODB_API_KEY\n});\n\napp.post('/api/search', async (req, res) => {\n  try {\n    const { query, projectId } = req.body;\n\n    const results = await client.vectors.search({\n      project_id: projectId,\n      query_vector: query,\n      limit: 10\n    });\n\n    res.json(results);\n  } catch (error) {\n    if (error instanceof RateLimitError) {\n      res.status(429).json({ error: 'Rate limit exceeded' });\n    } else {\n      res.status(500).json({ error: error.message });\n    }\n  }\n});\n\napp.listen(3000);\n```\n\n## Best Practices\n\n### 1. Reuse Client Instances\n\nCreate a single client instance and reuse it across your application:\n\n```typescript\n// lib/zerodb.ts\nimport { ZeroDBClient } from '@zerodb/mcp-client';\n\nexport const zerodbClient = new ZeroDBClient({\n  apiKey: process.env.ZERODB_API_KEY\n});\n```\n\n### 2. Handle Rate Limits\n\n```typescript\nasync function searchWithRetry(query: any, maxRetries = 3) {\n  for (let i = 0; i < maxRetries; i++) {\n    try {\n      return await client.vectors.search(query);\n    } catch (error) {\n      if (error instanceof RateLimitError && i < maxRetries - 1) {\n        await new Promise(resolve => setTimeout(resolve, error.retryAfter * 1000));\n        continue;\n      }\n      throw error;\n    }\n  }\n}\n```\n\n### 3. Validate Embeddings\n\n```typescript\nimport { validateEmbedding } from '@zerodb/mcp-client';\n\ntry {\n  validateEmbedding(myEmbedding, 1536);\n} catch (error) {\n  console.error('Invalid embedding:', error.message);\n}\n```\n\n### 4. Use TypeScript\n\nTake advantage of full type safety:\n\n```typescript\nimport { VectorSearchRequest, VectorSearchResult } from '@zerodb/mcp-client';\n\nasync function typedSearch(\n  request: VectorSearchRequest\n): Promise<VectorSearchResult> {\n  return client.vectors.search(request);\n}\n```\n\n## Testing\n\n```bash\nnpm test\n```\n\n## Examples\n\nSee the `examples/` directory for comprehensive usage examples:\n\n- `vectors-example.ts` - Vector operations\n- `tables-example.ts` - Table/NoSQL operations\n- `files-example.ts` - File storage operations\n\n## License\n\nMIT\n\n## Support\n\n- Documentation: https://docs.ainative.studio\n- Issues: https://github.com/ainative-studio/zerodb-mcp-client/issues\n- Email: support@ainative.studio\n\n## Contributing\n\nContributions are welcome! Please read our contributing guidelines before submitting PRs.\n","readmeFilename":"README.md","_rev":"1-02a6031163a0934f1d176d41a8359232"}