hyperspell-mcp

Instructions

Implementation Reference

• src/hyperspell_mcp/server.py:99-103 (handler)

  The handler function for the 'List Collections' tool, which fetches and returns the list of collections from the Hyperspell API using the Collection model.

  @mcp.tool_or_resource("collection://", name="List Collections")
  def list_collections() -> list[Collection]:
      """Get a list of all collections on Hyperspell"""
      r = mcp.api.collections.list()
      return Collection.from_pydantic(r.items)

• src/hyperspell_mcp/types.py:31-35 (schema)

  The Collection dataclass schema used for the output of the 'List Collections' tool, with from_pydantic conversion.

  @dataclass
  class Collection(BaseModel):
      name: str
      documents_count: int = 0

• src/hyperspell_mcp/server.py:99-99 (registration)

  Decorator registering the tool with name 'List Collections' and URI 'collection://', which conditionally adds it as tool or resource.

  @mcp.tool_or_resource("collection://", name="List Collections")

• src/hyperspell_mcp/types.py:17-29 (helper)

  The from_pydantic classmethod used by Collection to convert API responses to the dataclass format.

  @classmethod
  def from_pydantic(
      cls, model: PydanticBaseModel | Sequence[PydanticBaseModel]
  ) -> Self | list[Self]:
      """Convert a Pydantic model to a data class, selecting only the keys that are part of the data class."""
      if isinstance(model, Sequence):
          return [cls.from_pydantic(m) for m in model]
  
      data = model.model_dump()
      # Only select the keys in data that are part of this data class
      data = {key: value for key, value in data.items() if key in cls.__annotations__}
      return cls(**data)