Optuna MCP Server

Instructions

    search_space must be a string that can be evaluated to a dictionary to specify Optuna's distributions.

    Example:
        {"x": {"name": "FloatDistribution", "attributes": {"step": null, "low": -10.0, "high": 10.0, "log": false}}}
    

Implementation Reference

• optuna_mcp/server.py:136-167 (handler)

  The core handler function for the 'ask' tool. It parses the search_space into Optuna distributions and calls study.ask() to suggest new trial parameters, returning a TrialResponse.

  @mcp.tool(structured_output=True)
  def ask(search_space: dict) -> TrialResponse:
      """Suggest new parameters using Optuna
  
      search_space must be a string that can be evaluated to a dictionary to specify Optuna's distributions.
  
      Example:
          {"x": {"name": "FloatDistribution", "attributes": {"step": null, "low": -10.0, "high": 10.0, "log": false}}}
      """
      try:
          distributions = {
              name: optuna.distributions.json_to_distribution(json.dumps(dist))
              for name, dist in search_space.items()
          }
      except Exception as e:
          raise McpError(ErrorData(code=INTERNAL_ERROR, message=f"Error: {e}")) from e
  
      if mcp.study is None:
          raise McpError(
              ErrorData(
                  code=INTERNAL_ERROR,
                  message="No study has been created. Please create a study first.",
              )
          )
  
      trial = mcp.study.ask(fixed_distributions=distributions)
  
      return TrialResponse(
          trial_number=trial.number,
          params=trial.params,
      )

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

  Pydantic BaseModel defining the structured output schema for the 'ask' tool response, including trial_number, params, etc.

  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:685-687 (registration)

  Registration of all tools including 'ask' by calling register_tools on the OptunaMCP instance before running the server.

  mcp = OptunaMCP("Optuna", storage=args.storage)
  mcp = register_tools(mcp)
  mcp.run()

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

  The @mcp.tool decorator that registers the 'ask' function as an MCP tool with structured output.

  @mcp.tool(structured_output=True)