protocols-io-mcp-server

Instructions

Implementation Reference

• src/protocols_io_mcp/tools/protocol.py:190-202 (handler)

  The handler function for the 'get_protocol' MCP tool, decorated with @mcp.tool() for registration. It retrieves basic protocol information by ID from the protocols.io API.

  @mcp.tool()
  async def get_protocol(
      protocol_id: Annotated[int, Field(description="Unique identifier for the protocol")]
  ) -> Protocol | ErrorMessage:
      """
      Retrieve basic information for a specific protocol by its protocol ID. To get detailed protocol steps, use get_protocol_steps.
      """
      response = await helpers.access_protocols_io_resource("GET", f"/v4/protocols/{protocol_id}")
      if response["status_code"] != 0:
          return ErrorMessage.from_string(response["status_text"])
      protocol = await Protocol.from_protocol_id(response["payload"]["id"])
      return protocol

• src/protocols_io_mcp/tools/protocol.py:111-133 (schema)

  Pydantic model defining the structure of the Protocol returned by get_protocol, including a helper classmethod to instantiate from API response.

  class Protocol(BaseModel):
      id: Annotated[int, Field(description="Unique identifier for the protocol")]
      title: Annotated[str, Field(description="Title of the protocol")]
      description: Annotated[str, Field(description="Description of the protocol")]
      doi: Annotated[str | None, Field(description="DOI of the protocol, if the protocol is private, this will be null")] = None
      url: Annotated[str, Field(description="URL link to the protocol on protocols.io ")]
      created_on: Annotated[datetime, Field(description="Date and time the protocol was created")]
      published_on: Annotated[datetime | None, Field(description="Date and time the protocol was published, if the protocol is private, this will be null")] = None
  
      @classmethod
      async def from_protocol_id(cls, protocol_id: int) -> "Protocol":
          response = await helpers.access_protocols_io_resource("GET", f"/v4/protocols/{protocol_id}?content_format=markdown")
          protocol = response["payload"]
          return cls(
              id=protocol_id,
              title=protocol["title"],
              description=protocol.get("description") or "",
              doi=protocol.get("doi") or None,
              url=protocol.get("url"),
              created_on=datetime.fromtimestamp(protocol.get("created_on"), tz=timezone.utc),
              published_on=datetime.fromtimestamp(protocol.get("published_on"), tz=timezone.utc) if protocol.get("published_on") else None
          )

• src/protocols_io_mcp/tools/protocol.py:148-154 (schema)

  Pydantic model for error responses returned by get_protocol.

  class ErrorMessage(BaseModel):
      error_message: Annotated[str, Field(description="Error message describing the issue encountered")]
  
      @classmethod
      def from_string(cls, message: str) -> "ErrorMessage":
          return cls(error_message=message)

• src/protocols_io_mcp/tools/protocol.py:6-6 (helper)

  Import of helpers module used for API access in get_protocol.

  import protocols_io_mcp.utils.helpers as helpers