alibabacloud.mcp-proxy 0.1.4__tar.gz

alibabacloud_mcp_proxy-0.1.4/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+dist/
+build/
+*.pyc

alibabacloud_mcp_proxy-0.1.4/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: alibabacloud.mcp-proxy
+Version: 0.1.4
+Summary: Local stdio MCP proxy for Alibaba Cloud OpenAPI MCP servers.
+Project-URL: Homepage, https://github.com/aliyun/alibabacloud-api-mcp-server
+Project-URL: Repository, https://github.com/aliyun/alibabacloud-api-mcp-server
+Author: Alibaba Cloud
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.13
+Requires-Dist: alibabacloud-credentials>=1.0.8
+Requires-Dist: alibabacloud-openapi-util>=0.2.4
+Requires-Dist: alibabacloud-tea-openapi>=0.4.4
+Requires-Dist: alibabacloud-tea-util>=0.3.14
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp>=1.27.0
+Description-Content-Type: text/markdown
+
+# 阿里云 MCP Server 使用指南
+
+## [README of English](README-EN.md)
+
+## 📚 目录
+
+- [概述](#概述)
+- [部署模式](#部署模式)
+  - [远程模式](#远程模式)
+  - [本地模式](#本地模式)
+- [远程模式详解](#远程模式详解)
+  - [技术规格](#技术规格)
+  - [访问地址](#访问地址)
+  - [系统 MCP 服务列表](#系统-mcp-服务列表)
+    - [基础设施管理](#基础设施管理)
+    - [监控与审计](#监控与审计)
+    - [合规与治理](#合规与治理)
+  - [核心能力](#核心能力)
+    - [OpenAPI 定制化调优](#openapi-定制化调优)
+    - [Terraform As Tools](#terraform-as-tools)
+    - [多账号支持](#多账号支持)
+    - [自定义 OAuth](#自定义-oauth)
+- [本地模式详解](#本地模式详解)
+  - [运行机制](#运行机制)
+  - [服务列表](#服务列表)
+    - [数据库服务](#数据库服务)
+    - [数据分析服务](#数据分析服务)
+    - [DevOps 服务](#devops-服务)
+    - [其他服务](#其他服务)
+- [快速开始](#快速开始)
+  - [远程模式接入](#远程模式接入)
+  - [通过本地静态凭证接入](#通过本地静态凭证接入)
+  - [本地模式部署](#本地模式部署)
+- [参考文档](#参考文档)
+
+## 概述
+
+阿里云 MCP Server 是一个强大的云服务集成平台，通过 Model Context Protocol (MCP) 为 AI 应用提供阿里云服务的无缝集成能力。该平台支持数万个阿里云 OpenAPI，让开发者能够轻松地将阿里云的各种服务能力集成到 AI 工作流中。
+
+## 部署模式
+
+### 远程模式
+
+通过阿里云官方托管的 OpenAPI MCP Server，无需本地部署即可使用全量阿里云服务。适合快速集成、低维护成本的场景。
+
+阿里云现已提供 API MCP Server Core。该模式基于远程 CLI 模式运行，通过个位数的核心 tools 即可编排并触达阿里云全量能力（覆盖数万 OpenAPI）。
+
+### 本地模式
+
+基于 stdio 进程模式，在本地运行 MCP Server。适合对数据安全性要求高、需要自定义配置的场景。
+
+## 远程模式详解
+
+### 技术规格
+
+- **核心模式**：API MCP Server Core（远程 CLI 模式）
+- **支持协议**：SSE (Server-Sent Events)、Streamable HTTP
+- **认证方式**：OAuth 2.0
+- **API 数量**：支持阿里云数万个 OpenAPI
+- **部署方式**：云端托管，零运维
+
+### 访问地址
+
+| 区域 | 访问地址 | 适用场景 |
+|------|---------|----------|
+| **中国站** | https://api.aliyun.com/mcp | 中国大陆用户 |
+| **国际站** | https://api.alibabacloud.com/mcp | 海外及国际用户 |
+
+### 系统 MCP 服务列表
+
+阿里云官方提供了一系列经过精心调优的系统 MCP 服务，针对特定场景进行了优化：
+
+#### 基础设施管理
+
+| 服务名称 | 功能描述 |
+|---------|---------|
+| **Terraform Provider** | 提供阿里云 Terraform Provider 元数据，支持在线验证和执行 Terraform 命令的 Runtime 能力 |
+| **配额中心** | 根据云产品名称、配额描述、地域信息等，查询配额中心支持的产品通用配额信息 |
+| **资源搜索** | 支持当前账号下有权限资源的搜索和统计功能 |
+
+#### 监控与审计
+
+| 服务名称 | 功能描述 |
+|---------|---------|
+| **操作审计 AI** | 使用 AI 根据场景灵活调用操作审计的 LookupEvents 接口 |
+| **权限诊断** | API 请求因无权限被拒绝时，通过 EncodedDiagnosticMessage 进行权限诊断 |
+
+#### 合规与治理
+
+| 服务名称 | 功能描述 |
+|---------|---------|
+| **治理报告** | 基于 GovernanceReport 的 MCP Server |
+| **配置审计合规包** | 查询合规包模板、启用指定合规包、查询风险项概况及风险资源清单 |
+
+### 核心能力
+
+#### OpenAPI 定制化调优
+
+- 修改 API 描述，使其更适合 AI 理解
+- 精简非必填参数，降低调用复杂度
+- 优化参数说明，提高 AI 调用准确率
+
+#### Terraform As Tools
+
+- **HCL 代码集成**：将 Terraform HCL 代码作为完整工具引入
+- **变量自动解析**：Terraform 变量自动转换为工具参数
+- **确定性编排**：实现基础设施的确定性部署和管理
+
+#### 多账号支持
+
+- **角色扮演**：自动使用角色扮演能力操作特定账号
+- **账号切换**：灵活指定操作账号和扮演角色
+- **集中管理**：轻松实现多账号 AI 集成管理
+
+#### 自定义 OAuth
+
+- **Callback 白名单**：精确控制回调地址白名单
+- **Token 生命周期**：灵活设置 access token 和 refresh token 过期时间
+- **长期免登录**：最长可实现 1 年免登录
+
+## 本地模式详解
+
+### 运行机制
+
+本地模式基于 stdio 进程通信，MCP Server 作为独立进程在本地运行，通过标准输入输出与 AI 应用进行通信。
+
+### 服务列表
+
+#### 数据库服务
+
+| 服务 | 仓库地址 | 描述 |
+|------|---------|------|
+| **DMS** | [alibabacloud-dms-mcp-server](https://github.com/aliyun/alibabacloud-dms-mcp-server) | 数据管理服务，提供数据库管理能力 |
+| **RDS** | [alibabacloud-rds-openapi-mcp-server](https://github.com/aliyun/alibabacloud-rds-openapi-mcp-server) | 关系型数据库服务 OpenAPI 集成 |
+| **ADBPG** | [alibabacloud-adbpg-mcp-server](https://github.com/aliyun/alibabacloud-adbpg-mcp-server) | 分析型数据库 PostgreSQL 版 |
+
+#### 数据分析服务
+
+| 服务 | 仓库地址 | 描述 |
+|------|---------|------|
+| **DataWorks** | [alibabacloud-dataworks-mcp-server](https://github.com/aliyun/alibabacloud-dataworks-mcp-server) | 数据工场，提供大数据开发治理能力 |
+
+#### DevOps 服务
+
+| 服务 | 仓库地址 | 描述 |
+|------|---------|------|
+| **云效** | [alibabacloud-devops-mcp-server](https://github.com/aliyun/alibabacloud-devops-mcp-server) | 企业级 DevOps 平台集成 |
+| **运维开发** | [alibaba-cloud-ops-mcp-server](https://github.com/aliyun/alibaba-cloud-ops-mcp-server) | 运维开发工具集成 |
+
+#### 其他服务
+
+| 服务 | 仓库地址 | 描述 |
+|------|---------|------|
+| **ESA** | [mcp-server-esa](https://github.com/aliyun/mcp-server-esa) | 边缘安全加速服务 |
+| **可观测** | [alibabacloud-observability-mcp-server](https://github.com/aliyun/alibabacloud-observability-mcp-server) | 可观测性服务集成 |
+
+## 快速开始
+
+### 远程模式接入
+
+1. **访问控制台**
+   - 中国站用户访问：https://api.aliyun.com/mcp
+   - 国际站用户访问：https://api.alibabacloud.com/mcp
+
+2. **OAuth 认证**
+   - 配置 OAuth 应用
+   - 获取 Access Token
+   - 配置 Token 刷新策略
+
+3. **选择服务**
+   - 浏览系统 MCP 服务
+   - 选择需要的 OpenAPI
+   - 自定义 API 参数
+
+### 通过本地静态凭证接入
+
+现在阿里云 API MCP Server 可以通过本地静态凭证直接登录。你可以在本地配置阿里云 AccessKey 或已有凭证文件，然后通过 Alibaba Cloud MCP Proxy 自动换取访问 OpenAPI MCP Server 所需的令牌，无需在 MCP 客户端中手动维护 OAuth Token。
+
+代理工具的安装、MCP 客户端配置、安全策略和预检查说明请参考：[Alibaba Cloud MCP Proxy 使用说明](README-PROXY.md)。
+
+### 本地模式部署
+
+1. **克隆仓库**
+   ```bash
+   git clone https://github.com/aliyun/[具体服务仓库名称]
+   cd [仓库目录]
+   ```
+
+2. **安装依赖**
+   ```bash
+   npm install  # 或 yarn install
+   ```
+
+3. **配置认证**
+   ```bash
+   export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key
+   export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_secret_key
+   ```
+
+4. **启动服务**
+   ```bash
+   npm start  # 或按照具体仓库的启动说明
+   ```
+
+## 参考文档
+
+- 📖 **官方文档**：[OpenAPI MCP Server 使用指南](https://help.aliyun.com/zh/openapi/user-guide/openapi-mcp-server-guide)
+- 🔧 **技术支持**：通过阿里云工单系统或官方论坛获取技术支持
+- 💬 **社区交流**：加入阿里云开发者社区参与讨论，钉钉群：136325002292
+- 通过AgentScope使用示例<https://github.com/agentscope-ai/agentscope/tree/main/examples/alibabacloud_api_mcp>
+
+---
+
+*本文档持续更新中，欢迎提交 Issue 或 PR 贡献内容*

alibabacloud_mcp_proxy-0.1.4/README-EN.md

@@ -0,0 +1,213 @@
+# Alibaba Cloud MCP Server User Guide
+
+## [README of Chinese](README.md)
+
+## 📚 Table of Contents
+
+- [Overview](#overview)
+- [Deployment Modes](#deployment-modes)
+  - [Remote Mode](#remote-mode)
+  - [Local Mode](#local-mode)
+- [Remote Mode Details](#remote-mode-details)
+  - [Technical Specifications](#technical-specifications)
+  - [Access Endpoints](#access-endpoints)
+  - [System MCP Service List](#system-mcp-service-list)
+    - [Infrastructure Management](#infrastructure-management)
+    - [Monitoring & Auditing](#monitoring--auditing)
+    - [Compliance & Governance](#compliance--governance)
+  - [Core Capabilities](#core-capabilities)
+    - [OpenAPI Customization & Optimization](#openapi-customization--optimization)
+    - [Terraform As Tools](#terraform-as-tools)
+    - [Multi-Account Support](#multi-account-support)
+    - [Custom OAuth](#custom-oauth)
+- [Local Mode Details](#local-mode-details)
+  - [Operating Mechanism](#operating-mechanism)
+  - [Service List](#service-list)
+    - [Database Services](#database-services)
+    - [Data Analytics Services](#data-analytics-services)
+    - [DevOps Services](#devops-services)
+    - [Other Services](#other-services)
+- [Quick Start](#quick-start)
+  - [Remote Mode Access](#remote-mode-access)
+  - [Access with Local Static Credentials](#access-with-local-static-credentials)
+  - [Local Mode Deployment](#local-mode-deployment)
+- [Reference Documentation](#reference-documentation)
+
+## Overview
+
+Alibaba Cloud MCP Server is a powerful cloud service integration platform that provides seamless integration capabilities for Alibaba Cloud services to AI applications through the Model Context Protocol (MCP). The platform supports tens of thousands of Alibaba Cloud OpenAPIs, enabling developers to easily integrate various Alibaba Cloud service capabilities into AI workflows.
+
+## Deployment Modes
+
+### Remote Mode
+
+Use the full range of Alibaba Cloud services through the officially hosted Alibaba Cloud OpenAPI MCP Server without local deployment. Suitable for scenarios requiring rapid integration and low maintenance costs.
+
+Alibaba Cloud now provides API MCP Server Core. This mode follows a remote CLI pattern, enabling orchestration of the full Alibaba Cloud capability surface with a single-digit number of core tools (covering tens of thousands of OpenAPIs).
+
+### Local Mode
+
+Based on stdio process mode, running MCP Server locally. Suitable for scenarios with high data security requirements and need for custom configuration.
+
+## Remote Mode Details
+
+### Technical Specifications
+
+- **Core Mode**: API MCP Server Core (remote CLI mode)
+- **Supported Protocols**: SSE (Server-Sent Events), Streamable HTTP
+- **Authentication Method**: OAuth 2.0
+- **API Count**: Supports tens of thousands of Alibaba Cloud OpenAPIs
+- **Deployment Method**: Cloud-hosted, zero maintenance
+
+### Access Endpoints
+
+| Region | Access Endpoint | Applicable Scenarios |
+|--------|----------------|---------------------|
+| **China Site** | https://api.aliyun.com/mcp | Users in mainland China |
+| **International Site** | https://api.alibabacloud.com/mcp | Overseas and international users |
+
+### System MCP Service List
+
+Alibaba Cloud officially provides a series of carefully optimized system MCP services, optimized for specific scenarios:
+
+#### Infrastructure Management
+
+| Service Name | Function Description |
+|-------------|---------------------|
+| **Terraform Provider** | Provides Alibaba Cloud Terraform Provider metadata, supports online validation and runtime capabilities for executing Terraform commands |
+| **Quota Center** | Query general quota information for products supported by the Quota Center based on cloud product name, quota description, regional information, etc. |
+| **Resource Search** | Supports search and statistics functions for resources with permissions under the current account |
+
+#### Monitoring & Auditing
+
+| Service Name | Function Description |
+|-------------|---------------------|
+| **ActionTrail AI** | Uses AI to flexibly call the ActionTrail LookupEvents interface based on scenarios |
+| **Permission Diagnostics** | When API requests are rejected due to lack of permissions, perform permission diagnosis through EncodedDiagnosticMessage |
+
+#### Compliance & Governance
+
+| Service Name | Function Description |
+|-------------|---------------------|
+| **Governance Report** | MCP Server based on GovernanceReport |
+| **Config Compliance Pack** | Query compliance pack templates, enable specified compliance packs, query risk overview and risk resource inventory |
+
+### Core Capabilities
+
+#### OpenAPI Customization & Optimization
+
+- Modify API descriptions to make them more suitable for AI understanding
+- Simplify non-required parameters to reduce calling complexity
+- Optimize parameter descriptions to improve AI calling accuracy
+
+#### Terraform As Tools
+
+- **HCL Code Integration**: Introduce Terraform HCL code as complete tools
+- **Automatic Variable Parsing**: Terraform variables automatically convert to tool parameters
+- **Deterministic Orchestration**: Achieve deterministic deployment and management of infrastructure
+
+#### Multi-Account Support
+
+- **Role Assumption**: Automatically use role assumption capabilities to operate specific accounts
+- **Account Switching**: Flexibly specify operation accounts and assumed roles
+- **Centralized Management**: Easily achieve multi-account AI integrated management
+
+#### Custom OAuth
+
+- **Callback Whitelist**: Precisely control callback address whitelist
+- **Token Lifecycle**: Flexibly set access token and refresh token expiration times
+- **Long-term Login-free**: Achieve up to 1 year of login-free operation
+
+## Local Mode Details
+
+### Operating Mechanism
+
+Local mode is based on stdio process communication, with MCP Server running as an independent process locally, communicating with AI applications through standard input/output.
+
+### Service List
+
+#### Database Services
+
+| Service | Repository URL | Description |
+|---------|---------------|-------------|
+| **DMS** | [alibabacloud-dms-mcp-server](https://github.com/aliyun/alibabacloud-dms-mcp-server) | Data Management Service, provides database management capabilities |
+| **RDS** | [alibabacloud-rds-openapi-mcp-server](https://github.com/aliyun/alibabacloud-rds-openapi-mcp-server) | Relational Database Service OpenAPI integration |
+| **ADBPG** | [alibabacloud-adbpg-mcp-server](https://github.com/aliyun/alibabacloud-adbpg-mcp-server) | AnalyticDB for PostgreSQL |
+
+#### Data Analytics Services
+
+| Service | Repository URL | Description |
+|---------|---------------|-------------|
+| **DataWorks** | [alibabacloud-dataworks-mcp-server](https://github.com/aliyun/alibabacloud-dataworks-mcp-server) | Data Factory, provides big data development and governance capabilities |
+
+#### DevOps Services
+
+| Service | Repository URL | Description |
+|---------|---------------|-------------|
+| **Apsara DevOps** | [alibabacloud-devops-mcp-server](https://github.com/aliyun/alibabacloud-devops-mcp-server) | Enterprise-level DevOps platform integration |
+| **Operations Development** | [alibaba-cloud-ops-mcp-server](https://github.com/aliyun/alibaba-cloud-ops-mcp-server) | Operations development tools integration |
+
+#### Other Services
+
+| Service | Repository URL | Description |
+|---------|---------------|-------------|
+| **ESA** | [mcp-server-esa](https://github.com/aliyun/mcp-server-esa) | Edge Security Acceleration service |
+| **Observability** | [alibabacloud-observability-mcp-server](https://github.com/aliyun/alibabacloud-observability-mcp-server) | Observability service integration |
+
+## Quick Start
+
+### Remote Mode Access
+
+1. **Access Console**
+   - China Site users visit: https://api.aliyun.com/mcp
+   - International Site users visit: https://api.alibabacloud.com/mcp
+
+2. **OAuth Authentication**
+   - Configure OAuth application
+   - Obtain Access Token
+   - Configure Token refresh strategy
+
+3. **Select Services**
+   - Browse system MCP services
+   - Select required OpenAPI
+   - Customize API parameters
+
+### Access with Local Static Credentials
+
+Alibaba Cloud API MCP Server now supports direct login through local static credentials. You can configure an Alibaba Cloud AccessKey or an existing local credential profile, then use Alibaba Cloud MCP Proxy to automatically exchange it for the token required by OpenAPI MCP Server. This removes the need to manually maintain OAuth tokens in MCP client configuration.
+
+For proxy installation, MCP client configuration, safety policies, and pre-check usage, see: [Alibaba Cloud MCP Proxy User Guide](README-PROXY-EN.md).
+
+### Local Mode Deployment
+
+1. **Clone Repository**
+   ```bash
+   git clone https://github.com/aliyun/[specific-service-repository-name]
+   cd [repository-directory]
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   npm install  # or yarn install
+   ```
+
+3. **Configure Authentication**
+   ```bash
+   export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key
+   export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_secret_key
+   ```
+
+4. **Start Service**
+   ```bash
+   npm start  # or follow the specific repository's startup instructions
+   ```
+
+## Reference Documentation
+
+- 📖 **Official Documentation**: [OpenAPI MCP Server User Guide](https://www.alibabacloud.com/help/en/openapi/user-guide/openapi-mcp-server-guide)
+- 🔧 **Technical Support**: Get technical support through Alibaba Cloud ticket system or official forums
+- 💬 **Community Exchange**: Join the Alibaba Cloud Developer Community for discussions, DingTalk Group: 136325002292
+
+---
+
+*This document is continuously updated. Welcome to submit Issues or PRs to contribute content*

alibabacloud_mcp_proxy-0.1.4/README-PROXY-EN.md

@@ -0,0 +1,205 @@
+## Alibaba Cloud MCP Proxy
+
+A local stdio MCP (Model Context Protocol) proxy for Alibaba Cloud OpenAPI MCP servers. It bridges MCP clients (such as Claude Desktop, Cursor, or other AI-powered IDEs) with Alibaba Cloud's upstream MCP services, handling authentication, connection management, retries, and safety policies transparently.
+
+### Prerequisites
+
+The RAM user or role running the proxy **must** have the following permissions. Attach this policy in the [RAM Console](https://ram.console.aliyun.com/):
+
+Alibaba Cloud provides a built-in system policy named `AliyunOpenAPIMCPServerStaticCredentialAccess` (full Access policy for static-credential connection).
+
+```json
+{
+  "Version": "1",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": "ram:GenerateAccessToken",
+      "Resource": "*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": "openapiexplorer:*",
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+- **`ram:GenerateAccessToken`** — Required for the proxy to obtain bearer tokens via IMS.
+- **`openapiexplorer:*`** — Required for MCP server discovery and tool invocation.
+
+### Quick Start
+
+Run the proxy with `uvx` (always fetches the latest version, no install needed):
+
+```bash
+uvx alibabacloud.mcp-proxy@latest
+```
+
+If you have a custom MCP server URL, you can specify it explicitly:
+
+```bash
+uvx alibabacloud.mcp-proxy@latest --server-url <YOUR_MCP_SERVER_URL>
+```
+
+#### MCP Client Configuration (Claude Desktop / Cursor)
+
+Add the following to your MCP client configuration file (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "alibabacloud": {
+      "command": "uvx",
+      "args": ["alibabacloud.mcp-proxy@latest"]
+    }
+  }
+}
+```
+
+The proxy reads local Alibaba Cloud static credentials and automatically exchanges them for the access token required by the upstream OpenAPI MCP Server.
+
+### Local Static Credential Login
+
+Alibaba Cloud API MCP Server now supports direct login through local static credentials. You can configure credentials with Alibaba Cloud CLI or environment variables, and MCP Proxy will read them locally and call IMS `GenerateAccessToken` to obtain a Bearer Token. This removes the need to manually manage OAuth tokens in MCP client configuration.
+
+Common environment variable configuration:
+
+```bash
+export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
+export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
+uvx alibabacloud.mcp-proxy@latest
+```
+
+### Debugging
+
+To enable debug logging, use `--debug` together with `--log-file` to write detailed logs to a file:
+
+```bash
+uvx alibabacloud.mcp-proxy@latest --debug --log-file=/tmp/a.log --safety-policy "ecs:describe-*=allow,*=deny"
+```
+
+### Safety Policy
+
+You can constrain which MCP tools the proxy is allowed to invoke by specifying a **safety policy**. This is applied to the bearer token before connecting to the upstream MCP server, ensuring the token is scoped to only the allowed tool calls.
+
+#### Example: Allow only ECS describe operations
+
+```bash
+uvx alibabacloud.mcp-proxy@latest --safety-policy "ecs:describe-*=allow,*=deny"
+```
+
+#### MCP Client Configuration with Safety Policy
+
+```json
+{
+  "mcpServers": {
+    "alibabacloud": {
+      "command": "uvx",
+      "args": [
+        "alibabacloud.mcp-proxy@latest",
+        "--safety-policy", "ecs:describe-*=allow,*=deny"
+      ]
+    }
+  }
+}
+```
+
+You can also set the safety policy via environment variable:
+
+```bash
+export ALIBABACLOUD_MCP_SAFETY_POLICY="ecs:describe-*=allow,*=deny"
+uvx alibabacloud.mcp-proxy@latest
+```
+
+### Pre-check
+
+Before connecting to the upstream MCP server, you can verify that your local OAuth application is properly installed and authorized by running the **pre-check** command. This starts a lightweight local HTTP server, opens your browser to the Alibaba Cloud OAuth authorization page, and waits for the callback.
+
+```bash
+uvx alibabacloud.mcp-proxy@latest pre-check
+```
+
+For international sites:
+
+```bash
+uvx alibabacloud.mcp-proxy@latest pre-check --site-type INTL
+```
+
+With a custom OAuth client ID:
+
+```bash
+uvx alibabacloud.mcp-proxy@latest pre-check --client-id YOUR_OAUTH_CLIENT_ID
+```
+
+If the pre-check passes, you will see:
+
+```
+✓ Pre-check passed! You can connect via local static credentials.
+```
+
+### Configuration Reference
+
+Every CLI flag has a corresponding environment variable. **CLI flags take precedence** over environment variables.
+
+#### Connection Settings
+
+| CLI Flag | Environment Variable | Default | Description |
+|---|---|---|---|
+| `--server-url` | `ALIBABACLOUD_MCP_SERVER_URL` | *(auto-discover)* | Upstream Alibaba Cloud MCP streamable HTTP URL. If not set, the proxy discovers it via the `ListApiMcpServerCores` OpenAPI. |
+| `--site-type` | `ALIBABACLOUD_MCP_SITE_TYPE` | `CN` | Alibaba Cloud site type: `CN` (China) or `INTL` (International). |
+| `--connect-timeout` | `ALIBABACLOUD_MCP_CONNECT_TIMEOUT` | `10.0` | HTTP connect timeout in seconds. |
+| `--read-timeout` | `ALIBABACLOUD_MCP_READ_TIMEOUT` | `120.0` | HTTP read timeout in seconds. |
+
+#### Authentication Settings
+
+| CLI Flag | Environment Variable | Default | Description |
+|---|---|---|---|
+| `--bearer-token` | `ALIBABACLOUD_MCP_BEARER_TOKEN` | — | Explicit bearer token for the upstream MCP server. |
+| `--token-command` | `ALIBABACLOUD_MCP_TOKEN_COMMAND` | — | Shell command that prints a bearer token or JSON with `access_token`. |
+| `--client-id` | `ALIBABACLOUD_MCP_CLIENT_ID` | *(per site type)* | IMS `GenerateAccessToken` ClientId. Defaults to `4071151845732613353` (CN) or `4195410055503316452` (INTL). |
+| `--scope` | `ALIBABACLOUD_MCP_SCOPE` | `/internal/acs/openapi` | IMS `GenerateAccessToken` Scope. |
+| `--ims-endpoint` | `ALIBABACLOUD_MCP_IMS_ENDPOINT` | `ramoauth.aliyuncs.com` (CN) / `ramoauth.alibabacloudcs.com` (INTL) | IMS API endpoint hostname. Auto-selected based on `--site-type`. |
+
+#### Safety Policy
+
+| CLI Flag | Environment Variable | Default | Description |
+|---|---|---|---|
+| `--safety-policy` | `ALIBABACLOUD_MCP_SAFETY_POLICY` | — | Safety policy expression to constrain allowed MCP tool calls (e.g. `ecs:describe-*=allow,*=deny`). Applied to the bearer token before connecting. |
+
+#### Retry Settings
+
+| CLI Flag | Environment Variable | Default | Description |
+|---|---|---|---|
+| `--retry-max-attempts` | `ALIBABACLOUD_MCP_RETRY_MAX_ATTEMPTS` | `3` | Maximum attempts per upstream request before surfacing an error. |
+| `--retry-base-seconds` | `ALIBABACLOUD_MCP_RETRY_BASE_SECONDS` | `1.0` | Initial retry delay in seconds (exponential backoff). |
+| `--retry-max-seconds` | `ALIBABACLOUD_MCP_RETRY_MAX_SECONDS` | `8.0` | Maximum retry delay in seconds. |
+
+#### Token Refresh
+
+| CLI Flag | Environment Variable | Default | Description |
+|---|---|---|---|
+| — | `ALIBABACLOUD_MCP_REFRESH_SKEW_SECONDS` | `60` | Seconds before token expiry to trigger a proactive refresh. |
+
+#### Debug / Logging
+
+| CLI Flag | Environment Variable | Default | Description |
+|---|---|---|---|
+| `--debug` | `ALIBABACLOUD_MCP_DEBUG` | `false` | Enable debug logging. Requires `--log-file` to be set. |
+| `--log-file` | `ALIBABACLOUD_MCP_LOG_FILE` | — | Path to the log file. Required when `--debug` is enabled. |
+
+#### Pre-check Sub-command
+
+| CLI Flag | Default | Description |
+|---|---|---|
+| `--site-type` | `CN` | Alibaba Cloud site type: `CN` or `INTL`. |
+| `--client-id` | *(per site type)* | Custom OAuth application Client ID for the pre-check flow. |
+
+### Requirements
+
+- Python >= 3.13
+
+### License
+
+Apache-2.0