工具加载教程

完整教程：加载和管理 ToolUniverse 中的工具

本教程介绍了加载和访问ToolUniverse工具的两种主要方法：通过Python API使用``load_tools()``方法，以及通过终端命令使用MCP（模型上下文协议）服务器。

Python API：使用 load_tools()

load_tools() 方法是使用 Python 以编程方式操作 ToolUniverse 时加载工具的主要方式。

备注

For complete Python API documentation, see API参考 for the full API reference.

tooluniverse.execute_function.ToolUniverse.load_tools(self, categories=None, tool_type=None, exclude_tools=None, exclude_categories=None, include_tools=None, tool_config_files=None, tools_file=None, include_tool_types=None, exclude_tool_types=None, python_files=None, quiet=True)

Load tools into the instance, with optional filtering.

参数:

  • categories (list, optional) – Tool category names to load. If None, all categories are loaded. Use list_categories() to see available names.

  • tool_type (list, optional) – Deprecated alias for categories.

  • exclude_tools (list, optional) – Tool names to exclude. Supports glob patterns (e.g. ["EuropePMC_*"]).

  • exclude_categories (list, optional) – Category names to skip entirely.

  • include_tools (list or str, optional) – Only load these tools. Supports glob patterns (e.g. ["EuropePMC_*", "ChEMBL_*"]). Pass a file path string to read names from a text file (one per line).

  • tool_config_files (dict, optional) – Extra JSON config files to load. Format: {"category_name": "/path/to/config.json"}.

  • tools_file (str, optional) – Deprecated. Pass a file path to include_tools instead.

  • python_files (list, optional) – List of Python file paths (str or Path) to import as user tools. Each file should contain @register_tool-decorated classes. Example: python_files=["/path/to/my_tool.py"].

  • include_tool_types (list, optional) – Only load tools whose type field is in this list (e.g. ["RESTTool", "GraphQLTool"]).

  • exclude_tool_types (list, optional) – Skip tools whose type field is in this list.

  • quiet (bool, optional) – Suppress missing-API-key warnings and .env.template generation. Default True. Pass False to see which keys are missing.

示例

# Load everything (default) tu.load_tools()

# Load only two categories tu.load_tools(categories=[“ChEMBL”, “EuropePMC”])

# Load tools by name with glob wildcards tu.load_tools(include_tools=[“EuropePMC_*”, “ChEMBL_get_molecule_*”])

# Combine: exclude one category, exclude specific tools tu.load_tools(

exclude_categories=[“tool_finder”], exclude_tools=[“EuropePMC_slow_tool”],

请提供需要翻译的具体英文文本内容，我将为您翻译成自然流畅且专业的中文。

基本使用

加载所有可用工具：

from tooluniverse import ToolUniverse

# Initialize ToolUniverse
tu = ToolUniverse()

# Load all tools from all categories
tu.load_tools()

# Check how many tools were loaded
print(f"Loaded {len(tu.all_tools)} tools")

# List first 5 tools
tool_names = tu.list_built_in_tools(mode='list_name')
for tool in tool_names[:5]:
    print(f"  • {tool}")

选择性工具加载

加载特定工具类别：

# Load only specific categories
tu.load_tools(tool_type=["uniprot", "ChEMBL", "opentarget"])

# Load tools but exclude certain categories
tu.load_tools(exclude_categories=["mcp_auto_loader", "special_tools"])

按名称加载特定工具：

# Load only specific tools
tu.load_tools(include_tools=[
    "UniProt_get_entry_by_accession",
    "ChEMBL_get_molecule_by_chembl_id",
    "OpenTargets_get_associated_targets_by_disease_efoId"
])

# Load tools from a file
tu.load_tools(tools_file="/path/to/tool_names.txt")

高级过滤

按工具类型筛选：

# Include only specific tool types
tu.load_tools(include_tool_types=["OpenTarget", "ChEMBLTool"])

# Exclude specific tool types
tu.load_tools(exclude_tool_types=["ToolFinderEmbedding", "Unknown"])

排除特定工具：

# Load all tools except specific ones
tu.load_tools(exclude_tools=["problematic_tool", "slow_tool"])

加载其他配置

添加自定义工具配置文件：

# Load additional config files
tu.load_tools(tool_config_files={
    "custom_tools": "/path/to/custom_tools.json",
    "local_analysis": "/path/to/local_tools.json"
})

注意：tool_config_files 是一个包含工具类别名称和工具配置文件路径的字典，但这并不意味着工具已被加载。您需要使用 tool_type、include_tools 或 include_tool_types 来加载工具。

组合参数

结合多种加载选项：

tu.load_tools(
    tool_type=["uniprot", "ChEMBL", "custom"],              # Load specific categories
    exclude_tools=["problematic_tool"],            # Exclude specific tools
    exclude_tool_types=["Unknown"],                # Exclude tool types
    tool_config_files={                           # Add custom tools
        "custom": "/path/to/custom.json"
    }
)

MCP服务器功能

ToolUniverse 提供两种主要的 MCP 服务器功能，以满足不同的使用场景：

参见

For a comprehensive MCP overview, detailed configuration, best practices, and troubleshooting, see MCP Support.

  1. `tooluniverse-smcp` - Full-featured server with configurable transport (HTTP, SSE, stdio)

  2. `tooluniverse-smcp-stdio` - 专用于标准输入输出传输的服务器（适用于桌面级AI应用）

这两个功能通过模型上下文协议（MCP）提供相同的600多个科学工具，但采用不同的传输配置和参数处理方式。

tooluniverse-smcp Function

