/ 目录 / 演练场 / concierge
● 社区 concierge-hq ⚡ 即开即用

concierge

作者 concierge-hq · concierge-hq/concierge

构建 MCP server 的 Python SDK,工具按需显示,支持渐进式公开、工作流状态管理和语义工具搜索,可处理 100+ 个工具 API。

Concierge 不是终端用户 MCP,而是用于编写 MCP server 的框架,能防止 LLM 被过多工具所淹没。定义有序的工作流步骤,每个步骤仅公开必需的工具。在步骤间共享状态。工具超过可列出范围时,可对工具目录进行语义搜索。

为什么要用

核心特性

实时演示

实际使用效果

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

将大型 REST API(200+ 端点)包装为 MCP,无需担心上下文限制

👤 向 LLM 公开内部 API 的平台工程师 ⏱ ~90 min advanced

何时使用: 你公司的 API 有 300 个端点,如果天真地将所有端点都放进系统提示,会破坏延迟和命中率。

前置条件
  • Python 3.9+ — pyenv / uv
  • OpenAPI 规范或端点目录 — 你的 API 网关 / Swagger
步骤
  1. 使用 concierge-sdk 构建脚手架
    使用 concierge-sdk 为我的 OpenAPI 规范 ./openapi.yaml 构建一个 MCP server 脚手架。让它使用语义搜索而不是一开始就列出所有工具。✓ 已复制
    → 样板代码 + 搜索处理器
  2. 定义工作流阶段
    将端点分组为 3 个工作流:'读操作'、'创建操作'、'管理'。每个工作流仅公开自己的工具。✓ 已复制
    → 带有工具允许列表的工作流定义
  3. 使用 Claude 测试
    将 Claude Desktop 连接到这个 server,验证工具列表仅显示搜索工具 + 当前工作流工具 — 不是全部 300 个。✓ 已复制
    → Claude 看到约 10 个工具,而不是 300 个

结果: 一个大型 API 可被 LLM 使用,而不会导致系统提示长度溢出。

注意事项
  • 当描述过于相似时,语义搜索返回错误的工具 — 编写具有区分度的单行工具描述;用保留查询测试搜索

构建引导式多步工作流(例如客户入职)

👤 构建结构化 agent 流的开发者 ⏱ ~60 min advanced

何时使用: 你希望 LLM 遵循定义的序列:收集信息 → 验证 → 创建记录 → 通知。每个步骤有自己的工具集。

步骤
  1. 声明工作流
    定义一个 concierge 工作流 'customer_onboarding',包含步骤 [collect, validate, create, notify],每个步骤都有自己的工具集。✓ 已复制
    → 工作流配置
  2. 共享状态
    通过共享状态将 customer_data 字典从步骤 1 传入步骤 2、3、4。给我展示一下怎么做。✓ 已复制
    → 状态对象代码
  3. 处理失败
    如果验证失败,返回步骤 1 并指出具体需要修复的地方。✓ 已复制
    → 重试/回退逻辑

结果: 一个健壮的引导流程,让 LLM 保持在正轨上。

注意事项
  • LLM 尝试跳过步骤 — Concierge 在工具可见性层面强制执行顺序 — 如果你正确设置,跳过在物理上是不可能的

在 15 分钟内交付你的第一个 MCP server

👤 MCP 新手开发者 ⏱ ~15 min beginner

何时使用: 你想向 Claude 公开 3-5 个函数,不想学习原始 MCP 规范。

步骤
  1. 安装和构建脚手架
    pip install concierge-sdk。生成一个最小的 server,公开两个工具:add(a, b)greet(name)。使用 stdio 传输。✓ 已复制
    → 有效的 Python 文件
  2. 运行并连接
    添加到 Claude Desktop 配置并测试两个工具都可以调用。✓ 已复制
    → 工具调用在 Claude 中成功

结果: 一个你从头到尾在一个下午内编写的有效 MCP server。

注意事项
  • 缺少类型提示 — SDK 依赖它们生成工具模式 — 始终给参数和返回值添加类型 — concierge 从它们生成 MCP 模式

组合

与其他 MCP 搭配,撬动十倍杠杆

concierge + gateway

在安全网关后面运行 concierge 构建的 MCP,用于 PII 脱敏

在 :8001 启动 concierge server,然后使用 Presidio 插件将其作为 mcp-gateway 的上游添加。✓ 已复制

工具

此 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 倍
费用
免费开源
提示
不要主动公开每一个工具。从 'search' + 当前步骤工具开始。仅当分析显示 LLM 总是需要这些工具时,才添加主动公开的工具。

安全

权限、密钥、影响范围

凭据存储: 你的 MCP server 处理自己的凭据 — concierge 没有强制要求特定模型
数据出站: 取决于你的工具调用的内容

故障排查

常见错误与修复

工具未在预期步骤中显示

检查 @concierge.tool 上的 step 参数。一个带有 step=['create'] 的工具在 collect 期间是不可见的。

验证: 调用 search_tools 工具;如果没有返回任何内容,你的允许列表有问题
语义搜索未返回结果

工具描述可能为空。Concierge 从文档字符串构建嵌入 — 填写它们。

工作流状态在调用间丢失

Concierge 状态是会话作用域。确保你的客户端是粘性的(同一 MCP 会话在多个调用间)。

替代方案

concierge 对比其他方案

替代方案何时用它替代权衡
fastmcp (Python)你想要最流行的 Python MCP SDK,但不需要渐进式公开功能更轻量级,但没有内置工作流/工具门控功能
Official MCP Python SDK你想要零框架,最接近规范更多样板代码;你自己构建门控
TypeScript MCP SDK你的堆栈是 TS/Node不同的语言;没有直接的 concierge 等价物

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills