Yunzai-MCP-Plugin

20260628 应社区要求重传

实现LLM的插件自动化测试能力，从沙盒调试中解放出来
适用于trss yunzai (V3) ，项目时开发使用版本f793f5a(2025-01-03)

[!WARNING]
项目仅为内网环境开发环境、公共一次性测试实例设计；自用bot不建议端口暴露到公网，继续阅读即视为知晓风险

已实现的功能特性

够聪明的的LLM可以直接调度下列端点，碳基生物一般无需了解用法：

<details> <summary><strong>MCP 工具</strong></summary>

工具名	API 动作	分类	功能说明	关键参数/说明
bot_status	bot.status	Bot 管理	查询 Yunzai 当前运行状态、适配器、插件、路由与资源占用	无
bot_restart	bot.restart	Bot 管理	触发延迟重启 Bot，可选强制模式	force(可选), delay(毫秒)
bot_shutdown	bot.shutdown	Bot 管理	在指定延迟后优雅关闭 Bot 进程	delay(毫秒)
mock_incoming_message	mock.incoming.message	消息调试	向 Mock 适配器注入入站消息（单聊/群聊），可等待聚合回复	message, user_id; 可选 group_id, nickname, role, waitMs, traceId
mock_status	mock.status	Mock 环境	查看 Mock 适配器初始化状态及收发统计	无
mock_friend_add	mock.friend.add	Mock 环境	注册模拟好友档案，便于构造回放	user_id; 可选 nickname
mock_friend_remove	mock.friend.remove	Mock 环境	移除指定模拟好友	user_id
mock_friend_list	mock.friend.list	Mock 环境	列出全部模拟好友	无
mock_group_add	mock.group.add	Mock 环境	创建模拟群并返回基本信息	group_id; 可选 name
mock_group_remove	mock.group.remove	Mock 环境	删除指定模拟群	group_id
mock_group_list	mock.group.list	Mock 环境	列出所有模拟群	无
mock_group_member_add	mock.group.member.add	Mock 环境	向模拟群添加成员，支持角色设定	group_id, user_id; 可选 nickname, role
mock_group_member_remove	mock.group.member.remove	Mock 环境	从模拟群移除指定成员	group_id, user_id
mock_group_members	mock.group.members	Mock 环境	查询指定模拟群的成员列表	group_id
mock_history	mock.history	Mock 环境	查看模拟适配器的收发历史（合并 inbox/outbox）	可选 type, target, limit
message_history	message.history	消息查询	获取指定会话的历史消息记录	type; 可选 user_id, group_id, count, message_seq, bot_id
message_get	message.get	消息查询	根据消息 ID 获取完整消息内容	message_id; 可选 bot_id
message_forward	message.forward	消息查询	获取合并转发消息的节点内容	message_id; 可选 bot_id
recall_message	recall.message	消息查询	撤回指定消息（Mock 侧同步标记撤回状态）	message_id; 可选 type, user_id, group_id, bot_id

</details>

<details> <summary><strong>HTTP API 扩展动作</strong></summary>

API 动作	分类	功能说明	关键参数/说明
bot.info	Bot 管理	列出当前注册的 Bot 实例（uin、昵称、状态、好友/群数量）	无
time.get	时间服务	按指定时区返回当前时间戳、格式化结果与时间组件	可选 timezone
time.format	时间服务	将给定时间戳格式化为指定模板	timestamp; 可选 format, timezone
time.diff	时间服务	计算起止时间差并返回多单位表示与人类可读描述	start; 可选 end, unit
time.timezone	时间服务	查看常用时区的当前时间与偏移信息	可选 timezone
redis.get	Redis 管理	读取 Redis 键值并返回存在状态	key
redis.set	Redis 管理	写入 Redis 键值，可选过期秒数	key, value; 可选 expire
redis.del	Redis 管理	删除一个或多个 Redis 键	key 或 keys[]
redis.keys	Redis 管理	按模式列出 Redis 键并限制返回数量	可选 pattern, limit
redis.info	Redis 管理	汇总 Redis 服务器、内存、统计与键空间数据	无
redis.exists	Redis 管理	判断单个或多个键是否存在	key 或 keys[]
redis.ttl	Redis 管理	查询键的剩余过期时间及状态	key
redis.expire	Redis 管理	为键设置过期秒数并返回预计过期时间	key, seconds
logs.get	日志管理	按条件抓取最近日志记录，支持级别与关键词过滤	可选 lines, level, search, since, includeRaw
logs.clear	日志管理	清空日志缓冲区并返回清理数量	无
logs.stats	日志管理	获取日志数量、级别分布与最近窗口统计	无
logs.setLevel	日志管理	设置日志捕获级别并即时生效	level
logs.export	日志管理	按 JSON/CSV/TEXT 导出日志内容	可选 format, level, search, since
file.read	文件服务	从安全目录读取文件内容与元数据	path; 可选 encoding
file.write	文件服务	写入/覆盖安全目录中的文件	path, content; 可选 encoding
file.delete	文件服务	删除安全目录中的文件并返回删除结果	path
file.list	文件服务	列出安全目录下的文件/文件夹，支持递归	可选 path, recursive
file.info	文件服务	查看安全目录中文件/目录的详细属性	path
system.info	系统监控	返回操作系统、CPU、内存、网络等基础信息	无
system.stats	系统监控	获取进程、系统资源与磁盘使用等统计	无
system.processes	系统监控	列表化系统进程并按 CPU/内存排序	可选 limit, sortBy
memory.info	系统监控	查看 Node 进程与主机内存使用详情	无
system.performance	系统监控	评估 CPU、事件循环延迟与运行时性能指标	无
network.ping	网络诊断	对指定主机执行 ping 并返回丢包/耗时统计	host; 可选 count, timeout
network.request	网络诊断	发送 HTTP(S) 请求并返回响应头与内容	url; 可选 method, headers, body, timeout
network.download	网络诊断	下载远程文件到 data/mcp_client 并返回路径	url, savePath
network.connectivity	网络诊断	测试预置站点连通性并统计在线情况	无
network.interfaces	网络诊断	列出主机网络接口及地址信息	无
network.testPort	网络诊断	测试目标主机端口连通性并返回响应耗时	host, port; 可选 timeout
render.template	渲染服务	调用渲染器生成模板截图并写入 data/mcp_client	template/path; 可选 plugin, data, options
mock.init	Mock 环境	初始化并注册 Mock 适配器实例	无
mock.reset	Mock 环境	重置 Mock 适配器（好友/群/收发历史清空）	无
mock.send.friend	Mock 环境	通过 Mock 适配器向指定模拟好友发送消息，写入可回放的 outbox	user_id, message
mock.send.group	Mock 环境	通过 Mock 适配器向指定模拟群发送消息，写入可回放的 outbox	group_id, message

</details>

修改功能权限请自行在 config/config.yaml 中配置

快速上手

git clone https://github.com/XuF-163/Yunzai-MCP-plugin ./plugins/Yunzai-MCP-plugin

gitee源

git clone https://gitee.com/xyzqwefd/Yunzai-MCP-plugin ./plugins/Yunzai-MCP-plugin

依赖安装

pnpm i

效果演示

demo：使用TRAE 国服免费版本进行测试

TO DO

- [ ] 内置Context Engine以减少agent阅读代码时的token消耗以及索引效率提升用别的MCP替代就行了
- [ ] 对非合作Bot进行扫描、调试、风险评估、功能分析与二次开发
- [ ] 针对国产模型优化，提升较小上下文窗口条件下的开发质量 glm-4.6的200k够用了用serena顶一下

示例

推荐使用MCP ROUTER统筹管理

• Codex

[mcp_servers.mcp-router]
command = "C:\\Program Files\\nodejs\\node.exe" 
args = ["C:\\Users\\X\\AppData\\Roaming\\npm\\node_modules\\mcpr-cli\\dist\\mcpr.js", "connect"] 
env = { SystemRoot = 'C:\WINDOWS', COMSPEC = 'C:\WINDOWS\system32\cmd.exe' , MCPR_TOKEN = "mcpr_2gU3vMTLPcVjqJSY1KrPfPvJ848xDo5b" }

• ClaudeCode

略

• 在你的IDE(例如Aug. Trae 等)中以json格式导入MCP时候直接使用，注意替换路径

{
  "mcpServers": {
    "yunzai-mcp": {
      "command": "node",
      "args": [
        "C:\\Users\\X\\Desktop\\Bot-Dev\\Yunzai\\plugins\\Yunzai-MCP-plugin\\mode\\dist\\mcp-server.js"
      ],
      "env": {
        "YUNZAI_API_KEY": "mcp-yunzai-2024",
        "YUNZAI_BASE_URL": "http://127.0.0.1:2536",
        "YUNZAI_MCP_PATH": "/MCP"
      }
    }
  }
}

授权协议 (License)

本项目采用 MIT License + Commons Clause v1.0 联合授权，在保持开源自由的同时阻止商业化滥用。

MIT License

• 宽松许可证，允许自由使用、复制、修改、合并、出版、分发、再授权及销售软件副本，前提是保留原始版权声明。
  其中：

Commons Clause v1.0

• 该附加条款明确 禁止“销售” 本软件。“销售”被广义定义，包括但不限于：
  • 将本软件或其主要功能作为付费产品或服务提供；
  • 将本软件或其主要功能作为商业 SaaS 的一部分提供；
  • 利用本软件开发闭源或收费的衍生或非衍生的插件 / 项目；
  • 其它涉及传销、诈骗、引流、变现等不合乎社会公序良俗的活动；

使用须知

• 本项目服务于开源社区，Fork、Clone 或以任何方式使用即表示您已阅读并同意上述授权条款；
• 禁止将本项目的任何部分用于营利性闭源插件、传销、诈骗、引流、变现等违背社区精神或社会公序良俗的活动；

赞助与支持

通过我的AFF链接购买GLM Coding可享受九折优惠