protocols-io-mcp-server

Instructions

Implementation Reference

• src/protocols_io_mcp/tools/protocol.py:216-238 (handler)

  The primary handler function for the 'create_protocol' tool, decorated with @mcp.tool() for automatic registration. It creates a blank protocol, updates title and description via API calls, and returns the resulting Protocol or an ErrorMessage.

  @mcp.tool()
  async def create_protocol(
      title: Annotated[str, Field(description="Title of the new protocol (plain text only)")],
      description: Annotated[str, Field(description="Description of the new protocol (plain text only)")],
  ) -> Protocol | ErrorMessage:
      """
      Create a new protocol with the given title and description.
  
      Before creating a new protocol, ensure you have searched for at least 2 relevant public protocols using search_public_protocols and reviewed their detailed steps with get_protocol_steps for reference when adding steps.
      """
      response_create_blank_protocol = await helpers.access_protocols_io_resource("POST", f"/v3/protocols/{uuid.uuid4().hex}", {"type_id": 1})
      if response_create_blank_protocol["status_code"] != 0:
          return ErrorMessage.from_string(response_create_blank_protocol["error_message"])
      protocol = await Protocol.from_protocol_id(response_create_blank_protocol["protocol"]["id"])
      data = {"title": title, "description": description}
      response_update_protocol = await helpers.access_protocols_io_resource("PUT", f"/v4/protocols/{protocol.id}", data)
      if response_update_protocol["status_code"] != 0:
          return ErrorMessage.from_string(response_update_protocol["status_text"])
      response_get_protocol = await helpers.access_protocols_io_resource("GET", f"/v4/protocols/{protocol.id}")
      if response_get_protocol["status_code"] != 0:
          return ErrorMessage.from_string(response_get_protocol["status_text"])
      protocol = await Protocol.from_protocol_id(response_get_protocol["payload"]["id"])
      return protocol

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

  Pydantic schema for Protocol output type used by create_protocol.

  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-153 (schema)

  Pydantic schema for ErrorMessage output type used by create_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/utils/helpers.py:10-17 (helper)

  Key helper utility for making authenticated API requests to protocols.io, heavily used in the create_protocol handler.

  async def access_protocols_io_resource(method: Literal["GET", "POST", "PUT", "DELETE"], path: str, data: dict = None) -> dict[str, Any]:
      """Access protocols.io API with specified method and path."""
      headers = {
          "Authorization": f"Bearer {PROTOCOLS_IO_CLIENT_ACCESS_TOKEN}"
      }
      async with httpx.AsyncClient(timeout=30.0) as client:
          response = await client.request(method, f"{PROTOCOLS_IO_API_URL}{path}", json=data, headers=headers)
          return response.json()

• src/protocols_io_mcp/server.py:10-10 (registration)

  The import statement that loads the tools module, triggering registration of all @mcp.tool()-decorated functions including create_protocol.

  importlib.import_module('protocols_io_mcp.tools')