protocols-io-mcp-server

Instructions

Implementation Reference

• src/protocols_io_mcp/tools/protocol.py:155-173 (handler)

  The core handler function for the 'search_public_protocols' tool. It takes keyword and page parameters, queries the protocols.io API, handles errors, and returns search results or an error message.

  @mcp.tool()
  async def search_public_protocols(
      keyword: Annotated[str, Field(description="Keyword to search for protocols")],
      page: Annotated[int, Field(description="Page number for pagination, starting from 1")] = 1,
  ) -> ProtocolSearchResult | ErrorMessage:
      """
      Search for public protocols on protocols.io using a keyword. Results are sorted by protocol popularity and paginated with 3 protocols per page (use the page parameter to navigate, default is 1).
  
      When searching for reference protocols to create a new protocol:
      - Avoid referencing protocols from before 2015 as they may be outdated.
      - If the found protocols have topics that are not closely related to your needs, ask the user for clearer direction before proceeding.
      - If the found protocols are highly relevant, use get_protocol_steps to examine at least 2 protocols' detailed steps and integrate insights from different approaches to ensure more reliable protocol development.
      """
      page = page - 1 # weird bug in protocols.io API where it returns page 2 if page 1 is requested
      response = await helpers.access_protocols_io_resource("GET", f"/v3/protocols?filter=public&key={keyword}&page_size=3&page_id={page}")
      if response["status_code"] != 0:
          return ErrorMessage.from_string(response["error_message"])
      search_result = await ProtocolSearchResult.from_api_response(response)
      return search_result

• src/protocols_io_mcp/tools/protocol.py:134-147 (schema)

  Pydantic schema for the output of search_public_protocols, defining the structure of search results including protocols list and pagination info.

  class ProtocolSearchResult(BaseModel):
      protocols: Annotated[list[Protocol], Field(description="List of protocols matching the search criteria")]
      current_page: Annotated[int, Field(description="Current page number of the search results, starting from 1")]
      total_pages: Annotated[int, Field(description="Total number of pages available for the search results")]
  
      @classmethod
      async def from_api_response(cls, data: dict) -> "ProtocolSearchResult":
          protocols = [await Protocol.from_protocol_id(protocol["id"]) for protocol in data["items"]]
          return cls(
              protocols=protocols,
              current_page=data["pagination"]["current_page"],
              total_pages = data["pagination"]["total_pages"]
          )

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

  Pydantic schema used for error responses from the search_public_protocols tool.

  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/server.py:10-10 (registration)

  Import of the tools module in the MCP server setup, which triggers the loading and registration of all @mcp.tool()-decorated functions including search_public_protocols via their decorators.

  importlib.import_module('protocols_io_mcp.tools')

• src/protocols_io_mcp/tools/__init__.py:1-1 (registration)

  Import of the protocol module containing the tool definitions, facilitating the registration chain.

  from protocols_io_mcp.tools import protocol