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.

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.

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.

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.

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.

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.

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.

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': {...}}.

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.

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.

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.

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.

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.