qca-mcp-proxy 0.1.0__tar.gz

qca_mcp_proxy-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.DS_Store
+.env

qca_mcp_proxy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Larry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qca_mcp_proxy-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: qca-mcp-proxy
+Version: 0.1.0
+Summary: Filtered MCP proxy in front of the Qoder Cloud Agents (QCA) remote MCP server, over stdio or Streamable HTTP
+Project-URL: Homepage, https://github.com/xiaochus/qca_mcp_proxy
+Project-URL: Repository, https://github.com/xiaochus/qca_mcp_proxy
+Project-URL: Issues, https://github.com/xiaochus/qca_mcp_proxy/issues
+Author-email: Larry <xiaochus@live.cn>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cloud-agents,mcp,model-context-protocol,proxy,qoder,stdio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: uvicorn>=0.31
+Description-Content-Type: text/markdown
+
+# qca-mcp-proxy
+
+把 Qoder Cloud Agents（QCA）的远程 MCP 服务包一层 MCP 服务：只转发 **session 相关工具**，外加 `list_agents` / `list_environments` / `list_vaults` 三个只读查询和 `list_files` / `get_file` 两个文件元数据查询。其余工具（agent / environment / vault / skill / deployment 的写操作、session 资源等）既不列出也不可调用。
+
+- 上游：QCA 远程 MCP，Streamable HTTP + `Authorization: Bearer <PAT>`
+- 下游：两种跑法，同一套白名单
+  - `--transport stdio`（默认）：给 Qoder / Claude Desktop 这类拉起子进程的客户端
+  - `--transport http`：起一个 `http://127.0.0.1:8790/mcp` 的服务地址，客户端填 URL 即可
+- 实现用 MCP Python SDK v2（`mcp>=2,<3`）
+- 工具列表每次 5 分钟内缓存一次，避免每次 `tools/list` 都打上游
+
+## 暴露的工具（13 个）
+
+| 分组 | 工具 |
+| --- | --- |
+| session 生命周期 | `create_session` `get_session` `list_sessions` `update_session` `cancel_session` |
+| session 事件 | `send_session_events` `list_session_event_summaries` `list_session_events` |
+| 只读查询 | `list_agents` `list_environments` `list_vaults` |
+| 文件元数据 | `list_files`（传 `scope_id=<session_id>` 查会话产出）`get_file` |
+
+工具名与参数 schema 全部原样透传上游，不做改写；返回的 `content` / `structured_content` / `is_error` 也原样返回。
+
+刻意不在白名单里（`tools/list` 不返回，`tools/call` 也拒绝）：
+
+- session 资源四件套 `add_session_resource` / `get_session_resource` / `list_session_resources` / `delete_session_resource`：文件、GitHub 仓库、memory store 只能在 `create_session` 的 `resources` 里一次性挂上，会话中途不能再挂
+- `archive_session` / `delete_session`：只能 `cancel_session` 停掉会话，清理交给控制台或 `QCA_EXTRA_TOOLS` 追加
+- agent / environment / vault / skill / deployment 的写操作全部隐藏，只留三个 `list_*`
+
+## 安装
+
+```bash
+# 1) 直接跑源码（推荐本地开发）
+uvx --from /Users/wbc/Desktop/ascend_adapter/qca-mcp-proxy qca-mcp-proxy --check
+
+# 2) 从 git 安装
+uvx --from git+https://github.com/<you>/qca-mcp-proxy qca-mcp-proxy
+
+# 3) 装成常驻命令行
+uv tool install /Users/wbc/Desktop/ascend_adapter/qca-mcp-proxy
+qca-mcp-proxy --check
+```
+
+`--check` 会用当前 PAT 连一次上游，打印「上游工具数 / 已暴露 / 被隐藏」后退出，用来确认 PAT 和区域对不对。
+
+## 以服务地址跑（Streamable HTTP）
+
+```bash
+cd /Users/wbc/Desktop/ascend_adapter/qca-mcp-proxy
+export QCA_PAT=<你的 PAT>
+export QCA_REGION=cn
+
+# 起服务（默认监听 127.0.0.1:8790）
+.venv/bin/qca-mcp-proxy --transport http
+# 或者： uvx --from . qca-mcp-proxy --transport http
+```
+
+启动成功会打印：
+
+```
+[qca-proxy] INFO qca_mcp_proxy.server: serving Streamable HTTP on http://127.0.0.1:8790/mcp
+[qca-proxy] INFO qca_mcp_proxy.upstream: connected to https://mcp.qoder.cn/... (cn region)
+[qca-proxy] INFO qca_mcp_proxy.server: qca proxy ready: region=cn ...
+```
+
+然后在 agent 里把服务地址填成 `http://127.0.0.1:8790/mcp`；如果客户端用 `mcpServers` 配置，写：
+
+```json
+{"mcpServers": {"qca": {"url": "http://127.0.0.1:8790/mcp"}}}
+```
+
+相关开关：
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `--host` | `127.0.0.1` | 只给本机用就保持默认；要同网段访问改 `0.0.0.0`（SDK 只对回环地址做 DNS rebinding 防护，改后请自行加 `--auth-token`） |
+| `--port` | `8790` | 监听端口，端口冲突时换一个 |
+| `--stateless` | 关 | 不带 `mcp-session-id` 的无状态模式。有些 agent 每个请求都新开连接，用它会报 “session not found”，这时加这个参数 |
+| `--auth-token` | 空 | 要求请求带 `Authorization: Bearer <token>`，也可用 `QCA_HTTP_TOKEN`。只在本机测可以不加 |
+
+启动前会先探一次上游：PAT 不对或区域不匹配时直接一行报错退出，不会起一个连不上上游的空服务：
+
+```
+[qca-proxy] cannot reach QCA: MCPError(-32603): Server returned an error response
+
+The cn endpoint (https://mcp.qoder.cn/api/v1/mcp/servers/qca) rejected the request. ...
+```
+
+## 配置
+
+### Qoder / 兼容 `mcpServers` 的客户端
+
+`args` 里的 `--from` 有两种来源，按安装方式二选一。
+
+从 git 安装（推荐，换机器不用改路径）：
+
+```json
+{
+  "mcpServers": {
+    "qca": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/xiaochus/qca_mcp_proxy", "qca-mcp-proxy"],
+      "env": {
+        "QCA_PAT": "<你的 PAT>",
+        "QCA_REGION": "cn"
+      }
+    }
+  }
+}
+```
+
+从本机源码安装（改代码即时生效）：
+
+```json
+{
+  "mcpServers": {
+    "qca": {
+      "command": "uvx",
+      "args": ["--from", "/Users/wbc/Desktop/ascend_adapter/qca-mcp-proxy", "qca-mcp-proxy"],
+      "env": {
+        "QCA_PAT": "<你的 PAT>",
+        "QCA_REGION": "cn"
+      }
+    }
+  }
+}
+```
+
+等价命令行（先在终端验证能不能起）：
+
+```bash
+uvx --from git+https://github.com/xiaochus/qca_mcp_proxy qca-mcp-proxy --check
+
+# 固定到某个 commit / tag，避免每次拉到不一样的代码
+uvx --from git+https://github.com/xiaochus/qca_mcp_proxy@v0.1.0 qca-mcp-proxy --check
+```
+
+`uvx` 会把该仓库缓存到本地 `~/.cache/uv`，改了远端代码后需要 `--refresh` 或清缓存才会更新。
+
+### 环境变量
+
+| 变量 | 必填 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `QCA_PAT` | 是 | – | 个人访问令牌；也接受 `QODER_PAT` / `QCA_TOKEN`，带不带 `Bearer ` 前缀都可以 |
+| `QCA_REGION` | 否 | `cn` | `cn` → `https://mcp.qoder.cn/api/v1/mcp/servers/qca`；`global` → `https://mcp.qoder.com/api/v1/mcp/servers/qca` |
+| `QCA_MCP_URL` | 否 | 由 region 决定 | 直接指定上游 MCP 地址，优先于 region |
+| `QCA_EXTRA_TOOLS` | 否 | 空 | 在默认白名单上追加工具（逗号分隔），例如 `list_accessible_workspaces` |
+| `QCA_ALLOWED_TOOLS` | 否 | 默认白名单 | **整体替换**默认白名单（逗号分隔） |
+| `QCA_TOOLS_TTL` | 否 | `300` | 工具列表缓存秒数 |
+| `QCA_CONNECT_TIMEOUT` | 否 | `30` | 连接上游超时（秒） |
+| `QCA_READ_TIMEOUT` | 否 | `300` | 上游单次读取超时（秒） |
+| `QCA_DEBUG` | 否 | 关 | `1` 打开 DEBUG 日志（含 SDK 与 HTTP 层） |
+| `QCA_HTTP_TOKEN` | 否 | 空 | 仅 `--transport http` 生效：要求请求带 `Authorization: Bearer <值>` |
+
+常用扩展例子：
+
+```bash
+# 需要工作区选择能力时
+QCA_EXTRA_TOOLS=list_accessible_workspaces
+
+# 只要读，不要写
+QCA_ALLOWED_TOOLS=get_session,list_sessions,list_session_event_summaries,list_session_events,list_agents,list_environments,list_vaults,list_files,get_file
+```
+
+## 典型用法
+
+1. `list_agents` / `list_environments` / `list_vaults` 拿到 `agent_xxx` / `env_xxx` / `vault_xxx`
+2. `create_session` 传 `agent` + `environment_id`（需要凭证时再传 `vault_ids`，需要挂载文件/仓库/记忆库时传 `resources`）
+3. `send_session_events` 发一条 `user.message` 事件
+4. `list_session_event_summaries` 轮询进度（不带载荷，省 token），需要内容时再用 `list_session_events` 加 `types` 过滤、`limit` 调小
+5. 取产物：`list_files` 传 `scope_id=<session_id>` 拿到 `file_id`，再用 `get_file` 看元数据；下载走 HTTP `GET /files/{id}/content`（见上文）
+6. 结束：`cancel_session`（没有归档/删除权限）
+
+## 行为约定
+
+- **启动即连上游**：生命周期里建立一条长连接，PAT 无效或区域不匹配时启动直接失败，stderr 会给出换区域的提示（日志只走 stderr，stdout 留给协议）。这样也避免了在请求处理任务里创建 MCP 客户端任务组导致的 cancel scope 破坏。
+- **写操作不重试**：`create_session` / `send_session_events` 等调用失败不再自动重放，避免上游重复执行；失败以 `is_error=true` 的工具结果返回，模型可自行决定下一步。
+- **未授权工具双重拦截**：`tools/list` 不返回，`tools/call` 也直接拒绝并给出可调用的工具名。
+- **不暴露 resources / prompts**：上游只有 tools，本代理也只声明 tools 能力。

