plugin-development

MCP Tool Hub 插件开发指南

插件结构

每个插件目录包含：

• __init__.py — 导出 PLUGIN_CLASS 和 WIDGET_CLASS（可选）
• backend.py — 插件后端逻辑
• widget.py — 可选的 PySide6 UI 组件
• README.md — 插件文档（必须）

目录名不能以 _ 或 . 开头。

后端模式

基本结构

from api.base_plugin import BasePlugin
from api.tool import ToolDef, MCPToolResult
from api.config import ConfigModel, StringField
from pydantic import BaseModel, Field

# 可选：配置模型
class MyPluginConfig(ConfigModel):
    api_key = StringField(default="", label="API 密钥", description="...")

# 工具参数模型
class MyToolArgs(BaseModel):
    input_text: str = Field(description="输入文本")

# 插件类
class MyPlugin(BasePlugin[MyPluginConfig]):
    config_class = MyPluginConfig
    
    # 工具声明 — 使用类属性 ToolDef
    my_tool = ToolDef(
        name="my_tool",
        args_model=MyToolArgs,
        description="工具描述"
    )
    
    @property
    def meta(self) -> PluginMeta:
        return PluginMeta(
            name="my_plugin",
            display_name="我的插件",
            version="1.0.0",
            description="插件功能描述",
            author="MCP Tool Hub",
            icon="🔧"
        )
    
    async def handle_my_tool(self, args: MyToolArgs) -> MCPToolResult:
        try:
            result = f"处理: {args.input_text}"
            return MCPToolResult(content=[{"type": "text", "text": result}])
        except Exception as e:
            return MCPToolResult(
                content=[{"type": "text", "text": f"错误: {e}"}],
                is_error=True
            )

工具声明规范

• 使用 ToolDef 类属性（非装饰器）
• name: 工具唯一名称，全局唯一
• args_model: Pydantic BaseModel，用于参数验证和 JSON Schema 生成
• description: 工具功能描述，供 AI 客户端使用

返回格式

统一使用 MCPToolResult:

# 成功
MCPToolResult(content=[{"type": "text", "text": "结果"}])

# 错误
MCPToolResult(content=[{"type": "text", "text": "错误信息"}], is_error=True)

访问配置

class MyPlugin(BasePlugin[MyPluginConfig]):
    async def handle_my_tool(self, args):
        # 直接通过 self.config 访问配置字段
        api_key = self.config.api_key