Metadata-Version: 2.4
Name: stagenth-mcp-shim
Version: 0.2.0
Summary: stagenth file-relay 的本地 stdio MCP 代理壳 (shim)，桥接到远端 HTTPS MCP 服务
Project-URL: Homepage, https://stagenth.com/mcp/file-relay
Project-URL: Documentation, https://stagenth.com/mcp/file-relay
Project-URL: Source, https://stagenth.com
Author: stagenth
License: MIT
Keywords: file-relay,mcp,model-context-protocol,stagenth
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# stagenth-mcp-shim

把 [stagenth file-relay](https://stagenth.com/mcp/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。

## 安装

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

开发版 (本仓库):

```bash
cd mcp-shim
pip install -e .
```

装完应当拿到 `stagenth-mcp` CLI:

```bash
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), 加:

```json
{
  "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):

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

### 在 Cursor 里

`~/.cursor/mcp.json`:

```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`。

## 开发

```bash
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
