FlagQuantum MCP Server

FlagQuantum MCP サーバー

あらゆる MCP 対応エージェントに、FlagQuantum SDK へのローカルアクセスを提供する MCP サーバーです。量子回路の構築、コンパイル、ルーティング、シリアライズ、実行計画の作成を行い、認証情報も外部ネットワークへのアクセスもハードウェアへの送信もなしに、ローカルで実行できます。

ここで重要なのは「外部への通信」です。各ツールはすべてこのプロセス内で実行され、外部には一切アクセスしません。サーバーがプロバイダーを呼び出したり、トークンを読み取ったり、ジョブを送信したりすることはありません。また、サーバーはリッスンすることもできるため、クライアントを起動するのではなくクライアントに接続するゲートウェイからもアクセスできます。詳しくはHTTP 経由での提供をご覧ください。インバウンドリスナーは外部への通信ではありません。

FlagQuantum/mcp-servers の一部です。

上記の mcp-name コメントは飾りではありません。MCP Registry はこの README からその内容を読み取り、レジストリエントリを公開する人が PyPI パッケージも管理していることを確認します。削除すると、レジストリへの公開に支障が出ます。

機能

stdio または Streamable HTTP 経由で利用できる 27 個のツールです。研究ツールはインストール済みの FlagQuantum サービスコントラクトを直接使用します。MCP レイヤーでリクエストのデコード、推定、プロバイダーへのルーティング、科学的な検証を再実装することはありません。

構築と検査

ツール	回答する内容
describe_gate_set_tool	名前付きゲート（またはすべてのゲート）のワイヤー数、パラメーター名、エイリアス
analyze_circuit_tool	ゲート数、深さ、ワイヤーの使用状況、2 量子ビットゲート数
describe_layers_tool	並行して実行されるゲートと、深さの要因
serialize_circuit_tool	正規 IR JSON とそのコンテンツハッシュ
deserialize_circuit_tool	この IR が有効か、変更なくラウンドトリップするか

パラメーター

ツール	回答する内容
inspect_parameters_tool	この回路にパラメーターがあるか、各シンボルがどこにあるか
bind_parameters_tool	シンボルを数値に置き換えたときのアンザッツの形

コンパイルとルーティング

ツール	回答する内容
optimize_circuit_tool	ターゲットに依存しない最適化で何が変わったか
compile_circuit_tool	最適化とルーティングを行う完全なパイプラインが生成する回路
route_circuit_tool	ライン／リング／グリッド／カスタムトポロジー上で、この回路にかかるコスト
compare_topologies_tool	この回路で最もコストの低い接続構成
describe_topology_tool	接続構成と、2 つのワイヤー間の距離

エクスポートと表示

ツール	回答する内容
emit_openqasm_tool	OpenQASM 2.0 または 3.0 のテキスト
import_openqasm_tool	OpenQASM テキストから FlagQuantum IR への変換。emit_openqasm_tool の逆
emit_qcis_tool	QCIS テキスト
draw_circuit_tool	回路の ASCII 図
plan_execution_tool	SDK による実行方法（モード、デバイス、必要なメモリー量）
plan_evolution_tool	連続時間の Lindblad 発展を実行せずに検証し、規模を見積もる

実行

ツール	回答する内容
simulate_circuit_tool	ローカルの状態ベクトル実行によるカウント、サンプル、周辺確率、または期待値
evolve_dynamics_tool	ローカルの Lindblad 発展による時間分解集団、観測量、オプションの密度行列
train_parameters_tool	パウリ和ハミルトニアンに対する回路のエネルギーを下げる角度

研究機能のワークフロー

ツール	回答できること
search_capabilities_tool	構造化フィルターに一致する、承認済みのローカル研究操作はどれですか？
describe_capability_tool	ある操作が宣言する、正確なリクエスト、結果、制限事項、バリデーターは何ですか？
estimate_capability_tool	このリクエストはローカルでサポートされていますか？ また、FlagQuantum が推定する上限付きリソースは何ですか？
validate_capability_input_tool	型付きのリクエスト全体は、上流のバリデーションに合格しますか？
execute_local_capability_tool	ローカルプロバイダーの明示的な実行によって、どのような Evidence Bundle が得られますか？
validate_evidence_tool	返された Evidence Bundle は完全で、指定されたバリデーターによって科学的に受け入れられていますか？

具体的なリソースは4つあり、flagquantum://version、 flagquantum://gate-set、flagquantum://ir-schema、インストール済みの研究 カタログ flagquantum://capabilities/index です。2つのリソーステンプレートは、 上流のドキュメントをコピーせずにそのまま公開します。 flagquantum://capabilities/{capability_id}/{version} と flagquantum://schemas/{schema_id} です。

プロンプトは3つです。build_and_analyze_circuit、 compile_for_topology、export_circuit です。

これらは、Claude Desktop、MCP Inspector、またはスラッシュコマンドに変換するホストなど、 プロンプトを提示するクライアント向けのレシピです。自律型エージェントには、これらが 一切提供されないことがあります。記録された複数のセッションでは、プロンプトを 列挙できず、プロンプトが存在するかどうかも判断できないと報告されました。したがって、 エージェントが知る必要のある情報を、ここだけに記載することはありません。プロンプトに 記載された制約はすべて、ツールの概要、サーバーの指示、またはリソースにも記載されています。 例外はQCISに関する拒否と「仮定したことを伝える」というルールの2つでしたが、現在は emit_qcis_tool と bind_parameters_tool に記載されています。 tests/test_server_contract.py の PROMPT_CONSTRAINTS が、この状態を保ちます。

インストール

pip install flagquantum-mcp-server

これにより、torch に依存する flagquantum が取得されます。

Claude Code

claude mcp add flagquantum -- uvx flagquantum-mcp-server

Claude Desktop / Cline

{
  "mcpServers": {
    "flagquantum": {
      "command": "uvx",
      "args": ["flagquantum-mcp-server"]
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector uvx flagquantum-mcp-server

HTTP 経由での提供

プロセスを起動するクライアント（Claude Code、Claude Desktop、Inspector）は、デフォルトの stdio トランスポートを使用するため、以下の設定は不要です。複数のサーバーを保持する ゲートウェイなど、サーバーに接続するクライアントでは、サーバーがリッスンしている 必要があります。

flagquantum-mcp-server --transport http --host 0.0.0.0 --port 8105 \
    --allowed-host quantum-mcp:8105

エンドポイントはそのホストとポート上の /mcp で、Streamable HTTP を使用します。

フラグ	デフォルト	説明
--transport	stdio	stdio または http です。デフォルトは変更されないため、すでに動作しているものを編集する必要はありません
--host	127.0.0.1	バインドするインターフェイスです。デフォルトはループバックなので、サーバーが意図せず到達可能になることはありません
--port	8105	バインドするポートです
--allowed-host	なし	サーバーが応答する Host ヘッダーです。複数指定できます
--allowed-origin	なし	サーバーが応答するブラウザーの Origin です。複数指定できます

ループバック以外のインターフェイスにバインドするには、--allowed-host が必要です。 指定しない場合、誰がアクセスするかを確認せずにすべてのインターフェイスでリッスンするのではなく、 サーバーは起動を拒否します。

$ flagquantum-mcp-server --transport http --host 0.0.0.0
usage: flagquantum-mcp-server [-h] ...
flagquantum-mcp-server: error: --host 0.0.0.0 is not a loopback address, so the
server would answer any Host header that reaches it. Name the hosts it should
answer with --allowed-host HOST[:PORT], or bind 127.0.0.1.

--allowed-host または --allowed-origin を指定すると、ホストの検証が有効になります。 リストにない Host を含むリクエストには 421 Misdirected Request が返されます。 ループバックホストには常に応答するため、検証を有効にしてもローカルクライアントが締め出されることはありません。

設定する際に知っておくべきことが2つあります。

• 検証は http_app( allowed_hosts=...) ではなく、設定オブジェクトを通じて行ってください。 このキーワードは、 検証が有効になったときにのみ参照されるリストに値を追加するため、単独ではセキュリティ設定のように 見えても、何も強制しません。fastmcp 3.4.7 での測定では、キーワードを使うと不正な Host に 200 が返され、設定オブジェクトを使うと 421 が返されました。
• --transport http が追加するのは受信ソケットであり、送信ソケットではありません。 どのツールにもネットワーク経路は追加されません。AGENTS.md のルール4に変更はありません。

回路形式

入力形式は2種類あり、どちらもFlagQuantum独自のシリアライズ形式です。

ir（標準）— CircuitIR.to_json()で生成されるFlagQuantum IR JSONです。バージョン管理され、ハッシュ化でき、未知のフィールドを含む場合は拒否されます。

{
  "kind": "flagquantum.circuit_ir",
  "version": "1.0",
  "n_wires": 2,
  "dtype": "complex64",
  "shape": [4],
  "instructions": [
    {"opcode": "h", "wires": [0], "params": {}, "matrix": null, "metadata": {}},
    {"opcode": "cx", "wires": [0, 1], "params": {}, "matrix": null, "metadata": {}}
  ],
  "observables": [],
  "measurements": [],
  "metadata": {}
}

qir（簡易）— Circuit.to_qir()のコンパクトなゲートリストで、手書きしやすい形式です。

[{"name": "h", "index": [0]}, {"name": "cx", "index": [0, 1]}]

ゲートの引数は**parameters**の下に指定します。上記の例では、どちらのゲートにも引数がないため示されていません。

[{"name": "rz", "index": [0], "parameters": {"theta": 0.5}}]

2つの形式ではキー名が異なります。これが最もよくある間違いです。ゲートリストではゲートをname、ワイヤーをindexと呼びますが、シリアライズされたIRではそれぞれopcodeとwiresと呼びます。IRのキーをqirとして送信すると、その旨を明示するメッセージとともに拒否されます。また、空のゲートリストも拒否されます。ワイヤー数は最大インデックスから推定されるため、空のリストは回路を表さないからです。単一ワイヤーのゲートでは整数をそのまま指定できます（"index": 0は"index": [0]を意味します）。

どちらの形式も任意のツールに渡せます。serialize_circuit_toolはqirを標準形式のirに変換します。

もう1つ、名前に関する注意点があります。IRペイロードのバージョンフィールド名は**version**です。代わりにir_versionを送ると、未知のキーとして拒否されます。一方、ツールの結果では同じフィールドがir_versionとして報告されます。ペイロードのキー名と報告されるキー名は一致しません。

circuit_formatは選択肢が固定されています。JSONスキーマには"enum": ["ir", "qir"]が公開されているため、誤った値はツールの処理が実行される前に拒否されます。OpenQASMテキストは入力としてサポートされていません。 FlagQuantumには出力機能はありますが、QASMパーサーはないため、変換手段がありません。OpenQASMを扱う場合は、呼び出し側でFlagQuantumに読み込ませ、生成されたIRを送信する必要があります。

パラメーターについて

ゲートのパラメーターは数値またはシンボルです。シンボルは、名前をキーとする1つのキーだけを持つオブジェクトで記述します。

{"name": "ry", "index": [0], "parameters": {"theta": {"$parameter": "theta"}}}

これはどちらの入力形式でも使えます。シンボルがあると回路はアンザッツになります。inspect_parameters_toolで確認でき、bind_parameters_toolで数値に置き換えられます。

単なる文字列はシンボルではありません。 {"theta": "theta"}は参照ではなく値です。SDKはこれを値として保存するため、回路はパラメーター化されていないと報告されます。他の処理では問題が発生しません。draw_circuit_toolは渡された値を表示し、文字列は実際のシンボルと区別できないRY(theta)として表示されます。一方、plan_execution_toolは回路の実行を計画します。そのため、入力境界では、誤記されたマーカー（{"$unknown": ...}）や文字列以外のシンボル名とともに、ゲート名とパラメーターを示して拒否します。パラメーターで使用できるその他の表現は$expression、$complex、$tensorです。これら4つのキーのいずれも含まないマッピングも、同じ理由で拒否されます。flagquantum://ir-schemaリソースには、実例を示すparameter_exampleがあります。

SDKから引き継がれた不便な点が1つあります。実際のシンボルはSDKのreprで表示されるため、RY(theta)はRY(Parameter(name='theta'))のように表示されます。FlagQuantumのParameterには__str__が定義されていないため、str()は__repr__にフォールバックします。シンボル自体はそのままですが、図の表記が扱いにくくなります。この問題はどちらの入力形式にも同様に影響します。

エクスポートにはバインドが必要です。出力機能は数値を書き出すため、バインドされていない回路はbind_parametersを指定したメッセージとともに拒否されます。それ以外では不要です。analyze、optimize、route、draw、describe_layers、plan_execution_toolは、パラメーター値を読み取らないため、パラメーター化された回路をそのまま受け付けます。プランはペイロードの形状とdtypeから作成されます。出力テキストが必要な場合や、具体的な回路を実行する場合にバインドしてください。それまでは不要です。

明示的なユニタリゲートについて

ゲートの行列を指定するキーは、形式によって異なります。ゲートリストでは gate、シリアライズ済み IR では matrix です。

[{"name": "any", "index": [0], "gate": [[0, 1], [1, 0]]}]

半端に受け入れられるのではなく、拒否されるものが 2 つあります。

形式に合わないキー。 Circuit.from_qir は gate を読み取り、matrix は完全に無視するため、IR 形式のキーを使ったゲートリストは、行列なしでサイレントに構築されます。組み込み名の場合、呼び出し元が記述したものとは異なる回路になるため、キーの不一致を明示します。

組み込みオペコードに指定された行列。 行列は、FlagQuantum が行列用に予約しているオペコード any に属します。組み込み名に行列を指定すると、SDK は行列をペイロードに保持しますが、組み込みゲート独自の定義を優先します。その結果、ツール間で動作が分かれます。analyze_circuit_tool はそのゲートを組み込み名で報告する一方、エミッターはそれを低レベル表現に変換できません。代わりにゲート名として any を指定してください。

ワイヤ番号について

どちらの形式でも、ワイヤ番号は整数でなければならず、wires リストはリストでなければなりません。どちらも明記する価値があります。SDK は渡された値をそのまま反復し、各要素に int() を呼び出すためです。そのため、"1"、true、1.7、0.9 もワイヤとして扱われます。また、"01" はワイヤ 0 と 1 に、{"0": 1} はワイヤ 0 に変換されます。これが、これを利便性ではなくエラーとして扱う理由です。意味をなさない値が、見た目には問題のない回路に変わってしまいます。

エンベロープ自体のフィールドについて

同じルールは、instructions の外側にあるフィールドにも適用されます。n_wires と shape の各要素は int() で読み取られるため、"2"、2.7、true はいずれも幅として扱われます。dtype は torch の属性として検索されるため、文字列以外の値を指定すると、SDK 内部で属性検索が行われます。

拒否されるかどうかの基準は、JSON の型がスキーマと厳密に一致するかではなく、情報が失われるかどうかです。そのため、version: 1.0 は str(1.0) で元の値を再現できるので受け入れられます。一方、n_wires: 2.7 は 2 にサイレントに変換され、n_wires: true は 1 にサイレントに変換されるため、受け入れられません。

ここでは、dtype が文字列であることを確認します。どの文字列が有効かは SDK に委ねられます。SDK 独自のメッセージにルール（complex_dtype must be complex64 or complex128）が示されるため、両者のルールが食い違うことはありません。

オブザーバブルと測定について

どちらもオブジェクトのリストで、回路に何もない場合は空になります。各エントリーは簡潔で、残りの部分は読み込み時に SDK が補完します。

{
  "observables": [{"name": "ZZ", "wires": [0, 1]}],
  "measurements": [{"kind": "counts", "wires": [0, 1], "shots": 1024}]
}

SDK が保存するデータには省略可能なキーが追加され、オブザーバブル名は小文字に変換されます。そのため、"ZZ" は "coefficient": 1.0 を伴う "zz" として戻ります。coefficient は項の重みで、ゲート角度と同様にシンボルを指定できます（{"$parameter": "w"}）。これは、ハミルトニアンの項に変分重みを持たせる方法です。shots は省略すると null になります。

オブザーバブルは VQE ansatz が測定するためのものです。そのため、まず誤りなく、この形式で指定できることを確認しておく価値があります。flagquantum://ir-schema では、両方の形式が observable_example として並べて公開されています。

出力テキストについて

emit_openqasm_tool は、必要なワイヤを result_wires で指定しない限り、すべてのワイヤを測定します。そのため、通常、出力プログラムにはソース回路にはない測定が含まれます。たとえば、measurements のないベル回路でも c = measure q; が出力されます。ソース IR で測定を宣言しても何も変わりません。出力テキストは result_wires だけで決まります。結果の content_hash は、出力テキストではなくソース回路を識別します。emit_qcis_tool は何も追加しません。

インポートしたテキストについて

import_openqasm_tool は、FlagQuantum 独自のエミッターが出力する標準サブセットを読み込み、それ以外は UNSUPPORTED_FORMAT と、該当するステートメントおよび行を示すインポーター独自のメッセージを返して拒否します。汎用の OpenQASM フロントエンドではありません。他のツールチェーンのテキストは近似して処理されるのではなく、拒否される場合があります。また、プログラムが適合するように暗黙に書き換えられることはありません。

ラウンドトリップで保持されるのは、ソース回路ではなくテキストです。emit_openqasm_tool はソース回路になかった測定を追加するため、その出力をインポートすると、測定を行う回路になります。そのため、ソースを表すエミッターの content_hash とは異なります。2 回インポートするとハッシュは安定します。出力したものをインポートするとゲートシーケンスは一致しますが、測定が新たに追加されます。

content_hash について

すべてのペイロードには SDK の content_hash が含まれます。これは、metadata オブジェクトを含む正規化 JSON の SHA-256 です。metadata を省略した IR ペイロードも有効で、デフォルトは {} ですが、同じ回路でもランタイムメタデータを持つ場合とはハッシュが異なります。ハッシュはゲートシーケンスだけではなく、ペイロードを識別するものとして扱ってください。エージェントが参照する flagquantum://ir-schema リソースにも、同じ内容が記載されています。

制限

すべての上限は環境変数で変更できるため、コードを変更せずにデプロイ環境で厳しく設定できます。

変数	デフォルト値	上限の対象
FLAGQUANTUM_MCP_MAX_QUBITS	24	回路幅
FLAGQUANTUM_MCP_MAX_GATES	10000	命令数
FLAGQUANTUM_MCP_MAX_IR_BYTES	262144	シリアライズされた回路ペイロード
FLAGQUANTUM_MCP_MAX_QASM_CHARS	1000000	出力されるプログラムのサイズ
FLAGQUANTUM_MCP_MAX_COMPARE_TOPOLOGIES	4	比較あたりのトポロジー数
FLAGQUANTUM_MCP_MAX_TRAIN_SECONDS	60	1 回のトレーニング呼び出しの予測コスト
FLAGQUANTUM_MCP_MAX_RESPONSE_VALUES	65536	1 つの結果が返せる値の数
FLAGQUANTUM_MCP_MAX_HAMILTONIAN_TERMS	1024	期待値リクエストあたりのパウリ項数

最後の上限だけは、このサーバーが受け入れるものではなく、返すものに適用されます。結果はメモリではなくモデルのコンテキストに渡され、サンプリング結果は shots に応じて増加します。このほかの上限にはすべて収まる 200,000 回のサンプリングでも、回答としてははるかに多すぎます。

エラー

エラーには 2 つの層があり、スキーマで誤りを表現できるかどうかによって、どちらが応答するかが決まります。

スキーマ違反は、ツール本体の実行前に MCP 層で検出され、プロトコルエラーとして返されます。これには、列挙型の範囲外の circuit_format、必須引数の不足、引数の JSON 型の誤りが含まれます。

それ以外のすべては構造化されたエンベロープとして返されるため、呼び出し元は文章を解析せずにコードに基づいて分岐できます。

{"status": "error", "error": {"code": "LIMIT_EXCEEDED", "message": "..."}}

コード：INVALID_INPUT、LIMIT_EXCEEDED、UNSUPPORTED_FORMAT、SDK_UNAVAILABLE、INTERNAL_ERROR。

どちらの層のエラーも、クライアントが読み取れるエラーとして届きます。異なるのは層だけです。トランスポートを壊す未処理の例外が外部に漏れることはありません。呼び出しに失敗してもセッションは次の呼び出しに使用できることを、tests/test_server_process.py が実際の stdio 接続で検証しています。

このサーバーが意図的に行わないこと

• ハードウェアも認証情報も外部ネットワーク通信もありません。 FlagQuantum のリリース 0.2.0 にはリモート送信のエントリーポイントがなく、このアダプターも追加しません。HTTP トランスポートはリスニングソケットを開きますが、リクエストの到着後にツールが実行できることは何も変わりません。
• 命令レベルの NoiseModel オブジェクトは扱いません。 これらはシリアライズ可能な値ではなく、実行時の SDK オブジェクトです。連続時間の時間発展では、代わりに物理レートを含む、閉じた JSON 崩壊演算子記述子を受け付けます。
• ツリー内では連携しません。 このパッケージを FlagQuantum リポジトリからインポートしてはなりません。このプロジェクトの長期的なアーキテクチャ契約では、「メインリポジトリに本番用 MCP トランスポート依存関係がないこと」を廃止条件として定めており、tests/team/services/test_service_boundaries.py は、コアパスで mcp または fastmcp がインポート可能になると失敗します。ゲートウェイをツリーの外に置くことが、この契約の求めるところです。

実行することと、それが証明しないこと

plan_evolution_tool と evolve_dynamics_tool は、独立した連続時間の契約を使用します。ハミルトニアンと観測量はパウリ項のリスト、初期状態は基底ビット列または密状態、時刻は明示的かつ厳密に単調増加する値であり、振幅減衰はチャネル確率ではなくリンドブラッド方程式の物理レートです。実行ツールは、要求された時刻ごとに 1 行の人口データ、トレースのドリフト、有界人口のチェック、および数値手法／次数／ステップサイズ／精度の来歴を返します。どちらのツールも、プロバイダー、認証情報、ハードウェア、外部ネットワークアクセスを必要としない、ローカル CPU 上の決定論的な処理です。

simulate_circuit_tool は、このプロセス内で回路を実行します。CPU 上の状態ベクトルシミュレーションです。それがすべてです。リモートターゲットも、プロバイダーも、トークンもありません。最初からここにあったわけではありません。追加されるまでは、サーバーは計画を立てるだけで実行はせず、上の行もそのように書かれていました。実際のタスクでそのコストが明らかになったため、ツールをこっそり追加するのではなく、その行を変更しました。

実行場所は、要約ではなく SDK 独自のフィールドで結果に示されます。

"execution": {
  "execution_path": "local_statevector",
  "platform_provider": "pytorch_cpu",
  "mode": "statevector",
  "device": "cpu",
  "accuracy": {"metric": "not_measured", "...": "..."}
}

accuracy.metric は not_measured であり、同じ回路について plan_execution_tool は release_gate_allowed: false を報告します。この 2 つ目のフィールドは計画のもので、その summary にあります。上記のシミュレーション結果には execution、outputs、status が含まれ、accuracy ブロックには 5 つのフィールド（version、metric、value、tolerance、passed）があります。回路の理想シミュレーションが示すのは、その回路についてのことであり、それを実行するデバイスについてではありません。SDK はそれ以上の解釈を認めておらず、このサーバーもそれを付け加えません。

もっともらしい答えを返すことになるため、解釈を変えて受け入れるのではなく、拒否する入力が 3 つあります。

入力	拒否する理由
パラメーターが未束縛の回路	SDK の拒否メッセージは planned execution failed で、何が失敗したのかを示しません。ここではパラメーター名を示し、bind_parameters_tool を案内します
observables を含む回路	デフォルトの状態ベクトルパスはこのフィールドを読み取らないため、実行しても期待値もエラーも返りません。代わりに pauli または terms を使って期待値を直接要求してください
回路独自の measurements と同時に指定された outputs	SDK はどちらか一方を受け付け、そのことを、いずれのフィールド名も使わない用語で説明します

完全な確率分布を返せなくなる幅は SDK 独自の縮約限界であり、そのメッセージはこのサーバーが公開していない設定を示します。この拒否では SDK の文言を維持しながら、呼び出し元が実際にできることも追加します。少数のワイヤーを指定するか、発生した結果だけを報告する counts を要求してください。

エネルギーの測定

{"kind": "expectation", "pauli": "ZZ"} は1つの項を評価します。ハミルトニアンは重み付き和なので、代わりに terms を指定します。

{"kind": "expectation",
 "terms": [{"pauli": "ZZZZ", "coefficient": 1.0},
           {"pauli": "XIII", "coefficient": -1.0}]}

各項は、その coefficient と値を含む個別の行として返されます。これは SDK の計算内容をそのまま反映したものです。つまり、和を項ごとに評価し、合計は計算しません。したがって、⟨H⟩ は呼び出し側で計算します。

energy = sum(row["coefficient"] * row["value"][0] for row in rows)

これは利便性のためではなく、意図的な仕様です。ここで計算した合計値は、SDK が生成した値ではなく、このサーバーもその値の出どころを示せません。一方、項ごとの行があれば結果を監査でき、どの項が支配的だったかを確認できます。coefficient が表示されるのは、SDK が係数を設定した行だけです。つまり、重み付き期待値の項に限られます。

係数には実数を指定する必要があります。シンボルは受け付けられません。Z(0) * Parameter は観測量ではなくパラメーター式を構築するため、評価するものがありません。先に回路のゲートに値を設定してください。重み付けされていない単一の項も、引き続き "pauli": "ZZ" と記述します。この2つの記述は同じコードパスを通るため、動作に差が生じることはありません。

エネルギーの最小化

simulate_circuit_tool はエネルギーを評価します。train_parameters_tool は、状態ベクトルシミュレーションで報告される厳密な勾配を使って、エネルギーを小さくします。

{
  "circuit": "[{\"name\": \"ry\", \"index\": [0], \"parameters\": {\"theta\": {\"$parameter\": \"t0\"}}}]",
  "circuit_format": "qir",
  "hamiltonian": [{"pauli": "Z", "coefficient": -1.0}, {"pauli": "X", "coefficient": 1.0}],
  "steps": 100,
  "learning_rate": 0.1
}

各ステップ後の損失、終了時のパラメーター、開始時のパラメーターが返されます。実行を再開する場合は、返された parameters を values に設定して再度呼び出してください。

hamiltonian 引数は、expectation の出力で使うものと同じ項のリストで、必須です。目的関数がなければ、最小化する値はエネルギーではありません。各ワイヤーに1文字です。上の回路は1ワイヤーなので、各項は1文字です。2ワイヤーの回路では "ZZ" を指定します。回路と長さが一致しない項は、実行前に拒否されます。

呼び出す前に知っておきたい制限が2つあります。トレーニングはシミュレーションよりはるかに高コストです。実測では、16量子ビットの1ステップに85 msかかる一方、シミュレーションは数 msです。そのため、予測コストが FLAGQUANTUM_MCP_MAX_TRAIN_SECONDS を超える実行は、開始前に拒否されます。メッセージには予測値、幅、ステップ数が含まれます。幅の上限付近で支配的になるコストは状態の保持です。モデルによると、24ワイヤーではゲートを1つも適用する前から1ステップあたり25.2秒かかるため、24ワイヤーの回路では2ステップを超えて実行できません。また、ここで測定した71命令のレイヤー型アンザッツは、1ステップあたり119秒と予測されるため、実行できるステップはありません。これは幅ではなく回路についての説明です。24ワイヤーでもゲート1つなら予算内です。また、拒否の基準は幅ではなく予測コストです。そのため、同じ理由で幅の狭い多層回路も制限されます。2500命令の4ワイヤー回路は1ステップあたり0.5秒と予測されます。デフォルトの予算では、同じ幅のゲート1つの回路が3000ステップ実行できるときに、この回路は119ステップ実行できます。

そして、結果はあくまで結果です。損失曲線と角度の集合が返されます。実行が収束したかどうかは利用者が判断することであり、このツールが収束を主張することはありません。また、SDK の accuracy.metric == "not_measured" は、シミュレーションの場合と同様に実行結果に含まれます。

依拠するコントラクト

FlagQuantum は、名前付き検証テストがそれぞれ対応する、凍結済みの stable_exports スナップショット（31 個の名前）を公開し、flagquantum.compiler を「安定したエキスパート向けコンパイラーインターフェース」として説明し、各パッケージで独自の __all__ を宣言できるようにしています。このサーバーはこの 3 つの階層すべてを使用しており、tests/test_api_contract.py では各階層のメンバーを固定しています。

階層	対象範囲	使用箇所
1. 凍結済みスナップショット	Circuit、CircuitIR、Instruction、IR_VERSION、ExecutionOptions、ExecutionPlan、plan、Parameter、RuntimePolicy、…	analyze、serialize、deserialize、plan、パラメーターの検査／バインド、train_parameters
2. ドキュメント化されたモジュール	flagquantum.compiler：CouplingMap、optimize、route_to_topology、schedule_layers	optimize、route、compare、レイヤーの説明
3. 公開されているが凍結されていないもの	flagquantum.compiler.openqasm.emit_openqasm、flagquantum.compiler.qcis.emit_qcis、flagquantum.drawer.draw、flagquantum.core.{operator_manifest,gate_info,canonical_opcode}、flagquantum.algorithms.{Hamiltonian, pauli_term}	emit_openqasm、emit_qcis、draw、ゲートの検証、train_parameters

階層 3 は最も保証が弱く、単なる飾りではありません。 ゲートの検証には、各ゲートのワイヤー数とパラメーター名が必要であり、その唯一の根拠となるのは SDK のオペレーターマニフェストです。呼び出し側は回路フォーマットからこれらを推測できず、ここで再実装すれば、ずれが生じる二つ目の信頼できる情報源を作ることになります。マニフェストは、移動があった場合にツール呼び出し内で AttributeError が発生するのではなく、名前付きエラーに変換するヘルパーを通じて取得されます。また、階層 3 の名前はすべてテストで固定されているため、上流で移動があればユーザーに影響が及ぶ前にビルドが失敗します。防止するのは、より弱いゲート検査で誤記されたパラメーターが受け入れられ、破棄されるような、気づきにくい失敗です。

トレーニングツールは、階層だけでは説明しきれない唯一の箇所です。その目的関数には、凍結されていない flagquantum.algorithms 由来の Hamiltonian と pauli_term の 2 つの名前に加え、凍結されている名前が 1 つ必要です。RuntimePolicy は凍結済みスナップショットに含まれていますが、スナップショットで固定されるのは名前だけです。ハミルトニアンが実行に反映されるかどうかは、デフォルトが "z" である RuntimePolicy().observable によって決まるため、スナップショットにその値も含まれると信頼せず、tests/test_api_contract.py でそのデフォルト値も固定しています。

依存関係は flagquantum>=0.3.1,<0.4 に固定されています。これはバージョン範囲であり、git URL ではありません。依存関係テーブルに URL を指定すると、異なる上流リビジョンをインストールするすべての環境で依存関係を解決できなくなります。

機能カバレッジに関する判断

contracts/sdk-capability-coverage-v1.json には、固定された #632 以降の FlagQuantum ソースマニフェストにある、本番環境でサポートされる機能またはリリース認定済みの機能すべてに対する判断が記録されています。FlagQuantum 0.3.1 は、互換性のあるコアホイールとして初めて公開されたバージョンです。各判断では、このサーバーで提供する範囲を限定したツールを指定するか、ツールを公開しない理由を説明します。既存の描画ツール 1 つは、レガシーの実験的な例外として個別に記録されています。この台帳は、ほかの実験的なツールを追加する根拠にはなりません。CI チェッカーは、これらの判断を固定された上流の capability-maturity.toml およびサーバーが宣言するツール範囲と比較します。新たに対象となる機能、または判断が記録されていない MCP ツールがある場合、チェックは失敗します。

この台帳は公開範囲の監査であり、すべての Python 関数が MCP 経由で利用できるという主張ではありません。インストール済みパッケージとの互換性テストに代わるものでもありません。現在の flagquantum>=0.3.1,<0.4 依存関係は、テストマトリックスと、クリーンな環境にインストールしたホイールを使った MCP ハンドシェイクで別途検証されています。ソースの対応付けだけでは、新しいツールの追加は許可されず、将来の FlagQuantum リリースが動作することの証明にもなりません。

固定されたソースをローカルで確認するには、FlagQuantum のコミット 5c78e1d3b3fad31af5bce9e785ca8a1954229cf7 をチェックアウトし、次を実行します。

python tools/check_capability_coverage.py --upstream-root /path/to/FlagQuantum

開発

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/mypy --config-file ../mypy.ini src
.venv/bin/pytest -m "not integration"

リポジトリの README と CONTRIBUTING.md を参照してください。

ライセンス

Apache-2.0。