观达云建站 文章 MCP 接入指南适用对象:网站管理员、负责系统接入的技术人员或AI助手 无需了解接口详情、无技术基础的AI工具使用者,请参考另一篇文章:如何使用MCP 一、产品介绍观达云建站文章 MCP 为 AI 工具和业务系统提供文章查询、分类查询、新增文章及修改发布时间的能力。您可以在网站后台申请使用,开启 AI 接口开放后,通过支持远程 MCP 的客户端或自建程序接入。 例如,接入后可以向 AI 工具提出以下请求:
实际执行前,客户端需要根据工具参数补齐相应信息。新增文章和修改发布时间会改变站点内容,建议在客户端设置执行前确认。 二、能力范围
当前工具列表未提供文章删除或已有文章标题、正文编辑工具。请以实际 tools/list 返回结果为准。 三、开通与准备
注意:API Key 用于接口鉴权。请将其作为敏感凭证保管,不要放入公开文档、前端页面、代码仓库或公开截图。分享连接配置及排查日志前,应隐藏 URL 中的 key 值。 四、服务地址与鉴权4.1 MCP 接入地址将 <YOUR_API_KEY> 替换为您在后台获取的 API Key。key 通过 URL 查询参数传入;自行拼接 URL 时,应对参数值进行 URL 编码。 4.2 查询mcp能力说明该接口无需 API Key,可用于了解服务用途、鉴权方式和工具概要。它不返回完整的工具参数定义,也不代表您已获得站点操作权限。 获取完整工具定义(tools/list)和执行业务工具(tools/call)均需鉴权,且站点需开启 AI 接口开放。 五、在 AI 客户端中接入在客户端的 MCP 服务配置中,新增远程服务,并填写上述包含 API Key 的完整接入地址。各客户端的入口名称及配置格式可能不同,请参考您使用的客户端说明。 接入后,建议依次完成以下验证:
初次验证建议先使用查询工具。需要新增文章或修改发布时间时,再提供完整参数并确认执行。 六、技术接入流程以下内容供自建智能体客户端的技术人员参考。 6.1 请求地址与请求头以下请求均发送至: 服务可能通过 JSON 或 SSE(text/event-stream)返回数据。客户端应根据实际响应类型解析,不能假定每个响应都可以直接作为单个 JSON 对象读取。 6.2 初始化请求体: 初始化成功后,发送初始化完成通知。通知不包含 id: 本次接入验证中,初始化返回 HTTP 200,初始化完成通知返回 HTTP 202。若服务在初始化响应中返回 Mcp-Session-Id,后续请求应携带该会话标识。 6.3 获取工具定义工具定义位于 JSON-RPC 响应的 result.tools 中。每个工具提供 name、description 和 inputSchema。请使用 inputSchema 校验参数,并以服务实际返回的定义为准。 6.4 调用工具调用方法统一为 tools/call,使用 params.name 指定工具,使用 params.arguments 提供业务参数。 以下示例查询文章分类,不传入任何业务参数: 客户端应同时处理 HTTP 错误、JSON-RPC error,以及工具结果中可能出现的 isError。HTTP 200 本身不等于业务操作成功。 七、工具参数参考以下参数定义依据当前服务实际返回的 tools/list 整理。所有工具均设置 additionalProperties: false,请勿提交定义以外的参数。 7.1 查询文章:getNewsInfo按文章标题模糊查询文章列表,返回文章标题、摘要、详情及元数据。
调用示例: 当前工具参数未提供分页、排序或按文章 ID 查询选项。 7.2 查询文章分类:getNewsGroupList获取当前站点文章分类列表,包含未分类(id=0)。该工具无业务参数,arguments 传入空对象 {},完整示例见第 6.4 节。 新增文章前,可先使用此工具获取分类信息。 7.3 新增文章:addNews向站点新增一篇文章。
当前 Schema 将以上 12 个字段全部列为必填,客户端应完整提交。 字段必填表示不可省略,并不表示空字符串一定会被接受。 以下为参数结构模板,包含的占位符须按平台支持的业务规则替换,不能直接执行: 7.4 修改发布时间:updateNewsDate修改已有文章的发布时间。
以下为参数结构模板。12345 仅为示例文章 ID,执行前须替换为目标站点的实际文章 ID,并替换日期占位符: 该工具用于修改发布时间。不能仅根据工具名称推断其支持定时发布、下架或发布状态切换。 八、常见问题(1)返回 HTTP 401,如何处理?检查 URL 是否包含 key,参数值是否完整、有效,是否因复制、拼接或 URL 编码产生变化,并确认站点已开启 AI 接口开放。 鉴权失败的已观察响应示例: 客户端不要依赖 message 的固定文案判断错误,该提示可能调整。无需密钥的能力说明可访问 /capabilities。 (2)capabilities 可以访问,为什么 MCP 仍然调用失败?/capabilities 是公开的能力说明接口。它可以访问,不表示 API Key 有效,也不表示站点已开启 AI 接口开放。请使用带 key 的 MCP 地址完成初始化和工具列表查询。 (3)为什么工具列表响应中有 event: 和 data:?这表示响应使用了 SSE 格式。本次验证的 tools/list 响应采用该格式,JSON-RPC 消息位于事件的 data: 内容中。请使用支持相应传输方式的 MCP 客户端解析。 (4)文章分类 ID 可以传数组吗?当前 addNews.groupIds 的类型为字符串,不是数组。具体分类值及格式应遵循平台规则。 (5)新增请求超时后可以直接重试吗?建议先查询或在后台核对文章是否已新增,再决定是否重试,避免重复创建。当前工具定义未提供幂等键参数。 (6)工具参数发生变化怎么办?重新获取 tools/list,并根据最新 inputSchema 更新参数校验。本文记录的是上述更新日期对应的接口定义。 九、接入排查信息如需向平台技术方反馈问题,建议提供调用时间、工具名称、HTTP 状态码、请求id、脱敏后的参数及错误响应,便于定位。不要提交完整 API Key 或包含密钥的完整请求 URL。 |