tooluniverse-codex-plugin

OpenAI Codex 用 ToolUniverse プラグインをインストールする

Codex にワンステップでインストールできます。1000 以上の科学ツールと 130 以上の研究スキルを公開する MCP サーバーがすべて自動設定されます。（Claude Code 版については、tooluniverse-claude-code-plugin をご覧ください。）

前提条件（最初に一度だけ確認）

uv --version     # provides `uvx`; if missing:  curl -LsSf https://astral.sh/uv/install.sh | sh
codex --version  # OpenAI Codex CLI; if missing: https://developers.openai.com/codex

インストール（2 つのコマンド）

# 1. Register the ToolUniverse marketplace from GitHub
codex plugin marketplace add mims-harvard/ToolUniverse

# 2. Install the plugin from that marketplace
codex plugin add tooluniverse -m tooluniverse

Codex を再起動してください。初回使用時に、MCP サーバーが uvx tooluniverse 経由で自動起動します（パッケージのダウンロード中は初回起動に約 30 秒かかりますが、以降はすぐに起動します）。

mims-harvard/ToolUniverse は owner/repo 形式の省略表記のため、Codex には Git マーケットプレイスとして登録されます。これにより自動更新が有効になります（「更新」を参照）。プラグインのサブフォルダーや URL を直接指定しないでください。

インストールを確認する

codex plugin list           # expect: tooluniverse (enabled)
codex plugin list --json    # the JSON includes the installed "version"

あとは、Codex 内で自然な言葉で質問するだけです。

What are the top mutated genes in breast cancer?
Research the drug metformin.

研究スキルは該当する質問に応じて自動的に有効になり、MCP ツールは find_tools → execute_tool を通じて検出・実行されます。コマンドのプレフィックスは不要です。

利用できるもの

コンポーネント	機能	使用方法
MCP サーバー	find_tools、get_tool_info、execute_tool 経由で 1000 以上のツールを提供	自動で読み込まれます。操作は不要です
130 以上のスキル	創薬、バリアント解釈、ファーマコビジランス、系統学、統計モデリングなどの体系的な研究ワークフロー	該当する質問に応じて自動的に有効になります

Claude Code プラグインとは異なり、Codex プラグインに含まれるのは MCP ツールとスキルのみ です。スラッシュコマンドはありません。自然な言葉で質問するだけで操作できます。

API キー（任意ですが、推奨）

ほとんどのツールはキーなしで動作します。レート制限の緩和や、アクセスが制限されたデータベースを利用するには、Codex を起動する環境で必要なキーを設定してください。MCP サーバー（uvx tooluniverse）はこれらのキーを引き継ぎます。

export NCBI_API_KEY="your_key"
export ONCOKB_API_TOKEN="your_token"
export SEMANTIC_SCHOLAR_API_KEY="your_key"
# ...then start codex from that same shell

環境変数のエクスポートは、プラグインをアップグレードしても保持されるため、確実な方法です。（インストール済みプラグインのキャッシュ内にある .mcp.json の env ブロックを編集する方法もありますが、キャッシュされたコピーは更新のたびに置き換えられます。詳しくは以下をご覧ください。）

キーの全一覧については、同梱の setup-tooluniverse スキルにある API_KEYS_REFERENCE.md をご覧ください。

更新

Codex は、デフォルトで起動時に Git マーケットプレイスを自動アップグレードします。mims-harvard/ToolUniverse（owner/repo）を Git マーケットプレイスとして追加しているため、新しいバージョンが公開されると、特に操作しなくても次回の Codex 起動時に反映されます。（codex plugin update コマンドはありません。更新はマーケットプレイスを通じて行われます。）

待たずに手動で更新するには、次を実行します。

codex plugin marketplace upgrade              # all configured Git marketplaces
codex plugin marketplace upgrade tooluniverse # just this one

TUI で /plugins を開き、マーケットプレイスのタブで Ctrl+U を押してください。

ツール本体は uvx 経由で tooluniverse PyPI パッケージから取得されます。アップグレード後もツールが古いように感じられる場合は、uvx のキャッシュを消去してください。

uv cache clean tooluniverse

ツールのバージョンを固定する（任意、再現性を確保する場合）

長期間にわたる分析でツールの動作を固定するには、インストール済みプラグインの .mcp.json を編集し、パッケージのバージョンを指定します。

"args": ["[email protected]"]

1.3.0 を https://pypi.org/project/tooluniverse/ にある任意のリリースに置き換えてから、Codex を再起動してください。（ファイルは ~/.codex/plugins/cache/ 内にあります。）

アンインストール

codex plugin remove tooluniverse
codex plugin marketplace remove tooluniverse

別のインストール方法（ローカルチェックアウト／エアギャップ環境）

