AINative ZeroDB MCP Server

# ZeroDB MCP Server v2.0.0 - Enterprise Production Release **Release Date**: October 14, 2025 **Status**: Production Ready **Breaking Changes**: Yes (see migration guide) --- ## What's New in v2.0.0 Version 2.0.0 is a major release that transforms the ZeroDB MCP Server into a production-ready, enterprise-grade integration for AI agents, assistants, and frameworks. ### Key Highlights - **6 Production-Ready Operations** - Essential toolkit for vector search and persistent memory - **Automatic Token Management** - Zero authentication failures with background renewal - **Enterprise Security** - Zero HIGH/CRITICAL vulnerabilities, strict validation - **Unified Tool Naming** - `zerodb_` prefix for better namespace isolation - **Vector Validation** - Strict 1536-dimension enforcement (OpenAI ada-002 standard) - **Enhanced Error Handling** - Detailed error messages with structured responses --- ## New Features ### Core Operations (6 Total) 1. **zerodb_store_memory** - Store agent conversations and context - Automatic session/agent ID generation - Rich metadata support - Role-based organization (user/assistant/system) 2. **zerodb_search_memory** - Semantic memory search - Session and agent filtering - Configurable result limits - Timestamp-ordered results 3. **zerodb_get_context** - Retrieve conversation context - Smart token counting (4 chars = 1 token) - Context window management (default 8192 tokens) - Most recent messages first 4. **zerodb_store_vector** - Store 1536D vector embeddings - OpenAI ada-002 compatible - Namespace isolation (default: 'windsurf') - Custom metadata support 5. **zerodb_search_vectors** - Semantic vector search - Configurable similarity thresholds (default: 0.7) - Namespace filtering - Ranked results by similarity score 6. **zerodb_renew_token** - Manual token renewal (NEW) - Debug authentication issues - Force token refresh - View token expiry time ### Enterprise Features #### Automatic Token Management ```javascript // Background renewal every 25 minutes // 5-minute buffer before expiry // Zero authentication failures ``` #### Vector Validation ```javascript // Strict 1536-dimension enforcement // Clear error messages for mismatches // Compatible with OpenAI ada-002 ``` #### Error Handling ```javascript { "content": [{"type": "text", "text": "Detailed error message"}], "isError": true // New structured error flag } ``` #### Configuration Management ```bash # Environment-based configuration ZERODB_API_URL=https://api.ainative.studio/api/v1 ZERODB_PROJECT_ID=your-project-id ZERODB_USERNAME=admin@ainative.studio ZERODB_PASSWORD=your-password MCP_CONTEXT_WINDOW=8192 MCP_RETENTION_DAYS=30 ``` --- ## Breaking Changes ### 1. Tool Naming Convention All tools now use `zerodb_` prefix: | Old Name (v1.0.7) | New Name (v2.0.0) | |-------------------|-------------------| | `store_memory` | `zerodb_store_memory` | | `search_memory` | `zerodb_search_memory` | | `get_context` | `zerodb_get_context` | | `store_vector` | `zerodb_store_vector` | | `search_vectors` | `zerodb_search_vectors` | **Action Required**: Update all tool calls to use new names. ### 2. Vector Dimension Requirement Vectors must be **exactly 1536 dimensions** (OpenAI ada-002 standard). **Before**: Any dimension accepted **After**: Only 1536D accepted **Action Required**: Ensure embeddings are 1536D or use dimension reduction. ### 3. Default Namespace Change Vector namespace changed from `default` to `windsurf`. **Action Required**: Explicitly specify namespace if migrating existing data. ### 4. Error Response Format Errors now include `isError` flag for structured handling. **Action Required**: Update error handling to check `result.isError`. --- ## Installation ### NPM Install ```bash npm install ainative-zerodb-mcp-server@2.0.0 ``` ### Claude Desktop Add to `claude_desktop_config.json`: ```json { "mcpServers": { "zerodb": { "command": "npx", "args": ["-y", "ainative-zerodb-mcp-server@2.0.0"], "env": { "ZERODB_API_URL": "https://api.ainative.studio/api/v1", "ZERODB_PROJECT_ID": "your-project-id", "ZERODB_USERNAME": "admin@ainative.studio", "ZERODB_PASSWORD": "your-password" } } } } ``` ### Windsurf Add to Windsurf MCP configuration: ```json { "zerodb": { "command": "npx", "args": ["-y", "ainative-zerodb-mcp-server@2.0.0"], "env": { "ZERODB_API_URL": "https://api.ainative.studio/api/v1", "ZERODB_PROJECT_ID": "your-project-id", "ZERODB_USERNAME": "admin@ainative.studio", "ZERODB_PASSWORD": "your-password" } } } ``` --- ## Migration Guide **Time Required**: 15-30 minutes ### Quick Migration Steps 1. **Update package version** ```bash npm install ainative-zerodb-mcp-server@2.0.0 ``` 2. **Update tool names** ```javascript // Before await client.callTool('store_memory', {...}); // After await client.callTool('zerodb_store_memory', {...}); ``` 3. **Validate vector dimensions** ```javascript if (embedding.length !== 1536) { throw new Error(`Expected 1536 dimensions, got ${embedding.length}`); } ``` 4. **Update error handling** ```javascript const result = await client.callTool('zerodb_store_memory', params); if (result.isError) { console.error('Error:', result.content[0].text); } ``` 5. **Test thoroughly** ```bash npx ainative-zerodb-mcp-server # Verify: "ZeroDB MCP Server v2.0.0 running on stdio" ``` For detailed migration instructions, see [MIGRATION.md](./MIGRATION.md). --- ## Performance Improvements | Metric | v1.0.7 | v2.0.0 | Improvement | |--------|--------|--------|-------------| | Auth Failures | ~5% | ~0% | 100% reduction | | Error Clarity | Generic | Detailed | Better debugging | | Vector Validation | None | Strict | Data integrity | | Token Management | Manual | Automatic | Zero maintenance | ### Response Time Benchmarks | Operation | p50 | p95 | p99 | |-----------|-----|-----|-----| | store_memory | 50ms | 150ms | 300ms | | search_memory | 100ms | 300ms | 500ms | | store_vector | 75ms | 200ms | 400ms | | search_vectors | 150ms | 400ms | 800ms | | get_context | 100ms | 250ms | 500ms | --- ## Security Enhancements - Zero HIGH/CRITICAL npm vulnerabilities - Automatic token renewal (prevents expired token attacks) - Strict input validation (1536D vector enforcement) - Timeout protection (10s auth, 15s operations) - Error message sanitization (no internal exposure) - Updated dependencies (axios 1.7.7, uuid 11.0.3) --- ## Compatibility | Component | Version | Compatible | |-----------|---------|------------| | MCP Protocol | 1.0.0 | Yes | | Node.js | ≥18.0.0 | Yes | | npm | ≥9.0.0 | Yes | | ZeroDB API | v1 | Yes | | OpenAI ada-002 | 1536D | Yes | | OpenAI text-embedding-3-small | 1536D | Yes | | OpenAI text-embedding-3-large | 3072D → 1536D | Yes (with dimension param) | --- ## What's Next ### v2.1.0 (Planned) - Batch vector operations - Vector deletion and updates - Memory deletion operations - Advanced filtering options ### v3.0.0 (Future) - 54 additional operations (6 → 60 total operations) - Quantum-enhanced vector compression - NoSQL table operations - File storage operations - Event streaming - Project management - RLHF feedback collection - Admin operations See [Enhancement Plan](./docs/ZERODB_MCP_ENHANCEMENT_PLAN.md) for details. --- ## Documentation - **CHANGELOG**: [CHANGELOG.md](./CHANGELOG.md) - Complete version history - **MIGRATION GUIDE**: [MIGRATION.md](./MIGRATION.md) - Step-by-step migration from v1.x - **README**: [README.md](./README.md) - Getting started guide - **ENHANCEMENT PLAN**: [docs/ZERODB_MCP_ENHANCEMENT_PLAN.md](./docs/ZERODB_MCP_ENHANCEMENT_PLAN.md) - Future roadmap --- ## Support & Community ### Getting Help - **GitHub Issues**: https://github.com/AINative-Studio/ainative-zerodb-mcp-server/issues - **Email Support**: support@ainative.studio - **Documentation**: https://github.com/AINative-Studio/ainative-zerodb-mcp-server#readme ### Reporting Issues When reporting issues, please include: 1. ZeroDB MCP Server version (`2.0.0`) 2. Node.js version (`node --version`) 3. Error messages (from stderr logs) 4. Minimal reproduction steps 5. Environment details (OS, Claude/Windsurf version) ### Contributing We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. --- ## Testing ### Automated Tests ```bash # Run test suite npm test # Run with coverage npm run test:ci # Watch mode npm run test:watch ``` ### Manual Testing ```bash # Start server npx ainative-zerodb-mcp-server # Expected output: # ZeroDB MCP Server v2.0.0 running on stdio # API URL: https://api.ainative.studio/api/v1 # Project ID: your-project-id # Token expires: 2025-10-14T23:45:00.000Z ``` --- ## Known Issues None reported for v2.0.0 as of release date. If you discover issues, please report them at: https://github.com/AINative-Studio/ainative-zerodb-mcp-server/issues --- ## Credits ### Contributors - AINative Studio Team - MCP Protocol Community - Early adopters and testers ### Dependencies - @modelcontextprotocol/sdk ^1.0.0 - axios ^1.7.7 - uuid ^11.0.3 ### Special Thanks Thanks to all users who provided feedback during the beta period and helped shape this release. --- ## License MIT License - see [LICENSE](./LICENSE) for details. --- ## Release Checklist - [x] All tests passing (90%+ coverage) - [x] Security audit clean (zero HIGH/CRITICAL) - [x] Documentation updated - [x] CHANGELOG.md created - [x] MIGRATION.md created - [x] package.json version bumped to 2.0.0 - [x] Breaking changes documented - [x] Performance benchmarks verified - [x] Example configurations tested - [x] Backward compatibility analyzed - [x] Rollback procedure documented --- **Download**: `npm install ainative-zerodb-mcp-server@2.0.0` **Feedback**: https://github.com/AINative-Studio/ainative-zerodb-mcp-server/issues **Support**: support@ainative.studio --- **Thank you for using ZeroDB MCP Server!**