Derp MCP General Solver#

Source: examples/tools/derp_mcp_general_solver.py

Introduction#

This example shows the maintained DRAG + DERP path for selecting a packaged design-research problem, exposing it as an MCP tool server, and reading solver hints before making any optimization call. It is intentionally small: use the DERP catalog API for problem discovery, use the packaged DERP MCP CLI for tool launch, and keep provider-specific LLM setup outside the problem plumbing.

Technical Implementation#

  1. Search DERP with search_problem_summaries(...) instead of putting full problem briefs into the agent prompt.

  2. Load the selected optimization problem and read solver_hints() directly so variable domain and constraints do not need to be inferred from prose.

  3. Attach the packaged DERP MCP CLI with MCPServerConfig.python_module(...).

  4. Invoke solver_hints and evaluate through Toolbox and print one compact JSON payload.

        flowchart LR
    A["DERP search_problem_summaries"] --> B["Select problem id"]
    B --> C["DERP solver_hints()"]
    B --> D["python -m design_research_problems.mcp"]
    D --> E["DRAG Toolbox MCP tools"]
    C --> F["Agent-ready routing payload"]
    E --> F
    
  1from __future__ import annotations
  2
  3import json
  4from typing import Any
  5
  6import design_research_agents as drag
  7
  8INSTALL_HINT = 'python -m pip install "design-research-agents[mcp,gemini]" "design-research-problems[mcp]"'
  9
 10
 11def _missing_derp_payload(reason: str) -> dict[str, object]:
 12    return {
 13        "available": False,
 14        "example": "tools/derp_mcp_general_solver.py",
 15        "reason": reason,
 16        "install_hint": INSTALL_HINT,
 17    }
 18
 19
 20def _load_derp() -> Any | None:
 21    try:
 22        import design_research_problems as derp
 23    except ImportError:
 24        return None
 25    required = ("search_problem_summaries", "get_problem", "OptimizationProblem")
 26    if not all(hasattr(derp, name) for name in required):
 27        return None
 28    return derp
 29
 30
 31def _run_derp_workflow() -> dict[str, object]:
 32    derp = _load_derp()
 33    if derp is None:
 34        return _missing_derp_payload("design-research-problems with catalog summaries is not importable.")
 35
 36    summaries = derp.search_problem_summaries(text="pill", kind="optimization")
 37    if not summaries:
 38        return _missing_derp_payload("No optimization problem summary matched the query.")
 39
 40    summary = next(
 41        (candidate for candidate in summaries if candidate.problem_id == "pill_capsule_min_area"),
 42        summaries[0],
 43    )
 44    problem = derp.get_problem(summary.problem_id)
 45    if not isinstance(problem, derp.OptimizationProblem):
 46        return _missing_derp_payload(f"Selected problem is not optimization-backed: {summary.problem_id}")
 47
 48    local_solver_hints = problem.solver_hints()
 49    initial_candidate = problem.generate_initial_solution(seed=3).tolist()
 50
 51    try:
 52        with drag.Toolbox(
 53            enable_core_tools=False,
 54            mcp_servers=(
 55                drag.MCPServerConfig.python_module(
 56                    id="drp_problem",
 57                    module="design_research_problems.mcp",
 58                    args=(summary.problem_id, "--no-citation"),
 59                    timeout_s=45,
 60                ),
 61            ),
 62        ) as runtime:
 63            mcp_tools = sorted(spec.name for spec in runtime.list_tools() if spec.name.startswith("drp_problem::"))
 64            mcp_hints = runtime.invoke(
 65                "drp_problem::solver_hints",
 66                {},
 67                request_id="example-derp-solver-hints",
 68                dependencies={},
 69            )
 70            evaluation = runtime.invoke(
 71                "drp_problem::evaluate",
 72                {"x": initial_candidate},
 73                request_id="example-derp-evaluate",
 74                dependencies={},
 75            )
 76    except Exception as exc:
 77        return {
 78            "available": True,
 79            "example": "tools/derp_mcp_general_solver.py",
 80            "problem_id": summary.problem_id,
 81            "problem_summary": summary.to_dict(),
 82            "local_solver_hints": local_solver_hints,
 83            "mcp_available": False,
 84            "mcp_error": str(exc),
 85            "install_hint": INSTALL_HINT,
 86        }
 87
 88    return {
 89        "available": True,
 90        "example": "tools/derp_mcp_general_solver.py",
 91        "problem_id": summary.problem_id,
 92        "problem_summary": summary.to_dict(),
 93        "local_solver_hints": local_solver_hints,
 94        "mcp_tools": mcp_tools,
 95        "mcp_solver_hints": {
 96            "ok": mcp_hints.ok,
 97            "result": mcp_hints.result,
 98            "error": mcp_hints.error,
 99        },
100        "mcp_evaluation": {
101            "ok": evaluation.ok,
102            "result": evaluation.result,
103            "error": evaluation.error,
104        },
105    }
106
107
108def main() -> None:
109    """Run the maintained DERP MCP workflow and print JSON."""
110    print(json.dumps(_run_derp_workflow(), ensure_ascii=True, indent=2, sort_keys=True))
111
112
113if __name__ == "__main__":
114    main()

Expected Results#

Run Command

PYTHONPATH=src python3 examples/tools/derp_mcp_general_solver.py

When design-research-problems[mcp] is available, the example prints a JSON object containing the selected problem summary, local solver hints, MCP tool names, MCP solver hints, and one evaluation report. If DERP is not installed, it exits successfully with an available: false payload and an install hint.

{
  "available": true,
  "example": "tools/derp_mcp_general_solver.py",
  "mcp_tools": ["drp_problem::evaluate", "drp_problem::solver_hints", "drp_problem::submit_final"],
  "problem_id": "pill_capsule_min_area"
}

References#