tooluniverse-claude-code-plugin

# Install the ToolUniverse Plugin for Claude Code One-step install of the ToolUniverse plugin: MCP server with 1000+ tools, 120+ research skills, slash commands, and the research agent — all auto-configured. ## Prerequisites (check once) ```bash uv --version # must exist; if not: curl -LsSf https://astral.sh/uv/install.sh | sh claude --version # Claude Code CLI; if not: https://claude.com/claude-code ``` ## Install ```bash # 1. Register the ToolUniverse marketplace from GitHub claude plugin marketplace add mims-harvard/ToolUniverse # 2. Install the plugin claude plugin install tooluniverse@tooluniverse ``` That's it. Restart Claude Code. The MCP server auto-starts via `uvx tooluniverse` on first use (~30 s cold start, instant after). ### Recommended: turn on auto-update Third-party marketplaces default to **no auto-update** — without this, new tools/skills only reach you when you remember to run `claude plugin update tooluniverse` (see Update below). Turn it on once: ```bash python3 -c " import json, pathlib, sys p = pathlib.Path.home() / '.claude/plugins/known_marketplaces.json' d = json.loads(p.read_text()) if 'tooluniverse' not in d: sys.exit('Run the marketplace add command above first') d['tooluniverse']['autoUpdate'] = True p.write_text(json.dumps(d, indent=2)) print('autoUpdate enabled for tooluniverse') " ``` Equivalent interactive path: `/plugin` → Marketplaces → `tooluniverse` → Enable auto-update. With this on, Claude Code checks for marketplace + plugin updates in the background after each session start (up to a ~10 min random delay) and updates the installed plugin on disk automatically. You'll get a `/reload-plugins` prompt when an update lands, or it applies on your next launch — no more manual `claude plugin update`. This is local, per-machine state — it can't be shipped as a default from the plugin's own manifest. `marketplace.json` has no `autoUpdate` field; Claude Code intentionally keeps this a per-installation trust boundary so a publisher can't force silent auto-updates onto a user's machine. ### Important: Remove global skills if previously installed If you previously installed ToolUniverse skills globally (via `tooluniverse-install-skills` or manual copy), **remove them**. The plugin includes all skills — global copies interfere with the plugin's skill routing. ```bash # Check for global skills ls ~/.claude/skills/tooluniverse-* 2>/dev/null | wc -l # Remove them (the plugin replaces them) rm -rf ~/.claude/skills/tooluniverse-* rm -rf ~/.claude/skills/create-tooluniverse-skill rm -rf ~/.claude/skills/setup-tooluniverse ``` ### Pin the tool version (optional, for reproducibility) The MCP server runs the `tooluniverse` PyPI package via `uvx`. To lock tool behavior for a long-running analysis, pin the package version in the plugin's `.mcp.json` — change the args to: ```json "args": ["tooluniverse@1.2.2"] ``` Replace `1.2.2` with any released version from https://pypi.org/project/tooluniverse/. Restart Claude Code to apply. (`.mcp.json` location is shown under "API keys" below.) ## Verify it worked ```bash claude plugin list # Expect: tooluniverse (enabled) ``` Inside Claude Code, just ask naturally: ``` What are the top mutated genes in breast cancer? Research the drug metformin. ``` The router skill auto-dispatches to the right specialized skill — no command prefix needed. ## What you get | Component | What it does | How to invoke | |---|---|---| | **MCP server** | 1000+ tools via `find_tools`, `get_tool_info`, `execute_tool` | Auto-loaded; no action needed | | **`/tooluniverse:research`** | Multi-database investigation inline in this chat (you see each step) | Slash command | | **`/tooluniverse:translate-id`** | Resolve an ID across all relevant namespaces | Slash command | | **`/tooluniverse:cross-validate`** | Verify a claim across 3+ independent databases | Slash command | | **`/tooluniverse:compare`** | N-way side-by-side comparison with domain-appropriate columns | Slash command | | **`/tooluniverse:literature-sweep`** | Graded mini-review across PubMed + EuropePMC + Semantic Scholar | Slash command | | **`/tooluniverse:verify-references`** | Check that cited references are real and accurately described, including retraction status | Slash command | | **`/tooluniverse:self-review`** | Review current or supplied work against its actual goal; qualitative by default, with scoring only when explicitly requested | Slash command | | **`/tooluniverse:setup-keys`** | Configure ToolUniverse API keys | Slash command | | **`/tooluniverse:researcher`** | Same investigation as `research`, delegated to a forked subagent | Slash command | | **120+ skills** | Structured workflows (drug research, variant interpretation, pharmacovigilance, CRISPR screens, statistical modeling, etc.) | Auto-activate on matching questions | ## API keys (optional, but recommended) Most tools work without keys. For enhanced access, add the keys you care about to the MCP server's `env` block. Locate the installed plugin's `.mcp.json`: ```bash # Show component inventory + on-disk location: claude plugin details tooluniverse # Or find the file directly: find ~/.claude/plugins -name '.mcp.json' -path '*tooluniverse*' # Typical install location after marketplace install: # ~/.claude/plugins/cache/tooluniverse/tooluniverse/<version>/.mcp.json ``` ```json { "mcpServers": { "tooluniverse": { "command": "uvx", "args": ["tooluniverse"], "env": { "PYTHONIOENCODING": "utf-8", "NCBI_API_KEY": "your_key", "NVIDIA_API_KEY": "your_key", "ONCOKB_API_TOKEN": "your_token" } } } } ``` Full API-key list: `setup-tooluniverse` skill → `API_KEYS_REFERENCE.md`. ## Update If you enabled auto-update above, this happens automatically in the background — no action needed. Otherwise, update manually: ```bash claude plugin update tooluniverse # Also refresh the MCP server's tool cache: uv cache clean tooluniverse ``` Restart Claude Code. ## Uninstall ```bash claude plugin uninstall tooluniverse claude plugin marketplace remove tooluniverse ``` ## Alternative install paths ### Clone + local install (air-gapped or forks) ```bash git clone https://github.com/mims-harvard/ToolUniverse.git cd ToolUniverse claude plugin marketplace add ./ claude plugin install tooluniverse@tooluniverse ``` ### Download the release zip (no git needed) Grab `tooluniverse-plugin-vX.Y.Z.zip` from https://github.com/mims-harvard/ToolUniverse/releases, unzip, then: ```bash claude plugin marketplace add /path/to/unzipped-dir claude plugin install tooluniverse@tooluniverse ``` ## Troubleshooting | Symptom | Fix | |---|---| | `marketplace add` fails with "no marketplace.json" | Ensure you're using `mims-harvard/ToolUniverse` (owner/repo), not the plugin subdir. | | `uvx: command not found` | Install `uv` (see Prerequisites), reopen terminal. | | MCP server won't start | Test in terminal: `uvx tooluniverse`. If it fails there, it's an `uv`/Python issue. | | Plugin installs but tools missing | Restart Claude Code. First launch downloads the package (~30 s). | | `requires-python >= 3.10` | `uv python install 3.12` | | Tools feel outdated | `uv cache clean tooluniverse` then restart Claude Code. | | New release not picked up / tools run an OLD version | Run `uv tool list \| grep tooluniverse`. If it's listed, a global `uv tool install` is **shadowing** the plugin's `uvx` (uvx prefers an installed tool over the latest published version). Fix: `uv tool uninstall tooluniverse`, then restart. Normal users without that install always get the latest automatically. | Still stuck: https://github.com/mims-harvard/ToolUniverse/issues ## Automated diagnosis & repair If the table above didn't fix it, hand this skill to an agent — *"read the tooluniverse-claude-code-plugin skill and diagnose & fix my plugin install"* — or run these checks yourself in order. Each is safe and idempotent; apply the `FIX` for whatever fails, then restart Claude Code. ```bash # 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 actually resolve + run? (non-hanging proxy for the server) uvx --from tooluniverse tu --version || echo "FIX: uv/Python issue — see steps 1 and 5" # 3. Running an OLD version even after updating? (non-obvious!) uv tool list | grep -q tooluniverse \ && echo "FIX: uv tool uninstall tooluniverse (a global install shadows the plugin's uvx)" \ || echo "ok: nothing shadowing uvx" # 4. A new pip version was released but tools still stale? force a refresh uv cache clean tooluniverse # or one-shot: uvx --refresh tooluniverse --version # 5. Python too old (requires >= 3.10)? uv python install 3.12 # 6. Global skills interfering with the plugin's routing? ls ~/.claude/skills/tooluniverse-* 2>/dev/null && echo "FIX: rm -rf ~/.claude/skills/tooluniverse-*" # 7. Is the plugin actually enabled? claude plugin list | grep tooluniverse || echo "FIX: claude plugin install tooluniverse@tooluniverse" ``` An agent can run the whole sequence, apply each `FIX`, and tell you to restart — you don't need to understand the internals. ## For plugin maintainers This skill documents the **user-facing** install flow. The plugin source lives at `/plugin` in the repo with its own `.claude-plugin/plugin.json` and `.mcp.json`. The root `.claude-plugin/marketplace.json` is what makes `claude plugin marketplace add mims-harvard/ToolUniverse` work directly — it lists the plugin with `"source": "./plugin"`. When cutting a **plugin** release: - Easiest: put `[release:patch]` (or `:minor`/`:major`) in a commit message that touches `plugin/` or `.claude-plugin/` on `main`. `auto-release.yml` runs `scripts/release-plugin.sh`, which bumps `plugin/.claude-plugin/plugin.json` + root `.claude-plugin/marketplace.json`, commits, and tags; the tag push triggers `release-plugin.yml` to build the zip + GitHub Release. (Or run "Auto-release plugin" from the Actions UI.) - The next-version baseline is `max(plugin.json, latest vX.Y.Z tag)`, so a manifest that has drifted behind the tag line won't collide with an existing tag. - Plugin auto-update reaches users as soon as the version-bump commit lands on `main` (independent of the tag/zip). The **pip package** (`tooluniverse` on PyPI) is a SEPARATE release line: bump `pyproject.toml` → `publish-pypi.yml` publishes it (→ `publish-mcp-registry.yml`). Plugin and pip versions need NOT move together — `uvx tooluniverse` auto-resolves to the latest published pip version for users, so plugin-only and pip-only releases are both fine.