Research Report · 2026-08

matrix MCP Server
高保真复刻与公开部署平台

以 Go 重写 MiniMax matrix MCP server,工具面逐字节对齐线上,并在此基础上构建"本地归档 → 公开站点"的一键发布闭环。

Created by GearShell · 部署于 matrix.k0s.io · 源码 github.com/gearshell/matrix

MCP 工具(22 线上保真 + 2 复刻扩展)

schema 与线上 diff(tools/list 逐字节)

100%

全量测试通过(含 e2e 与真实 server 对比)

一条命令发布静态站点到公网

一、项目背景与定位

MiniMax matrix 是一个提供图像/视频/音频生成、网页搜索、站点部署等能力的 MCP server。本项目以 modelcontextprotocol/go-sdk 为基础,对其实施 高保真复刻:22 个工具的 name / description / inputSchema 与线上逐字节一致(tools/list 实时对比 DIFFS: 0),行为可通过 proxy 模式转发真实后端保持原真,也可在 mock / 本地部署模式下离线运行。

复刻之外,项目回答了另一个问题:一个部署在内网的 MCP server,如何让所有人无门槛地发布网站? 由此衍生出 upload / deploy 扩展、纯 HTTP 上传端点与配套 CLI,形成完整的公开发布平台。

二、架构设计

2.1 分层与接缝

schema 来源:线上 tools/list 抓取为 schema.json 嵌入二进制,杜绝反射漂移;
Handler 接口:22 个方法(每工具一个)是复刻/真实行为切换的接缝,proxy 与 mock 只是不同实现;
输出透传:Output = []byte,真实 server 的 content[0].text 原样透传,不做结构解析;
envelope 字节级补丁:go-sdk 表达不了的细节(display_data、显式 isError、deploy 的 required 还原) 通过 json.Decoder + InputOffset 定位后外科手术式拼接,未改动字节逐字节保留;
按需缓冲:仅 tools/list 与 deploy 响应走缓冲改写,其余请求流式透传。

2.2 复刻扩展(2 个新工具)

工具	输入	行为
`remote_deploy`	archive_url 或 archive_data(base64)	解压 tar.gz/zip 并发布为独立子域站点
`upload_file`	data(base64, ≤64MiB)	内容直接发布到 CDN 子域,返回直链
`upload_to_cdn`*(线上工具,本地实现)	file_path(server 端路径)	server 文件发布到 CDN,与真实语义一致

*upload_to_cdn 属于线上 22 工具,此处为本地真实实现而非 mock。

三、公开部署闭环

3.1 三条发布路径

路径	场景	效率
`POST /api/deploy`	curl / 脚本 / agent 有 shell	二进制直传,一步到位
`upload_file` → `remote_deploy`	必须走 MCP 工具	base64 膨胀 33%,两步
`remote_deploy(archive_url)`	归档已在公开 URL	零上传,server 拉取

上传后的文件本身即 CDN 直链(https://<site>.matrix.k0s.io/<file>),任何人可下载; remote_deploy 支持 /data/<site>/<file> 本地路径,自产自销零网络往返。

3.2 安全与工程细节

解压全程防护:zip-slip / tar 遍历拒绝、符号链接跳过、100 MiB 解压上限(防炸弹)、单顶级目录自动剥离;
路径穿越双保险:deploy 的 workspace 校验与站点服务的 Rel 检查;
全端点 CORS 放开(预检 204),URL scheme 可配(--scheme https),站点列表按 X-Forwarded-Proto 自适应;
注入能力:--inject 将 GearShell 品牌浮动球幂等注入每个 index.html(HTML5 tokenizer 级重写,字面 </body> 不误伤)。

四、使用方式

# 一条命令发布本地 dist(目录自动打包)
matrix deploy ./dist
# 或独立 CLI
deploy ./dist
# 或纯 HTTP
curl -X POST --data-binary @site.tar.gz -H 'Content-Type: application/gzip' \
  https://matrix.k0s.io/api/deploy

输出 {"website_id": ..., "website_url": "https://<random>.matrix.k0s.io", ...}, 每次部署生成全新随机子域,历史站点永久保留。MCP 端点: /mcp/message(24 工具)与 /mcp/mini/message(仅发布两件套)。

五、工程与部署事实

测试:全绿;22 工具调用级覆盖、envelope 字节保真、归档解压安全、CLI/API e2e 均有专项测试;
验证:与真实 server 的 tools/list 逐字节对比 0 diff;输出形状实测对齐(如 images_list 的 markdown 形态);
部署:k3s + traefik + cert-manager(DNS-01 通配符证书),启动时 git clone + go build(runtime-build 模式),PVC 持久化全部发布物;
分发:稳定 URL https://matrix.k0s.io/skill.md 承载 skill,crush 启动时注入上下文,随 server 部署自动更新。

六、结语

这个项目把"复刻一个线上服务"做成了"跑通一个公开平台":保真度以字节为单位计量,发布路径收敛到一条命令。后续方向:发布物生命周期管理(保留/清理策略)、按 token 的用量配额、以及把 mini 端点开放给更多客户端接入。