feat: multi-region support improvements across CLI, MCP, and docs (#13)

* feat: add CLI/Agent sections to getting-started docs + fix CLI multi-region gaps

- Add QVeris CLI and Agent Setup sections to all three getting-started
  docs (en-US, zh-CN, cn/zh-CN), reorder sections: CLI → MCP → SDK → API
- Fix CLI multi-region support: region-aware account URLs in login/credits,
  display region in doctor/whoami/config list, pass baseUrl in login validation,
  store region in session, add QVERIS_REGION to help text

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(cli): interactive region selection during login

When QVERIS_REGION or --base-url is not set, `qveris login` now prompts
the user to choose their region (Global/China) before showing the API key
URL. This removes the need to set environment variables before first login.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(cli): handle custom region in getSiteUrl and persist baseUrl in session

Address PR review feedback:
- getSiteUrl() now accepts baseUrl param to infer site URL for custom regions
- All callers pass baseUrl to getSiteUrl()
- Session now stores baseUrl alongside region for custom region support

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: update CLI docs for interactive region selection and region display

- login: document interactive region prompt (Global/China)
- whoami: mention region display
- doctor: mention region and base URL display
- session: document region and baseUrl storage

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: clarify agent/script region usage vs interactive login prompt

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore(cli): bump version to 0.4.0

- Interactive region selection during login
- Multi-region fixes (region-aware URLs, doctor/whoami/config region display)
- Custom region support (getSiteUrl inference, baseUrl in session)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs(mcp): add multi-region configuration documentation

- README: add QVERIS_REGION and QVERIS_BASE_URL env vars, Region section
  with key prefix table, priority chain, and China config example
- docs/en-US/mcp-server.md: add env var list, region auto-detection note,
  China region config example
- docs/zh-CN/mcp-server.md: same updates in Chinese

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(cli): use resolved baseUrl in all API calls instead of raw flag

All commands now pass the region-resolved baseUrl to API calls,
ensuring QVERIS_REGION env var and key prefix detection are respected
for actual requests, not just for display/session purposes.

Fixes: credits, discover, doctor, interactive

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(cli): remove duplicate resolveBaseUrl call in discover.mjs

Region and baseUrl are already resolved at function entry (line 11).
The second call inside the try block was redundant.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: linfangw

docs/en-US/mcp-server.md

@@ -54,12 +54,16 @@ Both surfaces map to the same QVeris protocol:
 npx -y @qverisai/mcp
 ```
 
-The MCP server reads your API key from:
+The MCP server reads configuration from environment variables:
 
 ```bash
-QVERIS_API_KEY=your-api-key
+QVERIS_API_KEY=your-api-key          # Required
+QVERIS_REGION=cn                      # Optional: force region (global | cn)
+QVERIS_BASE_URL=https://...          # Optional: override API base URL
 ```
 
+Region is auto-detected from your API key prefix (`sk-cn-xxx` → China, `sk-xxx` → Global). Set `QVERIS_REGION` only if you need to override.
+
 ### Claude Desktop example
 
 ```json
@@ -92,6 +96,25 @@ QVERIS_API_KEY=your-api-key
 }
 ```
 
+### China region example
+
+For users in mainland China, add `QVERIS_REGION` or use a `sk-cn-` prefixed key:
+
+```json
+{
+  "mcpServers": {
+    "qveris": {
+      "command": "npx",
+      "args": ["-y", "@qverisai/mcp"],
+      "env": {
+        "QVERIS_API_KEY": "sk-cn-your-api-key-here",
+        "QVERIS_REGION": "cn"
+      }
+    }
+  }
+}
+```
+
 For environment-specific setup guides, see:
 
 - [SETUP.md](../../agent/SETUP.md)

docs/zh-CN/mcp-server.md

@@ -54,12 +54,16 @@
 npx -y @qverisai/mcp
 ```
 
