fix(dxt): resolve token path ${HOME} and handle unset optional user_config (closes #204) (#220)

* fix(dxt): resolve default Garmin token path

* fix(auth): share token path normalization

* fix(auth): ignore unresolved credential placeholders

---------

Co-authored-by: Paweł Nadolski <pn@users.noreply.github.com>

Author: Taxuspt

dxt/manifest.json

@@ -49,7 +49,7 @@
       "title": "Token storage directory",
       "description": "Directory where your Garmin OAuth tokens are stored. You must run garmin-mcp-auth once in a terminal to generate these tokens before using the server.",
       "required": false,
-      "default": "${HOME}/.garminconnect"
+      "default": "~/.garminconnect"
     },
     "garmin_email": {
       "type": "string",

garmin-mcp.dxt

@@ -5,6 +5,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(dirname "$SCRIPT_DIR")"
 OUTPUT="$REPO_ROOT/garmin-mcp.dxt"
 
+rm -f "$OUTPUT"
 cd "$REPO_ROOT/dxt"
 zip "$OUTPUT" manifest.json
 echo "Built: $OUTPUT ($(du -h "$OUTPUT" | cut -f1))"

scripts/build_dxt.sh

@@ -62,6 +62,12 @@ def get_mfa() -> str:
     return input("Enter MFA code: ")
 
 
+def _normalize_optional_user_config(value: str | None, key: str) -> str | None:
+    """Treat an unresolved optional Desktop Extension value as unset."""
+    unresolved_placeholder = f"${{user_config.{key}}}"
+    return None if value == unresolved_placeholder else value
+
+
 # Get credentials from environment
 email = os.environ.get("GARMIN_EMAIL")
 email_file = os.environ.get("GARMIN_EMAIL_FILE")
@@ -83,8 +89,8 @@ def get_mfa() -> str:
     with open(password_file, "r") as password_file:
         password = password_file.read().rstrip()
 
-tokenstore = os.getenv("GARMINTOKENS") or "~/.garminconnect"
-tokenstore_base64 = os.getenv("GARMINTOKENS_BASE64") or "~/.garminconnect_base64"
+tokenstore = token_utils.get_token_path()
+tokenstore_base64 = token_utils.get_token_base64_path()
 is_cn = os.getenv("GARMIN_IS_CN", "false").lower() in ("true", "1", "yes")
 
 
@@ -218,6 +224,12 @@ def init_api(email, password):
     """Initialize Garmin API with your credentials."""
     import io
 
+    # Claude Desktop may leave blank optional user_config values as literal
+    # placeholders. Do not mistake those strings for credentials and trigger a
+    # rate-limited Garmin login from a non-interactive MCP process.
+    email = _normalize_optional_user_config(email, "garmin_email")
+    password = _normalize_optional_user_config(password, "garmin_password")
+
     try:
         # Using Oauth1 and OAuth2 token files from directory
         print(
@@ -294,17 +306,15 @@ def init_api(email, password):
                 file=sys.stderr,
             )
             # Encode Oauth1 and Oauth2 tokens to base64 string and save to file for next login (alternative way)
-            expanded_tokenstore = os.path.expanduser(tokenstore)
-            token_json_path = os.path.join(expanded_tokenstore, "garmin_tokens.json")
+            token_json_path = os.path.join(tokenstore, "garmin_tokens.json")
             with open(token_json_path, "r") as f:
                 token_data = f.read()
             token_base64 = base64.b64encode(token_data.encode()).decode()
-            dir_path = os.path.expanduser(tokenstore_base64)
-            with open(dir_path, "w") as token_file:
+            with open(tokenstore_base64, "w") as token_file:
                 token_file.write(token_base64)
-            os.chmod(dir_path, 0o600)
+            os.chmod(tokenstore_base64, 0o600)
             print(
-                f"Oauth tokens encoded as base64 string and saved to '{dir_path}' file for future use. (second method)\n",
+                f"Oauth tokens encoded as base64 string and saved to '{tokenstore_base64}' file for future use. (second method)\n",
                 file=sys.stderr,
             )
         except (

src/garmin_mcp/__init__.py

@@ -19,6 +19,7 @@
     token_exists,
     validate_tokens,
     get_token_info,
+    resolve_token_path,
     secure_token_dir as _secure_token_dir,
 )
 
@@ -121,6 +122,9 @@ def authenticate(token_path: str, token_base64_path: str, force_reauth: bool = F
     """
     import io
 
+    token_path = resolve_token_path(token_path)
+    token_base64_path = resolve_token_path(token_base64_path)
+
     # Check if tokens already exist and are valid
     if not force_reauth and token_exists(token_path):
         print(f"\nChecking existing tokens in '{token_path}'...")
@@ -164,20 +168,18 @@ def authenticate(token_path: str, token_base64_path: str, force_reauth: bool = F
 
         # Save tokens to directory
         garmin.client.dump(token_path)
-        expanded_token_path = os.path.expanduser(token_path)
-        _secure_token_dir(expanded_token_path)
-        print(f"\n✓ OAuth tokens saved to: {expanded_token_path}")
+        _secure_token_dir(token_path)
+        print(f"\n✓ OAuth tokens saved to: {token_path}")
 
         # Save tokens as base64
-        token_json_path = os.path.join(expanded_token_path, "garmin_tokens.json")
-        expanded_base64_path = os.path.expanduser(token_base64_path)
+        token_json_path = os.path.join(token_path, "garmin_tokens.json")
         with open(token_json_path, "r") as f:
             token_data = f.read()
         token_base64 = base64.b64encode(token_data.encode()).decode()
-        with open(expanded_base64_path, "w") as token_file:
+        with open(token_base64_path, "w") as token_file:
             token_file.write(token_base64)
-        os.chmod(expanded_base64_path, 0o600)
-        print(f"✓ OAuth tokens (base64) saved to: {expanded_base64_path}")
+        os.chmod(token_base64_path, 0o600)
+        print(f"✓ OAuth tokens (base64) saved to: {token_base64_path}")
 
         # Verify tokens work with an independent token-based login. The login
         # above runs with return_on_mfa=True, which skips profile loading, so a

src/garmin_mcp/auth_cli.py

@@ -7,14 +7,26 @@
 from garminconnect import Garmin, GarminConnectConnectionError
 
 
+def resolve_token_path(path: str) -> str:
+    """Resolve environment variables and the user-home marker in a token path.
+
+    Some MCP clients leave ``${HOME}`` unresolved when it comes from a nested
+    user-config default. The explicit replacement also covers Windows, where
+    ``HOME`` may be unset but Python can still resolve ``~`` via ``USERPROFILE``.
+    """
+    expanded = os.path.expandvars(path)
+    expanded = expanded.replace("${HOME}", os.path.expanduser("~"))
+    return os.path.expanduser(expanded)
+
+
 def secure_token_dir(path: str) -> None:
     """Set owner-only permissions on a token directory and the files inside it.
 
     OAuth tokens are ~6-month bearer credentials to the full Garmin account, so
     they must not be left world-readable on multi-user hosts. Safe to call on a
     path that is a single file rather than a directory.
     """
-    expanded = os.path.expanduser(path)
+    expanded = resolve_token_path(path)
     if not os.path.exists(expanded):
         return
     if os.path.isdir(expanded):
@@ -32,7 +44,7 @@ def get_token_path() -> str:
     Returns:
         str: Path to token storage directory
     """
-    return os.getenv("GARMINTOKENS") or "~/.garminconnect"
+    return resolve_token_path(os.getenv("GARMINTOKENS") or "~/.garminconnect")
 
 
 def get_token_base64_path() -> str:
@@ -41,7 +53,9 @@ def get_token_base64_path() -> str:
     Returns:
         str: Path to base64 token file
     """
-    return os.getenv("GARMINTOKENS_BASE64") or "~/.garminconnect_base64"
+    return resolve_token_path(
+        os.getenv("GARMINTOKENS_BASE64") or "~/.garminconnect_base64"
+    )
 
 
 def token_exists(token_path: str = None) -> bool:
@@ -56,7 +70,7 @@ def token_exists(token_path: str = None) -> bool:
     if token_path is None:
         token_path = get_token_path()
 
-    expanded_path = Path(os.path.expanduser(token_path))
+    expanded_path = Path(resolve_token_path(token_path))
     return expanded_path.exists()
 
 
@@ -75,6 +89,7 @@ def validate_tokens(token_path: str = None, is_cn: bool = False) -> Tuple[bool,
 
     if token_path is None:
         token_path = get_token_path()
+    token_path = resolve_token_path(token_path)
 
     # Check if tokens exist
     if not token_exists(token_path):
@@ -138,17 +153,19 @@ def remove_tokens(token_path: str = None, base64_path: str = None) -> None:
         token_path = get_token_path()
     if base64_path is None:
         base64_path = get_token_base64_path()
+    token_path = resolve_token_path(token_path)
+    base64_path = resolve_token_path(base64_path)
 
     # Remove token directory
-    expanded_token_path = Path(os.path.expanduser(token_path))
+    expanded_token_path = Path(token_path)
     if expanded_token_path.exists():
         if expanded_token_path.is_dir():
             shutil.rmtree(expanded_token_path)
         else:
             expanded_token_path.unlink()
 
     # Remove base64 token file
-    expanded_base64_path = Path(os.path.expanduser(base64_path))
+    expanded_base64_path = Path(base64_path)
     if expanded_base64_path.exists():
         expanded_base64_path.unlink()
 
@@ -165,6 +182,7 @@ def get_token_info(token_path: str = None, is_cn: bool = False) -> dict:
     """
     if token_path is None:
         token_path = get_token_path()
+    token_path = resolve_token_path(token_path)
 
     exists = token_exists(token_path)
     is_valid = False
@@ -175,7 +193,7 @@ def get_token_info(token_path: str = None, is_cn: bool = False) -> dict:
 
     return {
         "path": token_path,
-        "expanded_path": os.path.expanduser(token_path),
+        "expanded_path": token_path,
         "exists": exists,
         "valid": is_valid,
         "error": error_msg

src/garmin_mcp/token_utils.py

@@ -184,6 +184,48 @@ def test_successful_authentication(self, mock_chmod, mock_verify, mock_garmin, m
         # Verify restrictive permissions were applied to the base64 file
         mock_chmod.assert_any_call(os.path.expanduser(base64_path), 0o600)
 
+    @patch("garmin_mcp.auth_cli.token_exists", return_value=False)
+    @patch(
+        "garmin_mcp.auth_cli.get_credentials",
+        return_value=("test@example.com", "secret"),
+    )
+    @patch("garmin_mcp.auth_cli.Garmin")
+    @patch(
+        "garmin_mcp.auth_cli._verify_saved_tokens",
+        return_value=(True, "Test User"),
+    )
+    @patch("garmin_mcp.auth_cli.os.chmod")
+    def test_authentication_resolves_home_in_token_paths(
+        self,
+        mock_chmod,
+        mock_verify,
+        mock_garmin,
+        _mock_get_creds,
+        mock_exists,
+        monkeypatch,
+        tmp_path,
+    ):
+        """The CLI writes and verifies tokens at the same resolved paths."""
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("USERPROFILE", str(tmp_path))
+        mock_garmin.return_value.login.return_value = (None, None)
+
+        with patch("builtins.open", mock_open(read_data="{}")):
+            result = authenticate(
+                "${HOME}/.garminconnect",
+                "${HOME}/.garminconnect_base64",
+            )
+
+        expected_token_path = str(tmp_path / ".garminconnect")
+        expected_base64_path = str(tmp_path / ".garminconnect_base64")
+        assert result is True
+        mock_exists.assert_called_once_with(expected_token_path)
+        mock_garmin.return_value.client.dump.assert_called_once_with(
+            expected_token_path
+        )
+        mock_verify.assert_called_once_with(expected_token_path, False)
+        mock_chmod.assert_any_call(expected_base64_path, 0o600)
+
     @patch("garmin_mcp.auth_cli.token_exists")
     @patch("garmin_mcp.auth_cli.get_credentials")
     @patch("garmin_mcp.auth_cli.Garmin")

tests/unit/test_auth_cli.py

@@ -0,0 +1,37 @@
+"""Regression tests for the Desktop Extension manifest."""
+
+import json
+from pathlib import Path
+from zipfile import ZipFile
+
+
+REPO_ROOT = Path(__file__).parents[2]
+MANIFEST_PATH = REPO_ROOT / "dxt" / "manifest.json"
+BUNDLE_PATH = REPO_ROOT / "garmin-mcp.dxt"
+
+
+def _read_manifest():
+    return json.loads(MANIFEST_PATH.read_text())
+
+
+def test_token_path_default_does_not_require_nested_interpolation():
+    manifest = _read_manifest()
+    assert manifest["user_config"]["token_path"]["default"] == "~/.garminconnect"
+
+
+def test_user_config_defaults_do_not_contain_template_variables():
+    manifest = _read_manifest()
+
+    for config in manifest.get("user_config", {}).values():
+        default = config.get("default")
+        values = default if isinstance(default, list) else [default]
+        assert all("${" not in value for value in values if isinstance(value, str))
+
+
+def test_bundled_manifest_matches_source_manifest():
+    manifest = _read_manifest()
+    with ZipFile(BUNDLE_PATH) as bundle:
+        assert bundle.namelist() == ["manifest.json"]
+        bundled_manifest = json.loads(bundle.read("manifest.json"))
+
+    assert bundled_manifest == manifest