Skip to main content
Glama
Genetic Optimization MCP Server

Genetic Optimization MCP Server

by OuchiniKaeru

遺伝的最適化 MCP サーバー

AI エージェントの代わりに単目的遺伝的アルゴリズム最適化を実行する、再利用可能な MCP サーバーです。エージェントが変数、目的関数、制約、計算予算を定義すると、サーバーが定義を検証し、pymoo を用いた混合変数 GA を隔離されたワーカープロセスで実行し、構造化された結果を返します。

得られた結果は予算内で見つかった最良の候補であり、大域最適解を保証するものではありません。

機能

  • 混合変数型: float(線形/対数)、integer(ステップ付き)、choice、boolean。

  • 目的関数と制約は、サンドボックス化された数式評価パーサー、または管理者が登録した評価関数から指定可能。

  • 回帰テスト済みの評価予算: 最大評価回数、最大世代数、ウォールクロックタイムアウト、シード。

  • 管理者管理の評価関数フォルダ。各フォルダが独自の uv プロジェクトと .venv を持ち、uv run --locked と永続的な JSON Lines ワーカープロセスで実行。

  • 同期および非同期実行、SQLite バックアップの実行履歴、キャンセル、実行結果の比較。

  • MCP 応答はサニタイズ済み。ログは stderr とローテーションする JSON Lines ファイルに出力され(stdout には出力されない)。

Related MCP server: Vepathos MCP

要件

  • Python >= 3.12

  • uv(登録済み評価関数に必要)

インストール

uv sync --extra dev

これによりサーバー用の .venv が作成されます。登録済み評価関数はこの .venv にはインストールされません。各評価関数は独自の環境を持ちます。

実行

uv run optimization-mcp --config config/default.toml

デフォルトのトランスポートは stdio です。診断と設定確認:

uv run optimization-mcp --config config/default.toml --diagnose

MCP ホスト設定(stdio)

{
  "mcpServers": {
    "genetic-optimization": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/絶対パス/to/genetic-optimization-mcp",
        "optimization-mcp",
        "--config",
        "/絶対パス/to/genetic-optimization-mcp/config/default.toml"
      ]
    }
  }
}

ツール

ツール

目的

optimization.list_evaluators

許可リスト入り評価関数、そのスキーマ、準備状態を一覧表示

optimization.validate_problem

評価を行わずに問題を検証

optimization.solve

sync または async で最適化を実行

optimization.get_result

実行のステータスと結果サマリーを取得

optimization.list_runs

実行履歴を検索しページング

optimization.cancel

実行中/キューイング中のジョブのキャンセルを要求

optimization.compare_results

2–10 件の実行を比較し、明示的な非比較性の注記を付与

エージェントワークフロー(フェーズ 3)

  1. optimization.list_evaluators を呼び出し、available、deterministic、パラメータスキーマを確認する。

  2. 問題を定義し、optimization.validate_problem を validation_level="strict" で呼び出す。

  3. 小さい予算から始める: optimization.solve。

  4. 目的値を信用する前に、constraints.feasible、termination_reason、warnings、variables_at_bounds を確認する。

  5. 必要に応じて範囲や予算を変更し、再実行する。optimization.compare_results で比較する。目的関数、評価関数バージョン、パラメータ、制約が異なる場合、単一の改善率を報告することは拒否される。

  6. 最大 5 回の反復(上限 20 回)で終了し、結果を「探索により見つかった最良の候補」として、条件と残りの不確実性とともに報告する。

サーバーは LLM を呼び出さず、制約を勝手に緩和することもありません。

サンプル問題

球関数を最小化:

{
  "problem_name": "sphere_example",
  "variables": {
    "x": {"type": "float", "min": -5.0, "max": 5.0},
    "y": {"type": "float", "min": -5.0, "max": 5.0}
  },
  "objective": {
    "kind": "expression",
    "expression": "(x - 1) ** 2 + (y + 2) ** 2",
    "direction": "minimize"
  },
  "algorithm": {"population_size": 40, "generations": 60, "seed": 42},
  "budget": {"max_evaluations": 2000, "timeout_seconds": 30}
}

混合変数と制約:

{
  "problem_name": "mixed_example",
  "variables": {
    "lr": {"type": "float", "min": 0.0001, "max": 0.1, "scale": "log"},
    "depth": {"type": "integer", "min": 2, "max": 10, "step": 2},
    "optimizer": {"type": "choice", "options": ["adam", "sgd"]},
    "augment": {"type": "boolean"}
  },
  "objective": {
    "kind": "expression",
    "expression": "depth + 0.2 * augment",
    "direction": "minimize"
  },
  "constraints": [
    {"constraint_id": "lr_depth", "kind": "expression", "expression": "lr * depth", "operator": "<=", "limit": 0.5}
  ]
}

登録済み評価関数

evaluator_root(デフォルト ./evaluators)直下の各子フォルダが 1 つの評価関数です:

evaluators/
└── model_quality_v1/
    ├── evaluator.toml
    ├── params.schema.json
    ├── pyproject.toml
    ├── uv.lock
    ├── evaluator.py
    └── .venv/            # `uv sync --locked` で作成、コミット対象外

evaluator.toml:

evaluator_id = "model_quality_v1"
version = "1.0.0"
description = "Evaluates a deterministic toy model quality score"
module = "evaluator.py"
function = "evaluate"
deterministic = true
timeout_seconds = 30
params_schema_file = "params.schema.json"

evaluator.py は次のように公開します:

def evaluate(candidate: dict, params: dict, context: dict) -> float:
    ...

サーバーが強制する規則:

  • ID はスラッグ(^[a-z0-9][a-z0-9_-]{0,63}$)であり、フォルダ名と一致しなければならない。

  • フォルダは設定されたルートの直接の子でなければならない。ルートを抜けるシンボリックリンク、重複 ID、メタデータ/ロックファイルの欠落により評価関数は利用不可になる。

  • uv lock は MCP リクエストに応答して決して実行されない。ロックの欠落/不整合はエラーとなる。

  • uv sync --project <dir> --locked は初回使用時、またはロックのフィンガープリントが変更されたときに遅延実行される。

  • 評価ワーカーは JSON Lines を stdout で送信する。評価関数の print() 出力は stderr にリダイレクトされ、プロトコルを汚染しない。

  • 評価結果は有限の JSON 数値でなければならない(ブール値、NaN、Infinity は拒否される)。

サンプル評価関数の準備:

cd evaluators/model_quality_v1
uv lock
uv sync --locked

設定

config/default.toml を参照してください。パスは設定ファイルを基準として解決されます。環境変数のオーバーライドは OPTIMIZATION_MCP_ プレフィックスと __ でネストを表現します。例: OPTIMIZATION_MCP_LIMITS__MAX_VARIABLES=20。

管理者による上限値は MCP リクエストから引き上げることはできません。予算を超えるリクエストは BUDGET_EXCEEDED で拒否され、値は黙ってクランプされることはありません。

データとログ

  • SQLite データベース: data/optimization.db(WAL モード、トランザクション)。

  • JSON Lines ログ: logs/optimization-mcp.log(ローテーション、保持期間は設定済み)。

  • 標準出力は MCP stdio トランスポートに専用。ログは stderr/ファイルを使用。

  • フル人口ではなく、サマリーと上位候補のみが永続化される。

保持期間とバックアップ

persistence.log_retention_days と persistence.log_max_bytes / backup_count を設定してください。データベースを安全にバックアップするには:

sqlite3 data/optimization.db ".backup 'backup-optimization.db'"

復元はサーバーを停止し、data/optimization.db をバックアップと置き換えて行います。旧データベース取得時に running だった実行は、次回の起動時に failed(キャンセルが要求されていれば cancelled)として復旧します。完了済みの実行は引き続き問い合わせ可能です。

セキュリティに関する注意事項

  • 数式は Python ast で解析され、許可リストに基づいて評価される。eval、exec、属性アクセス、添字アクセス、内包表記、ラムダ、インポートは拒否される。

  • MCP 入力からコード、パス、モジュール名、コマンドを提供することはできない。管理者が登録した評価関数 ID のみがコードを実行できる。

  • uv 環境は依存関係の分離であり、OS サンドボックスではない。信頼できる評価関数コードのみを評価関数ルートに配置する。信頼できないコードには OS ユーザー/コンテナ/リソース制限を使用する。

  • エラー応答はサニタイズされる。トレースバック、絶対パス、環境変数は含まれない。

  • 認証、TLS、レート制限なしで Streamable HTTP を有効にしないこと(デフォルトでは無効)。

