Sherweb

Sherweb MCP 服务

面向 Sherweb 云市场和合作伙伴门户的模型上下文协议（MCP）服务。支持 AI 助手管理客户订阅、浏览产品目录并处理账单操作。

这是一个模型上下文协议（MCP）服务，可将 Claude（或任何兼容 MCP 的 AI）连接到您的 Sherweb 环境。

属于 MSP Claude Plugins 生态系统的一部分 — 为 MSP 技术栈打造且不断扩展的 AI 集成套件。由 MSP 为 MSP 打造。

安装

npm install @wyre-ai/sherweb-mcp

配置

复制 .env.example，并设置以下变量。

变量	必填	说明
SHERWEB_CLIENT_ID	用于 stdio 和 AUTH_MODE=env	Sherweb API 客户端 ID
SHERWEB_CLIENT_SECRET	用于 stdio 和 AUTH_MODE=env	Sherweb API 客户端密钥
SHERWEB_SUBSCRIPTION_KEY	用于 stdio 和 AUTH_MODE=env	Sherweb API 订阅密钥
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 默认值）或 env。Gateway 模式要求每个 /mcp 请求都包含 X-Sherweb-Client-ID、X-Sherweb-Client-Secret 和 X-Sherweb-Subscription-Key，且绝不会回退到 SHERWEB_*。只有在 S2S 身份验证成功后，env 模式才会使用这些变量。
CONDUIT_S2S_SECRET	HTTP 必填	服务间密钥。如果该值为空或是已知占位符（changeme、your-s2s-secret、placeholder、secret 以及类似的复制示例），HTTP 服务会记录错误并以非零状态码退出。未设置此值时，Compose 不会启动。切勿提交真实值。使用 openssl rand -hex 32 生成。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设为 1，以便在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制要求 X-Gateway-S2S，且仅绑定到 127.0.0.1。非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略，并记录此覆盖情况。仍会拒绝占位符密钥。
MCP_HTTP_HOST	否	当 MCP_TRANSPORT=http 且已设置 CONDUIT_S2S_SECRET 时使用的绑定地址。默认为 127.0.0.1。容器镜像设为 0.0.0.0。未设置真实密钥时，监听地址为 127.0.0.1。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

/health 和 /healthz 无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。如果缺少此标头或标头无效，将返回 401，且在此之前不会读取供应商凭据。密钥绝不会写入日志。

标头值为 t=<unix seconds>,v1=<hex hmac-sha256>。v1 是使用 CONDUIT_S2S_SECRET 作为密钥，对精确的 ASCII 字符串 t=<unix seconds> 进行 HMAC-SHA256 运算后，再以十六进制编码的结果（64 个小写十六进制字符）。时间戳必须在服务器时钟的 300 秒范围内。

t=1710000000,v1=<hmac-sha256("t=1710000000", CONDUIT_S2S_SECRET) as hex>

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Sherweb-Client-ID、X-Sherweb-Client-Secret 和 X-Sherweb-Subscription-Key。这些标头是该请求唯一的凭据来源。请求缺少其中任何一项都会返回 401，且不会回退到进程环境中的 SHERWEB_*。

使用方法

使用 Claude Desktop 运行

将以下内容添加到 Claude Desktop 的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "sherweb-mcp": {
      "command": "npx",
      "args": ["@wyre-ai/sherweb-mcp"],
      "env": {
        "SHERWEB_CLIENT_ID": "your-sherweb-client-id",
        "SHERWEB_CLIENT_SECRET": "your-sherweb-client-secret",
        "SHERWEB_SUBSCRIPTION_KEY": "your-sherweb-subscription-key"
      }
    }
  }
}

使用 Claude Code（CLI）运行

claude mcp add sherweb-mcp \
  -e SHERWEB_CLIENT_ID=your-value \
  -e SHERWEB_CLIENT_SECRET=your-value \
  -e SHERWEB_SUBSCRIPTION_KEY=your-value \
  -- npx -y @wyre-ai/sherweb-mcp

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），默认使用 AUTH_MODE=gateway。将端口发布到环回地址，并传入 S2S 密钥。在网关模式下，Sherweb 凭据会作为请求头随每个请求传入；不会从环境变量中读取。

docker build -t sherweb-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  sherweb-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；它会设置 AUTH_MODE=gateway，发布 127.0.0.1:8080:8080，并且不会将 SHERWEB_CLIENT_ID、SHERWEB_CLIENT_SECRET 或 SHERWEB_SUBSCRIPTION_KEY 传入容器：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 SHERWEB_*：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e SHERWEB_CLIENT_ID=your-value \
  -e SHERWEB_CLIENT_SECRET=your-value \
  -e SHERWEB_SUBSCRIPTION_KEY=your-value \
  -p 127.0.0.1:8080:8080 \
  sherweb-mcp

不使用密钥的本地 HTTP 仅供开发使用。它只绑定到 127.0.0.1（更宽泛的 MCP_HTTP_HOST 设置会被忽略），并会记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

可用领域

账单

查看分销商在某个账期的应付费用，以及单笔费用的详情。Sherweb 仅按账期返回费用集合，因此这两个工具都接受用于标识账期的可选 date。

目录

浏览可向指定客户销售的产品。在 Sherweb 中，目录按客户划分，没有全局产品列表，因此必须提供 customerId。

客户

列出和查找客户，并查看你在某个账期向客户收取的应收费用。

订阅

列出客户的订阅、获取某项订阅的详情，以及提交数量变更。变更是异步的：提交后会返回跟踪 ID，sherweb_subscriptions_amendment_status 会报告处理结果。

交互式订阅卡片（MCP Apps）

在 MCP Apps 主机（Claude Desktop/web）中，sherweb_subscriptions_get 会渲染为交互式只读卡片，显示产品、客户、状态、数量、账期、承诺/续订日期和费用；在其他主机中，纯 JSON 行为保持不变。卡片默认采用中性样式，可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）进行品牌定制，无需重新构建。

开发

# Clone the repository
git clone https://github.com/WYRE-AI/sherweb-mcp.git
cd sherweb-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# HTTP transport refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http npm start

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_TRANSPORT=http npm start

贡献

欢迎贡献！如果存在 CONTRIBUTING.md，请参阅该文件；也可以提交 issue 讨论变更。

许可证

本项目基于 Apache License 2.0 许可。详情请参阅 LICENSE。