qca-mcp-proxy 0.1.0__py3-none-any.whl

qca_mcp_proxy/__init__.py

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

qca_mcp_proxy/__main__.py

@@ -0,0 +1,152 @@
+"""Entry point: serve the filtered QCA proxy over stdio or Streamable HTTP."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from dataclasses import replace
+
+import anyio
+from mcp.server.stdio import stdio_server
+
+from .config import Config, ConfigError, load_config
+from .server import MCP_PATH, build_app, build_server, explain
+from .upstream import Upstream, UpstreamUnavailable
+
+
+def _configure_logging(debug: bool) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if debug else logging.INFO,
+        stream=sys.stderr,
+        format="[qca-proxy] %(levelname)s %(name)s: %(message)s",
+    )
+    # The SDK and its HTTP client are chatty at INFO; keep our own lines readable.
+    if not debug:
+        for noisy in ("httpx2", "httpcore", "mcp"):
+            logging.getLogger(noisy).setLevel(logging.WARNING)
+
+
+async def _serve(config: Config) -> None:
+    server = build_server(config)
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+async def _serve_http(config: Config, host: str, port: int, stateless: bool) -> int:
+    import uvicorn
+
+    # Probe the upstream first: a failed connection inside the ASGI lifespan only
+    # surfaces as a uvicorn startup traceback, which hides the actual cause.
+    probe = Upstream(config)
+    try:
+        await probe.open()
+    except UpstreamUnavailable as exc:
+        print(f"[qca-proxy] cannot reach QCA: {explain(exc, config)}", file=sys.stderr)
+        return 1
+    finally:
+        await probe.aclose()
+
+    app = build_app(config, host=host, stateless=stateless)
+    server = uvicorn.Server(
+        uvicorn.Config(
+            app,
+            host=host,
+            port=port,
+            log_config=None,
+            log_level="debug" if config.debug else "info",
+        )
+    )
+    logging.getLogger("qca_mcp_proxy.server").info(
+        "serving Streamable HTTP on http://%s:%d%s%s%s",
+        host,
+        port,
+        MCP_PATH,
+        " (bearer token required)" if config.http_token else "",
+        " (stateless)" if stateless else "",
+    )
+    await server.serve()
+    return 0
+
+
+async def _check(config: Config) -> int:
+    upstream = Upstream(config)
+    try:
+        try:
+            await upstream.open()
+            all_tools = await upstream.list_all_tools()
+        except UpstreamUnavailable as exc:
+            print(f"[qca-proxy] upstream unreachable: {explain(exc, config)}", file=sys.stderr)
+            return 1
+    finally:
+        await upstream.aclose()
+
+    names = sorted(tool.name for tool in all_tools)
+    exposed = [name for name in names if name in config.allowed_tools]
+    hidden = [name for name in names if name not in config.allowed_tools]
+    missing = sorted(config.allowed_tools - set(names))
+    print(f"endpoint   {config.endpoint} ({config.region})")
+    print(f"upstream   {len(names)} tools")
+    print(f"exposed    {len(exposed)}: {', '.join(exposed) if exposed else '-'}")
+    print(f"hidden     {len(hidden)}: {', '.join(hidden) if hidden else '-'}")
+    if missing:
+        print(f"allowlisted but absent upstream: {', '.join(missing)}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="qca-mcp-proxy",
+        description=(
+            "MCP proxy exposing only the Qoder Cloud Agents session tools, "
+            "over stdio or as a Streamable HTTP URL."
+        ),
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="verify the PAT against the upstream server, print the tool split, then exit",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "http"),
+        default="stdio",
+        help="stdio for a local MCP host (default), http to serve a URL over Streamable HTTP",
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="bind address for --transport http (default 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=8790, help="bind port for --transport http (default 8790)")
+    parser.add_argument(
+        "--auth-token",
+        default=None,
+        help="require 'Authorization: Bearer <token>' on the HTTP transport (env QCA_HTTP_TOKEN)",
+    )
+    parser.add_argument(
+        "--stateless",
+        action="store_true",
+        help="HTTP transport without a session id, for clients that open a new request per call",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        config = load_config()
+    except ConfigError as exc:
+        print(f"[qca-proxy] {exc}", file=sys.stderr)
+        return 2
+    if args.auth_token:
+        config = replace(config, http_token=args.auth_token)
+
+    _configure_logging(config.debug)
+    try:
+        if args.check:
+            return anyio.run(_check, config)
+        if args.transport == "http":
+            return anyio.run(_serve_http, config, args.host, args.port, args.stateless)
+        else:
+            anyio.run(_serve, config)
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

qca_mcp_proxy/config.py

@@ -0,0 +1,118 @@
+"""Proxy configuration: credentials, upstream endpoint and the tool allowlist."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+REGION_ENDPOINTS: dict[str, str] = {
+    "global": "https://mcp.qoder.com/api/v1/mcp/servers/qca",
+    "cn": "https://mcp.qoder.cn/api/v1/mcp/servers/qca",
+}
+
+# Everything the proxy is allowed to expose. Anything else on the QCA server
+# (agent/environment/vault writes, skills, deployments, memory stores, session
+# resources, ...) stays invisible: it is neither listed nor callable.
+DEFAULT_ALLOWED_TOOLS: tuple[str, ...] = (
+    # session lifecycle
+    "create_session",
+    "get_session",
+    "list_sessions",
+    "update_session",
+    "cancel_session",
+    # session runtime
+    "send_session_events",
+    "list_session_event_summaries",
+    "list_session_events",
+    # read-only lookups needed to feed the calls above
+    "list_agents",
+    "list_environments",
+    "list_vaults",
+    # files delivered by or attached to a session: metadata only, the upstream
+    # MCP has no download tool (GET /files/{id}/content is HTTP-only)
+    "list_files",
+    "get_file",
+)
+
+_TOKEN_ENV_VARS: tuple[str, ...] = ("QCA_PAT", "QODER_PAT", "QCA_TOKEN")
+
+
+class ConfigError(RuntimeError):
+    """Raised when the environment does not describe a usable proxy."""
+
+
+def _split_list(raw: str) -> list[str]:
+    return [item.strip() for item in raw.replace("\n", ",").split(",") if item.strip()]
+
+
+def _clean_token(raw: str) -> str:
+    token = raw.strip()
+    if token.lower().startswith("bearer "):
+        token = token[7:].strip()
+    return token
+
+
+@dataclass(frozen=True)
+class Config:
+    token: str
+    endpoint: str
+    region: str
+    allowed_tools: frozenset[str] = field(default_factory=lambda: frozenset(DEFAULT_ALLOWED_TOOLS))
+    connect_timeout: float = 30.0
+    read_timeout: float = 300.0
+    tools_ttl: float = 300.0
+    debug: bool = False
+    # when set, the HTTP transport requires `Authorization: Bearer <http_token>`
+    http_token: str | None = None
+
+    @property
+    def authorization(self) -> str:
+        return f"Bearer {self.token}"
+
+
+def load_config(env: Mapping[str, str] | None = None) -> Config:
+    source = os.environ if env is None else env
+
+    token = ""
+    for name in _TOKEN_ENV_VARS:
+        raw = source.get(name, "")
+        if raw.strip():
+            token = _clean_token(raw)
+            break
+    if not token:
+        raise ConfigError(
+            "missing QCA PAT: set QCA_PAT (or QODER_PAT) to a personal access token "
+            "issued at https://qoder.com.cn/cloud/pat-keys (CN) or "
+            "https://qoder.com/cloud/pat-keys (Global)"
+        )
+
+    region = source.get("QCA_REGION", "cn").strip().lower() or "cn"
+    if region not in REGION_ENDPOINTS:
+        raise ConfigError(f"unknown QCA_REGION {region!r}, expected one of {sorted(REGION_ENDPOINTS)}")
+
+    endpoint = source.get("QCA_MCP_URL", "").strip() or REGION_ENDPOINTS[region]
+    if not endpoint.startswith(("http://", "https://")):
+        raise ConfigError(f"QCA_MCP_URL must be an http(s) URL, got {endpoint!r}")
+
+    if "QCA_ALLOWED_TOOLS" in source:
+        allowed = frozenset(_split_list(source["QCA_ALLOWED_TOOLS"]))
+        if not allowed:
+            raise ConfigError("QCA_ALLOWED_TOOLS is set but empty")
+    else:
+        allowed = frozenset(DEFAULT_ALLOWED_TOOLS)
+    extra = frozenset(_split_list(source.get("QCA_EXTRA_TOOLS", "")))
+    if extra:
+        allowed |= extra
+
+    return Config(
+        token=token,
+        endpoint=endpoint,
+        region=region,
+        allowed_tools=allowed,
+        connect_timeout=float(source.get("QCA_CONNECT_TIMEOUT", 30)),
+        read_timeout=float(source.get("QCA_READ_TIMEOUT", 300)),
+        tools_ttl=float(source.get("QCA_TOOLS_TTL", 300)),
+        debug=source.get("QCA_DEBUG", "").strip().lower() in {"1", "true", "yes", "on"},
+        http_token=source.get("QCA_HTTP_TOKEN", "").strip() or None,
+    )

