search
Search within a specific collection using keywords, filter, sort, group, or facet results to refine queries. Retrieve documents based on defined criteria and paginate results for efficient data access in Typesense databases.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection_name | Yes | ||
| facet_by | No | ||
| filter_by | No | ||
| group_by | No | ||
| page | No | ||
| per_page | No | ||
| query | Yes | ||
| query_by | Yes | ||
| sort_by | No |
Input Schema (JSON Schema)
{
"properties": {
"collection_name": {
"title": "Collection Name",
"type": "string"
},
"facet_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Facet By"
},
"filter_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Filter By"
},
"group_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Group By"
},
"page": {
"default": 1,
"title": "Page",
"type": "integer"
},
"per_page": {
"default": 20,
"title": "Per Page",
"type": "integer"
},
"query": {
"title": "Query",
"type": "string"
},
"query_by": {
"title": "Query By",
"type": "string"
},
"sort_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Sort By"
}
},
"required": [
"collection_name",
"query",
"query_by"
],
"title": "searchArguments",
"type": "object"
}
Implementation Reference
- main.py:214-281 (handler)The handler function for the MCP tool named 'search'. Decorated with @mcp.tool(), it performs keyword search on a Typesense collection using the provided parameters and returns search results or error messages.@mcp.tool() async def search( ctx: Context, collection_name: str, query: str, query_by: str, filter_by: str | None = None, sort_by: str | None = None, group_by: str | None = None, # Added group_by facet_by: str | None = None, # Added facet_by per_page: int = 20, page: int = 1 # Added page ) -> dict | str: """ 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. """ if not collection_name: return "Error: collection_name parameter is required." if not query: return "Error: query parameter is required." if not query_by: return "Error: query_by parameter is required." search_params = { 'q': query, 'query_by': query_by, 'per_page': per_page, 'page': page, } if filter_by: search_params['filter_by'] = filter_by if sort_by: search_params['sort_by'] = sort_by if group_by: search_params['group_by'] = group_by if facet_by: search_params['facet_by'] = facet_by try: client: typesense.Client = ctx.request_context.lifespan_context.client search_results = client.collections[collection_name].documents.search(search_params) return search_results except typesense.exceptions.ObjectNotFound: return f"Error: Collection '{collection_name}' not found." except typesense.exceptions.RequestMalformed as e: return f"Error: Malformed search request for collection '{collection_name}'. Check parameters (query_by fields existence, filter/sort syntax, etc.). Details: {e}" except typesense.exceptions.TypesenseClientError as e: print(f"Error searching collection '{collection_name}': {e}") return f"Error searching collection '{collection_name}': {e}" except Exception as e: print(f"An unexpected error occurred while searching collection '{collection_name}': {e}") return f"An unexpected error occurred: {e}"
- main.py:214-214 (registration)The @mcp.tool() decorator registers the 'search' function as an MCP tool.@mcp.tool()