tooluniverse.smcp 模块¶
科学模型上下文协议（SMCP）——集成ToolUniverse的增强型MCP服务器
SMCP 是一款先进的 MCP（模型上下文协议）服务器，旨在弥合 AI 智能体与科学工具之间的鸿沟。它将 ToolUniverse 拥有的 350 多种科学工具与 MCP 协议无缝集成，使 AI 系统能够访问科学数据库、执行复杂分析并开展科学工作流程。
SMCP 模块通过标准化的 MCP 协议，提供了一套完整的解决方案，用于公开科学计算资源，使 AI 智能体能够以统一的方式轻松发现、理解和执行科学工具。
Usage Patterns¶
快速入门：
`python
# 具有自定义配置的高性能服务器
server = SMCP(
`
name=”生产科学API”，tool_categories=[“uniprot”, “ChEMBL”, “opentarget”, “hpa”]，max_workers=20，search_enabled=True
) server.run_simple(
transport=”http”，host=”0.0.0.0”，port=7000
请提供需要翻译的具体文本。¶
客户端集成：
`python
# 使用MCP客户端来发现和使用工具
import json
`
# 发现蛋白质分析工具 response = await client.call_tool(“find_tools”, {
“query”: “蛋白质结构分析”, “limit”: 5
抱歉，您提供的内容似乎不完整。请提供完整的文本内容，我将为您进行准确的翻译。
# 使用发现的工具 result = await client.call_tool(“UniProt_get_entry_by_accession”, {
“arguments”: json.dumps({“accession”: “P05067”})
抱歉，您提供的内容似乎不完整。请提供完整的文本内容，我将为您进行准确的翻译。¶
Architecture¶
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ MCP 客户端 │◄──►│ SMCP │◄──►│ ToolUniverse │ │ （AI 智能体） │ │ 服务器 │ │ （350+ 工具） │ └─────────────────┘ └──────────────────┘ └─────────────────┘
│ ▼
┌──────────────────┐ │ 科学数据库与服务 │ └──────────────────┘
SMCP 服务器充当智能中间件层，其功能包括： 1. 接收来自 AI 智能体/客户端的 MCP 请求 2. 将请求转换为 ToolUniverse 工具调用 3. 针对科学数据库/服务执行工具操作 4. 通过 MCP 协议返回格式化结果 5. 提供智能工具发现和推荐
Integration Points¶
- MCP 协议层:
标准MCP方法（tools/list、tools/call等）
自定义科学方法（tools/find, tools/search）
与传输无关的通信（stdio、HTTP、SSE）
正确的错误代码与JSON-RPC 2.0规范的遵从
- ToolUniverse 集成：
动态工具加载与配置
模式转换与验证
带错误处理的执行包装器
基于类别的工具组织
- AI智能体接口：
自然语言工具发现
上下文工具推荐
结构化参数模式
全面的工具文档
- class tooluniverse.smcp.SMCP[源代码]¶
基类：
FastMCP科学模型上下文协议（SMCP）服务器
SMCP 是一种增强型 MCP（模型上下文协议）服务器，能够无缝整合 ToolUniverse 丰富的科学及科学工具集合与 FastMCP 框架。它为科学计算、数据分析和研究工作流程提供了统一且可由 AI 访问的接口。
SMCP 服务器在标准 MCP 功能基础上，融合了科学领域专业知识、智能工具发现及针对科研应用的优化配置。它能够自动处理通过一致且文档完善的接口暴露数百种专业工具的复杂任务。
主要特性：¶
- 🔬 科学工具集成：原生支持350+专业工具，涵盖
科学数据库、文献检索、临床数据、基因组学、蛋白质组学、化学信息学及人工智能驱动的分析能力。
- 🧠 AI驱动的工具发现：采用多层次智能搜索系统，使用：
ToolFinderLLM：基于预过滤的成本优化型大语言模型语义理解
Tool_RAG：基于嵌入的相似度搜索
关键词搜索：作为可靠备选方案的简单文本匹配
- 📡 完整的 MCP 协议支持：全面实现 MCP 规范，包含：
标准方法（tools/list、tools/call、resources/、prompts/）
自定义科学方法（tools/find, tools/search）
多传输支持（stdio、HTTP、SSE）
符合 JSON-RPC 2.0 标准并具备完善的错误处理机制
- ⚡ 高性能架构：具备生产环境准备的功能，包括：
可配置线程池以实现工具的并发执行
智能工具加载与缓存
资源管理与优雅降级
全面的错误处理与恢复
- 🔧 开发者友好：简化的配置与部署，具备以下特点：
科学计算的合理默认设置
灵活的定制选项
全面的文档和示例
内置诊断和监控工具
自定义 MCP 方法：¶
- tools/find：
基于人工智能的工具发现，支持自然语言查询。支持语义搜索、类别筛选及灵活的响应格式。
- tools/search: 工具/搜索：
用于工具发现的替代端点，功能与 tools/find 完全相同，提供兼容性和便捷性。
参数：¶
- 名称str，可选
用于日志记录和识别的人类可读服务器名称。默认值：”SMCP Server” 示例：”Scientific Research API”、”Drug Discovery Server”
- tooluniverse_配置ToolUniverse 或 dict，可选项
预配置的 ToolUniverse 实例或配置字典。如果为 None，则使用默认设置创建新的 ToolUniverse。允许重用现有的工具配置和自定义内容。
- 工具类别字符串列表，可选项
特定的 ToolUniverse 类别加载。如果为 None 且 auto_expose_tools=True，则加载所有可用工具。常见组合包括： - 科学类：[“ChEMBL”, “uniprot”, “opentarget”, “pubchem”, “hpa”] - 文献类：[“EuropePMC”, “semantic_scholar”, “pubtator”, “agents”] - 临床类：[“fda_drug_label”, “clinical_trials”, “adverse_events”]
- 排除工具字符串列表，可选项
要排除加载的特定工具名称。即使这些工具位于已加载的类别中，也不会通过 MCP 界面暴露。适用于移除特定的有问题或不需要的工具。
- 排除类别字符串列表，可选项
工具类别排除加载。加载工具时将跳过整个类别。可与 tool_categories 结合使用，先选择类别，再排除特定类别。
- include_tools字符串列表，可选项
需包含的特定工具名称。若提供，仅加载这些工具，且不考虑类别。此设置优先于基于类别的选择。
- 工具_文件str，可选
包含工具名称的文本文件路径（每行一个）。作为 include_tools 参数的替代。注释（以 # 开头的行）和空行将被忽略。
- 工具配置文件可选的字符串字典
附加的工具配置文件，格式：{“category_name”: “/path/to/config.json”}。这些文件将在默认工具文件之外加载。
- 包含工具类型字符串列表，可选项
包含的特定工具类型。若提供，则仅加载这些类型的工具。可用类型包括：’OpenTarget’、’ToolFinderEmbedding’、’ToolFinderKeyword’、’ToolFinderLLM’ 等。
- 排除工具类型字符串列表，可选项
要排除加载的工具类型。加载工具时将跳过这些工具类型。适用于排除整类工具（例如，所有 ToolFinder 类型或所有 OpenTarget 工具）。
- profilestr or list of str, optional
Profile configuration URI(s) to load. Can be a single URI string or a list of URIs for loading multiple Profile configurations. Supported formats: - Local file: “./config.yaml” or “/path/to/config.yaml” - HuggingFace: “hf:username/repo” or “hf:username/repo/file.yaml” - HTTP URL: “https://example.com/config.yaml”
When provided, Profile configurations are loaded after tool initialization, applying LLM settings, hooks, and tool selections from the configuration files. Multiple profiles can be loaded sequentially, with later configurations potentially overriding earlier ones.
Example: profile=”./my-workspace.yaml” Example: profile=[“hf:community/bio-tools”, “./custom-tools.yaml”]
- 自动曝光工具bool，默认值为 True
是否自动将 ToolUniverse 工具作为 MCP 工具公开。设置为 True 时，所有已加载的工具均可通过 MCP 界面访问，且支持自动模式转换和执行封装。
- search_enabled 搜索已启用bool，默认值为 True
通过 tools/find 方法启用 AI 驱动的工具搜索功能。包括 ToolFinderLLM（基于 LLM 的成本优化方案）、Tool_RAG（基于嵌入的方案）以及具备智能回退机制的简单关键词搜索功能。
- 最大工作线程数int，默认值 5
用于工具执行的最大并发工作线程数。较高的值允许更多的工具并行调用，但会占用更多资源。建议值：5-20，具体取决于服务器容量和预期负载。
- hooks_enabled 挂钩启用布尔值，默认值为 False
是否启用输出处理钩子以对工具输出进行智能后处理。启用时，钩子可以自动汇总长输出、将结果保存到文件或应用其他转换。
- hook_config字典，可选
自定义钩子配置字典。如果提供，将覆盖默认钩子设置。应包含带有钩子定义的 “hooks” 列表。例如：{“hooks”: [{“name”: “summarization_hook”, “type”: “SummarizationHook”, …}]}
- 钩子类型str，可选
简单的钩子类型选择。可以是“SummarizationHook”、“FileSaveHook”或两者的列表。提供了一种无需完整配置即可启用钩子的简便方法。当指定时，优先于hooks_enabled。
- compact_mode布尔值，默认值为 False
Enable compact mode that only exposes core tools to prevent context window overflow. When True: - Only exposes search tools (find_tools), execute tool (execute_tool),
and tool discovery tools (list_tools, grep_tools, get_tool_info)
All tools are still loaded in background for execute_tool to work
Prevents automatic exposure of all tools, reducing context window usage
Maintains full functionality through search and execute capabilities
Tool discovery tools enable progressive disclosure: start with minimal info, request details when needed
Agent-friendly features: simple text search (no regex required), natural language task discovery, combined search+detail tools to reduce tool call overhead
- kwargs
传递给底层 FastMCP 服务器实例的附加参数。支持所有 FastMCP 配置选项以实现高级自定义。
提升：¶
- 导入错误
如果未安装 FastMCP，FastMCP 是 SMCP 的必需依赖项。请使用以下命令安装：pip install fastmcp
注意事项：¶
SMCP 会自动处理 ToolUniverse 工具加载和 MCP 转换
工具搜索在可用时使用优化成本的ToolFinderLLM，并在必要时优雅地回退到更简单的方法。
所有工具均支持通过 JSON 传递参数，以实现最大灵活性
服务器支持优雅关闭和全面的资源清理
线程池执行确保并发请求的非阻塞操作
内置错误处理功能提供详尽的调试信息
- __init__(name=None, tooluniverse_config=None, tool_categories=None, exclude_tools=None, exclude_categories=None, include_tools=None, tools_file=None, tool_config_files=None, include_tool_types=None, exclude_tool_types=None, profile=None, workspace=None, use_global=False, auto_expose_tools=True, search_enabled=True, max_workers=5, hooks_enabled=False, hook_config=None, hook_type=None, compact_mode=False, **kwargs)[源代码]¶
Initialize with an optional sequence of providers.
- 参数:
providers – Optional initial providers (without namespacing). For namespaced providers, use add_provider() instead.
- async get_tools()[源代码]¶
Return registered tools as {name: Tool} dict (fastmcp 2/3 compat).
fastmcp 2 had get_tools() returning a dict; fastmcp 3 replaced it with list_tools() returning a list. This shim unifies both APIs.
- async handle_tasks_result(task_id, auth_context=None, timeout=None)[源代码]¶
Wait for task completion and return its result.
- add_custom_tool(name, function, description=None, **kwargs)[源代码]¶
Add a custom Python function as an MCP tool.
- 参数:
- 返回:
The decorated function registered with FastMCP.
- async close()[源代码]¶
Gracefully shut down the SMCP server, stopping the task manager and thread pool.
- run(*args, **kwargs)[源代码]¶
重写运行方法以在FastMCP横幅之后显示ToolUniverse横幅。
此方法拦截了父类的 run() 调用，以便在 FastMCP 显示其启动横幅后立即插入我们的自定义横幅。