qca_mcp_proxy/server.py

@@ -0,0 +1,165 @@
+"""The downstream MCP server: exposes only the allowlisted QCA tools.
+
+Served either over stdio (``build_server``) or as a URL over Streamable HTTP
+(``build_app``, endpoint ``/mcp``).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from mcp.server import Server, ServerRequestContext
+from mcp.types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+)
+
+from . import __version__
+from .config import Config
+from .upstream import Upstream, UpstreamUnavailable
+
+logger = logging.getLogger("qca_mcp_proxy.server")
+
+MCP_PATH = "/mcp"
+
+INSTRUCTIONS = (
+    "Qoder Cloud Agents (QCA) through a filtered proxy. Session lifecycle "
+    "(create_session, get_session, list_sessions, update_session, cancel_session), "
+    "session events (send_session_events, list_session_event_summaries, "
+    "list_session_events), read-only list_agents / list_environments / list_vaults, "
+    "and file metadata via list_files / get_file. Call list_agents and "
+    "list_environments before create_session, attach any files, repositories or "
+    "memory stores in the same create_session call, then send a user.message with "
+    "send_session_events. Poll progress with list_session_event_summaries first - "
+    "it omits payloads - and only call list_session_events with a narrow types "
+    "filter and a small limit when you need the content. Files a session produced "
+    "arrive as agent.artifact_delivered events; pass the session id as scope_id to "
+    "list_files. Nothing else is exposed: no agent/environment/vault writes, no "
+    "session resources, no deployments, and no file download - use the QCA HTTP "
+    "API GET /files/{id}/content for that."
+)
+
+
+def _error(message: str) -> CallToolResult:
+    return CallToolResult(content=[TextContent(type="text", text=message)], is_error=True)
+
+
+def explain(exc: BaseException, config: Config) -> str:
+    """Append a hint about the region when the upstream rejected the request."""
+    text = str(exc)
+    lowered = text.lower()
+    rejected = (
+        "401" in text
+        or "403" in text
+        or "unauthorized" in lowered
+        or "forbidden" in lowered
+        or "error response" in lowered  # QCA answers a bad token with a bare -32603
+    )
+    if rejected:
+        other = "global" if config.region == "cn" else "cn"
+        text += (
+            f"\n\nThe {config.region} endpoint ({config.endpoint}) rejected the request. "
+            "The usual causes are an invalid or expired PAT, or a token issued for the other "
+            f"region - restart the proxy with QCA_REGION={other} to try that one."
+        )
+    return text
+
+
+def build_server(config: Config) -> Server:
+    upstream = Upstream(config)
+    available = ", ".join(sorted(config.allowed_tools))
+
+    @asynccontextmanager
+    async def lifespan(_server: Server) -> AsyncIterator[None]:
+        try:
+            await upstream.open()
+        except UpstreamUnavailable as exc:
+            raise RuntimeError(f"cannot reach QCA: {explain(exc, config)}") from exc
+        logger.info(
+            "qca proxy ready: region=%s endpoint=%s exposed=%d tools",
+            config.region,
+            config.endpoint,
+            len(config.allowed_tools),
+        )
+        try:
+            yield None
+        finally:
+            await upstream.aclose()
+
+    async def on_list_tools(
+        ctx: ServerRequestContext, params: PaginatedRequestParams | None
+    ) -> ListToolsResult:
+        try:
+            tools = await upstream.list_tools()
+        except UpstreamUnavailable as exc:
+            raise RuntimeError(f"cannot list QCA tools: {explain(exc, config)}") from exc
+        return ListToolsResult(tools=tools)
+
+    async def on_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+        if params.name not in config.allowed_tools:
+            return _error(f"tool {params.name!r} is not exposed by this proxy. Available: {available}")
+        try:
+            return await upstream.call_tool(params.name, params.arguments or {})
+        except Exception as exc:
+            logger.warning("upstream call %s failed: %s", params.name, exc)
+            return _error(f"{params.name} failed. {explain(exc, config)}")
+
+    return Server(
+        "qca-proxy",
+        version=__version__,
+        instructions=INSTRUCTIONS,
+        lifespan=lifespan,
+        on_list_tools=on_list_tools,
+        on_call_tool=on_call_tool,
+    )
+
+
+class _BearerGuard:
+    """ASGI middleware requiring `Authorization: Bearer <token>` on HTTP requests."""
+
+    def __init__(self, app: object, token: str) -> None:
+        self._app = app
+        self._expected = f"Bearer {token}"
+
+    async def __call__(self, scope: dict, receive: object, send: object) -> None:
+        if scope["type"] in {"http", "websocket"}:
+            headers = {key.decode("latin-1").lower(): value.decode("latin-1") for key, value in scope["headers"]}
+            if headers.get("authorization", "") != self._expected:
+                body = b'{"error":"unauthorized"}'
+                await send(
+                    {
+                        "type": "http.response.start",
+                        "status": 401,
+                        "headers": [
+                            (b"content-type", b"application/json"),
+                            (b"content-length", str(len(body)).encode()),
+                        ],
+                    }
+                )
+                await send({"type": "http.response.body", "body": body})
+                return
+        await self._app(scope, receive, send)  # type: ignore[operator]
+
+
+def build_app(config: Config, *, host: str = "127.0.0.1", stateless: bool = False):
+    """ASGI app serving the proxy over Streamable HTTP at ``/mcp``.
+
+    ``host`` is the bind address: the SDK only enables DNS rebinding protection
+    for loopback, so a non-loopback host is served as-is. ``stateless`` drops the
+    per-client session id, which some agents that open a fresh request per call
+    need; the upstream connection is shared either way.
+    """
+    app = build_server(config).streamable_http_app(
+        streamable_http_path=MCP_PATH,
+        host=host,
+        stateless_http=stateless,
+        debug=config.debug,
+    )
+    if config.http_token:
+        return _BearerGuard(app, config.http_token)
+    return app

qca_mcp_proxy/upstream.py

@@ -0,0 +1,128 @@
+"""Connection to the upstream QCA MCP server, with the allowlist applied on read."""
+
+from __future__ import annotations
+
+import logging
+import time
+from contextlib import AsyncExitStack
+
+import httpx2
+from mcp import Client
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared.exceptions import MCPError
+from mcp.types import CallToolResult, Tool
+
+from .config import Config
+
+logger = logging.getLogger("qca_mcp_proxy.upstream")
+
+
+class UpstreamUnavailable(RuntimeError):
+    """The upstream QCA MCP server could not be reached or authenticated."""
+
+
+def describe(exc: BaseException) -> str:
+    """Flatten a (possibly nested) exception group into one readable line."""
+    if isinstance(exc, BaseExceptionGroup):
+        parts = [describe(inner) for inner in exc.exceptions]
+        unique = list(dict.fromkeys(part for part in parts if part))
+        return "; ".join(unique) or type(exc).__name__
+    if isinstance(exc, MCPError):
+        detail = f"MCPError({exc.code}): {exc.message}"
+        return f"{detail} data={exc.data}" if exc.data else detail
+    text = str(exc).strip()
+    return f"{type(exc).__name__}: {text}" if text else type(exc).__name__
+
+
+class Upstream:
+    """One long-lived Streamable HTTP session to the remote QCA server.
+
+    The connection must be opened from the server lifespan task, not from a
+    request handler: the MCP client owns a task group, and leaving one open
+    across a handler boundary corrupts the request task's cancel scope stack.
+    """
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._stack: AsyncExitStack | None = None
+        self._client: Client | None = None
+        self._tools: list[Tool] = []
+        self._tools_at = 0.0
+
+    async def open(self) -> None:
+        if self._client is not None:
+            return
+        stack = AsyncExitStack()
+        await stack.__aenter__()
+        try:
+            http_client = await stack.enter_async_context(
+                httpx2.AsyncClient(
+                    headers={
+                        "Authorization": self._config.authorization,
+                        "Accept": "application/json, text/event-stream",
+                    },
+                    timeout=httpx2.Timeout(self._config.connect_timeout, read=self._config.read_timeout),
+                )
+            )
+            client = await stack.enter_async_context(
+                Client(streamable_http_client(self._config.endpoint, http_client=http_client))
+            )
+        except BaseException as exc:
+            await stack.aclose()
+            if isinstance(exc, Exception):
+                raise UpstreamUnavailable(describe(exc)) from exc
+            raise
+        self._stack, self._client = stack, client
+        logger.info("connected to %s (%s region)", self._config.endpoint, self._config.region)
+
+    async def aclose(self) -> None:
+        stack, self._stack, self._client = self._stack, None, None
+        self._tools, self._tools_at = [], 0.0
+        if stack is None:
+            return
+        try:
+            await stack.aclose()
+        except Exception:  # teardown of a broken connection is best effort
+            logger.debug("error while closing upstream connection", exc_info=True)
+
+    def _require_client(self) -> Client:
+        if self._client is None:
+            raise UpstreamUnavailable("upstream connection is not open")
+        return self._client
+
+    async def _fetch_tools(self) -> list[Tool]:
+        client = self._require_client()
+        tools: list[Tool] = []
+        cursor: str | None = None
+        while True:
+            page = await client.list_tools(cursor=cursor)
+            tools.extend(page.tools)
+            if page.next_cursor is None:
+                return tools
+            cursor = page.next_cursor
+
+    async def list_all_tools(self) -> list[Tool]:
+        """Return every tool the upstream advertises, allowlist ignored."""
+        try:
+            return await self._fetch_tools()
+        except Exception as exc:
+            raise UpstreamUnavailable(describe(exc)) from exc
+
+    async def list_tools(self, *, refresh: bool = False) -> list[Tool]:
+        """Return the exposed subset of the upstream tool list."""
+        fresh = self._tools_at > 0 and (time.monotonic() - self._tools_at) < self._config.tools_ttl
+        if fresh and not refresh:
+            return self._tools
+        tools = await self.list_all_tools()
+        exposed = [tool for tool in tools if tool.name in self._config.allowed_tools]
+        logger.info(
+            "upstream exposes %d tools, %d proxied, %d hidden",
+            len(tools),
+            len(exposed),
+            len(tools) - len(exposed),
+        )
+        self._tools, self._tools_at = exposed, time.monotonic()
+        return exposed
+
+    async def call_tool(self, name: str, arguments: dict[str, object]) -> CallToolResult:
+        return await self._require_client().call_tool(name, arguments)

qca_mcp_proxy-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+qca_mcp_proxy/__init__.py,sha256=Y1yEFo9iSLJ32K-XTR1aNpST6hwZrCbYX0mxLAKzdMQ,77
+qca_mcp_proxy/__main__.py,sha256=PieqXx9T-teuUlH3iGZqoaJOF7tzBauN3VkTJJNGUO4,5129
+qca_mcp_proxy/config.py,sha256=9DbSvKa2PhWxyxRCSXITSlsuPq4KuycE6AdM9CTX3vo,3988
+qca_mcp_proxy/server.py,sha256=KX8OcpsDKH3kkFrYGZOj97Wm3rt_GkjzGJqRtGIvc7w,6444
+qca_mcp_proxy/upstream.py,sha256=KNN6qOBp3jBE4yhy0_RKfu6NY2fKp0Xkh2EINGABxzU,4956
+qca_mcp_proxy-0.1.0.dist-info/METADATA,sha256=4a2OcEz9Dr8-ONdLYS1IPuDwZPu425Qd-sVMGxEvqNo,9344
+qca_mcp_proxy-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+qca_mcp_proxy-0.1.0.dist-info/entry_points.txt,sha256=NZl2P140ivwx7WqCi4LwbR-5vyDzOWT1lKOetDs1lEM,62
+qca_mcp_proxy-0.1.0.dist-info/licenses/LICENSE,sha256=ZoG5VPXzt8SAEPlyFFln01G0Ofb2DrKpECHwDzFsSwI,1061
+qca_mcp_proxy-0.1.0.dist-info/RECORD,,

qca_mcp_proxy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

qca_mcp_proxy-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qca-mcp-proxy = qca_mcp_proxy.__main__:main

qca_mcp_proxy-0.1.0.dist-info/licenses/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.