setup-tooluniverse

What this skill does

# 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 1200+ 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 '{"drug_name": "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 | `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

Make sure Step 2 is done. For detailed patterns, invoke the `tooluniverse-sdk` skill.

```bash
uv pip install tooluniverse
```

### 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)

Make sure Step 2 is done (`uv --version` works).

### Add ToolUniverse to your app's config

**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" }
    }
  }
}
```

**Config file locations:**

> **Claude Code users**: skip manual MCP config — use the plugin instead. Invoke the `tooluniverse-claude-code-plugin` skill or run:
> ```bash
> claude plugin marketplace add mims-harvard/ToolUniverse
> claude plugin install tooluniverse@tooluniverse
> ```
> This installs MCP server + 115 skills + slash commands in one step.

| 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