git clone https://github.com/mims-harvard/ToolUniverse.git
codex plugin marketplace add ./ToolUniverse
codex plugin add tooluniverse -m tooluniverse

ローカルパスで追加したマーケットプレイスは、自動アップグレードされません（自動アップグレードの対象は owner/repo 形式の Git マーケットプレイスのみです）。新しいコミットを取得した後、codex plugin marketplace upgrade を再実行するか、Codex を再起動してください。

トラブルシューティング

症状	対処方法
marketplace add が失敗する	プラグインのサブフォルダーへのパスや生の URL ではなく、mims-harvard/ToolUniverse（owner/repo）を使用してください。
uvx: command not found	uv をインストールし（「前提条件」を参照）、ターミナルを開き直してください。
プラグインはインストールされたが、ツールが表示されない	Codex を再起動してください。初回起動時にパッケージがダウンロードされます（約 30 秒）。サーバーの簡易チェックとして、ターミナルで uvx tooluniverse を実行してください。
MCP サーバーが起動しない	通常のターミナルでも uvx tooluniverse が失敗する場合、問題は Codex ではなく uv／Python にあります。
requires-python >= 3.10	uv python install 3.12
更新後もツールが古いように感じる	uv cache clean tooluniverse を実行し、Codex を再起動してください。
更新が反映されない	自動アップグレードは Git マーケットプレイス（owner/repo）にのみ適用されます。ローカルパスを追加した場合は、codex plugin marketplace upgrade を実行してください。
ツールが古いバージョンで動作する	uv tool list | grep tooluniverse を実行してください。グローバルな uv tool install tooluniverse は uvx を 優先してしまいます。対処するには、uv tool uninstall tooluniverse を実行してから再起動してください。

まだ解決しない場合：https://github.com/mims-harvard/ToolUniverse/issues

自動診断と修復

このスキルをエージェントに渡して「tooluniverse-codex-plugin スキルを読んで、Codex プラグインを診断して修正してください」と指示するか、以下を順番に実行してください。どれも安全で冪等です。失敗した項目に対応する FIX を適用してから、Codex を再起動してください。

# 1. Is uv/uvx installed?  (most common cause of "no tools at all")
command -v uvx || echo "FIX: curl -LsSf https://astral.sh/uv/install.sh | sh"

# 2. Can the MCP package resolve + run?  (non-hanging proxy for the server)
uvx --from tooluniverse tu --version || echo "FIX: uv/Python issue — see steps 1 and 6"

# 3. Is the plugin installed + enabled?
codex plugin list | grep -q tooluniverse || echo "FIX: codex plugin add tooluniverse -m tooluniverse"

# 4. Running an OLD version even after updating?  (a global install shadows uvx)
uv tool list | grep -q tooluniverse \
  && echo "FIX: uv tool uninstall tooluniverse" \
  || echo "ok: nothing shadowing uvx"

# 5. Pull the latest plugin version now (don't wait for next startup)
codex plugin marketplace upgrade tooluniverse

# 6. Python too old (requires >= 3.10)?
uv python install 3.12

# 7. Force a fresh tool package
uv cache clean tooluniverse        # or one-shot: uvx --refresh tooluniverse --version

プラグインのメンテナー向け

このスキルでは、ユーザー向けのインストール手順を説明しています。Codex プラグインのソースは plugins/tooluniverse/ にあり、独自の .codex-plugin/plugin.json、.mcp.json、skills/ を備えています。リポジトリのルートにある .agents/plugins/marketplace.json により、codex plugin marketplace add mims-harvard/ToolUniverse が機能します。このファイルでは、プラグインを "source": {"source": "local", "path": "./plugins/tooluniverse"} として登録しています（外部リポジトリではなく、クローンしたマーケットプレイスリポジトリ内のパスです）。

• スキルは生成されたコピーです。正規の skills/ ツリーを編集してから、plugin/sync-skills.sh を実行してください。このスクリプトは Claude と Codex の両方のスキルセットを再構築し、Codex 固有の正規化を適用します（Codex が無視する disable-model-invocation マーカーの削除、Codex の説明文の上限である 1024 文字を超える説明の短縮）。
• Codex プラグインのバージョンは plugins/tooluniverse/.codex-plugin/plugin.json にあります。scripts/release-plugin.sh は Claude のマニフェストとともにバージョンを更新し、両プラグインが <package MAJOR.MINOR>.<plugin revision> にそろうようにします。
• Codex はバージョン文字列とは無関係に、git push（起動時の自動アップグレード）を通じて更新を配信します。ただし、バージョンの更新により両プラグインの整合性が保たれ、Codex のバージョンごとのキャッシュにも対応できます。