refactor(settings/docs): CLI-only endpoint mapping; drop ENV/@file support

- settings.build_endpoint_mapping(): remove env/file handling, parse CLI strings only
- __init__.py: build mappings from CLI only
- tests: update to reflect CLI-only behavior
- docs: remove ENV and @file examples; clarify CLI-only usage; CHANGELOG updated

Change-Id: Ia869f1af56573a23e2d04de928656701daebf486
Co-developed-by: Cursor <[email protected]>

Author: haibin.lhb

CHANGELOG.md

@@ -2,11 +2,10 @@
 
 ## 0.3.2
 - 新增全局配置 Settings：支持 SLS/ARMS endpoint 映射与模板回退
-  - 启动参数：`--sls-endpoints`、`--arms-endpoints`（支持 `REGION=HOST`、逗号/空格分隔，或 `@file` 加载 JSON/纯文本）
-  - 环境变量：`SLS_ENDPOINTS`、`ARMS_ENDPOINTS`
+  - 启动参数：`--sls-endpoints`、`--arms-endpoints`（仅支持 `REGION=HOST`，逗号/空格分隔）比如 `--sls-endpoints "cn-shanghai=cn-hangzhou.log.aliyuncs.com"`
   - 未命中映射时回退：SLS `"{region}.log.aliyuncs.com"`，ARMS `"arms.{region}.aliyuncs.com"`
 - 统一客户端端点解析，并打印使用的 region/endpoint/source（explicit/mapping/template）
-- CLI 清理：仅保留 `--sls-endpoints`（移除其他变体）
+- CLI 清理：仅保留 `--sls-endpoints`（移除其他变体），不再支持环境变量与 @file 加载
 
 ## 0.3.1
 - 修复ARMS工具返回结果类型错误问题,会导致高版本的MCP出现返回值提取错误

README.md

@@ -214,7 +214,7 @@ python -m mcp_server_aliyun_observability --transport sse --access-key-id <your_
 
 ### 端点映射与全局配置（SLS/ARMS）
 
-支持在启动时覆盖各区域的服务端点，并在运行时打印实际生效的区域与端点（source=explicit/mapping/template）。
+支持在启动时通过命令行覆盖各区域的服务端点，并在运行时打印实际生效的区域与端点（source=explicit/mapping/template）。
 
 - SLS 端点映射（CLI）
 ```
@@ -228,24 +228,13 @@ python -m mcp_server_aliyun_observability \
 python -m mcp_server_aliyun_observability --arms-endpoints "cn-shanghai=arms.internal"
 ```
 
-- 环境变量方式（优先级低于 CLI）
-```
-SLS_ENDPOINTS="cn-shanghai=cn-hangzhou.log.aliyuncs.com" \
-ARMS_ENDPOINTS="cn-shanghai=arms.internal" \
-python -m mcp_server_aliyun_observability --transport sse
-```
-
-- 从文件加载（@file），文件可为 JSON 对象或纯文本 pairs
-```
-echo '{"cn-shanghai":"cn-hangzhou.log.aliyuncs.com"}' > sls_endpoints.json
-python -m mcp_server_aliyun_observability --sls-endpoints @sls_endpoints.json
-```
+- 仅支持命令行参数方式（不支持环境变量与 @file 加载）
 
 - 默认回退模板（未命中映射时）：
   - SLS: `{region}.log.aliyuncs.com`
   - ARMS: `arms.{region}.aliyuncs.com`
 
-- CMS 说明：CMS 工具内部使用 SLS 客户端，自动复用 `--sls-endpoints` 的映射，无需单独 cms 配置。
+- CMS 说明：CMS 工具内部使用 SLS 客户端，自动复用 `--sls-endpoints` 的映射。
 
 - 日志示例（控制台与文件均会输出）：
 ```

README_EN.md

@@ -215,7 +215,7 @@ python -m mcp_server_aliyun_observability --transport sse --access-key-id <your_
 
 ### Endpoint Overrides and Global Settings (SLS/ARMS)
 
-You can override service endpoints per region at startup. The server logs the effective region/endpoint and its source (explicit/mapping/template) when a client is created.
+You can override service endpoints per region at startup via CLI only. The server logs the effective region/endpoint and its source (explicit/mapping/template) when a client is created.
 
 - SLS endpoint overrides (CLI)
 ```
@@ -229,24 +229,13 @@ python -m mcp_server_aliyun_observability \
 python -m mcp_server_aliyun_observability --arms-endpoints "cn-shanghai=arms.internal"
 ```
 
-- Environment variables (lower precedence than CLI)
-```
-SLS_ENDPOINTS="cn-shanghai=cn-hangzhou.log.aliyuncs.com" \
-ARMS_ENDPOINTS="cn-shanghai=arms.internal" \
-python -m mcp_server_aliyun_observability --transport sse
-```
-
-- Load from file (@file). File can be a JSON object or plain pairs text
-```
-echo '{"cn-shanghai":"cn-hangzhou.log.aliyuncs.com"}' > sls_endpoints.json
-python -m mcp_server_aliyun_observability --sls-endpoints @sls_endpoints.json
-```
+- CLI only (environment variables and @file loading are not supported)
 
 - Template fallback when no mapping matched:
   - SLS: `{region}.log.aliyuncs.com`
   - ARMS: `arms.{region}.aliyuncs.com`
 
-- CMS note: CMS tools internally reuse the SLS client, so it automatically respects `--sls-endpoints`.
+- CMS note: CMS tools internally reuse the SLS client and automatically respect `--sls-endpoints`.
 
 - Example logs (to console and file):
 ```

src/mcp_server_aliyun_observability/__init__.py

@@ -48,13 +48,13 @@
     "--sls-endpoints",
     "sls_endpoints",
     type=str,