-MCP 服务器从以下环境变量读取 API 密钥：
+MCP 服务器从以下环境变量读取配置：
 
 ```bash
-QVERIS_API_KEY=your-api-key
+QVERIS_API_KEY=your-api-key          # 必填
+QVERIS_REGION=cn                      # 可选：强制区域（global | cn）
+QVERIS_BASE_URL=https://...          # 可选：覆盖 API 地址
 ```
 
+区域从 API key 前缀自动检测（`sk-cn-xxx` → 中国区，`sk-xxx` → 全球）。仅在需要覆盖时设置 `QVERIS_REGION`。
+
 ### Claude Desktop 配置示例
 
 ```json
@@ -92,6 +96,25 @@ QVERIS_API_KEY=your-api-key
 }
 ```
 
+### 中国区配置示例
+
+中国大陆用户可添加 `QVERIS_REGION` 或使用 `sk-cn-` 前缀的 key：
+
+```json
+{
+  "mcpServers": {
+    "qveris": {
+      "command": "npx",
+      "args": ["-y", "@qverisai/mcp"],
+      "env": {
+        "QVERIS_API_KEY": "sk-cn-your-api-key-here",
+        "QVERIS_REGION": "cn"
+      }
+    }
+  }
+}
+```
+
 各环境的详细配置指南，请参考：
 
 - [Agent 安装指南](../../agent/SETUP.md)

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qverisai/cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "QVeris CLI -- discover, inspect, and call 10,000+ capabilities",
   "type": "module",
   "bin": {

packages/cli/src/commands/credits.mjs

@@ -14,7 +14,7 @@ export async function runCredits(flags) {
 
   try {
     // The backend returns remaining_credits in every /search response
-    const result = await discoverTools({ apiKey, baseUrl: flags.baseUrl, query: "credit balance", limit: 1, timeoutMs: 10000 });
+    const result = await discoverTools({ apiKey, baseUrl, query: "credit balance", limit: 1, timeoutMs: 10000 });
     spinner.stop();
 
     const credits = result.remaining_credits;

packages/cli/src/commands/discover.mjs

@@ -8,6 +8,7 @@ import { createSpinner } from "../output/spinner.mjs";
 
 export async function runDiscover(query, flags) {
   const apiKey = resolveApiKey(flags.apiKey);
+  const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
   const limit = parseInt(flags.limit, 10) || 5;
   const timeoutMs = (parseInt(flags.timeout, 10) || 30) * 1000;
 
@@ -16,7 +17,7 @@ export async function runDiscover(query, flags) {
   try {
     const result = await discoverTools({
       apiKey,
-      baseUrl: flags.baseUrl,
+      baseUrl: resolvedBaseUrl,
       query,
       limit,
       timeoutMs,
@@ -26,7 +27,6 @@ export async function runDiscover(query, flags) {
 
     // Store richer session data for index resolution
     const tools = result.results ?? [];
-    const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
     writeSession({
       discoveryId: result.search_id,
       query,

packages/cli/src/commands/doctor.mjs

@@ -30,7 +30,7 @@ export async function runDoctor(flags) {
     // Test connectivity
     process.stderr.write(`  \u2026 Testing API connectivity...\r`);
     try {
-      await discoverTools({ apiKey, baseUrl: flags.baseUrl, query: "test", limit: 1, timeoutMs: 10000 });
+      await discoverTools({ apiKey, baseUrl, query: "test", limit: 1, timeoutMs: 10000 });
       console.log(`  ${green("\u2713")} API connectivity OK                `);
     } catch (err) {
       console.log(`  ${red("\u2718")} API connectivity failed: ${err.message}  `);

packages/cli/src/commands/interactive.mjs

@@ -14,8 +14,7 @@ import { createSpinner } from "../output/spinner.mjs";
 
 export async function runInteractive(flags) {
   const apiKey = resolveApiKey(flags.apiKey);
-  const baseUrl = flags.baseUrl;
-  const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: baseUrl, apiKey });
+  const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
   const limit = parseInt(flags.limit, 10) || 5;
   const discoverTimeout = (parseInt(flags.timeout, 10) || 30) * 1000;
   const callTimeout = (parseInt(flags.timeout, 10) || 60) * 1000;
@@ -58,7 +57,7 @@ export async function runInteractive(flags) {
           const query = rest.join(" ");
           if (!query) { console.log("  Usage: discover <query>"); break; }
           const sp = createSpinner("Discovering...");
-          const result = await discoverTools({ apiKey, baseUrl, query, limit, timeoutMs: discoverTimeout });
+          const result = await discoverTools({ apiKey, baseUrl: resolvedBaseUrl, query, limit, timeoutMs: discoverTimeout });
           sp.stop();
           state.discoveryId = result.search_id;
           state.results = (result.results ?? []).map((t, i) => ({
@@ -73,7 +72,7 @@ export async function runInteractive(flags) {
           const toolId = resolveId(rest[0], state);
           if (!toolId) { console.log("  Usage: inspect <index|tool_id>"); break; }
           const sp2 = createSpinner("Inspecting...");
-          const result = await inspectToolsByIds({ apiKey, baseUrl, toolIds: [toolId], discoveryId: state.discoveryId, timeoutMs: discoverTimeout });
+          const result = await inspectToolsByIds({ apiKey, baseUrl: resolvedBaseUrl, toolIds: [toolId], discoveryId: state.discoveryId, timeoutMs: discoverTimeout });
           sp2.stop();
           console.log(formatInspectResult(result));
           break;
@@ -85,7 +84,7 @@ export async function runInteractive(flags) {
           const paramsStr = rest.slice(1).join(" ") || "{}";
           const parameters = resolveParams(paramsStr);
           const sp3 = createSpinner("Calling...");
-          const result = await callTool({ apiKey, baseUrl, toolId, discoveryId: state.discoveryId, parameters, timeoutMs: callTimeout });
+          const result = await callTool({ apiKey, baseUrl: resolvedBaseUrl, toolId, discoveryId: state.discoveryId, parameters, timeoutMs: callTimeout });
           sp3.stop();
           console.log(formatCallResult(result));
           if (result.success) {

packages/mcp/README.md

@@ -17,7 +17,7 @@ This SDK provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.
 
 ### 1. Get Your API Key
 
-Visit [QVeris](https://qveris.ai) to get your API key.
+Visit [QVeris](https://qveris.ai) (Global) or [QVeris](https://qveris.cn) (China) to get your API key.
 
 ### 2. Configure Your MCP Client
 
@@ -182,11 +182,41 @@ The `full_content_file_url` is valid for 120 minutes.
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `QVERIS_API_KEY` | ✓ | Your QVeris API key |
+| `QVERIS_REGION` | | Force region: `global` or `cn` (auto-detected from key prefix if not set) |
+| `QVERIS_BASE_URL` | | Override API base URL (highest priority, for custom endpoints) |
+
+## Region
+
+Region is auto-detected from your API key prefix — no extra configuration needed.
+
+| Key prefix | Region | API endpoint |
+|------------|--------|--------------|
+| `sk-xxx` | Global | `https://qveris.ai/api/v1` |
+| `sk-cn-xxx` | China | `https://qveris.cn/api/v1` |
+
+To override manually, set environment variables in your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "qveris": {
+      "command": "npx",
+      "args": ["-y", "@qverisai/mcp"],
+      "env": {
+        "QVERIS_API_KEY": "your-api-key",
+        "QVERIS_REGION": "cn"
+      }
+    }
+  }
+}
+```
+
+**Priority:** `QVERIS_BASE_URL` > `QVERIS_REGION` > API key prefix auto-detection > default (global)
 
 ## Requirements
 
 - Node.js 18.0.0 or higher
-- A valid QVeris API key
+- A valid QVeris API key ([qveris.ai](https://qveris.ai) or [qveris.cn](https://qveris.cn))
 
 ## Development