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