-    help="REGION=HOST pairs (comma/space separated) or @file (JSON object or pairs).",
+    help="REGION=HOST pairs (comma/space separated)",
 )
 @click.option(
     "--arms-endpoints",
     "arms_endpoints",
     type=str,
-    help="REGION=HOST pairs (comma/space separated) or @file (JSON object or pairs) for ARMS.",
+    help="REGION=HOST pairs (comma/space separated) for ARMS.",
 )
 def main(
     access_key_id,
@@ -73,18 +73,8 @@ def main(
 
     # Configure global settings (process-wide, frozen)
     try:
-        sls_mapping = build_endpoint_mapping(
-            cli_pairs=None,
-            combined=sls_endpoints,
-            file_ref=None,
-            env_var="SLS_ENDPOINTS",
-        )
-        arms_mapping = build_endpoint_mapping(
-            cli_pairs=None,
-            combined=arms_endpoints,
-            file_ref=None,
-            env_var="ARMS_ENDPOINTS",
-        )
+        sls_mapping = build_endpoint_mapping(cli_pairs=None, combined=sls_endpoints)
+        arms_mapping = build_endpoint_mapping(cli_pairs=None, combined=arms_endpoints)
         settings = GlobalSettings(
             sls=SLSSettings(endpoints=sls_mapping),
             arms=ArmsSettings(endpoints=arms_mapping),

src/mcp_server_aliyun_observability/settings.py

@@ -12,7 +12,6 @@
 
 from dataclasses import dataclass, field
 from threading import RLock
-from pathlib import Path
 from typing import Optional, Dict, Iterable
 import json
 import os
@@ -46,65 +45,21 @@ def _parse_pairs_str(s: str | None) -> Dict[str, str]:
     return out
 
 
-def _load_mapping_from_file(path: str) -> Dict[str, str]:
-    """Load a mapping from a file. Supports JSON object or pairs text.
-
-    - If content starts with '{', parse as JSON object: {"cn-hangzhou":"x", ...}
-    - Otherwise parse as pairs text like "cn-shanghai=foo,cn-hangzhou=bar"
-    """
-    p = Path(path).expanduser()
-    if not p.exists():
-        raise FileNotFoundError(f"Endpoints file not found: {path}")
-    text = p.read_text(encoding="utf-8").strip()
-    if not text:
-        return {}
-    if text.startswith("{"):
-        data = json.loads(text)
-        if not isinstance(data, dict):
-            raise ValueError("Expected a JSON object for endpoints mapping")
-        return {str(k): str(v) for k, v in data.items()}
-    return _parse_pairs_str(text)
-
-
 def build_endpoint_mapping(
     cli_pairs: Iterable[str] | None,
     combined: Optional[str],
-    file_ref: Optional[str],
-    env_var: str = "SLS_ENDPOINTS",
 ) -> Dict[str, str]:
-    """Build endpoint mapping from multiple sources with precedence:
+    """Build endpoint mapping from CLI inputs only.
 
-    file (lowest) < env var < combined < repeated cli pairs (highest)
+    Precedence: combined string < repeated cli_pairs (last wins).
     """
     mapping: Dict[str, str] = {}
 
-    # File (lowest)
-    if file_ref:
-        src = file_ref.strip()
-        if src.startswith("@"):
-            src = src[1:]
-        mapping.update(_load_mapping_from_file(src))
-
-    # ENV
-    env_val = os.getenv(env_var)
-    if env_val:
-        env_val = env_val.strip()
-        if env_val.startswith("{"):
-            data = json.loads(env_val)
-            if isinstance(data, dict):
-                mapping.update({str(k): str(v) for k, v in data.items()})
-        else:
-            mapping.update(_parse_pairs_str(env_val))
-
-    # Combined
+    # Combined string
     if combined:
-        c = combined.strip()
-        if c.startswith("@"):
-            mapping.update(_load_mapping_from_file(c[1:]))
-        else:
-            mapping.update(_parse_pairs_str(c))
+        mapping.update(_parse_pairs_str(combined.strip()))
 
-    # Repeated CLI pairs (highest)
+    # Repeated CLI pairs (override)
     for pair in (cli_pairs or []):
         mapping.update(_parse_pairs_str(pair))
 

tests/test_settings_endpoints.py

@@ -13,24 +13,17 @@
 )
 
 
-def test_build_endpoint_mapping_precedence(tmp_path, monkeypatch):
-    # file (lowest)
-    f = tmp_path / "eps.json"
-    f.write_text(json.dumps({"cn-beijing": "file.example.com"}), encoding="utf-8")
-
-    # env (overrides file)
-    monkeypatch.setenv("SLS_ENDPOINTS", "cn-beijing=env.example.com cn-shanghai=env-sh.example.com")
-
-    # combined (overrides env)
+def test_build_endpoint_mapping_precedence():
+    # combined (base)
     combined = "cn-beijing=combined.example.com,cn-hangzhou=combined-hz.example.com"
 
-    # repeated CLI (highest)
+    # repeated CLI (override)
     cli_pairs = [
         "cn-beijing=cli.example.com",
         "cn-shanghai=cli-sh.example.com",
     ]
 
-    mapping = build_endpoint_mapping(cli_pairs, combined, f"@{str(f)}")
+    mapping = build_endpoint_mapping(cli_pairs, combined)
     assert mapping["cn-beijing"] == "cli.example.com"
     assert mapping["cn-shanghai"] == "cli-sh.example.com"
     assert mapping["cn-hangzhou"] == "combined-hz.example.com"
@@ -57,7 +50,6 @@ def test_configure_and_get_settings(monkeypatch):
     assert get_settings().arms.resolve("cn-shanghai") == "arms.internal"
 
 
-def test_build_arms_endpoint_mapping(monkeypatch):
-    monkeypatch.setenv("ARMS_ENDPOINTS", "cn-hangzhou=arms.hz.example.com")
-    mapping = build_endpoint_mapping(None, None, None, env_var="ARMS_ENDPOINTS")
+def test_build_arms_endpoint_mapping():
+    mapping = build_endpoint_mapping(None, "cn-hangzhou=arms.hz.example.com")
     assert mapping["cn-hangzhou"] == "arms.hz.example.com"