three.ws Concierge

@three-ws/concierge-mcp

通过任意 AI 助手，向任意网站的 AI 礼宾助手提出有依据的问题，并生成可添加到网站的嵌入代码。

---

一个 Model Context Protocol 服务，让任意 AI 助手都能通过 stdio 使用 three.ws Concierge，这是一款可嵌入的网站 AI 聊天组件，带有会说话的 3D 头像。

提供三个工具：

工具	功能	网络
concierge_ask	向网站的 AI 礼宾助手提问。提供 url 后，它会抓取页面，并根据真实内容（标题、标题层级、导航、正文）作答，让你能够向任意网站提问。也可以传入 knowledge/content，根据已有文本作答。	免费的 three.ws 通道 + 抓取 URL
concierge_embed	生成可直接粘贴的嵌入代码，为网站添加 Concierge：可以是单标签 <script>、<three-concierge> Web 组件、npm 代码片段或命令式 mount() 调用，并可配置强调色、头像、问候语、精选知识和推荐提示词。	离线
concierge_avatars	列出 Concierge 可使用的绑定骨骼 3D 头像。	离线

无需 API 密钥、签名者或付费。concierge_ask 使用公开的免费 POST /api/concierge 答案通道运行；另外两个工具则是纯本地生成器。

安装

npm install @three-ws/concierge-mcp

也可以使用 npx 运行（无需安装）：

npx @three-ws/concierge-mcp

快速开始

Claude Code，一行命令：

claude mcp add concierge -- npx -y @three-ws/concierge-mcp

Claude Desktop / Cursor（claude_desktop_config.json 或 mcp.json）：

{
	"mcpServers": {
		"concierge": {
			"command": "npx",
			"args": ["-y", "@three-ws/concierge-mcp"]
		}
	}
}

使用 MCP Inspector 检查可用功能：

npx -y @modelcontextprotocol/inspector npx -y @three-ws/concierge-mcp

用途

根据网站的真实内容向任意网站提问：

使用 concierge_ask，根据 https://example.com/pricing 回答“Pro 套餐包含什么？”

服务会抓取页面、提取可读文本，并将其发送给礼宾助手的答案引擎，返回的答案会遵循不编造页面未提及内容的原则。

根据已有文本提问（无需 URL）：

concierge_ask：question = "退款期限是多久？"，knowledge = "接受 30 天内的退货。"

为网站生成可直接复制粘贴的嵌入代码：

使用 concierge_embed，siteName 为 "Acme"，accent 为 "#f97316"，avatar 为 "nova"，suggestions 为 ["What is Acme?", "Pricing?"]，flavor 为 "script"

返回可直接添加到网站 HTML 中的准确 <script> 标签。

先选择头像：

concierge_avatars → 然后在 concierge_embed 的 avatar 参数中使用你喜欢的头像 ID

工具详解

concierge_ask

只读、开放世界。

参数	类型	说明
question	string（必填）	用自然语言提出的问题。
url	string（url）	用于为答案提供依据的页面。会抓取并提取内容。
siteName	string	显示名称；省略时会根据页面推断。
knowledge	string	精选的权威事实。优先于抓取的文本。
content	string	未传入 url 时，用于提供依据的原始文本。
persona	string	回复语气说明。
lang	string	BCP-47 提示，例如 en、es。

必须至少提供 url、knowledge 或 content 之一。返回 { ok, question, answer, grounded_in, provider, model, endpoint }。

concierge_embed

只读、幂等、离线。

关键参数：siteName、flavor（script | web-component | npm | imperative | all，默认值为 all）、accent、avatar、customAvatar、position、theme、greeting、persona、knowledge、suggestions[]、endpoint、muted、open、noPicker、noTeaser、lang。返回 { ok, flavor, snippets, applied_config, docs }。script、web-component 和 imperative 代码片段都是可直接粘贴的纯 HTML（会加载 CDN 全局构建版本）；npm 代码片段适用于使用打包器的用户。

concierge_avatars

只读、幂等、离线。无参数。返回 { ok, default, count, avatars, note }，每个头像都包含 id、name、tagline、style 和 framing。

配置

所有可选环境变量：

变量	默认值	用途
THREE_WS_BASE	https://three.ws	答案调用的 API 来源，以及嵌入代码片段指向的来源。
THREE_WS_TIMEOUT_MS	45000	Concierge 答案的超时时间（可能会在不同 LLM 提供方之间故障转移）。
CONCIERGE_PAGE_TIMEOUT_MS	12000	concierge_ask 中抓取页面的超时时间。

错误

工具调用失败时，会返回 MCP 错误结果（isError: true），其文本为一个 JSON 对象：{ "ok": false, "error": "<code>", "message": "…" }；上游拒绝请求时还会包含 status：

error	含义	处理方式
bad_request	参数错误：concierge_ask 未提供 url/knowledge/content、url 不是 http(s) 地址，或 avatar id 未知。	修正调用。
unsupported_media	抓取的 url 不是 HTML/文本页面。	指向可读取的页面，或传入 content。
upstream_error	答案端点拒绝了请求；status 包含 HTTP 状态码（429 = 免费通道的 IP 速率限制）。	根据 status 处理；遇到 429 时降低请求频率。
stream_error	答案流在完成前失败。	重试。
timeout	在 THREE_WS_TIMEOUT_MS 内未获得答案，或页面抓取耗时超过 CONCIERGE_PAGE_TIMEOUT_MS。	重试或延长超时时间。
network_error	请求未能到达 API（DNS、离线、TLS）。	检查网络连接和 THREE_WS_BASE。
bad_config	THREE_WS_TIMEOUT_MS 不是正数。此错误会在服务启动时（加载模块时）抛出，因此进程会在开始提供服务前退出。	修正环境变量。

与小组件的关系

此服务是浏览器小组件 @three-ws/concierge 面向 Agent 的一侧。两者使用相同的答案引擎、头像目录和依据模型，并将其作为 MCP 工具公开，让助手可以使用网站的 Concierge 或安装一个，而不仅仅是供人类访客使用。

• 小组件和文档：three.ws/concierge
• 参考文档：three.ws/docs/concierge
• 构建教程：three.ws/docs/tutorials/build-a-site-concierge

开发

npm test    # node --test, offline (registration, harvest, embed, SSE parsing)
npm start   # run the server over stdio

针对运行中的 three.ws 进行实时端到端检查（test/_manual-e2e.mjs），通过真实的 stdio 客户端调用全部三个工具；运行方法请参阅文件头部。

许可证

Apache-2.0。参见 LICENSE。可免费调用公开的 three.ws API。