setup-tooluniverse

设置 ToolUniverse

逐步引导用户设置 ToolUniverse。

Agent 行为

• 检测语言：根据用户的第一条消息判断语言。使用用户的语言回复；命令和 URL 保持英文。
• 每次只进行一步。继续之前先征求同意。
• 使用 AskQuestion 提供结构化选项。
• 用通俗语言简要说明。庆祝每个小进展。
• 出现问题时，先协助排查，再继续。

内部说明（不要显示）

ToolUniverse 有 2,700 多个工具。tooluniverse 命令会自动启用紧凑模式，仅公开 5 个核心 MCP 工具（list_tools、grep_tools、get_tool_info、execute_tool、find_tools），同时仍可通过 execute_tool 使用所有工具。

什么是 ToolUniverse？

始终先用通俗语言说明：

ToolUniverse 是一款免费、开源的软件，可连接 2,000 多个科学数据库（PubMed、UniProt、ChEMBL、FAERS、ClinicalTrials.gov 等）。你无需逐个访问网站，只需在一个地方搜索即可。可以把它想象成科学数据库的万能遥控器。

为什么要使用 AI 助手？ AI 会读取你的问题，判断要搜索哪些数据库，执行查询并总结结果。你只需提出问题。

第 1 步：选择使用方式

通过 AskQuestion 提供以下选项：

模式	含义	适用对象
聊天模式	向 AI 助手提问。无需编写代码。	大多数研究人员。
命令行	在终端中输入简短命令。	快速测试。适应终端的用户。
Python 代码	编写脚本以实现自动化工作流。	程序员。

选项：“我想提问” → 聊天模式 | “快速试用” → CLI | “我写 Python” → SDK | “我不知道” → 推荐聊天模式

如果选择聊天模式，询问要使用哪个应用（AskQuestion）：Cursor、Claude Desktop、VS Code/Copilot、Windsurf、Claude Code、Gemini CLI、Codex、Cline/Trae/Antigravity/OpenCode。“我没有” → 推荐 Claude Desktop。

第 2 步：安装 uv

唯一的前置条件：uv（它会自动管理其他所有内容）。

终端帮助（如有需要）：Mac：按 Cmd+Space → 输入“Terminal” → 按 Enter。Windows：按 Win 键 → 输入“PowerShell” → 按 Enter。

curl -LsSf https://astral.sh/uv/install.sh | sh

（这是一个安全的标准命令，用于下载并安装 uv，这是一款轻量级包管理器。Python 开发者广泛使用它。安装完成后，请关闭并重新打开终端。）

验证：uv --version

CLI 设置

确认已完成第 2 步，然后尝试：

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"}'

首次运行大约需要 30 秒（下载软件包），之后即可即时启动。快捷方式：运行 uv tool install tooluniverse，之后直接使用 tu 即可。

所有 CLI 子命令

命令	功能	示例
tu status	显示工具数量和主要类别	tu status
tu list	列出工具（模式：names、categories、basic、by_category、summary、custom）	tu list --mode basic --limit 20
tu find	使用自然语言搜索（基于关键词评分，无需 API 密钥）	tu find 'protein structure analysis'
tu grep	按文本或正则表达式搜索	tu grep '^UniProt' --mode regex
tu info	显示工具参数和架构	tu info PubMed_search_articles
tu run	执行工具	tu run PubMed_search_articles '{"query": "CRISPR"}'
tu test	使用示例输入测试工具	tu test UniProt_get_entry_by_accession
tu build	为 Coding API 生成类型化 Python 封装（也会就地重新生成内部延迟加载注册表，不受 --output 影响）	tu build --output ./my_tools
tu serve	启动 MCP stdio 服务（与 uvx tooluniverse 相同）	tu serve

输出标志（除 build/serve 外的大多数命令）：--json（美化格式）或 --raw（紧凑格式，便于管道处理）。

继续进行 第 3 步（API 密钥）。

SDK 设置

