chroma_add_documents

Instructions

Args:
    collection_name: Name of the collection to add documents to
    documents: List of text documents to add
    ids: List of IDs for the documents (required)
    metadatas: Optional list of metadata dictionaries for each document

Implementation Reference

• src/chroma_mcp/server.py:332-393 (handler)

  The chroma_add_documents tool handler. Decorated with @mcp.tool() for automatic registration in FastMCP. Implements document addition to ChromaDB collection with validation for empty inputs, ID uniqueness, and length matching. Uses get_chroma_client() helper and performs add operation.

  @mcp.tool()
  async def chroma_add_documents(
      collection_name: str,
      documents: List[str],
      ids: List[str],
      metadatas: List[Dict] | None = None
  ) -> str:
      """Add documents to a Chroma collection.
      
      Args:
          collection_name: Name of the collection to add documents to
          documents: List of text documents to add
          ids: List of IDs for the documents (required)
          metadatas: Optional list of metadata dictionaries for each document
      """
      if not documents:
          raise ValueError("The 'documents' list cannot be empty.")
      
      if not ids:
          raise ValueError("The 'ids' list is required and cannot be empty.")
      
      # Check if there are empty strings in the ids list
      if any(not id.strip() for id in ids):
          raise ValueError("IDs cannot be empty strings.")
      
      if len(ids) != len(documents):
          raise ValueError(f"Number of ids ({len(ids)}) must match number of documents ({len(documents)}).")
  
      client = get_chroma_client()
      try:
          collection = client.get_or_create_collection(collection_name)
          
          # Check for duplicate IDs
          existing_ids = collection.get(include=[])["ids"]
          duplicate_ids = [id for id in ids if id in existing_ids]
          
          if duplicate_ids:
              raise ValueError(
                  f"The following IDs already exist in collection '{collection_name}': {duplicate_ids}. "
                  f"Use 'chroma_update_documents' to update existing documents."
              )
          
          result = collection.add(
              documents=documents,
              metadatas=metadatas,
              ids=ids
          )
          
          # Check the return value
          if result and isinstance(result, dict):
              # If the return value is a dictionary, it may contain success information
              if 'success' in result and not result['success']:
                  raise Exception(f"Failed to add documents: {result.get('error', 'Unknown error')}")
              
              # If the return value contains the actual number added
              if 'count' in result:
                  return f"Successfully added {result['count']} documents to collection {collection_name}"
          
          # Default return
          return f"Successfully added {len(documents)} documents to collection {collection_name}, result is {result}"
      except Exception as e:
          raise Exception(f"Failed to add documents to collection '{collection_name}': {str(e)}") from e

• src/chroma_mcp/server.py:332-332 (registration)

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

  @mcp.tool()

• src/chroma_mcp/server.py:333-338 (schema)

  Input schema defined by function type hints: collection_name (str), documents (List[str]), ids (List[str]), metadatas (optional List[Dict]). Returns str confirmation.

  async def chroma_add_documents(
      collection_name: str,
      documents: List[str],
      ids: List[str],
      metadatas: List[Dict] | None = None
  ) -> str: