Skip to main content
Glama
io.github.KoyoYeager/pystub

io.github.KoyoYeager/pystub

by KoyoYeager

verify

Checks generated stubs by importing project modules in the target Python environment, removes stubs that cause new failures, and returns verified stub sets for safe application.

Instructions

スタブに差し替えた状態を、対象環境の python で実際に import して確かめます(任意実行)。

警告: run_entry=True と実行の記録(record=True)は対象のプログラムを実際に実行します。ファイルの書き込み・削除、通信、機器の操作などの副作用が 起きえます。AI エージェントは、利用者が明示的に求めた時だけ run_entry=True / record=True を指定してください。GUI や常駐型の プログラムは終了しないので timeout で打ち切られます。既定(run_entry=False)は import だけで、別の子プロセスでグラフ上のモジュールを import します(各モジュールの直下のコードは動きますが、エントリーのスクリプトは動かしません。エントリーを import するローカルのモジュールは対象から外し、import の途中でエントリーのファイルを開く操作は止めます。Python の open を通る読み込みは、別名(短いパス名・拡張パス形式・UNC・ハードリンク)でも、ファイルの同一性で見分けて止めます。OS のコピー API(shutil.copy2 の CopyFile2 など)、ctypes、外部コマンド(cmd /c type 等)での読み込みと、それでコピーしたファイル経由の import(zipimport 等)は止められません)。run_entry=True のエントリーは、標準出力をファイルにつないだ普段の起動と同じ条件(主な違いは PYTHONPATH の先頭の起動用フォルダと環境変数 MCP_PYSTUB_BOOT の 2 つ。ほかの違いは docs/safety.md の表を参照: 標準入力は空、標準出力はファイル、import sitecustomize が成功する、元のパッケージのファイルがディスクに残る、など。子プロセスは監査イベントで分かる起動を親子の対応で確かめ、ctypes・COM / WMI 経由の起動は検出できません。MPLBACKEND などは付けないので、窓を開くエントリーは呼ぶ側の環境変数で指定してください)で動かします。timeout は子プロセス 1 回あたりで、打ち切った時と終わった後は孫を含むプロセスの木を止めます。結果の verified_sets(確かめた組)をそのまま適用してください。一部だけを適用するなら、その組で確かめ直してください。確認済み(実行)は、docs/safety.md の「普段の実行との違い」の表の範囲で、動かした入力について確かめた結果です。配布前に、ビルドした exe を普段のやり方で試してください。

静的解析(analyze)は候補を出すだけです。verify は生成したスタブを一時フォルダに置き、対象環境の python を子プロセスで起動して、import グラフ上の全モジュールを import します。site-packages は 書き換えません。スタブ無しの基準と比べて新たに失敗したものの原因のスタブを外し、検証を通った組を返します。

Args: entry_point: プロジェクトのエントリーポイント python_path: 対象環境の site-packages(空なら現在の環境) packages: 確かめるスタブ化パッケージ(省略時は analyze の stubbable) submodules: 確かめるサブモジュール("asammdf.gui=>PySide6" の形で対象の C 拡張も指定。省略時は analyze のヒント) nofollow: 除外して確かめるパッケージ(省略時は analyze の nofollow) run_entry: True ならエントリー本体も実行して出力を元と比べる(False では import だけを確かめる) timeout: 子プロセス 1 回あたりの制限時間(秒) entry_args: エントリーに渡す引数(sys.argv[1:]。既定は空) cwd: エントリーを実行する作業フォルダ(既定はエントリーのあるフォルダ) record: True かつ run_entry=True のとき、基準(スタブなし)のエントリー実行で実行の記録も取る(追加の実行はしない) trace_files: 利用者が python -m mcp_pystub.trace で作った記録ファイル(合算して各項目の観測の区分に使う)

Returns: passed: 検証を通った組 / rejected: 外した項目と失敗の原文 / unresolved: 原因を特定できなかった項目 (passed には入れない)/ entry_matched・entry_note: エントリーの出力の一致(確かめていない時はその旨)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "entry_point": "<entry_point>"
    },
    "name": "verify"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNo
recordNo
timeoutNo
nofollowNo
packagesNo
run_entryNo
entry_argsNo
submodulesNo
entry_pointYes
python_pathNo
trace_filesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.3.1

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly: it names side effects of run_entry (file writes/deletes, network, device control), explains that GUI/resident programs hang and are cut off by timeout, states that site-packages is never modified and stubs go to a temp folder, and describes how the process tree is killed after timeout. It even discloses the limits of its own safeguards (OS copy APIs, ctypes, external commands, zipimport, ctypes/COM/WMI child launches cannot be blocked or detected).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical routing and safety guidance appears early, which is good, but the body is heavily overloaded with run-on parentheticals about file-identity detection, shutil.copy2/CopyFile2, ctypes and cmd /c type that bury the actionable information. It is denser and longer than an agent needs to select and invoke the tool correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter tool with no annotations and no output schema, the description covers arguments, safe defaults, side-effect envelope, failure modes, and even a Returns section (passed / rejected / unresolved, entry_matched / entry_note). Nothing essential for correct invocation is missing, and return values are described despite the absence of a structured output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 11 parameters, and the Args section compensates by explaining every one, including non-obvious semantics such as python_path being the target site-packages (empty = current env), packages defaulting to analyze's stubbable set, the "asammdf.gui=>PySide6" form for submodules, timeout being per subprocess, and record only taking effect with run_entry=True. This is meaning well beyond the schema's bare titles and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and mechanism: it confirms the stubbed state by actually importing modules with the target environment's python. It explicitly distinguishes itself from the sibling analyze ("静的解析(analyze)は候補を出すだけです。verify は..."), so an agent can tell the two apart without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use and when-not-to-use guidance: the default run_entry=False is import-only, the AI agent should set run_entry=True / record=True only when the user explicitly asks, and there is a direct alternative-routing statement versus analyze. It also instructs how to apply results (apply verified_sets as-is, or re-verify a subset), leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools