SillyTavern 的 MCP 扩展

此扩展为 SillyTavern 添加了基于 WebSocket 的工具执行支持，允许通过标准化接口注册和执行外部工具。

特性

• 用于实时通信的 WebSocket 服务器
• 工具注册和执行系统
• 工具定义的 JSON Schema 验证
• 实时执行状态更新
• 可配置的日志记录和 WebSocket 设置
• 集成到 SillyTavern 中的基于 Web 的设置界面

安装

方法 1：Web 界面（推荐）

请参阅 INSTRUCTIONS.md 以获取通过 SillyTavern 的 Web 界面安装的分步说明。

方法 2：手动安装

1. 将此仓库克隆到你的 SillyTavern 插件目录中：

   cd /path/to/SillyTavern/plugins
   git clone https://github.com/CG-Labs/SillyTavern-MCP-Extension.git mcp-extension
   

2. 安装依赖项：

   cd mcp-extension
   npm install
   

3. 重启 SillyTavern

配置

可以通过 SillyTavern UI 在“设置”>“扩展”>“MCP 扩展”下配置扩展。

可用设置

• WebSocket 端口：WebSocket 服务器的端口号（默认：5005）
• 日志级别：日志详细程度（debug, info, warn, error）

使用

注册工具

要注册工具，请发送以下格式的 WebSocket 消息：

{
    "type": "register_tool",
    "data": {
        "name": "example_tool",
        "schema": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "First parameter"
                },
                "param2": {
                    "type": "number",
                    "description": "Second parameter"
                }
            },
            "required": ["param1"]
        }
    }
}

执行工具

要执行已注册的工具，请发送以下格式的 WebSocket 消息：

{
    "type": "execute_tool",
    "data": {
        "executionId": "unique_execution_id",
        "name": "example_tool",
        "args": {
            "param1": "value1",
            "param2": 42
        }
    }
}

执行状态更新

该扩展将执行状态更新广播给所有连接的客户端：

执行开始

{
    "type": "tool_execution_started",
    "data": {
        "executionId": "unique_execution_id",
        "name": "example_tool",
        "args": {
            "param1": "value1",
            "param2": 42
        }
    }
}

执行完成

{
    "type": "tool_execution_completed",
    "data": {
        "executionId": "unique_execution_id",
        "result": {
            // Tool-specific result data
        }
    }
}

执行失败

{
    "type": "tool_execution_failed",
    "data": {
        "executionId": "unique_execution_id",
        "error": {
            "code": "ERROR_CODE",
            "message": "Error message"
        }
    }
}

错误代码

• INVALID_NAME：无效的工具名称
• INVALID_SCHEMA：无效的工具模式
• INVALID_URI：无效的资源 URI
• INVALID_HANDLER：无效的处理器实现
• INVALID_ARGUMENTS：无效的工具参数
• TOOL_EXISTS：工具已注册
• TOOL_NOT_FOUND：未找到工具
• TOOL_EXECUTION_FAILED：工具执行失败
• SERVER_ERROR：内部服务器错误

开发

项目结构

mcp-extension/
├── index.js              # Main plugin entry point
├── manifest.json         # Plugin manifest
├── package.json         # Dependencies and scripts
├── public/              # Public assets
│   ├── script.js        # Client-side JavaScript
│   ├── style.css        # Client-side styles
│   └── templates/       # HTML templates
├── utils/               # Utility modules
│   ├── errors.js        # Error handling
│   ├── logger.js        # Logging utility
│   └── validation.js    # Input validation
└── README.md            # This documentation

添加新工具

要添加新工具：

1. 连接到 WebSocket 服务器
2. 使用模式注册你的工具
3. 监听执行请求
4. 处理执行并返回结果

示例工具实现：

const ws = new WebSocket('ws://localhost:5005');

ws.onopen = () => {
    // Register tool
    ws.send(JSON.stringify({
        type: 'register_tool',
        data: {
            name: 'example_tool',
            schema: {
                type: 'object',
                properties: {
                    input: {
                        type: 'string'
                    }
                },
                required: ['input']
            }
        }
    }));
};

ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    
    if (message.type === 'execute_tool' && 
        message.data.name === 'example_tool') {
        // Handle execution
        const result = doSomething(message.data.args.input);
        
        // Send result
        ws.send(JSON.stringify({
            type: 'tool_execution_completed',
            data: {
                executionId: message.data.executionId,
                result
            }
        }));
    }
};

贡献

1. 分叉仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

支持

如果你遇到任何问题或有疑问：

1. 检查 GitHub Issues 是否已有相关问题
2. 如果你的问题尚未报告，请创建一个新的 issue
3. 加入 SillyTavern Discord 社区寻求支持

许可证

MIT 许可证 - 详情请参见 LICENSE 文件