疑難排解

客戶端搵唔到工具

• 確認 uvx 已安裝而且客戶端執行得到
• 固定版本可避免升級後行為變化：uvx --from "usmartsg-mcp==1.1.0" usmartsg-mcp
• 呢個指令會保持運行等 MCP stdio 訊息，屬正常行為，應由客戶端拉起

工具清單入面冇 place_order / modify_order

本地版預設註冊全部 11 個工具。如果呢兩個缺失，順序檢查：

1. 客戶端設定嘅 env 入面有冇設定 USMART_READONLY（值為 1、true、yes、on 時寫入工具唔會註冊）
2. 有冇設定 USMART_PROFILE=directory（呢個值只註冊 5 個查詢工具）
3. 改完之後有冇重啟客戶端，呢啲變數喺進程啟動時讀取
4. 確認裝嘅係 usmartsg-mcp

憑證檢查失敗

• 檢查 USMART_HOME 指向嘅目錄、config.json 是否存在而且讀取到，以及檔案權限
• 唔好將真實憑證貼落聊天
• 授權失敗時，確認無改動 config.json 入面嘅 clientId 同 redirectUri；刪除 ~/.usmart/config.json 重啟就會重新生成預設設定

OAuth 授權後仍提示未授權

• 確認 oauth_login_status 回傳授權成功
• 確認 redirectUri 無被改動（含端口、路徑、大小寫）
• 工作階段檔係 ~/.usmart/oauth_session.json，刪除即等於本地登出

授權後瀏覽器打唔開 localhost:5100

呢個通常係本機回調被代理、瀏覽器「只限 HTTPS」模式或保安軟件攔截，唔影響授權本身：網址列入面以 http://localhost:5100/callback 開頭嘅完整連結仍然有效。

• 將該連結交俾助手，叫佢用 oauth_login_status 嘅 callback_url 參數提交；連結只可用一次、10 分鐘內有效，唔好轉發去其他地方
• 端口被佔用時：Windows 用 netstat -ano | findstr :5100，macOS 用 lsof -i :5100 查佔用進程
• 長期被攔截時，喺客戶端 env 設定 USMART_OAUTH_SKIP_LISTENER=1，直接用手動回填

落單回傳 100034

寫入接口要求 X-Request-Id 非空，代碼會自動生成。如果仍然報錯，確認無用 extraHeaders 覆蓋成空值。

落單回傳 100073

呢個係平台風控嘅「價格偏離市價較大」提示，唔係鑑權失敗。人工核對價格後可以傳 force_entrust_flag=true 繼續，呢個參數只應喺核對後使用。