Weav

Weav.com Model Context Protocol (MCP)

了解如何使用 Model Context Protocol (MCP)，让 AI Agent 安全地访问和交互您的 Weav 工作区。

Weav 工作区可使用 Weav MCP 服务。

本仓库介绍的是 工作区 服务（com.weav/mcp，地址为 https://mcp.weav.com/mcp）。另有一个独立的公共服务，无需登录即可回答定价和产品相关问题：

服务	URL	身份验证	注册表
Weav（本仓库）	https://mcp.weav.com/mcp	OAuth	com.weav/mcp
Weav 客户服务	https://weav.com/mcp	无	io.github.dubdubdubco/weav-customer-service

公共服务无法读取收件箱、客户、培训数据或帮助中心数据。来源：dubdubdubco/weav-site-mcp。

什么是 Model Context Protocol？

MCP 是一种协议，可让 AI 工具和应用以安全、标准化的方式连接 Weav 的数据和服务。它为 AI 模型提供了一种结构化方法，用于：

• 查找和检索 Weav 数据（对话、客户、Agent 培训数据、帮助中心文章）
• 使用 Weav 提供的特定工具和功能
• 使用 AI 助手时保留有关您的 Weav 工作区的上下文

MCP 如何工作

Weav 托管的远程 MCP 服务遵循经过身份验证的远程 MCP 规范（文档）。此服务负责处理 AI 工具发出的请求，并通过安全接口提供对 Weav 数据的访问。

连接 URL：

• 可流式传输的 HTTP：https://mcp.weav.com/mcp

当 AI 工具或应用需要访问 Weav 数据时：

1. 工具连接到 Weav 的 MCP 服务
2. 工作区管理员或所有者在浏览器中完成 OAuth 授权
3. 随后，工具即可访问该工作区的相关 Weav 数据和功能
4. 连接会一直保持，直到被撤销

使用 MCP 的优势

• 安全访问：所有数据访问均经过身份验证和授权。只有工作区管理员或所有者才能完成授权。
• 标准化接口：不同 AI 工具采用一致的交互方式
• 上下文理解：AI 助手能够了解您的 Weav 收件箱、客户、Agent 培训数据和帮助中心
• 提高开发效率：通过您已在使用的 AI 工具，对对话进行分类处理、回复客户，以及管理 Agent 培训数据和帮助中心文章

可用工具

Weav MCP 服务提供 37 个工具，用于与您的工作区交互：4 个对话工具、2 个客户工具、5 个 Agent 培训数据工具，以及 26 个帮助中心工具。

对话

search_conversations

像在 Weav 收件箱中一样搜索支持对话。

主要功能：

• 匹配主题、客户姓名或电子邮件地址
• 仅返回至少包含一条消息的对话
• 除非 spam 为 true，否则排除垃圾信息
• 可选筛选条件：status（open、closed）、channel（email、chat）、limit（1–50）

get_conversation

获取对话，包括近期消息。

主要功能：

• 使用 search_conversations 返回的对话 UUID
• 返回对话元数据和近期消息记录

send_reply

以工作区团队成员的身份向对话发送回复。

主要功能：

• 必须提供 conversation_id 和 content
• 在已连接的工作区中发送回复

update_conversation

更新对话的状态、优先级或受派人。不会删除对话。

主要功能：

• status：open 或 closed
• priority：low、normal、high 或 urgent
• assignee_id 加上 assignee_type（user 或 agent）；省略则保持不变，发送 null 则取消分派

客户

search_customers

按姓名或电子邮件地址搜索客户。

主要功能：

• 可选的 query 和 limit（1–50）

get_customer

获取客户资料、公司信息和近期对话。

主要功能：

• 使用 search_customers 返回的客户 UUID

Agent 训练数据

这是 Weav AI Agent 回答所依据的来源，与由 kb_* 工具管理的公开帮助中心相互独立。

search_training_data

按标题、描述、类型或来源搜索 Agent 训练数据条目。

主要功能：

• 可选的 type 筛选器：text、url、file、video、qa
• 可选的 limit（1–50）

get_training_data

获取单条训练数据。

主要功能：

• 使用 search_training_data 返回的训练数据 UUID

add_training_data

以文本、问答或网站 URL 的形式添加 Agent 训练数据。工作区中的每个 Agent 都会自动获得访问权限。

