setup-tooluniverse

# Setup ToolUniverse Guide the user step-by-step through setting up ToolUniverse. ## Agent Behavior - **Detect language** from user's first message. Respond in their language; keep commands/URLs in English. - Go **one step at a time**. Ask before proceeding. - Use **AskQuestion** for structured choices. - **Explain briefly** in plain language. Celebrate small wins. - When something goes wrong, help troubleshoot before moving on. ## Internal Notes (do not show) ToolUniverse has 2,700+ tools. The `tooluniverse` command enables compact mode automatically, exposing only 5 core MCP tools (list_tools, grep_tools, get_tool_info, execute_tool, find_tools) while keeping all tools accessible via execute_tool. ## What is ToolUniverse? **Always explain first, in plain language:** ToolUniverse is free, open-source software connecting to 2,000+ scientific databases (PubMed, UniProt, ChEMBL, FAERS, ClinicalTrials.gov, etc.). Instead of visiting each website, you search from one place. Think of it like a universal remote for scientific databases. **Why AI assistants?** The AI reads your question, figures out which databases to search, runs queries, and summarizes results. You just ask your question. ## Step 1: Choose How to Use It Present using AskQuestion: | Mode | What it means | Who it's for | |------|---------------|-------------| | **Chat mode** | Ask questions to an AI assistant. No coding. | Most researchers. | | **Command line** | Type short commands in Terminal. | Quick tests. Terminal-comfortable users. | | **Python code** | Write scripts for automated pipelines. | Programmers. | Options: "I want to ask questions" → Chat mode | "Quick try" → CLI | "I write Python" → SDK | "I don't know" → Recommend Chat mode **If Chat mode**, ask which app (AskQuestion): Cursor, Claude Desktop, VS Code/Copilot, Windsurf, Claude Code, Gemini CLI, Codex, Cline/Trae/Antigravity/OpenCode. "I don't have any" → Recommend [Claude Desktop](https://claude.ai/download). ## Step 2: Install uv Only prerequisite: `uv` (manages everything else automatically). **Terminal help** (if needed): Mac: Cmd+Space → "Terminal" → Enter. Windows: Win key → "PowerShell" → Enter. ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` (This is a safe, standard command that downloads and installs `uv`, a small package manager. It's widely used by Python developers. Close and reopen your terminal after it finishes.) Verify: `uv --version` ## CLI Setup Make sure Step 2 is done, then try: ```bash uvx --from tooluniverse tu status # How many tools? uvx --from tooluniverse tu find 'drug safety' # Search by topic uvx --from tooluniverse tu info FAERS_count_death_related_by_drug # See params uvx --from tooluniverse tu run FAERS_count_death_related_by_drug '{"medicinalproduct": "metformin"}' ``` First run takes ~30s (downloads package), then instant. **Shortcut**: `uv tool install tooluniverse` → then just use `tu` directly. ### All CLI subcommands | Command | What it does | Example | |---------|-------------|---------| | `tu status` | Show tool count and top categories | `tu status` | | `tu list` | List tools (modes: names, categories, basic, by_category, summary, custom) | `tu list --mode basic --limit 20` | | `tu find` | Search by natural language (keyword scoring, no API key needed) | `tu find 'protein structure analysis'` | | `tu grep` | Text/regex pattern search | `tu grep '^UniProt' --mode regex` | | `tu info` | Show tool parameters and schema | `tu info PubMed_search_articles` | | `tu run` | Execute a tool | `tu run PubMed_search_articles '{"query": "CRISPR"}'` | | `tu test` | Test a tool with its example inputs | `tu test UniProt_get_entry_by_accession` | | `tu build` | Generate typed Python wrappers for Coding API (also regenerates the internal lazy-load registry in place — unaffected by `--output`) | `tu build --output ./my_tools` | | `tu serve` | Start MCP stdio server (same as `uvx tooluniverse`) | `tu serve` | **Output flags** (most commands except `build`/`serve`): `--json` (pretty) or `--raw` (compact, pipe-friendly). Continue to **Step 3** (API Keys). ## SDK Setup > **Install `uv` first (Step 2). Do not use system `pip`.** On a current Mac > (Homebrew Python 3.13/3.14) `pip install tooluniverse` stops with > `error: externally-managed-environment` (PEP 668), and `python3 -m venv` can > fail at `ensurepip`. `uv` avoids both because it downloads and manages its own > Python. ```bash uv venv --python 3.12 # own Python + virtualenv, ignores system pip source .venv/bin/activate # Windows: .venv\Scripts\activate uv pip install tooluniverse ``` `uv pip install` needs an active virtualenv — run `uv venv` first, or use `uv tool install tooluniverse` if you only want the `tu` command. For detailed patterns, invoke the `tooluniverse-sdk` skill. **Optional extras**: the base install covers API/database tools. Local ML, cheminformatics, and plotting tools need extras — `uv pip install 'tooluniverse[ml]'`, `[visualization]`, `[bioinformatics]`, or `[all]`. Run `tooluniverse-doctor` to see which groups you are missing. Note `[all]` does **not** include `singlecell`, `smolagents`, `client`, or `build`; install those separately. ### Coding API — 3 calling patterns **Pattern 1: Direct import** (typed, with autocomplete): ```python from tooluniverse.tools import UniProt_get_entry_by_accession result = UniProt_get_entry_by_accession(accession="P12345") ``` **Pattern 2: Attribute access** (no import needed per tool): ```python from tooluniverse import ToolUniverse tu = ToolUniverse() tu.load_tools() result = tu.tools.UniProt_get_entry_by_accession(accession="P12345") ``` **Pattern 3: JSON-based** (dynamic, for pipelines): ```python result = tu.run({"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P12345"}}) ``` Generate typed wrappers: `tu build` (creates importable Python modules with autocomplete). ### Agentic Tools & Code Executor ToolUniverse also includes **23 AI-powered agentic tools** (ScientificTextSummarizer, HypothesisGenerator, ExperimentalDesignScorer, peer-review tools, etc.) and **2 code executor tools** (python_code_executor, python_script_runner). These are called like any other tool — via `tu.run()` or `execute_tool()`. Agentic tools require an LLM API key (e.g., `OPENAI_API_KEY`). Continue to **Step 3** (API Keys). ## MCP Setup (Chat Mode) **Offer the two low-effort paths first.** Editing JSON by hand is the fallback, not the recommendation — a mistyped comma is the single most common setup failure. Only walk through the manual path if neither option below fits. **Path A — let an AI agent do it.** If the user already has any agent (Claude, Cursor, Copilot, Gemini, Codex...), they can paste this into it: ``` Read https://aiscientist.tools/setup.md and set up ToolUniverse for me. ``` The agent handles config, keys, skills, and validation. No terminal, no JSON. **Path B — Claude Code or Codex users: one-liner, no config file at all.** Claude Code: ```bash claude plugin marketplace add mims-harvard/ToolUniverse claude plugin install tooluniverse@tooluniverse ``` See the `tooluniverse-claude-code-plugin` skill's "Recommended: turn on auto-update" step so future releases apply without manual `claude plugin update`. Codex: ```bash codex plugin marketplace add mims-harvard/ToolUniverse codex plugin add tooluniverse -m tooluniverse ``` See the `tooluniverse-codex-plugin` skill for verification, updates, and troubleshooting. Both install the MCP server plus 180+ skills in one step. Google Antigravity users: see the `tooluniverse-antigravity-plugin` skill instead — its install flow differs (`agy plugin install`, not a marketplace add). ### Manual config (fallback) Make sure Step 2 is done (`uv --version` works). **Config file help** (if user seems unfamiliar): Config files are plain text that store settings — like a preference list for the app. You don't need to understand the format; just paste exactly what's shown below. Most apps have a Settings button that opens the file for you (see table). If the file is empty, paste the entire block. If it already has content, the agent should help merge it. **Default config** (same for most clients): ```json { "mcpServers": { "tooluniverse": { "command": "uvx", "args": ["tooluniverse"], "env": { "PYTHONIOENCODING": "utf-8" } } } } ``` > **Paste safely.** Copy the block whole — do not retype it. If the file already > has an `mcpServers` block, add only the `"tooluniverse": { ... }` entry inside > it and put a comma after the previous entry. If the file was empty, paste the > whole block. Then validate before restarting the app: > ```bash > python3 -m json.tool < "<path-to-config>" > /dev/null && echo "JSON OK" > ``` > A trailing comma after the last entry, or a missing one between entries, is > the usual cause of "MCP server won't start". **`args` — `["tooluniverse"]` vs `["--refresh", "tooluniverse"]`**: plain is the default and starts fast from `uv`'s cache, but can stay on a cached older release until you run `uv cache clean tooluniverse`. Adding `--refresh` checks PyPI for the newest version on every launch — always current, a few seconds slower to start. Use plain unless the user specifically wants auto-updates. **Config file locations:** | Client | File | How to Access | |--------|------|---------------| | Cursor | `~/.cursor/mcp.json` | Settings → MCP → Add new global MCP server | | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | Settings → Developer → Edit Config | | Claude Code | `~/.claude.json` or `.mcp.json` | `claude mcp add` or edit directly (or use plugin — see above) | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | MCP hammer icon → Configure | | Cline | `cline_mcp_settings.json` | Cline panel → MCP Servers → Configure | | Gemini CLI | `~/.gemini/settings.json` | `gemini mcp add` or edit directly | | Trae | `.trae/mcp.json` | Ctrl+U → AI Management → MCP → Configure | **Different formats**: VS Code uses `"servers"` key with `"type": "stdio"`. Codex uses TOML. OpenCode uses `"mcp"` key. See [references/mcp-configs.md](references/mcp-configs.md) for these. Continue to **Step 3** (API Keys). ## Step 3: API Keys Many tools work without keys, but some unlock powerful features. **Ask research interests first** (AskQuestion): - Literature / Drug discovery / Protein structure / Genomics / Rare diseases / Enzymology / Patent search / AI analysis / All / Skip Map to recommended keys (2-4 to start). Walk through **one at a time**: explain what it unlocks, give registration link, wait for key, add to config. **Tier 1 (Core — recommend for most users):** | Key | Unlocks | Free? | Registration | |-----|---------|-------|-------------| | `NCBI_API_KEY` | PubMed (rate limit 3→10/s) | Yes | https://account.ncbi.nlm.nih.gov/settings/ | | `NVIDIA_API_KEY` | 16 tools: AlphaFold2, docking, genomics | Yes | https://build.nvidia.com | | `BIOGRID_API_KEY` | Protein interaction queries | Yes | https://webservice.thebiogrid.org/ | | `FDA_API_KEY` | FDA adverse events, drug labels (rate 240→1000/min) | Yes | https://open.fda.gov/apis/authentication/ | **Tier 2 (Specialized — based on interests):** | Key | Unlocks | Registration | |-----|---------|-------------| | `DISGENET_API_KEY` | Gene-disease associations | https://disgenet.com/academic-apply | | `OMIM_API_KEY` | Mendelian/rare disease | https://omim.org/api | | `ONCOKB_API_TOKEN` | Precision oncology | https://www.oncokb.org/apiAccess | | `UMLS_API_KEY` | Medical terminology | https://uts.nlm.nih.gov/uts/ | See [API_KEYS_REFERENCE.md](API_KEYS_REFERENCE.md) for the complete list with all tiers. **Adding keys:** Chat mode — add to `env` block in MCP config: ```json "env": { "PYTHONIOENCODING": "utf-8", "NCBI_API_KEY": "your_key_here" } ``` CLI — set environment variables: ```bash export NCBI_API_KEY="your_key_here" # Current session echo 'export NCBI_API_KEY="key"' >> ~/.zshrc # Persist across sessions ``` SDK — same as CLI (export or `.env` file). ## Step 4: Test Together **Don't just tell — do it WITH the user.** **Chat mode**: Ask user to restart app. Then run a test call yourself: 1. `list_tools` or `grep_tools` with "PubMed" — confirm tools visible 2. `execute_tool("PubMed_search_articles", {"query": "CRISPR", "max_results": 1})` — confirm it works 3. Celebrate: "It works! You have access to 2,700+ scientific tools." **CLI**: Run together: ```bash