zhineng.dev
繁體中文
開始使用

Getting started / start small

從準備環境，
到完成第一次連接。

擴展與 MCP 可以分別安裝。先選一個小任務，在測試環境驗證，再慢慢接入自己的日常工作。

01 / 安裝 VS Code 擴展

在 VS Code 擴展市場中查找 Claude Code Config Helper，確認發佈者為 liliangshan。市場版本以頁面顯示為準；本地測試版與市場版本可能不同。

打開擴展市場項目源碼與說明

也可以安裝 VSIX

如果你已取得本地 VSIX，在 VS Code 的“擴展 → … → 從 VSIX 安裝”中選擇文件。安裝後在方便的時候重載窗口，重載會中斷運行中的 CLI 任務。

02 / 完成三步引導

  1. 選擇語言，準備 CLI從引導下載並驗證 CLI，或選擇已安裝的可執行文件。默認使用官方源，中國鏡像源需主動選擇。
  2. 添加提供商與模型配置你自己的服務地址、認證方式與 API Key，獲取模型列表或手動添加。無需為完成引導發送付費測試消息。
  3. 選擇工作區模型，進入聊天設置普通模型、可選任務流 / 壓縮模型與思考等級。完成後右側顯示主會話，點擊並行會話可打開左側獨立會話。
沒有當前環境的全局完成記錄時會進入引導；已有 CLI 或提供商會預填，但不會自動視為已完成。模型調用費用由你使用的服務商決定。

03 / 選擇工具，複製配置

下面只生成本機配置示例，不連接服務器，不收集密碼，也不會安裝 npm 包。示例地址與路徑需要替換；憑據應在客戶端本機配置。

.mcp.json
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@liangshanli/mcp-server-mysql"
      ],
      "env": {
        "MYSQL_HOST": "db.example.com",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "ai_reader",
        "MYSQL_PASSWORD": "${MYSQL_PASSWORD}",
        "MYSQL_DATABASE": "app_db",
        "MYSQL_SSL": "true",
        "READONLY": "true",
        "ALLOW_DDL": "false",
        "ALLOW_DROP": "false",
        "ALLOW_DELETE": "false"
      }
    }
  }
}

MySQL 示例啓用只讀和 TLS。請使用只讀數據庫賬戶，並確保域名與數據庫證書匹配。

變量和配置文件的區別

  • Claude Code：使用 mcpServers，放在項目根目錄 .mcp.json。示例中的 ${MYSQL_PASSWORD} 等變量依賴啓動客戶端時可用的環境變量；以客戶端實際規則為準。
  • VS Code 原生 MCP：使用 servers，放在 .vscode/mcp.json。示例密碼使用 VS Code 的密碼輸入提示，不是網站輸入框。
  • Cursor：放在 .cursor/mcp.json，使用 mcpServers。環境變量展開取決於客戶端版本，不要把未展開的佔位符當真實密碼。
  • 本擴展：原生 .mcp.json 由 CLI 發現；--strict-mcp-config 會限制來源。擴展讀取 VS Code 配置的功能不等於 VS Code 原生輸入變量解析，建議在本擴展中使用 Claude Code 格式。

配置文件已存在時，只合併需要的 server 條目，不要覆蓋整份配置。Windows 如無法直接啓動 npx，可使用本機 Node.js 的絕對路徑配合已安裝包入口，具體方式查看對應 npm 文檔。

04 / 先確認工具確實可用

  1. 檢查本機運行環境安裝受支持的 Node.js；SSH 包明確要求 Node.js 20+。其他包的實際要求以 npm 文檔為準。確認客戶端能找到 node / npx。
  2. 重新連接 MCP 或重啓對應 CLI保存配置後，在客戶端重新加載工具。本擴展中重啓對應一側 CLI 即可；確認沒有正在執行的重要任務。
  3. 從低影響的操作開始先讓客戶端列出工具並測試連接，再查看數據庫表結構、讀取 Redis 測試鍵，或對自有 API 發起 GET 請求。

可嘗試這樣描述任務：

第一個任務 · 示例提示詞
先檢查當前 MCP 工具是否可用。
只讀取測試數據庫的表結構，說明表之間的關係。
不要修改數據或結構；缺少連接或權限時先告訴我。

05 / 先設邊界，再加能力

最小權限

數據庫使用只讀或專用低權限賬戶；SSH 使用專用賬戶和可信主機指紋；API 先限制請求方法。提示詞和應用開關不能替代底層權限。

憑據留在本機

不要向此網站提交密碼或私鑰。配置文件可能含連接憑據，按需加入 Git 忽略規則；本地日誌和模型輸出在分享前也應檢查。

bypassPermissions 會跳過 CLI 的部分權限檢查，不表示 MCP 服務獲得了額外的數據庫或系統權限，也不能解決連接失敗。僅在明確可信的工作區使用。

06 / 沒有看到 MCP 工具？

  • 確認配置文件名稱、目錄與頂層字段匹配客戶端。
  • 確認配置 JSON 合法，包名正確，客戶端能找到啓動命令。
  • 檢查工作區信任、MCP 批准狀態、CLI 嚴格模式和工具開關。
  • 檢查數據庫 / SSH / API 地址、網絡、憑據和服務端權限。
  • 重啓對應 CLI 後查看輸出日誌，不要把整個含密鑰配置粘貼到公開渠道。
查看更多常見問題 ↗