主要功能：

• type：text、qa 或 url
• url 会抓取网站，并根据发现的页面进行训练
• urls 仅根据列出的页面进行训练，不会抓取网站的其余部分

delete_training_data

删除训练数据条目。

主要功能：

• 对于网站/URL 来源，也会删除发现的 URL 和内容块

resync_training_data

重新抓取现有的 URL 训练数据条目。

主要功能：

• 需要提供 URL 来源的训练数据 UUID

帮助中心知识库

kb_* 工具用于管理工作区的公开帮助中心文章和分类，与由 *_training_data 管理的 Agent 训练数据相互独立。

浏览

kb_get_overview

获取帮助中心的数量统计和可用语言区域。

主要功能：

• 无参数
• 包含按显示顺序排列的分区

kb_list_categories

列出帮助中心分类。

主要功能：

• 可选的 limit（1–50，默认值为 20）和 page（默认值为 1）

kb_list_sections

按显示顺序列出帮助中心分区。

主要功能：

• 可选的 limit（1–50，默认值为 20）和 page（默认值为 1）

kb_list_articles

列出帮助中心文章摘要。

主要功能：

• 可选筛选器：category_id 或 uncategorized、status（draft、published）和 locale
• 可选的 limit（1–50，默认值为 20）和 page（默认值为 1）

kb_search_articles

搜索帮助中心文章标题和内容。

主要功能：

• 必填的 query（1–255 个字符）
• 可选筛选器：locale、status（draft、published）、category_id 或 uncategorized
• 可选的 limit（1–50，默认值为 20）和 page（默认值为 1）

kb_get_article

获取完整的帮助中心文章及其翻译内容。

主要功能：

• 必填的 article_id；可选的 locale

修订版本

kb_list_article_revisions

列出文章的修订版本摘要。

主要功能：

• 必填的 article_id；可选的 locale、limit（1–50，默认值为 20）和 page（默认值为 1）

kb_get_article_revision

获取修订版本的完整内容。

主要功能：

• 必填的 article_id 和 revision_id

kb_restore_article_revision

从先前的修订版本恢复文章翻译。

主要功能：

• 必填的 article_id 和 revision_id；可选的 expected_version
• 恢复前会将当前翻译保存为修订版本

改进提案（只读）

kb_list_proposals

列出帮助中心的改进提案。

主要功能：

• 可选的 status（pending、needs_decision、published、dismissed、ignored）；默认会省略已忽略的提案
• 可选的 limit（1–50，默认值为 20）和 page（默认值为 1）

kb_get_proposal

获取改进提案的完整详情。

主要功能：

• 必填的 proposal_id

文章

kb_create_article

创建帮助中心文章。

主要功能：

• 至少需要一个包含 locale、title 和 Markdown content 的 translations 条目；excerpt 和 slug 为可选项
• excerpt 也用作元描述
• 翻译条目可选接受 seo_title（搜索/社交标题；页面标题仍为 title）、noindex（对搜索引擎隐藏）、canonical_url（绝对 HTTP(S) URL）和 og_image_url（HTTPS 社交预览图片）
• category_id、position 和 status（draft 或 published）均为可选项

kb_update_article

更新帮助中心文章。

主要功能：

• 必需参数为 article_id；expected_version、category_id、position、status 和 translations 均为可选项
• 翻译条目接受与 kb_create_article 相同的可选 SEO 字段；excerpt 也用作元描述
• 发送 category_id: null 可取消分类；省略该参数则保留当前分类
• 编辑现有语言的内容会保存修订版本；仅编辑 SEO 字段不会。新增语言需要提供 title 和 content

kb_publish_article

立即发布文章。

主要功能：

• 必需参数为 article_id；expected_version 为可选项

kb_unpublish_article

将已发布的文章恢复为草稿。

主要功能：

• 必需参数为 article_id；expected_version 为可选项

kb_delete_article

软删除帮助中心文章。

主要功能：

• 必需参数为 article_id；expected_version 为可选项

kb_delete_article_translation

删除文章的一种翻译。

主要功能：

• 必需参数为 article_id 和 locale；expected_version 为可选项
• 文章必须至少保留一种翻译

kb_reorder_articles

设置一个分类组中所有文章的顺序。

主要功能：

• 必需参数 ids，包含按所需顺序排列的所有文章 UUID
• category_id 为可选项；省略该参数或发送 null，表示未分类文章

