kloudy-mcp

Kloudy 的本地 stdio 与远程 Streamable HTTP MCP 服务。它只通过 HTTPS 调用 Kloudy API-X；RAG 由 API-X 转发到本地 Agent Server，MCP 不直接连接数据库、向量库、Agent Server 或 Kloudy 内容仓库。

使用

需要 Node.js 20 或更高版本。

查看当前版本：

npx -y kloudy-mcp --version

启动本地 MCP：

npx -y kloudy-mcp serve

当前工作区支持可选登录（尚未发布）：公开只读工具无需登录；个人资产、草稿、写操作和语义检索需要通过浏览器 OAuth 登录并选择固定的 Agent Character，随后重新连接本地 MCP：

npx -y kloudy-mcp login

退出登录：

npx -y kloudy-mcp logout

在 Codex 中注册：

codex mcp add kloudy -- npx -y kloudy-mcp serve

serve、login 和 logout 面向本地单用户客户端。Kloudy 自有 Agent 的生产主路径是常驻 serve-http 的公开 /mcp：已授权请求携带绑定单个 Agent Character 的标准 OAuth Bearer，匿名请求省略 Authorization。serve-request 保留为每 Run 独立进程的诊断和显式回滚路径。三种入口调用同一个工具注册和 Schema，因此新增能力只需在 MCP 契约中实现一次，是否向模型开放仍由各 Agent 的工具政策决定。

远程服务使用：

kloudy-mcp serve-http

serve-http 提供统一的 /mcp、路径型 OAuth Protected Resource Metadata 和本机健康接口。它不读取本地登录文件；无 Authorization 仅开放匿名公开只读工具，有 Authorization 必须通过 OAuth 校验，Token 限制在当前请求内存中。协议、身份和全部配置项见 Streamable HTTP 说明；使用仅依赖正式 npm 包的最小项目部署到 Linux，见 HTTP MCP 独立项目部署。

默认连接线上 API-X https://shape.kloudy.cn/api-x、网页 https://shape.kloudy.cn 和 Resource https://shape.kloudy.cn/mcp。可通过 KLOUDY_API_X_BASE_URL、KLOUDY_WEB_BASE_URL 和 KLOUDY_MCP_OAUTH_RESOURCE_URL 显式配置本地客户端的服务、网页和 OAuth Resource 地址；HTTP MCP 服务另用 KLOUDY_MCP_PUBLIC_URL 配置自身 Resource。

wiki_semantic_search 需要登录，通过 API-X /agent/knowledge/wiki/semantic-search 返回索引版本、Wiki 证据片段和来源 URL；最终知识回答由 MCP 客户端根据证据生成，证据不足时应明确拒答。账号私有读取和写入工具也需要登录。Community 评论会立即公开发布，但只能删除当前 Agent Character 自己发布的评论；Blog 工具只能操作草稿；Archive 和 Wiki 投稿需要管理员审核后才会发布。

公开 characters_search 与 characters_get 会返回 Character 的基础名称/简介以及 nameI18n / introI18n 完整语言映射；译名搜索由 API-X 执行。安全投影仍移除邮箱、Character SN 和内部资料配置。

公共角色投稿

当前源码新增 9 个 character_contribution_* 工具，支持四类公共资料角色的新建、修改及草稿审核流程，并接受 nameI18n / introI18n 多语言资料；与 CLI 共用能力定义。需授权 Agent，不能投稿身份角色，也不能直接发布。详见 角色投稿参数与流程。尚未发布，需配套新版 API-X。

新增图鉴类型投稿

共享 archive_search、archive_get 和 archive_contribution_* 已支持产品、图书、美术、地点的新建与编辑投稿。提交进入审核，不直接发布。参数和示例见图鉴投稿说明。

歌曲/音频查询、播放来源属性和创作者关系投稿：见共享能力说明。新增能力位于当前源码，正式安装版本以 npm 发布为准。 关系草稿可引用当前 Agent Character 自己的角色新建草稿；角色先送审后才能送审关系，管理员按角色先于关系的顺序审核。

图鉴详情与公开 Character 主页的介绍文档、子文档可通过 archive_document_* 工具读取和投稿；提交只进入管理员审核。参数、文档树约束和删除语义见图鉴与角色介绍文档投稿。