Schema & Collection Management

Relevant source files

The following files were used as context for generating this wiki page:

• packages/weaviate-mcp/src/weaviate_mcp/tools/schema_tools.py
• packages/weaviate-mcp/src/weaviate_mcp/tools/collection_tools.py
• packages/weaviate-mcp/src/weaviate_mcp/tools/data_tools.py
• packages/weaviate-mcp/README.md
• tests/weaviate-mcp/integration/test_mcp_tools_integration.py
• tests/weaviate-mcp/unit/tools/test_collection_tools.py

The Schema & Collection Management system within weaviate-mcp provides a robust set of tools for defining, validating, and inspecting the structure of a Weaviate vector database. It enables AI models to dynamically create collections, manage property definitions, and retrieve detailed statistical information about the database state. This module acts as a bridge between high-level Model Context Protocol (MCP) requests and the underlying Weaviate client operations, ensuring that database schemas are consistent and accessible to AI assistants.

The system is designed to handle complex vector database tasks such as configuring vectorizers (e.g., OpenAI text-to-vector models), validating collection existence before data operations, and comparing schemas between different collections. By exposing these capabilities as standardized MCP tools, the project allows for "AI-Ready" integration where models can naturally interact with vector storage without direct credential exposure.

Sources: packages/weaviate-mcp/README.md:41-52, packages/weaviate-mcp/src/weaviate_mcp/tools/schema_tools.py:1-10

Core Architecture & Components

The architecture relies on the WeaviateService to communicate with the Weaviate gRPC and HTTP endpoints. Tools are registered using the @mcp.tool decorator, which allows the MCP server to expose them to external clients.

Component Interaction Flow

The following diagram illustrates how a schema request flows from the MCP Tool through the service layer to Weaviate.

Collection Lifecycle Management

Collection management encompasses the creation, deletion, and retrieval of collection definitions. The primary tool, weaviate_create_collection, supports advanced configurations including vectorizer types and generative AI modules.

Key Tools & Functions

Tool Name	Purpose	Key Parameters
weaviate_create_collection	Creates a new collection with custom schema.	name, description, properties, vectorizer_config
weaviate_delete_collection	Removes a collection and all its data.	collection_name
weaviate_get_schema	Retrieves the full database schema.	N/A

Vectorizer Configuration

When creating collections, users can specify vectorizer configurations. A common pattern involves using text2vec_openai with specific models like text-embedding-3-small. The system also handles internal logic for index_searchable defaults based on data types (e.g., True for text, False for numeric/boolean).

Sources: packages/weaviate-mcp/README.md:148-175, tests/weaviate-mcp/unit/tools/test_collection_tools.py:180-210

Schema Inspection & Validation

Schema tools allow for granular inspection of existing collections. This is critical for AI models to understand available "context" before performing searches or insertions.

Validation Workflow

Before an AI assistant attempts to insert data, it often uses weaviate_validate_collection_exists to verify the target structure.

Database Statistics & Comparisons

The system provides tools for high-level oversight and migration planning:

• weaviate_get_database_stats: Aggregates object counts across all collections to provide a database-wide summary.
• weaviate_compare_collections: Identifies property differences (missing fields, type mismatches, or indexing changes) between two collections.

Sources: packages/weaviate-mcp/src/weaviate_mcp/tools/schema_tools.py:202-280, packages/weaviate-mcp/src/weaviate_mcp/tools/schema_tools.py:283-325

Property Data Models

Properties define the fields within a collection. The management tools support various Weaviate data types and indexing options.

Supported Property Attributes

Attribute	Type	Description
name	String	The unique identifier for the property.
data_type	String	Supported types: text, int, number, boolean, text_array.
index_filterable	Boolean	Whether the property can be used in filters.
index_searchable	Boolean	Whether the property is included in keyword/vector search.

Sources: packages/weaviate-mcp/src/weaviate_mcp/tools/schema_tools.py:151-175, tests/weaviate-mcp/unit/tools/test_collection_tools.py:220-250

Implementation Example: Schema Retrieval

The tool weaviate_get_schema_info builds a human-readable summary of the schema by iterating through collections and their properties.

# From packages/weaviate-mcp/src/weaviate_mcp/tools/schema_tools.py
for collection_name, collection_info in schema_result.items():
    count_result = await service.aggregate(collection_name)
    count = count_result["results"].get("total_count", 0)
    
    schema_info.extend([
        f"Collection: {collection_name}",
        f"  Object Count: {count}",
        "  Properties:",
    ])
    # ... iterates through properties to append type and description

Sources: packages/weaviate-mcp/src/weaviate_mcp/tools/schema_tools.py:44-58

Summary of Management Significance

Schema and Collection Management is the foundational layer of the weaviate-mcp integration. By providing automated validation, detailed statistical reporting, and dynamic creation tools, it ensures that AI models can operate autonomously within a vector database environment while maintaining structural integrity. It handles the nuances of Weaviate's gRPC-based schema management, abstracting them into simple, callable functions for the Model Context Protocol.

Sources: packages/weaviate-mcp/README.md:120-135, tests/weaviate-mcp/integration/test_mcp_tools_integration.py:210-230