MCP常見問題 - AI Coding Assistant Lingma

本文詳細介紹了 MCP 服務在安裝和運行過程中遇到的異常情況，並提供了相應的解決方案和排查步驟，包括處理缺少命令環境、服務初始化失敗及配置錯誤等問題。

服務添加或安裝異常

1. 缺少 npx 命令所需環境

異常資訊：failed to start command: exec: "npx": executable file not found in $PATH
解決方案：下載並安裝 Node.js。

警告

Node.js 版本須在 v18 及以上，npm 版本須在 v8 及以上。版本過低可能導致工具調用失敗

您可以訪問 Node.js 官網，下載並安裝 Node.js 18 或更高版本，也可以選擇通過以下方式完成：
安裝驗證步驟
Windows 系統
1.下載並安裝，使用 nvm-windows 管理多版本：
nvm install 22.14.0 # 安裝指定版本 nvm use 22.14.0
2.安裝完成後，在終端中運行以下命令確認是否安裝成功。
node -v npx -v
3.安裝成功後，終端將顯示已安裝的 Node.js 版本號碼。
Mac 系統
下載並安裝，使用 brew 安裝（需先安裝 brew）。
# 1. 更新並安裝brew brew update brew install node # 2. 驗證核心工具鏈 echo "Node.js版本: $(node -v)" echo "npm版本: $(npm -v)" echo "npx版本: $(npx -v)" # 3. 配置環境變數（必要時） echo 'export PATH="/usr/local/opt/node@16/bin:$PATH"' >> ~/.zshrc

2. 缺少 uvx 命令所需環境

異常資訊：failed to start command: exec: "uvx": executable file not found in $PATH
解決方案：安裝 uv， uvx 是 uv 提供的命令列工具，用於快速運行 Python 指令碼。
- 您可以前往 Python 官網，下載並安裝 Python 3.8 或更高版本，也可以選擇通過以下方式完成：
  安裝驗證步驟
  1.下載並安裝
  Windows 系統
  Windows 使用下面命令安裝
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  Mac 系統
  macOS 和 Linux 使用下面命令安裝
  curl -LsSf https://astral.sh/uv/install.sh | sh
  2.安裝完成後，在終端中運行以下命令確認是否安裝成功。
```
uv --version
```
  3.安裝成功後，終端將顯示已安裝的 uv 版本號碼。

3. 無法初始化 MCP Client

異常資訊：failed to initialize MCP client: context deadline exceeded
異常原因，包括但不限於以下原因：
- 服務參數配置錯誤：MCP 服務的參數設定可能存在錯誤或其他情況，影響服務初始化。
- 資源拉取失敗：由於網路問題，無法成功拉取資源導致的安裝失敗。
- 網路安全限制：由於公司內部安全性群組件的攔截，導致 MCP 服務初始化異常。
排查步驟：

1. 單擊複製完整命令，可以擷取完整的命令。

莫3@1x (64)

2. 在終端中運行該命令，可以擷取詳細異常資訊。

莫3@1x (67)

3.分析異常資訊，進行對應修複。

常見問題 1：配置錯誤

在以上異常樣本中，通過異常資訊可以看出，是由於 Redis 串連URL 配置錯誤導致串連失敗，據此應檢查並通過編輯該MCP服務，修正錯誤的URL配置。

常見問題2：資源拉取失敗

如果由於資源拉取問題導致命令運行失敗，可以在命令列中執行以下命令，添加鏡像源，再重啟 lingma 進程後再試。

Windows 系統

npm config set registry https://registry.npmmirror.com

Mac 系統

export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

常見問題3：Node.js 運行被安全性群組件攔截

根據安全性群組件的攔截提示，對Node.js進程或相關執行檔案進行授權或加白操作。

工具使用相關問題

說明

如果您在使用 MCP 廣場中的服務存在問題，請聯絡魔搭社區，擷取支援人員。

ModelScope 開發人員群（DingTalk群號 44837352）

1. 環境變數或參數填寫錯誤，導致工具執行失敗

排查步驟：

如果 MCP 工具調用出現異常或返回結果不符合預期，建議您首先展開工具調用詳情，查看具體的錯誤資訊，並據此進行分析與排查。

重要

部分 MCP 服務（如 Mastergo 和 Figma）的 API_KEY 或 TOKEN 等關鍵認證資訊包含在“參數（args）”中。

因此，在通過 MCP 廣場安裝後，仍需手動設定這些參數。

莫3@1x (62)

解決方案：

進入我的服務頁面。
找到對應 MCP 服務，單擊編輯。
在服務配置中，查看參數（args）部分。
替換其中需要更新或填寫的變數內容，確保其準確無誤，重新串連服務後再嘗試調用。

莫3@1x (68)

2. 模型無法正常調用 MCP 工具

確認當前在智能體模式。
重要
如果未開啟相關工程目錄，系統將僅進入智能問答模式，無法調用 MCP 工具。請先載入對應的工程目錄，並切換到智能體模式。
確認 MCP 服務處於已串連狀態：

如果服務串連中斷，在介面右側單擊，系統會自動嘗試重新啟動 MCP 服務。

莫3@1x (66)

使用建議：避免MCP服務及其工具使用相似命名（如 TextAnalyzer-Pro 和 TextAnalyzer-Plus 都包含名為 fetchText 的工具且功能類似），防止模型調用時產生歧義。

3. 個人設定、MCP 工具頁無法開啟，會話面板顯示空白。

當頁面顯示空白並在 idea.log 中有如下報錯資訊：“WARN - #c.i.u.j.JBCefApp - JCefAppConfig.class is not from a JBR module”。

異常原因：Android Studio 預設設定不支援 JCEF，導致無法載入個人設定、MCP 等頁面。

解決方案：

配置 JCEF：在 IDE 中選擇Help > Find Action..，在彈出的輸入框中輸入 "Registry" 並開啟。啟用選項`ide.browser.jcef.enabled` 關閉選項`ide.browser.jcef.sandbox.enable`
配置 IDE Runtime：再次選擇Help > Find Action..，在輸入框中輸入 "Choose Boot Runtime for the IDE" 並開啟，選擇較新的 JCEF Runtime 版本，然後確定。重啟 IDE。

4. MCP 服務列表無法正常載入

服務列表持續顯示載入中。

重新啟動 IDE。
如果問題仍未解決，可嘗試手動啟動 Lingma 服務：
Windows 系統
進入目錄：.lingma/bin/x.x.x/CPU架構_64_系統/
執行命令：
```
Lingma.exe start
```
Mac 系統
單擊電腦左上方蘋果表徵圖，選擇“關於本機”查看處理器型號，然後根據處理器型號進入對應的目錄。
- m1 晶片：/.lingma/bin/x.x.x/aarch64_darwin/Lingma
- intel 晶片：/.lingma/bin/x.x.x/x86_64_darwin/Lingma
執行命令：
```
Lingma start
```
等待啟動成功後，重新單擊登入按鈕。