跳至主要内容

連線自定義 MCP 工具

案例演示 透過本地 MCP 查詢公開 QC 表

本例透過小型本地 MCP 服務提供公開 RNA-seq QC 表。它讀取固定 CSV，提供兩個操作，不聯網、不安裝包、不修改資料。

閱讀平臺
選擇會在章節間保留。

下載真實示例​

儲存到本地並記下完整路徑。服務只用 Python 標準庫，啟動時讀取 CSV；替換輸入後應明確重啟/重連。

在應用中新增​

  1. Settings → Connectors → Add connector → Local command。
  2. Display name 填 GSE60450 QC。
  3. Command 選擇 python3 — script file；Windows 也可選擇 Other… 並填寫實際 Python 程式路徑。
  4. 展開 Advanced settings，名稱/ID 填 gse60450-qc，描述為只讀訪問 QC 表。
  5. Arguments 第一行寫指令碼絕對路徑，第二行寫 CSV 絕對路徑。每行是一個引數，路徑有空格也不要額外新增 Shell 引號。
  6. 本例 Environment 留空，檢查指令碼後勾選 I trust this connector，點選 Add。
  7. 搜尋 GSE60450，確認 Connected 及 Main Agent 可用性。

實際本地 MCP 配置

/absolute/path/qc-mcp-server.py
/absolute/path/rnaseq-sample-qc.csv

這是路徑模板，不能原樣貼上。若應用找不到 python3，選擇 Other 填實際直譯器路徑；啟動器必須在當前電腦存在。

工具輸入與實際輸出​

工具輸入實際內容
get_dataset_summary空物件GSE60450、來源 URL、檔名、12 行與完整樣本 ID
get_sample_qcsample_id 字串指定樣本的四個 QC 指標

可以請求：

Use the connected gse60450-qc Connector. Call get_dataset_summary, then get_sample_qc for MCL1-DG_BC2CTUACXX_ACTTGA_L002_R1. Report only actual responses and preserve the CSV.

本例中，原生應用返回該樣本總計數 23,227,641、零基因 8,664、檢出基因 18,515、中位數 237，彙總返回 12 行，與儲存的 QC 表一致。

成功連線的自定義 Connector

服務與錯誤行為​

指令碼透過 stdio 實現 MCP 初始化、ping、工具發現與呼叫，兩個工具結構都在下載原始碼中。標準輸出是協議通道，普通除錯列印可能破壞連線，診斷應寫入標準錯誤。

直接協議測試對 NOT_A_SAMPLE 返回了明確服務錯誤；同一負例在應用中顯示為 connector_unavailable。正常呼叫已驗證，業務錯誤的清晰傳遞沒有驗證透過，應保留區別。

不要把協議 tools/list 當業務工具交給 host.mcp。應用在連線時發現工具；嘗試 gse60450-qc/tools/list 實際被拒絕為 unknown tool。使用已發現的操作名，或檢查服務原始碼結構。

匯出與遷移​

選擇 Actions → Export，檢查格式與預覽。實際匯出提示兩個引數為本地路徑。Save configuration 只儲存配置，不包含 Python、指令碼或 CSV。單獨複製檔案、更新路徑、確認本地信任，再複測兩個正常操作。

失敗檢查
命令無法啟動直譯器、指令碼路徑及權限
CSV 不可讀第二引數和真實檔案位置
已連線但工具不可用Agent 分配、當前目錄和操作名
輸入錯誤必填 sample_id 和完整原始 ID，不使用繪圖短標籤替代
失敗後出現 Connector 錯誤檢查應用/服務詳情，按情況重連
終端可用、應用不可用應用可見環境及 stdout 是否只輸出協議

擴充套件時定義範圍明確的輸入，返回來源編號，驗證正常、空結果和錯誤輸入，讓使用者能檢查每次讀取或修改什麼。

實現依據: ConnectorAddForm.tsx, service.ts。

需要在指令碼中管理同一份自定義 MCP 配置時，使用 Connector CLI 或 SDK 方法。連線測試成功只證明工具發現，仍需單獨完成一個有邊界的業務呼叫。

最後於 更新