请先安装 uv（步骤 2）。不要使用系统 pip。 在较新的 Mac 上 （Homebrew Python 3.13/3.14），pip install tooluniverse 会报错 error: externally-managed-environment（PEP 668），而 python3 -m venv 可能会在 ensurepip 处失败。uv 会下载并管理自己的 Python，因此可以避免这两种情况。

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 需要已激活的虚拟环境——请先运行 uv venv，或者如果你只需要 tu 命令，请使用 uv tool install tooluniverse。

如需了解详细用法模式，请调用 tooluniverse-sdk 技能。

可选额外依赖：基础安装涵盖 API/数据库工具。本地 ML、 化学信息学和绘图工具需要额外依赖——uv pip install 'tooluniverse[ml]'、[visualization]、[bioinformatics] 或 [all]。 运行 tooluniverse-doctor 查看缺少哪些依赖组。 请注意，[all] 不包含 singlecell、smolagents、client 或 build；需单独安装这些依赖。

编码 API——3 种调用模式

模式 1：直接导入（带类型提示和自动补全）：

from tooluniverse.tools import UniProt_get_entry_by_accession
result = UniProt_get_entry_by_accession(accession="P12345")

模式 2：属性访问（无需为每个工具导入）：

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()
result = tu.tools.UniProt_get_entry_by_accession(accession="P12345")

模式 3：基于 JSON（动态，适用于流水线）：

result = tu.run({"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P12345"}})

生成带类型的封装：tu build（创建可导入且支持自动补全的 Python 模块）。

Agent 工具与代码执行器

ToolUniverse 还包含 23 个由 AI 驱动的 Agent 工具（ScientificTextSummarizer、HypothesisGenerator、ExperimentalDesignScorer、同行评审工具等）和 2 个代码执行器工具（python_code_executor、python_script_runner）。这些工具的调用方式与其他工具相同——通过 tu.run() 或 execute_tool() 调用。Agent 工具需要 LLM API 密钥（例如 OPENAI_API_KEY）。

继续执行步骤 3（API 密钥）。

MCP 设置（聊天模式）

优先提供两种省力的方式。 手动编辑 JSON 是备用方案， 而非推荐方案——逗号拼写错误是最常见的设置失败原因。只有在以下两种方式都不适用时， 才引导用户使用手动方式。

方式 A——让 AI Agent 来操作。 如果用户已经使用任何 Agent（Claude、 Cursor、Copilot、Gemini、Codex 等），可以将以下内容粘贴给它：

Read https://aiscientist.tools/setup.md and set up ToolUniverse for me.

Agent 会处理配置、密钥、技能和验证。无需终端，无需 JSON。

方式 B——Claude Code 或 Codex 用户：一行命令，无需配置文件。

Claude Code：

claude plugin marketplace add mims-harvard/ToolUniverse
claude plugin install tooluniverse@tooluniverse

请参阅 tooluniverse-claude-code-plugin 技能中的“推荐：启用 自动更新”步骤，以便未来发布时自动应用更新，无需手动运行 claude plugin update。

Codex：

codex plugin marketplace add mims-harvard/ToolUniverse
codex plugin add tooluniverse -m tooluniverse

请参阅 tooluniverse-codex-plugin 技能，了解验证、更新和 故障排查。

两种方式都可以一步安装 MCP 服务和 180 多个技能。Google Antigravity 用户：请改为参阅 tooluniverse-antigravity-plugin 技能——其安装 流程不同（使用 agy plugin install，而非添加到市场）。

手动配置（备用）

确保已完成 Step 2（uv --version 可正常运行）。

配置文件说明（适用于不熟悉配置文件的用户）：配置文件是用于存储设置的纯文本文件，就像应用的偏好设置列表。你不需要了解其格式；只需按下方所示原样粘贴即可。大多数应用都有一个可打开配置文件的“设置”按钮（见下表）。如果文件为空，请粘贴整个代码块。如果文件已有内容，Agent 应帮助合并。

默认配置（适用于大多数客户端）：

