Optuna MCP Server

Instructions

Implementation Reference

• optuna_mcp/server.py:238-257 (handler)

  The handler function for the 'get_trial_user_attrs' tool. It fetches the trial from Optuna storage using the trial_number and returns a TrialResponse with the user_attrs.

  @mcp.tool(structured_output=True)
  def get_trial_user_attrs(trial_number: int) -> TrialResponse:
      """Get user attributes in a trial"""
      if mcp.study is None:
          raise McpError(
              ErrorData(
                  code=INTERNAL_ERROR,
                  message="No study has been created. Please create a study first.",
              )
          )
  
      storage = mcp.study._storage
      trial_id = storage.get_trial_id_from_study_id_trial_number(
          mcp.study._study_id, trial_number
      )
      trial = storage.get_trial(trial_id)
      return TrialResponse(
          trial_number=trial_number,
          user_attrs=trial.user_attrs,
      )

• optuna_mcp/server.py:84-98 (schema)

  Pydantic model defining the output structure for the tool, including the user_attrs field.

  class TrialResponse(BaseModel):
      trial_number: int
      params: dict[str, typing.Any] | None = Field(
          default=None, description="The parameter values suggested by the trial."
      )
      values: list[float] | None = Field(
          default=None, description="The objective values of the trial."
      )
      user_attrs: dict[str, typing.Any] | None = Field(
          default=None, description="User-defined attributes for the trial."
      )
      system_attrs: dict[str, typing.Any] | None = Field(
          default=None, description="System-defined attributes for the trial."
      )

• optuna_mcp/server.py:686-686 (registration)

  The register_tools function is called here to register all tools, including 'get_trial_user_attrs', with the MCP server.

  mcp = register_tools(mcp)