qca_mcp_proxy-0.1.0/README.md

@@ -0,0 +1,178 @@
+# qca-mcp-proxy
+
+把 Qoder Cloud Agents（QCA）的远程 MCP 服务包一层 MCP 服务：只转发 **session 相关工具**，外加 `list_agents` / `list_environments` / `list_vaults` 三个只读查询和 `list_files` / `get_file` 两个文件元数据查询。其余工具（agent / environment / vault / skill / deployment 的写操作、session 资源等）既不列出也不可调用。
+
+- 上游：QCA 远程 MCP，Streamable HTTP + `Authorization: Bearer <PAT>`
+- 下游：两种跑法，同一套白名单
+  - `--transport stdio`（默认）：给 Qoder / Claude Desktop 这类拉起子进程的客户端
+  - `--transport http`：起一个 `http://127.0.0.1:8790/mcp` 的服务地址，客户端填 URL 即可
+- 实现用 MCP Python SDK v2（`mcp>=2,<3`）
+- 工具列表每次 5 分钟内缓存一次，避免每次 `tools/list` 都打上游
+
+## 暴露的工具（13 个）
+
+| 分组 | 工具 |
+| --- | --- |
+| session 生命周期 | `create_session` `get_session` `list_sessions` `update_session` `cancel_session` |
+| session 事件 | `send_session_events` `list_session_event_summaries` `list_session_events` |
+| 只读查询 | `list_agents` `list_environments` `list_vaults` |
+| 文件元数据 | `list_files`（传 `scope_id=<session_id>` 查会话产出）`get_file` |
+
+工具名与参数 schema 全部原样透传上游，不做改写；返回的 `content` / `structured_content` / `is_error` 也原样返回。
+
+刻意不在白名单里（`tools/list` 不返回，`tools/call` 也拒绝）：
+
+- session 资源四件套 `add_session_resource` / `get_session_resource` / `list_session_resources` / `delete_session_resource`：文件、GitHub 仓库、memory store 只能在 `create_session` 的 `resources` 里一次性挂上，会话中途不能再挂
+- `archive_session` / `delete_session`：只能 `cancel_session` 停掉会话，清理交给控制台或 `QCA_EXTRA_TOOLS` 追加
+- agent / environment / vault / skill / deployment 的写操作全部隐藏，只留三个 `list_*`
+
+## 安装
+
+```bash
+# 1) 直接跑源码（推荐本地开发）
+uvx --from /Users/wbc/Desktop/ascend_adapter/qca-mcp-proxy qca-mcp-proxy --check
+
+# 2) 从 git 安装
+uvx --from git+https://github.com/<you>/qca-mcp-proxy qca-mcp-proxy
+
+# 3) 装成常驻命令行
+uv tool install /Users/wbc/Desktop/ascend_adapter/qca-mcp-proxy
+qca-mcp-proxy --check
+```
+
+`--check` 会用当前 PAT 连一次上游，打印「上游工具数 / 已暴露 / 被隐藏」后退出，用来确认 PAT 和区域对不对。
+
+## 以服务地址跑（Streamable HTTP）
+
+```bash
+cd /Users/wbc/Desktop/ascend_adapter/qca-mcp-proxy
+export QCA_PAT=<你的 PAT>
+export QCA_REGION=cn
+
+# 起服务（默认监听 127.0.0.1:8790）
+.venv/bin/qca-mcp-proxy --transport http
+# 或者： uvx --from . qca-mcp-proxy --transport http
+```
+
+启动成功会打印：
+
+```
+[qca-proxy] INFO qca_mcp_proxy.server: serving Streamable HTTP on http://127.0.0.1:8790/mcp
+[qca-proxy] INFO qca_mcp_proxy.upstream: connected to https://mcp.qoder.cn/... (cn region)
+[qca-proxy] INFO qca_mcp_proxy.server: qca proxy ready: region=cn ...
+```
+
+然后在 agent 里把服务地址填成 `http://127.0.0.1:8790/mcp`；如果客户端用 `mcpServers` 配置，写：
+
+```json
+{"mcpServers": {"qca": {"url": "http://127.0.0.1:8790/mcp"}}}
+```
+
+相关开关：
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `--host` | `127.0.0.1` | 只给本机用就保持默认；要同网段访问改 `0.0.0.0`（SDK 只对回环地址做 DNS rebinding 防护，改后请自行加 `--auth-token`） |
+| `--port` | `8790` | 监听端口，端口冲突时换一个 |
+| `--stateless` | 关 | 不带 `mcp-session-id` 的无状态模式。有些 agent 每个请求都新开连接，用它会报 “session not found”，这时加这个参数 |
+| `--auth-token` | 空 | 要求请求带 `Authorization: Bearer <token>`，也可用 `QCA_HTTP_TOKEN`。只在本机测可以不加 |
+
+启动前会先探一次上游：PAT 不对或区域不匹配时直接一行报错退出，不会起一个连不上上游的空服务：
+
+```
+[qca-proxy] cannot reach QCA: MCPError(-32603): Server returned an error response
+
+The cn endpoint (https://mcp.qoder.cn/api/v1/mcp/servers/qca) rejected the request. ...
+```
+
+## 配置
+
+### Qoder / 兼容 `mcpServers` 的客户端
+
+`args` 里的 `--from` 有两种来源，按安装方式二选一。
+
+从 git 安装（推荐，换机器不用改路径）：
+
+```json
+{
+  "mcpServers": {
+    "qca": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/xiaochus/qca_mcp_proxy", "qca-mcp-proxy"],
+      "env": {
+        "QCA_PAT": "<你的 PAT>",
+        "QCA_REGION": "cn"
+      }
+    }
+  }
+}
+```
+
+从本机源码安装（改代码即时生效）：
+
+```json
+{
+  "mcpServers": {
+    "qca": {
+      "command": "uvx",
+      "args": ["--from", "/Users/wbc/Desktop/ascend_adapter/qca-mcp-proxy", "qca-mcp-proxy"],
+      "env": {
+        "QCA_PAT": "<你的 PAT>",
+        "QCA_REGION": "cn"
+      }
+    }
+  }
+}
+```
+
+等价命令行（先在终端验证能不能起）：
+
+```bash
+uvx --from git+https://github.com/xiaochus/qca_mcp_proxy qca-mcp-proxy --check
+
+# 固定到某个 commit / tag，避免每次拉到不一样的代码
+uvx --from git+https://github.com/xiaochus/qca_mcp_proxy@v0.1.0 qca-mcp-proxy --check
+```
+
+`uvx` 会把该仓库缓存到本地 `~/.cache/uv`，改了远端代码后需要 `--refresh` 或清缓存才会更新。
+
+### 环境变量
+
+| 变量 | 必填 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `QCA_PAT` | 是 | – | 个人访问令牌；也接受 `QODER_PAT` / `QCA_TOKEN`，带不带 `Bearer ` 前缀都可以 |
+| `QCA_REGION` | 否 | `cn` | `cn` → `https://mcp.qoder.cn/api/v1/mcp/servers/qca`；`global` → `https://mcp.qoder.com/api/v1/mcp/servers/qca` |
+| `QCA_MCP_URL` | 否 | 由 region 决定 | 直接指定上游 MCP 地址，优先于 region |
+| `QCA_EXTRA_TOOLS` | 否 | 空 | 在默认白名单上追加工具（逗号分隔），例如 `list_accessible_workspaces` |
+| `QCA_ALLOWED_TOOLS` | 否 | 默认白名单 | **整体替换**默认白名单（逗号分隔） |
+| `QCA_TOOLS_TTL` | 否 | `300` | 工具列表缓存秒数 |
+| `QCA_CONNECT_TIMEOUT` | 否 | `30` | 连接上游超时（秒） |
+| `QCA_READ_TIMEOUT` | 否 | `300` | 上游单次读取超时（秒） |
+| `QCA_DEBUG` | 否 | 关 | `1` 打开 DEBUG 日志（含 SDK 与 HTTP 层） |
+| `QCA_HTTP_TOKEN` | 否 | 空 | 仅 `--transport http` 生效：要求请求带 `Authorization: Bearer <值>` |
+
+常用扩展例子：
+
+```bash
+# 需要工作区选择能力时
+QCA_EXTRA_TOOLS=list_accessible_workspaces
+
+# 只要读，不要写
+QCA_ALLOWED_TOOLS=get_session,list_sessions,list_session_event_summaries,list_session_events,list_agents,list_environments,list_vaults,list_files,get_file
+```
+
+## 典型用法
+
+1. `list_agents` / `list_environments` / `list_vaults` 拿到 `agent_xxx` / `env_xxx` / `vault_xxx`
+2. `create_session` 传 `agent` + `environment_id`（需要凭证时再传 `vault_ids`，需要挂载文件/仓库/记忆库时传 `resources`）
+3. `send_session_events` 发一条 `user.message` 事件
+4. `list_session_event_summaries` 轮询进度（不带载荷，省 token），需要内容时再用 `list_session_events` 加 `types` 过滤、`limit` 调小
+5. 取产物：`list_files` 传 `scope_id=<session_id>` 拿到 `file_id`，再用 `get_file` 看元数据；下载走 HTTP `GET /files/{id}/content`（见上文）
+6. 结束：`cancel_session`（没有归档/删除权限）
+
+## 行为约定
+
+- **启动即连上游**：生命周期里建立一条长连接，PAT 无效或区域不匹配时启动直接失败，stderr 会给出换区域的提示（日志只走 stderr，stdout 留给协议）。这样也避免了在请求处理任务里创建 MCP 客户端任务组导致的 cancel scope 破坏。
+- **写操作不重试**：`create_session` / `send_session_events` 等调用失败不再自动重放，避免上游重复执行；失败以 `is_error=true` 的工具结果返回，模型可自行决定下一步。
+- **未授权工具双重拦截**：`tools/list` 不返回，`tools/call` 也直接拒绝并给出可调用的工具名。
+- **不暴露 resources / prompts**：上游只有 tools，本代理也只声明 tools 能力。