{
  "mcpServers": {
    "tooluniverse": {
      "command": "uvx",
      "args": ["tooluniverse"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

安全粘贴。 请完整复制代码块，不要重新输入。如果文件中已有 mcpServers 块，只需将 "tooluniverse": { ... } 条目添加到其中，并在前一个条目后加上逗号。如果文件为空，请粘贴整个代码块。然后，在重启应用前进行验证：

python3 -m json.tool < "<path-to-config>" > /dev/null && echo "JSON OK"

最后一个条目后多加逗号，或条目之间漏加逗号，是导致“MCP 服务无法启动”的常见原因。

args — ["tooluniverse"] 与 ["--refresh", "tooluniverse"]：默认使用普通配置，从 uv 缓存中快速启动，但可能会一直使用缓存中的旧版本，直到运行 uv cache clean tooluniverse。添加 --refresh 后，每次启动都会向 PyPI 检查最新版本，确保始终为最新版，但启动速度会慢几秒。除非用户明确需要自动更新，否则请使用普通配置。

配置文件位置：

客户端	文件	访问方式
Cursor	~/.cursor/mcp.json	设置 → MCP → 添加新的全局 MCP 服务
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	设置 → 开发者 → 编辑配置
Claude Code	~/.claude.json 或 .mcp.json	claude mcp add 或直接编辑（也可使用插件 — 见上文）
Windsurf	~/.codeium/windsurf/mcp_config.json	MCP 锤子图标 → 配置
Cline	cline_mcp_settings.json	Cline 面板 → MCP 服务 → 配置
Gemini CLI	~/.gemini/settings.json	gemini mcp add 或直接编辑
Trae	.trae/mcp.json	Ctrl+U → AI 管理 → MCP → 配置

不同格式：VS Code 使用 "servers" 键和 "type": "stdio"。Codex 使用 TOML。OpenCode 使用 "mcp" 键。详见 references/mcp-configs.md。

继续执行 Step 3（API 密钥）。

第 3 步：API 密钥

许多工具无需密钥即可使用，但有些密钥可以解锁强大功能。先询问研究兴趣（AskQuestion）：

• 文献 / 药物发现 / 蛋白质结构 / 基因组学 / 罕见疾病 / 酶学 / 专利检索 / AI 分析 / 全部 / 跳过

根据兴趣推荐密钥（先配置 2–4 个）。每次逐个介绍一个：说明它能解锁什么功能，提供注册链接，等待用户提供密钥，然后将其添加到配置中。

第 1 层（核心——推荐给大多数用户）：

密钥	解锁的功能	免费？	注册
NCBI_API_KEY	PubMed（速率限制从 3 提升至 10 次/秒）	是	https://account.ncbi.nlm.nih.gov/settings/
NVIDIA_API_KEY	16 个工具：AlphaFold2、分子对接、基因组学	是	https://build.nvidia.com
BIOGRID_API_KEY	蛋白质相互作用查询	是	https://webservice.thebiogrid.org/
FDA_API_KEY	FDA 不良事件、药品标签（速率限制从 240 提升至 1000 次/分钟）	是	https://open.fda.gov/apis/authentication/

第 2 层（专用——根据兴趣选择）：

密钥	解锁的功能	注册
DISGENET_API_KEY	基因-疾病关联	https://disgenet.com/academic-apply
OMIM_API_KEY	孟德尔遗传病 / 罕见疾病	https://omim.org/api
ONCOKB_API_TOKEN	精准肿瘤学	https://www.oncokb.org/apiAccess
UMLS_API_KEY	医学术语	https://uts.nlm.nih.gov/uts/

完整列表（含所有层级）请参阅 API_KEYS_REFERENCE.md。

添加密钥：

聊天模式——添加到 MCP 配置中的 env 区块：

"env": {
  "PYTHONIOENCODING": "utf-8",
  "NCBI_API_KEY": "your_key_here"
}

CLI——设置环境变量：

export NCBI_API_KEY="your_key_here"       # Current session
echo 'export NCBI_API_KEY="key"' >> ~/.zshrc  # Persist across sessions

SDK——与 CLI 相同（使用 export 或 .env 文件）。

第 4 步：一起测试

不要只告诉用户怎么做——要和用户一起操作。

聊天模式：请用户重启应用，然后自行运行测试调用：

1. 使用 "PubMed" 调用 list_tools 或 grep_tools——确认工具可见
2. 调用 execute_tool("PubMed_search_articles", {"query": "CRISPR", "max_results": 1})——确认功能正常
3. 庆祝：“成功了！你现在可以使用 2,700 多个科学工具。”

CLI：一起运行：

tu status && tu find 'protein' && tu run PubMed_search_articles '{"query": "CRISPR", "max_results": 1}'

SDK：一起运行 SDK 设置中的 Python 代码片段。

如果遇到问题：最常见的原因是应用未重启、uv 不在 PATH 中（重新打开终端），或配置中的 JSON 语法错误。

第 5 步：安装技能（推荐用于聊天模式）

技能是预先构建的研究工作流，可将基本工具调用转化为专家级研究。

聊天模式用户：Agent 应代用户运行以下命令：

git clone --depth 1 https://github.com/mims-harvard/ToolUniverse.git /tmp/tu-skills

然后复制到客户端的技能目录：

客户端	命令
Cursor	mkdir -p .cursor/skills && cp -r /tmp/tu-skills/skills/* .cursor/skills/
Claude Code	mkdir -p .claude/skills && cp -r /tmp/tu-skills/skills/* .claude/skills/
Windsurf	mkdir -p .windsurf/skills && cp -r /tmp/tu-skills/skills/* .windsurf/skills/
Codex	mkdir -p .agents/skills && cp -r /tmp/tu-skills/skills/* .agents/skills/
Gemini CLI	mkdir -p .gemini/skills && cp -r /tmp/tu-skills/skills/* .gemini/skills/

清理：rm -rf /tmp/tu-skills

技能会根据用户的问题自动激活。试试：“研究二甲双胍”或“文献中关于 CRISPR 与癌症的研究有哪些发现？”

CLI 用户：技能是为 AI 聊天 Agent 设计的。请改用 tu find、tu info、tu run。如需执行完整的多步骤工作流，请使用聊天模式或构建 SDK 流水线。

接下来做什么？（引导式首次使用）

不要列出建议——要和用户一起进行实时演示。

根据研究兴趣选择演示查询（来自步骤 3）：

兴趣	首个查询	技能
文献	"关于 CRISPR 在癌症中的应用，文献有哪些结论？"	literature-deep-research
药物发现	"研究药物 metformin"	drug-research
蛋白质结构	"查找人类 EGFR 的蛋白质结构"	protein-structure-retrieval
基因组学	"哪些基因与 2 型糖尿病相关？"	disease-research
罕见病	"患者出现进行性共济失调和眼球运动失用——鉴别诊断是什么？"	rare-disease-diagnosis
药物安全	"pembrolizumab 的不良事件有哪些？"	pharmacovigilance
通用	"研究药物 aspirin"	drug-research

运行演示 — 调用技能并展示真实结果。

提示词速查表（演示后分享）

聊天模式用户：

1. "研究药物 [name]" — 完整的药物档案
2. "研究 [disease]" — 全面的疾病分析
3. "[drug] 的已知靶点有哪些？" — 靶点情报
4. "关于 [topic]，文献有哪些结论？" — 深度文献综述
5. "查找 [protein] 的蛋白质结构" — 3D 结构
6. "[variant] 是否具有致病性？" — 变异解读
7. "有哪些药物可以重新用于治疗 [disease]？" — 药物再利用
8. "[drug] 的不良事件有哪些？" — 安全性分析
9. "查找 [disease/drug] 的临床试验" — 试验匹配
10. "[gene] 的蛋白质相互作用有哪些？" — 相互作用网络
11. "[condition] 的临床指南有哪些？" — 实践指南
12. "检查 [drug1] 和 [drug2] 之间的药物相互作用" — DDI 分析

直接自然地提问即可——我会判断要搜索哪些数据库。

CLI 用户：

tu find 'drug safety'           # 发现工具
tu info PubMed_search_articles  # 查看参数
tu run PubMed_search_articles '{"query": "CRISPR cancer", "max_results": 3}'
tu run UniProt_get_entry_by_accession '{"accession": "P12345"}'
tu run FAERS_count_death_related_by_drug '{"medicinalproduct": "metformin"}'

编写 Agent 记忆

完成设置后，在 Agent 的记忆文件中写入提醒，以便后续会话知道 ToolUniverse 可用。

客户端	文件
Cursor	.cursor/rules/tooluniverse.md
Claude Code	CLAUDE.md 或 .claude/CLAUDE.md（追加）
Windsurf	.windsurf/rules/tooluniverse.md
VS Code/Copilot	.github/copilot-instructions.md（追加）
Codex / OpenCode	AGENTS.md（追加）
Gemini CLI	GEMINI.md（追加）
Cline	.clinerules/tooluniverse.md
Trae	.trae/rules/tooluniverse.md

内容：

# ToolUniverse
For any scientific research question (drugs, genes, proteins, diseases, literature, clinical trials, etc.), invoke the `tooluniverse` skill — it routes to specialized research skills and 2,700+ database tools.

追加（不要覆盖）。先检查是否已有相关部分。征求用户许可。

团队 / 项目级设置

如果要为团队或共享项目设置 ToolUniverse：

共享 API 密钥：在项目根目录创建 .env 文件，写入所有密钥。大多数客户端以及 CLI/SDK 都会自动从 .env 中读取密钥：

NCBI_API_KEY=your_shared_key
NVIDIA_API_KEY=your_shared_key

项目级 MCP 配置（让所有团队成员都能自动使用 ToolUniverse）：

• Cursor：项目根目录中的 .cursor/mcp.json
• Claude Code：项目根目录中的 .mcp.json
• VS Code：项目根目录中的 .vscode/mcp.json
• Windsurf：通过 Windsurf UI 进行项目级配置

项目级技能：将技能安装到项目中（例如 .cursor/skills/），以便所有团队成员共享。

团队范围升级：每位团队成员运行 uv cache clean tooluniverse 并重启应用。若要固定特定版本，请在 MCP 配置中使用 "args": ["tooluniverse==X.Y.Z"]。

常见问题

问题	解决方法
error: externally-managed-environment (PEP 668)	系统 pip 拒绝安装。使用 uv — uv venv --python 3.12 && source .venv/bin/activate && uv pip install tooluniverse。切勿使用 sudo pip 或 --break-system-packages。
python3 -m venv 在 ensurepip 处失败	Homebrew Python（3.13/3.14）缺少可用的 ensurepip。使用 uv venv --python 3.12 — uv 会提供自己的 Python。
uv pip install → "No virtual environment found"	先运行 uv venv，或者使用 uv tool install tooluniverse 仅安装 tu 命令。
requires-python >= 3.10	uv python install 3.12
uvx: command not found	运行步骤 2 中的安装脚本，然后重启终端
上下文窗口溢出	使用 uvx tooluniverse 验证（默认采用紧凑模式）
工具运行时出现 ModuleNotFoundError	缺少可选扩展。运行 tooluniverse-doctor 查看缺少哪个组，然后运行 uv pip install 'tooluniverse[ml]'（或 [visualization]、[bioinformatics]、[all]）。
工具已列出，但运行失败	对依赖扩展的工具来说，这是正常情况 — tu status 统计的是已加载的配置，而不是已安装的依赖项。tooluniverse-doctor 会报告缺少哪些组。
MCP 服务无法启动	测试：在终端中运行 uvx tooluniverse。使用 python3 -m json.tool < <config> 验证配置。
API 密钥 401/403	检查 env 块中的密钥，重启应用，并确认密钥名称
需要升级	运行 uv cache clean tooluniverse，然后重启应用

健康检查：tooluniverse-doctor 会报告加载失败的工具，以及 尚未安装的可选依赖组。工具意外报错时，请先使用此命令。

[all] 并不包含所有内容：它涵盖 dev, docs, graph, visualization, space, embedding, ml, bioinformatics。必须按名称安装 singlecell、smolagents、client 和 build。

仍未解决？请查看 GitHub issues 或发送邮件给 Shanghua Gao。

快速参考

• 默认方式：uvx tooluniverse — 自动安装，紧凑模式
• 升级：uv cache clean tooluniverse + 重启
• 所有科学 API 密钥均免费
• 技能：https://github.com/mims-harvard/ToolUniverse/tree/main/skills