版块

kb_create_section

创建帮助中心版块。

主要功能：

• 必需参数为 name；slug 和 position 为可选项

kb_update_section

更新帮助中心版块。

主要功能：

• 必需参数为 section_id；name、slug 和 position 为可选项

kb_delete_section

删除帮助中心版块。

主要功能：

• 必需参数为 section_id；其分类将变为未分配版块

kb_reorder_sections

设置所有帮助中心版块的显示顺序。

主要功能：

• 必需参数 ids，包含按所需顺序排列的所有版块 UUID

分类

kb_create_category

创建帮助中心分类。

主要功能：

• 必需参数为 name；slug、position 和 section_id 为可选项

kb_update_category

更新帮助中心分类。

主要功能：

• 必需参数为 category_id；name、slug、position 和 section_id 为可选项
• 发送 section_id: null 可清除版块分配

kb_delete_category

删除帮助中心分类。

主要功能：

• 必需参数为 category_id；其文章将变为未分类

kb_reorder_categories

设置所有帮助中心分类的显示顺序。

主要功能：

• 必需参数 ids，包含按所需顺序排列的所有分类 UUID

帮助中心行为

• 新文章默认是草稿。创建或更新时设置 status: published，或使用 kb_publish_article，即可立即发布；无需审核。
• 先使用 kb_search_articles 搜索；更新现有文章，而不是创建重复文章。
• kb_get_article 会返回一个 version。更新、发布、取消发布、删除、删除译文或恢复时，将其作为 expected_version 传入。版本过期时会返回 PRECONDITION_FAILED 和 current_version；请重新读取并重试。如果在等待期限内无法获取文章锁，工具会返回 ARTICLE_LOCKED；请稍后重试。其他错误代码包括 SLUG_TAKEN。
• 本地语言按语言匹配：en、en-US 和 en-GB 都会匹配英文内容。
• 通过 MCP 创建的文章，其来源为 mcp；每个修订版本都会记录执行操作的用户和 MCP 客户端。
• 通过 MCP 无法设置帮助中心、上传徽标和图片、同步 GitHub，也无法发布或驳回改进提案；请使用 Weav 应用。

设置

身份验证

MCP 服务使用 OAuth。连接时，Weav 会打开浏览器授权页面。

• 只有工作区的 管理员 或 所有者 才能完成授权
• 令牌的作用范围仅限于该工作区，并具有 mcp:use 权限
• 管理员之后可以在 设置 → 开发者 → MCP 连接 中断开客户端

没有 API 令牌或 Bearer 令牌的快捷方式。请通过 OAuth 连接。

配置示例

配置指南 以下示例是通用模板。请始终参考 LLM 提供商的官方文档，以获取最新配置说明，因为设置细节可能因版本和提供商而异。

对于 OAuth 身份验证：

{
  "mcpServers": {
    "weav": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.weav.com/mcp"
      ]
    }
  }
}

必需的权限范围

Weav MCP 服务会签发具有 mcp:use 权限范围的令牌。工作区管理员或所有者完成授权后，即会授予此权限范围。

MCP-Remote 调试与故障排除

1. 身份验证问题

# Kill existing connections
pkill -f mcp-remote

# Clear MCP auth cache
rm -rf ~/.mcp-auth

2. 连接测试

# Test direct connection (starts the OAuth browser flow)
npx mcp-remote https://mcp.weav.com/mcp

3. 查看活动 MCP 连接

ps aux | grep mcp-remote | grep -v grep

错误处理

• 身份验证失败：重新启动 OAuth 流程。确认工作区管理员或所有者已完成授权。
• 401 Unauthorized：访问令牌缺失、已过期，或连接已在设置中撤销。
• PRECONDITION_FAILED：自传入 expected_version 后，文章已发生更改；请重新读取文章，并使用 current_version 重试。
• ARTICLE_LOCKED：等待文章锁超时；请稍后重试。
• 工具错误：确认传入的 ID 属于已连接的工作区。

故障排除提示

• 配置更改后，重新启动 AI Agent
• 确认 URL 为 https://mcp.weav.com/mcp（包括 /mcp）
• 检查浏览器中是否有 OAuth 授权错误
• 如果客户端卡住，请在 设置 → 开发者 → MCP 连接 中断开并重新连接