テスト

uv run pytest
uv run ruff check src tests

uv 環境を必要とするテストは、uv が利用できない場合や OPTIMIZATION_MCP_SKIP_UV_TESTS=1 が設定されている場合はスキップされます。

Available Tools

7 tools
optimization.cancelB

Request cancellation of a queued or running run.

    Cancellation is cooperative first; if the worker does not stop within
    the grace period, its process group is terminated.  ``accepted`` and
    ``termination_confirmed`` are reported separately.
    

Inputs: run_id (required), reason. Returns: result

optimization.compare_resultsB

Compare 2–10 runs and report condition mismatches.

    When objective definitions, variables, constraints, evaluator versions or
    parameters differ, ``comparable=false`` and no single improvement
    percentage is produced.
    

Inputs: run_ids (required), compare_fields. Returns: result

optimization.get_resultA

Fetch run status, progress and the stored result summary.

    Full candidate populations are never returned; ``top_solutions`` is
    capped by the run's ``top_k``.  Set ``include_top_solutions=false`` for a
    smaller response.
    

Inputs: run_id (required), include_top_solutions. Returns: result

optimization.list_evaluatorsC

List administrator-registered evaluators and their readiness.

Returns IDs, versions, descriptions, parameter schema summaries, determinism, estimated cost, timeout and environment status. Internal paths and environment variables are never returned.

Inputs: limit, query. Returns: result

optimization.list_runsA

List run history newest-first with optional status/problem filters.

    Default page size is 20; the administrator maximum is enforced.  Pass the
    returned ``next_cursor`` to fetch the next page.
    

Inputs: limit, cursor, status, problem_name. Returns: result

optimization.solveA

Run the optimization.

    ``execution_mode="sync"`` waits for completion and returns the summary.
    ``execution_mode="async"`` returns immediately with a ``run_id`` and
    ``status``; poll it with ``optimization.get_result``.  A repeated
    ``client_request_id`` returns the existing run instead of starting a
    duplicate.
    

Inputs: problem (required), execution_mode, client_request_id. Returns: result

optimization.validate_problemA

Validate a problem definition without evaluating anything.

    Checks variable ranges/types, expressions, constraints, evaluator
    availability and parameter schemas, and administrator budgets.  Use
    ``strict`` to surface non-deterministic evaluators and oversized budgets.
    

Inputs: problem (required), validation_level. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool maps to a distinct stage of the optimization lifecycle: validate, submit, poll, list history, cancel, compare, and enumerate evaluators. The only potentially adjacent pair (solve vs. validate_problem) is clearly separated by the descriptions, since validation explicitly evaluates nothing. No two tools could plausibly be mistaken for one another.

    Naming Consistency5/5

    All tools share a uniform 'optimization.' namespace and use snake_case verb_noun naming (get_result, validate_problem, list_evaluators, list_runs, compare_results). The bare 'solve' is the sole noun-less verb but reads naturally as the primary action and does not break the pattern.

    Tool Count5/5

    Seven tools is well within the sweet spot and every tool earns its place: submission, polling, validation, enumeration, history, cancellation, and comparison are all genuinely needed. There is no filler or redundant surface.

    Completeness4/5

    The run lifecycle is fully covered end-to-end, including idempotency, async polling, cancellation, and cross-run comparison, which is unusually thorough. Minor gaps remain: no way to delete/prune run history or manage stored problems, and no streaming/partial-progress retrieval beyond status polling.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Provides constraint satisfaction and optimization capabilities to LLMs and AI agents for scheduling, resource allocation, routing, budget optimization, and configuration problems using Google OR-Tools CP-SAT solver.
      5
      6
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to submit asynchronous last-mile fleet optimizations that assign stops to vehicles and sequence routes from a depot, then retrieve status, summaries, ordered stop sequences, or unassigned ids. Supports hundreds to thousands of stops with optional weight, volume and time-window constraints, with results retained for 24 hours.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable agents to solve scheduling and integer optimization problems using Google OR-Tools, return proven-optimal or valid solutions, independently verify proposed solutions, and explain infeasible rule sets.
      MIT