stagenth-mcp-shim 0.3.0

stagenth file-relay 的本地 stdio MCP 代理壳 (shim)，桥接到远端 HTTPS MCP 服务

stagenth-mcp-shim

把 stagenth file-relay 这个远端 HTTPS MCP 服务 装进一个跑在你本机的 stdio MCP server, 让 Cline / Claude Desktop / Cursor 等只支持 stdio 的客户端能无痛接入, 并且 让 download_file 真正把文件下到你本地磁盘而不是让 AI 在上下文里读一堆 base64 再自己写代码解码。

为什么存在

直接用远端 HTTPS MCP (type: "http" / url: "https://...") 配置, 在 VS Code Cline 等客户端上握手/鉴权经常踩坑。本地 stdio 形态是所有客户端最稳定支持的方式。

本 shim 做两件事:

1. 透明代理 —— Cline 发的 JSON-RPC 用 stdio 收进来, 转成 HTTPS POST 打到 https://stagenth.com/mcp/file-relay/, 响应按 SSE 解析后写回 stdio。
2. download_file 劫持 —— 在远端原参数基础上多一个 save_to 字段。AI 调用后, 字节在 shim 进程里流式写到你本机磁盘, AI 的上下文只看到 {"saved_to": "/abs/path", "size_bytes": ..., "sha256": "..."}, 不再拉 base64, 也不需要 AI 自己 curl。

安装

# 需要 Python >= 3.10
pip install stagenth-mcp-shim

开发版 (本仓库):

cd mcp-shim
pip install -e .

装完应当拿到 stagenth-mcp CLI:

stagenth-mcp --help    # (目前无参数, 直接跑就是 stdio server)

拿 API Token

1. 浏览器打开 https://stagenth.com/mcp/file-relay/console/tokens
2. NEW TOKEN → 复制明文 (mcp_xxxxxxxx... 47 字符, 只会显示一次)
3. 下一步把它填进客户端配置的 env

在 VS Code Cline 里接入

打开 Cline 的 MCP 配置 (Cline 图标 → Settings → MCP Servers → Edit), 加:

{
  "mcpServers": {
    "stagenth-file-relay": {
      "command": "stagenth-mcp",
      "env": {
        "STAGENTH_TOKEN": "mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

保存 → Cline 会自动重启这个 server → 应当看到 10 个工具 (绿灯)。

在 Claude Desktop 里

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "stagenth-file-relay": {
      "command": "stagenth-mcp",
      "env": {
        "STAGENTH_TOKEN": "mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

在 Cursor 里

~/.cursor/mcp.json:

{
  "mcpServers": {
    "stagenth-file-relay": {
      "command": "stagenth-mcp",
      "env": {
        "STAGENTH_TOKEN": "mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

可选环境变量

变量	默认	说明
STAGENTH_TOKEN	(必填)	file-relay API Token
STAGENTH_ENDPOINT	https://stagenth.com/mcp/file-relay/	远端 MCP endpoint, 末尾 / 必须
STAGENTH_TIMEOUT	600	单请求超时 (秒); 大文件上传可能要久
STAGENTH_DOWNLOAD_DIR	~/Downloads	默认下载目录 (没传 save_to 时)

10 个工具

跟远端完全对齐, 唯一区别是 download_file 多了两个参数:

• save_to (string, optional) —— 落地路径, 相对路径基于 $STAGENTH_DOWNLOAD_DIR
• overwrite (boolean, default false) —— 已存在时是否覆盖, false 时加 (1) (2) 后缀

其它工具 (list_files / upload_file / get_user_quota / create_share_link / download_shared_file / import_shared_file / search_files / get_file_info / delete_file) 100% 透传, 文档见 https://stagenth.com/mcp/file-relay 或仓库里的 docs/MCP.md。

Troubleshooting

客户端显示 "connection closed" / "server crashed"

stderr 日志里有线索 (Cline 里点 MCP server 卡片能看到 stderr):

• FATAL: STAGENTH_TOKEN 环境变量未设置 → 检查 env 块拼写
• 远端 HTTP 401: mcp_invalid_token → Token 错/过期, 重新生成
• 远端 HTTP 403: feature_not_in_plan → 档位不够, 去 https://stagenth.com/mcp/file-relay?tab=plans 升级
• SSE 响应里没找到 data: 行 → 网络中间件吞了 SSE (公司网关常见), 换网络或联系运维

下载后文件在哪

默认 ~/Downloads。想改: 配置里加 env.STAGENTH_DOWNLOAD_DIR, 或让 AI 调用时传 save_to 绝对路径。

同名文件不想被覆盖

默认不覆盖, shim 会自动加 (1) / (2) 后缀。想覆盖: AI 传 overwrite: true。

开发

pip install -e ".[dev]"
# 手动跑一下, 用 stdin/stdout 跟它对话
STAGENTH_TOKEN=mcp_xxx stagenth-mcp
# 粘一个 initialize 请求:
# {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"0"}}}

License

MIT