語言EN繁
首頁
文件

SDK 教學 · 4 / 10

連接 MCP Server

當 capability 已經存在於 MCP server 後方時，就使用 MCP。產品端選擇並信任 server；Heddle 探索 catalog，並讓選定 tools 走過正常的 runtime、approval、trace 與 artifact 路徑。

客製化深度

層級 2 · 外部能力

託管深度

在 Node.js host 啟動時準備

文件狀態

可執行參考範例

前置假設

  • Node.js host 可以啟動或連線到受信任的 MCP server。
  • Host 在準備 extension 前已有耐久的 workspaceRoot 與 stateRoot。
  • 產品已決定哪些 MCP tools 應讓模型看見。
Heddle 負責
  • 重新整理 MCP catalog、把找到的 schema 轉成 Heddle tools，並把 calls 接到 approval 與 trace behavior。
  • 套用 include/exclude filter、名稱 override 與選用的 result-artifact capture。
  • 啟動失敗時回傳明確 preparation result、失敗 step 與安全的 error。
產品端負責
  • 選擇、安裝、設定並信任 MCP server 及其 operating-system permissions。
  • 提供 server 所需的環境變數、executable path、authentication 與 lifecycle policy。
  • 篩選 model-visible tool surface，並為每個實際動作定義產品 authorization。

建立 engine 前先準備 extension

使用解析完成的 host roots，並把範例 command 換成產品實際營運且受信任的 MCP server：

TypeScript
import { join } from 'node:path'
import {
  prepareMcpHostExtension,
  runQuickstartConversationCli,
} from '@roackb2/heddle'

const workspaceRoot = process.cwd()
const stateRoot = join(workspaceRoot, '.heddle')

const prepared = await prepareMcpHostExtension({
  id: 'document-operations',
  workspaceRoot,
  stateRoot,
  serverId: 'documents',
  server: {
    type: 'stdio',
    command: 'node',
    args: ['./dist/document-mcp-server.js'],
    cwd: workspaceRoot,
  },
  hideDefaultMcpTools: true,
  resultArtifacts: true,
  systemContext: 'Use document tools for drafting, validation, and export.',
})

if (!prepared.ok) {
  throw new Error(
    'MCP setup failed at ' + prepared.step + ': ' + prepared.error,
  )
}

await runQuickstartConversationCli({
  workspaceRoot,
  stateRoot,
  hostExtensions: [prepared.extension],
})

若是 embedded product，則把同一個 prepared.extension 傳給 createConversationEngine({ hostExtensions: [...] })。

篩選 model-visible surface

Preparation 預設會暴露 refreshed server catalog 中所有 enabled tools。請有意識地縮小範圍：

TypeScript
const prepared = await prepareMcpHostExtension({
  id: 'document-operations',
  workspaceRoot,
  stateRoot,
  serverId: 'documents',
  server,
  includeTools: ['create_document', 'validate_document'],
  excludeTools: ['delete_document'],
})
  • 用 includeTools 與 excludeTools 建立穩定、經過篩選的 surface。
  • 當同一個 server 可能同時出現在 raw MCP tools 與 curated host-tool names 時，設定 hideDefaultMcpTools: true。
  • 只有多個 servers 暴露相同名稱時才使用 toolNamePrefix。
  • 用 toolOverrides 調整 description、public name、capability tag 或 approval behavior。

擷取大型 MCP result

resultArtifacts: true 會掃描 generated text、HTML、JSON 與其他大型字串，把它們存成 artifact，並用精簡 reference 取代重複的 text/structured mirror。請先使用 boolean 設定；觀察真實 server result shape 後，才加入 threshold、path hint 或 manual rule。

安全邊界

MCP declaration 是 integration，不是 trust grant。本機 stdio server 會使用 host process user 的 operating-system permissions 執行。Tool call 抵達 server 前，先驗證並授權 product request，且讓 approval policy 與真實 side effects 保持一致。

失敗行為

Preparation 是明確的 startup work。請把 prepared.step 與 operational context 一起記錄；必要 server 無法準備時，deployment readiness 應失敗，避免無聲移除必要能力。不要把 server credential 或可能含 secret 的 raw diagnostics 洩漏給 browser client。

權威來源