previewglow

previewglow

previewglow 是一个小型本地桥接程序，连接托管的 Shareglow MCP 服务，负责处理链接预览 和 Open Graph 图片。指定一个公开页面，它便会 报告该页面的预览元数据、各平台的 预览效果，以及发现的任何问题，并提供 修复建议。它可以使用 工作区中的模板渲染 1200x630 的 OG 图片，为网站的品牌 设计全新模板，创建带有自身预览效果的短链接， 报告这些链接的点击情况，并强制社交平台 重新抓取标签刚刚更改的页面。

该桥接程序不会自行保存预览数据。它会在本地提供 上游服务的工具列表，该列表与从实时端点捕获的内容完全一致，并将每次 工具调用转发到上游，原样返回结果。 此处的所有操作都针对调用者自己的 Shareglow 工作区或调用者指定的公开页面；此界面中 没有发送、支付或消息工具。

工具

• scan_url — 扫描公开页面并报告其 链接预览（Open Graph / Twitter Card）元数据、 各平台的预览效果，以及问题和修复 建议。必填：url。
• generate_og_image — 使用模板渲染 1200x630 的 Open Graph 图片。必填：templateId。 可选：params（标题和副标题等文本值）以及 exp（Unix 秒数；使签名 URL 过期，适用于付费方案）。返回永久图片 URL，以及图片是否已缓存。
• create_template_from_url — 使用 AI 根据网站的品牌 （徽标、颜色、字体）设计新的 OG 图片模板。必填：url。返回选定的 layoutId、要传入的变量以及提取的 品牌套件。
• list_templates — 列出工作区可用于渲染的 OG 图片模板 （内置和自定义），包括 id、 name、version 和 dimensions。不接受参数； 在调用 generate_og_image 之前调用此工具以选择 templateId。
• create_short_link — 创建带有自身链接预览的短链接。 必填：destination。可选：slug 和最多三个 A/B variants。返回 id、shortUrl 和 variants。
• get_link_stats — 获取短链接的点击分析数据：总数，以及按天、 国家/地区、设备、浏览器和引荐来源划分的数据。必填：linkId。 可选：from / to 日期（YYYY-MM-DD）。
• refresh_preview — 在页面的 OG 标签或图片更改后， 强制社交平台重新抓取其链接预览。必填：url。

配置

• SHAREGLOW_MCP_URL（可选）— 覆盖 上游端点。默认值为 https://mcp.getshareglow.com/mcp。（此覆盖 钩子是本次重建中自行标注的还原实现。）
• SHAREGLOW_API_KEY（可选）— 设置后，每个 上游请求都会携带 Authorization: Bearer <key> 标头，用于传入 调用者自己的 Shareglow 密钥（在调用者的 Shareglow 控制台中创建的 sk_live_... 密钥）。未设置时， 不会发送密钥标头。（标头 名称和 Bearer 模板由原始注册记录确定；通过此 环境变量转发密钥是自行标注的还原实现—— 捕获原始界面时未使用密钥。）

转发机制

首次调用工具时，客户端会与上游建立一个可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26， clientInfo 名称为 previewglow），然后发送 notifications/initialized 通知，接着发送携带调用方参数且 未作任何修改的 tools/call 请求。上游响应 initialize 时，如果带有 Mcp-Session-Id 标头，该值会随 此会话的每个后续请求一同发送；该会话会在进程的整个生命周期内 重复使用。响应可能是普通 JSON，也可能是服务器发送事件； 两种格式都会读取。

成功的上游结果会原样传递，包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或 无法完成的请求——会作为 isError 结果返回，其 文本以 previewglow error: 开头（这种呈现方式是本次重建自行添加的标注）。

CLI

每个工具也是一个子命令，接受一个 JSON 参数字符串：

npx @reneturcios/previewglow scan_url '{"url":"https://example.com/landing"}'
npx @reneturcios/previewglow get_link_stats '{"linkId":"lnk_abc-123"}'
npx @reneturcios/previewglow --version

退出码：成功时为 0，结果为 isError 时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/previewglow mcp

MCP 客户端配置：

{
  "mcpServers": {
    "previewglow": {
      "command": "npx",
      "args": ["-y", "@reneturcios/previewglow", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/previewglow
docker run --rm ghcr.io/cloudcorprecords/previewglow --version

容器的默认命令是 mcp，因此第一种形式会启动一个 stdio MCP 服务；其他参数则会照常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全针对一个模拟的 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT——参见 LICENSE。