qca_mcp_proxy-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qca-mcp-proxy"
+version = "0.1.0"
+description = "Filtered MCP proxy in front of the Qoder Cloud Agents (QCA) remote MCP server, over stdio or Streamable HTTP"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Larry", email = "xiaochus@live.cn" }]
+keywords = ["mcp", "model-context-protocol", "proxy", "qoder", "cloud-agents", "stdio"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: Proxy Servers",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["mcp>=2.0,<3", "uvicorn>=0.31"]
+
+[project.urls]
+Homepage = "https://github.com/xiaochus/qca_mcp_proxy"
+Repository = "https://github.com/xiaochus/qca_mcp_proxy"
+Issues = "https://github.com/xiaochus/qca_mcp_proxy/issues"
+
+[project.scripts]
+qca-mcp-proxy = "qca_mcp_proxy.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qca_mcp_proxy"]
+
+[dependency-groups]
+dev = ["pytest>=8", "uvicorn>=0.30"]

qca_mcp_proxy-0.1.0/scripts/release.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+#
+# qca-mcp-proxy 发布脚本：校验 -> 构建 -> twine check -> 上传
+#
+#   scripts/release.sh --test      # 演练：上传到 TestPyPI
+#   scripts/release.sh --prod      # 正式发布到 PyPI
+#
+# 可选：HTTPS_PROXY=http://127.0.0.1:7897 scripts/release.sh --prod
+#
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+# 本机 ~/.config/pip/pip.conf 设了 user = true，会让 venv 及 build 的隔离环境
+# 报 "Can not perform a '--user' install"。导出给所有子进程覆盖掉。
+export PIP_USER=false
+
+TARGET="pypi"
+ALLOW_DIRTY=0
+ASSUME_YES=0
+
+usage() {
+  printf '用法: scripts/release.sh [选项]\n\n'
+  printf '  --test, --testpypi   上传到 TestPyPI（演练，可随便覆盖）\n'
+  printf '  --prod, --pypi       上传到正式 PyPI（默认，版本号不可复用）\n'
+  printf '  --allow-dirty        允许 git 工作区有未提交改动\n'
+  printf '  -y, --yes            跳过上传前的确认提示\n'
+  printf '  -h, --help           显示本帮助\n'
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --test|--testpypi) TARGET="testpypi" ;;
+    --prod|--pypi)     TARGET="pypi" ;;
+    --allow-dirty)     ALLOW_DIRTY=1 ;;
+    -y|--yes)          ASSUME_YES=1 ;;
+    -h|--help)         usage; exit 0 ;;
+    *) printf '未知参数: %s（用 --help 查看用法）\n' "$arg" >&2; exit 2 ;;
+  esac
+done
+
+step() { printf '\n\033[1;34m==> %s\033[0m\n' "$1"; }
+die()  { printf '\033[1;31m错误: %s\033[0m\n' "$1" >&2; exit 1; }
+
+# ---------------------------------------------------------------- 1. 构建环境
+step "1/6 检查构建环境"
+if [[ ! -x .venv/bin/python ]]; then
+  echo "未找到 .venv，创建虚拟环境并安装 build/twine ..."
+  python3 -m venv .venv
+  .venv/bin/pip install -q -U build twine
+fi
+if ! .venv/bin/python -c "import build, twine" >/dev/null 2>&1; then
+  echo "补装 build/twine ..."
+  .venv/bin/pip install -q -U build twine
+fi
+
+# ---------------------------------------------------------------- 2. 版本一致
+step "2/6 校验版本号"
+VERSION="$(.venv/bin/python - <<'PY'
+import pathlib, tomllib
+data = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))
+print(data["project"]["version"])
+PY
+)"
+INIT_VERSION="$(.venv/bin/python - <<'PY'
+import ast, pathlib
+tree = ast.parse(pathlib.Path("src/qca_mcp_proxy/__init__.py").read_text(encoding="utf-8"))
+for node in tree.body:
+    if isinstance(node, ast.Assign):
+        for target in node.targets:
+            if getattr(target, "id", "") == "__version__":
+                print(ast.literal_eval(node.value))
+                raise SystemExit
+print("")
+PY
+)"
+printf '  pyproject.toml   version     = %s\n' "$VERSION"
+printf '  __init__.py      __version__ = %s\n' "${INIT_VERSION:-<缺失>}"
+[[ -n "$INIT_VERSION" ]] || die "src/qca_mcp_proxy/__init__.py 里没有 __version__"
+[[ "$VERSION" == "$INIT_VERSION" ]] || die "两处版本号不一致，先同步再发布"
+
+# ---------------------------------------------------------------- 3. 工作区
+step "3/6 检查 git 工作区"
+if [[ -n "$(git status --porcelain)" ]]; then
+  git status --short
+  if [[ $ALLOW_DIRTY -eq 1 ]]; then
+    echo "工作区有未提交改动，按 --allow-dirty 继续"
+  else
+    die "工作区有未提交改动，请先 commit（或加 --allow-dirty 强制继续）"
+  fi
+fi
+if git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null 2>&1; then
+  die "已存在 tag v$VERSION，该版本可能已发布；请先提升 version"
+fi
+
+# ---------------------------------------------------------------- 4. 构建
+step "4/6 构建分发包"
+rm -rf dist
+.venv/bin/python -m build
+ls -1 dist/
+
+# ---------------------------------------------------------------- 5. 校验
+step "5/6 元数据校验"
+.venv/bin/twine check dist/*
+
+# ---------------------------------------------------------------- 6. 上传
+step "6/6 上传到 $TARGET"
+
+# 凭据预检。twine 的优先级：命令行 > 环境变量 > ~/.pypirc > 钥匙串 > 交互输入。
+KEYRING_SERVICE="https://upload.pypi.org/legacy/"
+[[ "$TARGET" == "testpypi" ]] && KEYRING_SERVICE="https://test.pypi.org/legacy/"
+if [[ -n "${TWINE_PASSWORD:-}" ]]; then
+  echo "凭据来源：环境变量 TWINE_PASSWORD"
+elif .venv/bin/python -c "import keyring, sys; sys.exit(0 if keyring.get_password('$KEYRING_SERVICE', '__token__') else 1)" >/dev/null 2>&1; then
+  echo "凭据来源：macOS 钥匙串"
+elif [[ -t 0 ]]; then
+  echo "钥匙串中未找到该仓库的 token，twine 将提示输入。"
+  echo "  想永久保存：.venv/bin/keyring set \"$KEYRING_SERVICE\" \"__token__\""
+else
+  die "非交互环境无法输入 token，请先执行 keyring set \"$KEYRING_SERVICE\" \"__token__\""
+fi
+
+if [[ $ASSUME_YES -eq 0 ]]; then
+  printf '即将上传 %s 到 %s，确认？(yes/no) ' "$VERSION" "$TARGET"
+  read -r reply
+  [[ "$reply" == "yes" ]] || { echo "已取消"; exit 1; }
+fi
+if [[ "$TARGET" == "testpypi" ]]; then
+  .venv/bin/twine upload --repository testpypi dist/*
+else
+  .venv/bin/twine upload dist/*
+fi
+
+printf '\n\033[1;32m==> 完成：%s 已发布到 %s\033[0m\n\n' "$VERSION" "$TARGET"
+
+if [[ "$TARGET" == "testpypi" ]]; then
+  printf '验证安装：\n'
+  printf '  pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple qca-mcp-proxy==%s\n\n' "$VERSION"
+else
+  printf '验证安装：\n'
+  printf '  pip install qca-mcp-proxy==%s\n\n' "$VERSION"
+  printf '打 tag 并推送：\n'
+  printf '  git tag -a v%s -m "release v%s"\n' "$VERSION" "$VERSION"
+  printf '  git push origin v%s\n' "$VERSION"
+fi

qca_mcp_proxy-0.1.0/src/qca_mcp_proxy/__init__.py

@@ -0,0 +1,3 @@
+"""Filtered MCP proxy for Qoder Cloud Agents (QCA)."""
+
+__version__ = "0.1.0"