/ 目錄 / 演練場 / concierge
● 社群 concierge-hq ⚡ 即開即用

concierge

作者 concierge-hq · concierge-hq/concierge

用於建構 MCP 伺服器的 Python SDK,讓工具只在相關時才出現——漸進式揭露、工作流程狀態管理,以及針對 100+ 工具 API 的語意工具搜尋。

Concierge 不是終端使用者用的 MCP,而是一個用來撰寫不會讓 LLM 不知所措的 MCP 伺服器框架。定義具有有序步驟的工作流程,每個步驟只暴露所需的工具,並在步驟間共享狀態。當工具數量過多時,可對工具目錄進行語意搜尋。

為什麼要用

核心特性

即時演示

實際使用效果

concierge.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "concierge": {
      "command": "uvx",
      "args": [
        "concierge"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "concierge": {
      "command": "uvx",
      "args": [
        "concierge"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "concierge": {
      "command": "uvx",
      "args": [
        "concierge"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "concierge": {
      "command": "uvx",
      "args": [
        "concierge"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "concierge",
      "command": "uvx",
      "args": [
        "concierge"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "concierge": {
      "command": {
        "path": "uvx",
        "args": [
          "concierge"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add concierge -- uvx concierge

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: concierge

將擁有大量端點(200+)的 REST API 包裝成 MCP,而不撐爆 context

👤 將內部 API 開放給 LLM 使用的平台工程師 ⏱ ~90 min advanced

何時使用: 貴公司的 API 有 300 個端點,而一個粗糙的 MCP 實作會將所有端點塞進系統提示,嚴重影響延遲與命中率。

前置條件
  • Python 3.9+ — pyenv / uv
  • OpenAPI 規格或端點清單 — API 閘道器 / Swagger
步驟
  1. 使用 concierge-sdk 建立專案骨架
    使用 concierge-sdk,建立一個 MCP 伺服器骨架,包裝位於 ./openapi.yaml 的 OpenAPI 規格。讓它使用語意搜尋,而非一次列出所有工具。✓ 已複製
    → 產生樣板程式碼與搜尋處理器
  2. 定義工作流程階段
    將端點分成 3 個工作流程:「讀取操作」、「建立操作」、「管理員」。每個工作流程只暴露自己的工具。✓ 已複製
    → 含有工具允許清單的工作流程定義
  3. 使用 Claude 進行測試
    將此伺服器連線至 Claude Desktop,並驗證列出工具時只顯示搜尋工具與當前工作流程的工具,而非全部 300 個。✓ 已複製
    → Claude 看到約 10 個工具,而非 300 個

結果: 大型 API 介面可供 LLM 使用,而不會因系統提示過長而崩潰。

注意事項
  • 當工具描述過於相似時,語意搜尋可能返回錯誤的工具 — 為每個工具撰寫獨特的單行描述;使用保留的查詢詞對搜尋進行測試

建構引導式多步驟工作流程(例如:客戶入會流程)

👤 建構結構化代理流程的開發者 ⏱ ~60 min advanced

何時使用: 您希望 LLM 遵循定義好的序列:收集資訊 → 驗證 → 建立記錄 → 通知。每個步驟都有自己的工具。

步驟
  1. 宣告工作流程
    定義一個名為 'customer_onboarding' 的 concierge 工作流程,包含步驟 [collect, validate, create, notify],每個步驟都有自己的工具集。✓ 已複製
    → 工作流程設定
  2. 共享狀態
    透過共享狀態將步驟 1 的 customer_data 字典傳遞到步驟 2、3、4。請示範做法。✓ 已複製
    → 狀態物件程式碼
  3. 處理失敗情況
    若驗證失敗,帶著具體的修正說明返回步驟 1。✓ 已複製
    → 重試/回溯邏輯

結果: 一個穩健的引導式流程,讓 LLM 保持在正軌上。

注意事項
  • LLM 嘗試跳過步驟 — Concierge 在工具可見性層級強制執行順序——如果您的接線正確,跳過步驟在物理上是不可能的

在 15 分鐘內發布您的第一個 MCP 伺服器

👤 剛接觸 MCP 的開發者 ⏱ ~15 min beginner

何時使用: 您想將 3-5 個函式開放給 Claude 使用,且不想學習原始 MCP 規格。

步驟
  1. 安裝並建立骨架
    pip install concierge-sdk。產生一個最小化伺服器,暴露兩個工具:add(a, b)greet(name)。使用 stdio 傳輸。✓ 已複製
    → 可運作的 Python 檔案
  2. 執行並連線
    加入至 Claude Desktop 設定,並測試兩個工具均可被呼叫。✓ 已複製
    → 工具呼叫在 Claude 中成功執行

結果: 一個您在一個下午就能從頭到尾完成的可運作 MCP 伺服器。

注意事項
  • 缺少型別提示——SDK 依賴型別提示來產生工具結構描述 — 務必為參數和回傳值加上型別標註——concierge 會從中產生 MCP 結構描述

組合

與其他 MCP 搭配,撬動十倍槓桿

concierge + gateway

將 concierge 建構的 MCP 部署在安全閘道器後方,以進行 PII 遮蔽

在 :8001 上啟動 concierge 伺服器,然後將其作為上游加入至 mcp-gateway,並啟用 Presidio 外掛。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
concierge.workflow(name) name, steps, initial_state 定義一個具名的多步驟流程 framework only
concierge.tool(workflow, step) step allowlist 將一個函式作為工具附加到一個或多個步驟的作用域中 framework only
concierge.search_tools query: str 當工具數量過多而無法全部列出時自動暴露 free
concierge.serve() transport: 'stdio'|'http'|'sse' 您的腳本進入點 free

成本與限制

運行它的成本

API 配額
無——您就是作者
每次呼叫 Token 數
取決於您的工具設計;漸進式揭露可將系統提示縮減 5-10 倍
費用
免費且開放原始碼
提示
不要急著暴露所有工具。從「搜尋」加上當前步驟的工具開始。只有在效能分析顯示 LLM 始終需要某些工具時,才將其加入急切暴露清單。

安全

權限、密鑰、影響範圍

憑證儲存: 您的 MCP 伺服器自行管理憑證——concierge 不強制規定模型
資料出站: 取決於您的工具呼叫的對象

故障排查

常見錯誤與修復

Tools not appearing in the expected step

檢查 @concierge.tool 上的 step 參數。帶有 step=['create'] 的工具在 collect 階段是不可見的。

驗證: Call the search_tools tool; if nothing returns, your allowlist is wrong
Semantic search returns no results

工具描述可能是空的。Concierge 從 docstring 建立嵌入向量——請務必填寫。

Workflow state lost between calls

Concierge 的狀態是工作階段範圍的。請確保您的客戶端具有黏性(在所有呼叫中使用同一個 MCP 工作階段)。

替代方案

concierge 對比其他方案

替代方案何時用它替代權衡
fastmcp (Python)您想使用最流行的 Python MCP SDK,但不需要漸進式揭露功能更輕量,但沒有內建的工作流程/工具閘控功能
Official MCP Python SDK您想要零框架、最貼近規格的實作需要更多樣板程式碼;閘控邏輯需自行建構
TypeScript MCP SDK您的技術堆疊是 TS/Node語言不同;目前沒有直接對應的 concierge 替代方案

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills