Typesense MCP Server

Instructions

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.

Implementation Reference

• main.py:574-611 (handler)

  Handler function for the 'create_document' tool. It creates a new document in a Typesense collection using the provided client from the context. Includes error handling for common Typesense exceptions.

  @mcp.tool()
  async def create_document(ctx: Context, collection_name: str, document: dict) -> dict | str:
      """
      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.
      """
      if not collection_name:
          return "Error: collection_name parameter is required."
      if not isinstance(document, dict):
          return "Error: document parameter must be a dictionary."
      # Consider adding check for 'id' field if not using auto-id generation
  
      try:
          print(f"Creating document in collection '{collection_name}' with ID: {document.get('id', 'N/A')}")
          client: typesense.Client = ctx.request_context.lifespan_context.client
          # NOTE: Assuming create is *sync* based on observed pattern
          created_doc = client.collections[collection_name].documents.create(document)
          return created_doc
      except typesense.exceptions.ObjectNotFound:
          return f"Error: Collection '{collection_name}' not found."
      except typesense.exceptions.ObjectAlreadyExists as e:
           # Occurs if document ID already exists
           return f"Error: Document with ID '{document.get('id', 'N/A')}' already exists in collection '{collection_name}'. Use upsert to update. Details: {e}"
      except typesense.exceptions.RequestMalformed as e:
           return f"Error: Malformed create document request for collection '{collection_name}'. Check document structure against schema. Details: {e}"
      except typesense.exceptions.TypesenseClientError as e:
          print(f"Error creating document in '{collection_name}': {e}")
          return f"Error creating document in '{collection_name}': {e}"
      except Exception as e:
          print(f"An unexpected error occurred while creating document in '{collection_name}': {e}")
          return f"An unexpected error occurred: {e}"

• main.py:574-574 (registration)

  The @mcp.tool() decorator registers the create_document function as an MCP tool.

  @mcp.tool()