{"id":49273920,"url":"https://github.com/zvec-ai/zvec-mcp-server","last_synced_at":"2026-04-25T15:05:24.574Z","repository":{"id":350137916,"uuid":"1171656433","full_name":"zvec-ai/zvec-mcp-server","owner":"zvec-ai","description":"Zvec Official MCP Server","archived":false,"fork":false,"pushed_at":"2026-04-09T02:20:21.000Z","size":37,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T04:17:21.673Z","etag":null,"topics":["ai","mcp-server","vector-search"],"latest_commit_sha":null,"homepage":"https://zvec.org/en/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zvec-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-03T13:20:13.000Z","updated_at":"2026-04-09T02:19:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zvec-ai/zvec-mcp-server","commit_stats":null,"previous_names":["zvec-ai/zvec-mcp-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zvec-ai/zvec-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zvec-ai","download_url":"https://codeload.github.com/zvec-ai/zvec-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32266023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","mcp-server","vector-search"],"created_at":"2026-04-25T15:04:53.963Z","updated_at":"2026-04-25T15:05:24.559Z","avatar_url":"https://github.com/zvec-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zvec MCP Server\n\nA Model Context Protocol (MCP) server for [Zvec](https://github.com/alibaba/zvec), a high-performance embedded vector database by Alibaba.\n\n## Overview\n\nThis MCP server enables LLMs to interact with Zvec vector database through well-designed tools. It provides comprehensive functionality for:\n\n- **Collection Management**: Create, open, and manage vector database collections\n- **Document Operations**: Insert, update, delete, and fetch documents with full CRUD support\n- **Vector Search**: Single-vector and multi-vector similarity search with re-ranking\n- **Index Management**: Create and manage vector indexes (HNSW, IVF, FLAT) for fast retrieval\n- **AI Embedding**: OpenAI-powered dense embedding with automatic text-to-vector conversion\n\n## Features\n\n- 🚀 **17 Comprehensive Tools**: Full API coverage for common vector database operations\n- 🤖 **AI-Powered Embedding**: Built-in OpenAI embedding for semantic search\n- 📊 **Multiple Response Formats**: Support both JSON and Markdown output formats\n- 🔍 **Multi-Vector Search**: Combine multiple embeddings with advanced re-ranking\n- 🎯 **Hybrid Search**: Combine vector similarity with scalar filters\n- 🛡️ **Type Safety**: Full Pydantic v2 validation for all inputs\n- 📝 **Rich Documentation**: Detailed tool descriptions with examples\n\n## Installation\n\n### Requirements\n\n- Python 3.10 - 3.14\n- Supported platforms: Linux (x86_64, ARM64), macOS (ARM64), Windows (x86_64)\n\n### Install from PyPI\n\n```bash\n# Using uv (recommended)\nuv pip install zvec-mcp-server\n\n# Or using pip\npip install zvec-mcp-server\n```\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/zvec-ai/zvec-mcp-server.git\ncd zvec-mcp-server\n\n# Using uv (recommended)\nuv venv \u0026\u0026 source .venv/bin/activate\nuv pip install -e \".[dev]\"\n\n# Or using pip\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n### Running the Server\n\n```bash\n# Using the installed package\npython -m zvec_mcp\n\n# Or with uv\nuv run python -m zvec_mcp\n\n# Test with MCP Inspector\nnpx @modelcontextprotocol/inspector python -m zvec_mcp\n```\n\n### IDE Integration (Qoder/Cursor/Claude Desktop)\n\nAdd to your IDE's MCP configuration file:\n\n**Qoder MCP Config** (`~/.qoder/mcp.json` or `~/.config/qoder/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"zvec-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"zvec-mcp-server\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"your-api-key\",\n        \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n        \"OPENAI_EMBEDDING_MODEL\": \"text-embedding-3-small\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop Config** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"zvec-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"zvec-mcp-server\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n**Environment Variables:**\n\n- `OPENAI_API_KEY` (required): OpenAI API key for embedding generation\n- `OPENAI_BASE_URL` (optional): Custom API endpoint (e.g., for DashScope)\n- `OPENAI_EMBEDDING_MODEL` (optional): Model name, default is `text-embedding-3-small`\n\n### Basic Usage Example\n\n```python\n# 1. Create and open a collection\ncreate_and_open_collection({\n    \"path\": \"./my_vectors\",\n    \"collection_name\": \"docs_col\",\n    \"vector_fields\": [\n        {\n            \"name\": \"embedding\",\n            \"data_type\": \"VECTOR_FP32\",\n            \"dimension\": 1536\n        }\n    ],\n    \"scalar_fields\": [\n        {\n            \"name\": \"title\",\n            \"data_type\": \"STRING\",\n            \"nullable\": False\n        }\n    ]\n})\n\n# 2. Insert documents with auto-generated embeddings (requires OPENAI_API_KEY)\nembedding_write({\n    \"collection_name\": \"docs_col\",\n    \"field_name\": \"embedding\",\n    \"documents\": [\n        {\n            \"id\": \"doc1\",\n            \"text\": \"This is a sample document about machine learning.\",\n            \"fields\": {\"title\": \"ML Introduction\"}\n        }\n    ]\n})\n\n# 3. Semantic search with natural language query\nembedding_search({\n    \"collection_name\": \"docs_col\",\n    \"field_name\": \"embedding\",\n    \"query_text\": \"artificial intelligence and neural networks\",\n    \"topk\": 10\n})\n```\n\n## Available Tools\n\n### Collection Management (4 tools)\n- `create_and_open_collection` - Create new collection with schema and auto-create indexes\n- `open_collection` - Open existing collection into session cache\n- `get_collection_info` - Get schema and statistics\n- `destroy_collection` - Permanently delete collection\n\n### Document Operations (5 tools)\n- `insert_documents` - Insert new documents (fail if exists)\n- `upsert_documents` - Insert or update documents\n- `update_documents` - Update existing documents\n- `delete_documents` - Delete documents by ID\n- `fetch_documents` - Retrieve documents by ID\n\n### Vector Search (2 tools)\n- `vector_query` - Single-vector similarity search with optional filtering\n- `multi_vector_query` - Multi-vector search with re-ranking (Weighted/RRF)\n\n### Index Management (3 tools)\n- `create_index` - Create vector index (HNSW/IVF/FLAT) or scalar index (INVERT)\n- `drop_index` - Remove index from field\n- `optimize_collection` - Optimize collection for better performance\n\n### AI Embedding (3 tools)\n- `generate_dense_embedding` - Generate embedding for text using OpenAI API\n- `embedding_write` - Auto-embed text documents and upsert to collection\n- `embedding_search` - Natural language semantic search with auto-embedding\n\n## Tool Details\n\n### Vector Data Types\n- `VECTOR_FP32`, `VECTOR_FP64`, `VECTOR_FP16` - Dense float vectors\n- `VECTOR_INT8` - Dense integer vectors\n- `SPARSE_VECTOR_FP32`, `SPARSE_VECTOR_FP16` - Sparse vectors (Dict[int, float])\n\n### Scalar Data Types\n- `INT32`, `INT64`, `UINT32`, `UINT64` - Integer types\n- `FLOAT`, `DOUBLE` - Floating point types\n- `STRING`, `BOOL` - Text and boolean\n\n### Index Types\n\n**Vector Indexes:**\n- `HNSW` - Hierarchical Navigable Small World (recommended for most cases)\n- `IVF` - Inverted File Index (good for large datasets)\n- `FLAT` - Brute-force exact search (small datasets)\n\n**Scalar Indexes:**\n- `INVERT` - Inverted index for scalar fields with optional range optimization\n\n### Distance Metrics\n- `COSINE` - Cosine similarity\n- `IP` - Inner product\n- `L2` - Euclidean distance\n\n### Re-ranking Strategies (Multi-Vector Query)\n- `WEIGHTED` - Weighted score fusion with custom weights per field\n- `RRF` - Reciprocal Rank Fusion (rank-based fusion)\n\n## Architecture\n\n### Modular Structure\n\n```\nzvec-mcp-server/\n├── src/\n│   └── zvec_mcp/\n│       ├── __init__.py       # Package entry point\n│       ├── server.py         # MCP server implementation (17 tools)\n│       ├── schemas.py        # Pydantic input validation models\n│       ├── types.py          # Enums and type definitions\n│       └── utils.py          # Helper functions and formatters\n├── tests/\n│   └── test_server.py        # Pytest test suite\n├── pyproject.toml            # Project configuration\n├── README.md                 # This file\n├── CONTRIBUTING.md           # Contribution guidelines\n└── LICENSE                   # Apache 2.0 License\n```\n\n### MCP Resources\nThe server exposes two MCP resources for introspection:\n- `zvec://collections` - List all opened collections in the current session\n- `zvec://collection/{collection_name}` - Get detailed schema and stats for a specific collection\n\n### Error Handling\nAll tools provide clear, actionable error messages:\n- Resource not found errors with suggestions\n- Validation errors from Pydantic v2\n- Zvec API errors with context\n\n### Response Formats\nTools support two output formats:\n- **JSON**: Structured data for programmatic processing\n- **Markdown**: Human-readable formatted text with headers and lists\n\n## Development\n\n### Running Tests\n\nThe project includes a comprehensive pytest test suite with 21 test cases covering all functionality.\n\n```bash\n# Install dev dependencies (includes pytest and pytest-asyncio)\nuv pip install -e \".[dev]\"\n\n# Run all tests\npytest tests/test_server.py -v\n```\n## References\n\n- [Zvec GitHub](https://github.com/alibaba/zvec)\n- [Zvec Documentation](https://zvec.org/)\n- [MCP Specification](https://modelcontextprotocol.io/)\n- [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk)\n\n## License\n\n[Apache 2.0](LICENSE)\n\n## Contributing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.\n\nPlease note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzvec-ai%2Fzvec-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzvec-ai%2Fzvec-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzvec-ai%2Fzvec-mcp-server/lists"}