内置工具

内置工具是插件核心功能的一部分，位于 src/mcp/tools/ 目录。

目录结构

src/mcp/tools/
├── index.js         # 工具加载器
├── basic.js         # 基础工具
├── user.js          # 用户信息
├── group.js         # 群组信息
├── message.js       # 消息操作
├── admin.js         # 群管理
├── groupStats.js    # 群统计
├── file.js          # 文件操作
├── media.js         # 媒体处理
├── web.js           # 网页访问
├── search.js        # 搜索工具
├── utils.js         # 实用工具
├── memory.js        # 记忆管理
├── context.js       # 上下文管理
├── bot.js           # Bot信息
├── voice.js         # 语音/声聊
├── extra.js         # 扩展工具
├── shell.js         # 系统命令（危险）
├── schedule.js      # 定时任务
├── bltools.js       # 扩展工具集
├── reminder.js      # 定时提醒
└── helpers.js       # 工具函数

工具类别（20个）

类别	名称	说明
basic	基础工具	时间获取、随机数等基础功能
user	用户信息	获取用户信息、好友列表等
group	群组信息	获取群信息、成员列表等
message	消息操作	发送消息、@用户、获取聊天记录、转发消息解析
admin	群管理	禁言、踢人、设置群名片等管理功能
groupStats	群统计	群星级、龙王、发言榜、幸运字符、不活跃成员
file	文件操作	群文件上传下载、本地文件读写、URL下载
media	媒体处理	图片解析、语音处理、二维码生成等
web	网页访问	访问网页、获取内容等
search	搜索工具	网页搜索、Wiki查询、翻译等
utils	实用工具	计算、编码转换、时间处理等
memory	记忆管理	用户记忆的增删改查
context	上下文管理	对话上下文、群聊上下文等
bot	Bot信息	获取机器人自身信息、状态、好友列表等
voice	语音/声聊	AI语音对话、TTS语音合成、语音识别等
extra	扩展工具	天气查询、一言、骰子、倒计时、提醒、插画
shell	系统命令	执行Shell命令、获取系统信息（⚠️危险）
schedule	定时任务	创建、管理定时任务，支持周期执行
bltools	扩展工具	QQ音乐、表情包、B站视频、GitHub、AI图片编辑等
reminder	定时提醒	设置定时提醒，支持相对/绝对时间、重复

创建内置工具

1. 在对应类别文件中添加工具

// src/mcp/tools/basic.js
export const basicTools = [
  {
    name: 'my_tool',
    description: '我的工具描述',
    
    inputSchema: {
      type: 'object',
      properties: {
        input: {
          type: 'string',
          description: '输入参数'
        }
      },
      required: ['input']
    },
    
    handler: async (args) => {
      const { input } = args
      // 实现逻辑
      return { success: true, result: input }
    }
  },
  // ...其他工具
]

2. 注册工具模块（如果是新类别）

// src/mcp/tools/index.js
const toolModules = {
  basic: { file: './basic.js', export: 'basicTools' },
  myCategory: { file: './myCategory.js', export: 'myCategoryTools' },
  // ...
}

const categoryMeta = {
  myCategory: { 
    name: '我的类别', 
    description: '类别描述', 
    icon: 'Tool' 
  }
}

3. 配置启用

builtinTools:
  enabledCategories:
    - basic
    - myCategory

工具示例

获取时间

// src/mcp/tools/basic.js
{
  name: 'get_current_time',
  description: '获取当前时间和日期信息',
  
  inputSchema: {
    type: 'object',
    properties: {
      format: {
        type: 'string',
        description: '时间格式：full(完整)、date(仅日期)、time(仅时间)、timestamp(时间戳)',
        enum: ['full', 'date', 'time', 'timestamp']
      },
      timezone: {
        type: 'string',
        description: '时区，默认 Asia/Shanghai'
      }
    }
  },
  
  handler: async (args) => {
    const now = new Date()
    const tz = args.timezone || 'Asia/Shanghai'
    const format = args.format || 'full'
    
    const options = { timeZone: tz }
    const dateStr = now.toLocaleDateString('zh-CN', { ...options, year: 'numeric', month: '2-digit', day: '2-digit' })
    const timeStr = now.toLocaleTimeString('zh-CN', { ...options, hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false })
    const weekday = ['日', '一', '二', '三', '四', '五', '六'][now.getDay()]
    
    return {
      text: `当前时间: ${dateStr} ${timeStr} 星期${weekday}`,
      datetime: now.toISOString(),
      timestamp: now.getTime(),
      timezone: tz
    }
  }
}

发送消息（需要上下文）

// src/mcp/tools/message.js
import { getBuiltinToolContext } from '../BuiltinMcpServer.js'

{
  name: 'send_private_message',
  description: '发送私聊消息',
  
  inputSchema: {
    type: 'object',
    properties: {
      user_id: { type: 'string', description: '目标用户QQ号' },
      message: { type: 'string', description: '消息内容' }
    },
    required: ['user_id', 'message']
  },
  
  handler: async (args) => {
    const ctx = getBuiltinToolContext()
    const bot = ctx.getBot()
    
    await bot.pickUser(args.user_id).sendMsg(args.message)
    return { success: true, text: '消息已发送' }
  }
}

工具属性

属性	类型	说明
name	string	工具名称（必需，唯一标识）
description	string	工具描述（必需，AI可见）
inputSchema	object	JSON Schema 参数定义
handler	function	异步处理函数 async (args) => result

下一步

• 自定义 JS 工具 - 开发用户工具
• 安全与权限 - 工具安全配置