Typesense MCP Server

Checks the health status of the configured Typesense server. Args: ctx (Context): The MCP context, providing access to application resources. Returns: dict | str: The health status dictionary from Typesense or an error message.

Retrieves a list of all collections in the Typesense server. Args: ctx (Context): The MCP context. Returns: list | str: A list of collection schemas or an error message string.

Retrieves the schema and metadata for a specific collection. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection to describe. Returns: dict | str: The collection schema dictionary or an error message string.

Exports all documents from a specific collection. Warning: This can be memory-intensive for very large collections. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection to export. Returns: list[dict] | str: A list of document dictionaries or an error message string.

Performs a keyword search on a specific collection. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection to search within. query (str): The search query string. Use '*' for all documents. query_by (str): Comma-separated list of fields to search in. filter_by (str | None): Filter conditions (e.g., 'price:>100 && category:Electronics'). Defaults to None. sort_by (str | None): Sorting criteria (e.g., 'price:asc, rating:desc'). Defaults to None. group_by (str | None): Field to group results by. Defaults to None. facet_by (str | None): Fields to facet on. Defaults to None. per_page (int): Number of results per page. Defaults to 20. page (int): Page number to retrieve. Defaults to 1. Returns: dict | str: The search results dictionary from Typesense or an error message string.

Performs a vector similarity search on a specific collection. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection to search within. vector_query (str): The vector query string, formatted as 'vector_field:([v1,v2,...], k: num_neighbors)'. query_by (str | None): Optional: Comma-separated list of text fields for hybrid search query ('q' parameter). Defaults to None. filter_by (str | None): Filter conditions to apply before vector search. Defaults to None. sort_by (str | None): Optional sorting criteria (less common for pure vector search). Defaults to None. per_page (int): Number of results per page. Defaults to 10. page (int): Page number to retrieve. Defaults to 1. Returns: dict | str: The vector search results dictionary from Typesense or an error message string.

Creates a new collection with the provided schema. Args: ctx (Context): The MCP context. schema (dict): The collection schema dictionary (must include 'name' and 'fields'). Returns: dict | str: The created collection schema dictionary or an error message string.

Deletes a specific collection. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection to delete. Returns: dict | str: The deleted collection schema dictionary or an error message string.

Truncates a collection by deleting all documents but keeping the schema. Achieved by retrieving schema, deleting collection, and recreating it. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection to truncate. Returns: str: A success or error message string.

Creates a single new document in a specific collection. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection. document (dict): The document data to create (must include an 'id' field unless auto-schema). Returns: dict | str: The created document dictionary or an error message string.

Upserts (creates or updates) a single document in a specific collection. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection. document (dict): The document data to upsert (must include an 'id' field). Returns: dict | str: The upserted document dictionary or an error message string.

Indexes (creates, upserts, or updates) multiple documents in a batch. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection. documents (list[dict]): A list of document dictionaries to index. action (str): The import action ('create', 'upsert', 'update'). Defaults to 'upsert'. Returns: list[dict] | str: A list of result dictionaries (one per document) or an error message string. Each result dict typically looks like {'success': true/false, 'error': '...', 'document': {...}}.

Deletes a single document by its ID from a specific collection. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection. document_id (str): The ID of the document to delete. Returns: dict | str: The deleted document dictionary or an error message string.

Imports documents from CSV data (as a string) or a file path into a collection. Assumes CSV header row maps directly to Typesense field names. Does basic type inference for int/float, otherwise treats as string. Args: ctx (Context): The MCP context. collection_name (str): The name of the collection. csv_data_or_path (str): Either the raw CSV data as a string or the path to a CSV file. batch_size (int): Number of documents to import per batch. Defaults to 100. action (str): Import action ('create', 'upsert', 'update'). Defaults to 'upsert'. Returns: dict: A summary of the import process including total processed, successful, failed count, and any errors.