hyperspell-mcp

Instructions

Implementation Reference

• src/hyperspell_mcp/server.py:113-120 (handler)

  Handler function that implements the 'Get Document' tool by calling the Hyperspell API to fetch a document by its ID and converting it to a Document object.

  @mcp.tool_or_resource("document://{document_id}", name="Get Document")
  def get_document(document_id: int) -> Document | Error:
      """Get a document from a collection"""
      # try:
      r = mcp.api.documents.get(document_id=document_id)
      return Document.from_pydantic(r)
      # except APIError as e:
      # return Error(error=e.__class__.__name__, message=e.message)

• src/hyperspell_mcp/types.py:37-43 (schema)

  Dataclass schema defining the structure of a Document returned by the tool.

  @dataclass
  class Document(BaseModel):
      id: int
      title: str
      type: str
      summary: str

• src/hyperspell_mcp/types.py:52-56 (schema)

  Dataclass schema defining the structure of an Error that may be returned by the tool.

  @dataclass
  class Error(BaseModel):
      error: str
      message: str

• src/hyperspell_mcp/server.py:71-85 (helper)

  Custom decorator that registers the tool function either as a tool or resource based on config, handling the registration for 'Get Document'.

  def tool_or_resource(self, uri: str, name: str | None = None):
      def decorator(fn: Callable):
          description = fn.__doc__
          if self.config.use_resources:
              self.resource(
                  uri,
                  name=name,
                  description=description,
                  mime_type="application/json",
              )(fn)
          if self.config.use_tools:
              self.add_tool(fn, name=name, description=description)
          return fn
  
      return decorator