Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TYPESENSE_HOST | Yes | The host address of the Typesense server | |
| TYPESENSE_PORT | No | The port of the Typesense server | |
| TYPESENSE_API_KEY | Yes | The API key for authenticating with the Typesense server | |
| TYPESENSE_PROTOCOL | No | The protocol to use (http or https) for the Typesense server |
Schema
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| check_typesense_health | 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. |
| list_collections | 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. |
| describe_collection | 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. |
| export_collection | 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. |
| search | 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. |
| vector_search | 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. |
| create_collection | 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. |
| delete_collection | 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. |
| truncate_collection | 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. |
| create_document | 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. |
| upsert_document | 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. |
| index_multiple_documents | 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': {...}}. |
| delete_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. |
| import_documents_from_csv | 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. |