The tooluniverse-smcp function is the main entry point for ToolUniverse’s SMCP server, providing full configurability for different deployment scenarios.

基本服务器启动

使用所有工具启动一个基础的 MCP 服务器：

# Start server on default port 7000
tooluniverse-smcp

# Start server on specific port
tooluniverse-smcp --port 8000

# Start with custom server name
tooluniverse-smcp --name "My ToolUniverse Server" --port 8000

钩子配置

启用智能输出处理钩子：

# Enable hooks with default SummarizationHook
tooluniverse-smcp --hooks-enabled --port 8000

# Use specific hook type
tooluniverse-smcp --hook-type SummarizationHook --port 8000
tooluniverse-smcp --hook-type FileSaveHook --port 8000

# Use custom hook configuration
tooluniverse-smcp --hook-config-file /path/to/hook_config.json --port 8000

可用的钩子类型

  • SummarizationHook：基于人工智能的长文本摘要生成

  • FileSaveHook：将输出及元数据保存到文件中

有关详细的钩子配置，请参见 后处理工具输出。

传输配置

不同的传输协议：

# HTTP transport (default)
tooluniverse-smcp --transport http --port 8000

# STDIO transport (for desktop apps)
tooluniverse-smcp --transport stdio

# Server-Sent Events transport
tooluniverse-smcp --transport sse --port 8000

基于类别的加载

仅加载特定工具类别：

# Load specific categories
tooluniverse-smcp --categories uniprot ChEMBL opentarget --port 8000

# Load all except certain categories
tooluniverse-smcp --exclude-categories mcp_auto_loader special_tools --port 8000

工具特定加载

按名称加载特定工具：

# Load only specific tools
tooluniverse-smcp --include-tools "UniProt_get_entry_by_accession" "ChEMBL_get_molecule_by_chembl_id" --port 8000

# Load tools from a file
tooluniverse-smcp --tools-file "/path/to/tool_names.txt" --port 8000

基于类型的过滤

按工具类型筛选：

# Include only specific tool types
tooluniverse-smcp --include-tool-types "OpenTarget" "ToolFinderEmbedding" --port 8000

# Exclude specific tool types
tooluniverse-smcp --exclude-tool-types "ToolFinderLLM" "Unknown" --port 8000

服务器配置

高级服务器配置：

# Configure server parameters
tooluniverse-smcp \
    --port 8000 \
    --host 0.0.0.0 \
    --max-workers 10 \
    --transport http \
    --verbose

发现命令

列出可用的类别和工具：

# List all available categories
tooluniverse-smcp --list-categories

# List all available tools
tooluniverse-smcp --list-tools

自定义配置文件

加载更多工具配置：

# Load custom config files
tooluniverse-smcp --tool-config-files "custom:/path/to/custom_tools.json" --port 8000

tooluniverse-smcp-stdio 函数

tooluniverse-smcp-stdio 函数专为 stdio 传输设计，非常适合 Claude Desktop 集成及其他桌面 AI 应用。默认情况下，该函数启用输出处理钩子，以实现工具输出的智能后处理。

基础标准输入输出服务器启动

使用默认设置（启用钩子）启动 stdio 服务器：

# Start stdio server with default SummarizationHook enabled
tooluniverse-smcp-stdio

# Start with specific categories
tooluniverse-smcp-stdio --categories uniprot ChEMBL opentarget

钩子配置

stdio 服务器支持智能输出处理钩子：

# Disable hooks (default is enabled)
tooluniverse-smcp-stdio --no-hooks

# Use FileSaveHook instead of SummarizationHook
tooluniverse-smcp-stdio --hook-type FileSaveHook

# Use custom hook configuration
tooluniverse-smcp-stdio --hook-config-file /path/to/hook_config.json

可用的钩子类型

  • **SummarizationHook**（默认）：基于人工智能的长文本摘要生成

  • FileSaveHook：将输出及元数据保存到文件中

有关详细的钩子配置，请参见 后处理工具输出。

️ Practical Examples

研究工作流程设置

科学研究的准备工作：

# Python approach
from tooluniverse import ToolUniverse

tu = ToolUniverse()

# Load tools for drug discovery research
tu.load_tools(tool_type=[
    "uniprot",        # Protein information
    "ChEMBL",         # Chemical data
    "opentarget",     # Target-disease associations
    "pubchem",        # Chemical compounds
    "fda_drug_adverse_event"  # Safety data
])

# Ready for research queries
result = tu.run({
    "name": "UniProt_get_entry_by_accession",
    "arguments": {"accession": "P04637"}  # p53 protein
})

# MCP server approach (run_smcp_server)
tooluniverse-smcp \
    --categories uniprot ChEMBL opentarget pubchem fda_drug_adverse_event \
    --port 8000 \
    --name "Drug Discovery Server"

# Or stdio server approach (run_stdio_server) with hooks enabled by default
tooluniverse-smcp-stdio \
    --categories uniprot ChEMBL opentarget pubchem fda_drug_adverse_event \
    --name "Drug Discovery Tools"

# Stdio server with FileSaveHook for data archiving
tooluniverse-smcp-stdio \
    --categories uniprot ChEMBL opentarget pubchem fda_drug_adverse_event \
    --hook-type FileSaveHook \
    --name "Drug Discovery Tools with File Archiving"

️ File Formats

工具名称文件格式

创建一个文本文件，每行填写一个工具名称：

# my_tools.txt - Lines starting with # are comments
OpenTargets_get_associated_targets_by_disease_efoId
Tool_Finder_LLM
ChEMBL_search_similar_molecules

# You can add comments anywhere
Tool_Finder_Keyword