非官方Cosmos.so MCP：让AI读取设计素材库的完整指南

你是一名设计师或者是一名经常和设计素材打交道的开发者。你的工作流大概是这样的把品牌参考、竞品截图、海报灵感、情绪板全部整理在 Cosmos.so 里分类成 Space 和 Collection。某天你想让 AI 助手帮你从素材库里找出去年某个项目的三张主视觉或者按品牌色把旧素材重新归档。结果你发现无论怎么提示AI 都只能回答一句“我无法访问你的 Cosmos 数据”。这不是 AI 不够聪明而是 AI 和数据之间缺了一条通道。最近频繁出现的 MCP 协议就是专门解决这个问题的。而 Cosmos.so 这类垂直工具目前并没有推出官方 MCP Server所以社区环境里出现了“Unofficial Cosmos.so MCP”这样的非官方项目。这篇文章我想讲清楚三件事MCP 到底是什么为什么会有人做一个非官方的 Cosmos.so MCP以及作为开发者你该怎么评估、配置甚至在必要的时候自己写一个这样的 MCP Server。如果你正在做设计资产库、知识库或其他垂直数据系统的 AI 接入这篇文章可以给你一套完整的参考思路。我给出的核心判断是Unofficial Cosmos.so MCP 的价值不在于“现在就能用”而在于它示范了一类非常重要的模式——把任意垂直领域的数据系统以标准协议的方式接进 AI 工作流。你掌握了这个模式今天接的是 Cosmos明天接的可能就是公司的私域素材库。1. 先搞清楚两个概念Cosmos.so 和 MCP1.1 Cosmos.so设计师的视觉资产管理平台Cosmos.socosmos.so是一个面向设计师和创意团队的视觉书签与素材管理工具。你可以把网页、图片、视频、品牌 VI、字体、色彩方案等内容统一收藏起来并通过 Space 和 Collection 进行组织和分享。它解决的问题和 Pinterest 有重叠但更偏向专业工作流适合做品牌调研、竞品分析、情绪板和团队灵感库。从产品形态上看Cosmos.so 首先是一个收集工具其次是一个整理工具最后是一个展示和协作工具。很多设计团队把它当作“团队的视觉记忆库”因为相比本地图片文件夹它支持快速检索、标签分类、团队共享和跨设备访问。不过这类工具的短板也很明显数据被封闭在产品内部外面的程序很难访问。过去如果你想用脚本批量读取 Cosmos 里的素材只能依赖它是否提供开放的 API或者去抓取内部接口。而现在借助 MCP 协议AI 客户端终于有机会以标准化的方式读取这些数据。1.2 MCPAI 与应用之间的 USB 接口MCPModel Context Protocol模型上下文协议是 Anthropic 在 2024 年末提出的开放协议目标很直接让 AI 应用能够以统一的标准连接外部数据和工具。你可以把 MCP 理解为“AI 世界的 USB-C 接口”——过去每个设备都要专门的线现在大家统一用同一个标准插上就能通信。在 MCP 的架构里有两个核心角色MCP ClientAI 应用这一端比如 Claude Desktop、Cursor、Trae或者其他支持 MCP 的智能体平台。MCP Server负责连接具体数据源或工具服务的一端可以访问本地文件、数据库、第三方 API并提供给 AI 调用。两者之间通过一套标准的 JSON-RPC 消息协议通信传输方式可以是本地进程的 stdio也可以是 HTTP 或 SSE。这样带来的结果就是同一个 MCP Server可以被多个不同的 AI 客户端复用同一个 AI 客户端也可以同时挂载几十个不同的 MCP Server。这也是为什么最近“MCP server”“MCP 工具”“.mcp 文件”这些词频繁出现在技术社区里。从 Figma MCP、蓝湖 MCP到数据库、浏览器、设计稿工具各种 MCP Server 像雨后春笋一样冒出来。1.3 MCP 和普通 API 封装、Agent Skill 有什么区别很多读者看到这里会问这不就是把 API 包一层吗确实MCP Server 底层很可能就是调用某个 API但它和普通 API 封装的差别在于标准层的位置。普通 API 封装是“每个 AI 应用自己定义工具格式”Agent 端要逐个适配MCP 则统一了工具描述、参数校验、调用协议和结果返回格式。一个 MCP Server 写好后Claude、Cursor、其他智能体平台都能直接识别。它提供的“工具查找、参数说明、资源发现”能力也让 AI 在不确定时主动去询问 Server 有哪些能力而不是靠人写死 prompt。另外MCP 和最近同样热门的概念 Agent Skill 不是一回事。Agent Skill 通常指一组指令、模板或者工作流技能告诉 AI 怎么思考和执行MCP 则偏数据访问和工具执行通道。两者可以配合但解决的问题层级不同。2. 为什么会出现 Unofficial Cosmos.so MCP2.1 官方缺位社区补位先说一个背景不是每个 SaaS 产品都会第一时间跟进 MCP。Cosmos.so 的核心用户是设计师产品重心在体验和协作上官方对 AI 生态的开放策略并不激进的阶段推出官方 MCP Server 的优先级自然不会太高。但设计师和开发者又有真实需求。于是社区里就出现了“Unofficial Cosmos.so MCP”这类项目。项目名里的“Unofficial”是在明确表态这不是官方维护的而是一个社区爱好者或开发者自己实现的桥接层。这种“官方没做社区先做”的路径在开源生态里非常常见。用 React 生态类比官方框架没提供的功能社区会先写一个 hook用数据库生态类比官方不支持的插件社区会先做一个适配器。MCP 生态现在正处在这个阶段。2.2 这类项目一般怎么实现从社区 MCP 项目的通常做法来看一个 Unofficial Cosmos.so MCP 大致会做这些事封装 Cosmos.so 的数据接口把收藏项、集合、空间等数据暴露给 AI。提供若干 Tool比如按关键词搜索素材、列出某个 Collection 下的所有条目、获取某个条目的详细信息和标签。通过环境变量或配置文件接收用户的 API Token保证一次配置、长期使用。具体实现上有基于官方公开 API 的也有基于产品前端接口做逆向的。前者稳定但功能可能受限后者功能丰富但存在接口变动和账号风控风险。这也是非官方项目需要特别注意的地方后面我会专门讲安全边界。2.3 它解决了什么问题又解决不了什么问题通过 Cosmos.so MCPAI 助手第一次能够“看到”你的视觉素材库。你可以对 AI 说“在我 Cosmos 的 Brand 集合里找和今年春季主视觉风格相近的素材”AI 会先去调用 MCP Server 搜索再把结果返回给你。对创意团队来说这是从“自己翻素材”到“让 AI 帮你翻素材”的转变。但它解决不了的问题也很明显。它不能替代 Cosmos 本身的收藏和管理功能它不能保证搜索语义一定精确因为底层可能只是关键词匹配它也不能消除数据权限风险因为 MCP Server 能否访问什么数据完全取决于你给的 Token 范围。理解这些边界你才不会对它产生不切实际的期待。3. MCP 的架构与核心机制3.1 客户端-服务器模型一个完整的 MCP 调用链路大致是这样AI 客户端Claude Desktop / Cursor │ │ JSON-RPC over stdio / HTTP ▼ MCP Serverunofficial-cosmos-mcp │ │ HTTPS ▼ Cosmos.so 数据接口左边是 AI 客户端中间是 MCP Server右边是数据源。MCP Server 不直接和用户交互它在本地作为客户端的一个子进程运行或者作为一个远程服务被客户端连接。这条链路里有一个容易被忽视的细节MCP Server 通常运行在用户本机API Token 也保存在本机环境变量或配置文件中。也就是说数据不是通过公网中转的而是直接在本机和数据源之间流动。这对隐私来说相对友好但同时也意味着一旦你的机器上跑了一个恶意的 MCP Server它会拥有和你一样的数据访问权限。3.2 三个核心原语Tools、Resources、PromptsMCP 协议定义了多种能力日常打交道最多的是这三类Tools可被 AI 主动调用的函数。比如“search_items”就是搜索素材的工具。AI 会阅读工具的描述和参数定义然后决定要不要调用、传什么参数。Resources可以被读取的数据资源。比如把某个 Collection 的 JSON 导出挂成一个资源地址客户端可以直接读取。Prompts可复用的提示词模板。比如“整理素材库”这类的固定工作流模板让 AI 按指定格式执行。对 Cosmos MCP 来说Tools 是最重要的部分因为它需要支持“搜索”“读取”“列出”这类高频操作。Resources 适合做静态数据暴露Prompts 则适合做工作流模板比如“为某系列海报找参考素材”这种固定任务。3.3 MCP 和 CLI 工具架构的区别还有一个常见困惑MCP Server 和命令行工具CLI有什么区别CLI 是给人用的由人输入指令、查看输出MCP Server 是给 AI 用的由 AI 根据上下文决定调用哪个工具、传入什么参数。把 CLI 包成 MCP Server 的思路是可行的很多开源项目就是这么做的在 CLI 外层加一层 stdio 通信让 AI 可以执行原来由人执行的命令。但反过来CLI 的设计并不适合 AI 直接使用因为命令行的交互逻辑强依赖人的判断参数错误时 AI 往往无法自行恢复。MCP 的 Tool 定义恰恰补上了这一点——它给每个工具提供了机器可读的参数结构和描述。4. 环境准备与前置条件在开始配置 Unofficial Cosmos.so MCP 之前先把环境准备好。不同客户的配置路径略有差异但前置条件基本一致。4.1 准备一个支持 MCP 的客户端目前主流选择有以下几类Claude DesktopMCP 协议的发起方对 MCP 支持最原生通过claude_desktop_config.json配置。Cursor代码编辑器内支持 MCP Server通过项目级.mcp.json或用户级配置挂载。Trae、Dify 等平台Trae 支持在 IDE 中配置 MCP ServerDify 则是通过管理后台添加本地 MCP 服务或远程 MCP 服务。从实践角度看第一次测试建议使用 Claude Desktop 或 Cursor 这类本地客户端因为配置直观、日志可见出问题时好排查。4.2 准备运行时环境大多数社区 MCP Server 使用 Node.js 或 Python 编写运行时环境以项目 README 为准。本文的示例涉及两种Node.js要求 18 以上版本建议 20 LTS。Python要求 3.10 以上版本示例用到fastmcp和httpx依赖。可以用node -v或python --version先确认版本。如果版本过低优先升级因为 MCP SDK 普遍依赖较新的语法和网络特性。4.3 获取 Cosmos.so 的访问凭证MCP Server 要读取 Cosmos 的数据通常需要一个访问凭证。具体凭证的获取方式要看社区项目的设计常见有两种在 Cosmos.so 账户设置里生成 API Token。从产品登录会话中提取访问令牌仅限自用且要评估风险。这里必须强调无论用哪种方式都不要把 Token 分享给他人更不要提交到公开仓库。Token 的权限范围决定了 MCP Server 能用你的账户读到什么数据。如果项目支持优先申请只读权限把写操作留到需要时再开启。5. 接入配置以 Claude Desktop 和 Cursor 为例拿到项目之后最关键的一步是把 MCP Server 挂到 AI 客户端上。下面以社区项目的通用配置方式为例具体包名以项目 README 为准。5.1 在 Claude Desktop 中配置 MCP ServermacOS 的配置文件路径是~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 的路径是%APPDATA%\Claude\claude_desktop_config.json找到文件后编辑为以下内容{ mcpServers: { cosmos: { command: npx, args: [ -y, your-scope/unofficial-cosmos-mcp ], env: { COSMOS_API_TOKEN: 粘贴你的访问凭证 } } } }保存后完全退出 Claude Desktop 再重新打开。如果配置正确对话界面里应该能看到新增的“cosmos”服务以及它暴露的工具列表。5.2 在 Cursor 中配置 MCP ServerCursor 支持项目级配置。在项目根目录创建.mcp.json文件{ mcpServers: { cosmos: { command: npx, args: [-y, your-scope/unofficial-cosmos-mcp], env: { COSMOS_API_TOKEN: 粘贴你的访问凭证 } } } }也可以使用cursor mcp相关命令来管理具体以当前版本 Cursor 的文档为准。配置完成后在 Cursor 的 MCP 面板里应该能看到已经连接的cosmos服务。5.3 如果项目在本地仓库怎么配置如果你把项目 clone 到本地想自己调试更稳妥的配置方式是直接运行本地构建产物避免 npx 每次远程拉包git clone 仓库地址 cd unofficial-cosmos-mcp npm install npm run build然后配置为{ mcpServers: { cosmos: { command: node, args: [/绝对路径/unofficial-cosmos-mcp/dist/server.js], env: { COSMOS_API_TOKEN: 粘贴你的访问凭证 } } } }这里有一个非常容易踩坑的地方如果路径写的是相对路径MCP 客户端进程不一定能找到文件建议写绝对路径。另外Windows 下路径中的反斜杠要转义或使用正斜杠否则 JSON 解析会出错。6. 自己实现一个最小 Cosmos MCP Server如果社区项目不满足需求或者你只是想学习这个模式自己写一个最小实现是最好的方式。下面分别用 TypeScript 和 Python 演示核心代码。6.1 TypeScript 版本需要依赖modelcontextprotocol/sdk和zodnpm install modelcontextprotocol/sdk zod创建src/server.ts// 文件路径src/server.ts import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; const API_BASE process.env.COSMOS_API_BASE || https://api.cosmos.so/v1; const API_TOKEN process.env.COSMOS_API_TOKEN || ; const server new McpServer({ name: unofficial-cosmos-mcp, version: 0.1.0, }); async function callCosmos(path: string, params: Recordstring, unknown {}) { const url new URL(${API_BASE}${path}); Object.entries(params).forEach(([key, value]) { if (value ! undefined) { url.searchParams.set(key, String(value)); } }); const res await fetch(url.toString(), { headers: { Authorization: Bearer ${API_TOKEN}, Content-Type: application/json, }, }); if (!res.ok) { throw new Error(Cosmos API 请求失败: ${res.status} ${res.statusText}); } return res.json(); } server.tool( search_cosmos_items, { query: z.string(), limit: z.number().optional() }, async ({ query, limit 20 }) { const data await callCosmos(/search, { query, limit }); return { content: [{ type: text, text: JSON.stringify(data, null, 2) }], }; } ); server.tool( list_collection_items, { collectionId: z.string(), limit: z.number().optional() }, async ({ collectionId, limit 50 }) { const data await callCosmos(/collections/${collectionId}/items, { limit }); return { content: [{ type: text, text: JSON.stringify(data, null, 2) }], }; } ); const transport new StdioServerTransport(); await server.connect(transport);这段代码的关键点有三个第一McpServer是 SDK 提供的服务端入口StdioServerTransport让服务通过标准输入输出和 AI 客户端通信。第二server.tool方法注册了一个可被 AI 调用的工具第一个参数是工具名第二个参数是 zod 参数校验第三个是实际执行逻辑。第三所有对外调用的路径和接口请以 Cosmos.so 官方 API 文档或项目 README 为准。我示例里的/search和/collections/{id}/items是通用设计不代表真实接口路径。6.2 Python 版本使用 FastMCP 可以大幅简化代码pip install fastmcp httpx创建server.py# 文件路径server.py import json import os import httpx from fastmcp import FastMCP mcp FastMCP(unofficial-cosmos-mcp) API_BASE os.getenv(COSMOS_API_BASE, https://api.cosmos.so/v1) API_TOKEN os.getenv(COSMOS_API_TOKEN, ) async def call_cosmos(path: str, params: dict | None None): headers {Authorization: fBearer {API_TOKEN}} async with httpx.AsyncClient(base_urlAPI_BASE, headersheaders, timeout30) as client: resp await client.get(path, paramsparams or {}) resp.raise_for_status() return resp.json() mcp.tool() async def search_items(query: str, limit: int 20) - str: 在 Cosmos.so 中按关键词搜索收藏项。 data await call_cosmos(/search, {query: query, limit: limit}) return json.dumps(data, ensure_asciiFalse, indent2) mcp.tool() async def list_collection_items(collection_id: str, limit: int 50) - str: 列出某个 Collection 下的所有收藏项。 data await call_cosmos(f/collections/{collection_id}/items, {limit: limit}) return json.dumps(data, ensure_asciiFalse, indent2) if __name__ __main__: mcp.run()运行之前可以把 Token 放到环境变量里避免写死在代码中export COSMOS_API_TOKEN粘贴你的访问凭证 python server.pyPython 版本的优势是代码量更少适合快速原型验证TypeScript 版本的优势是和前端、编辑器生态更接近社区项目的默认实现也多以 Node.js 为主。两者选其一即可。6.3 工具参数设计的两个细节实现时有两个细节会影响 AI 的实际使用效果。一个是工具描述要语义清晰。AI 是依据工具名和描述来判断“什么时候该用哪个工具”的所以描述里要写清楚“按关键词搜索收藏项”还是“列出某个 Collection 下的所有收藏项”否则 AI 可能会混淆。另一个是返回值格式要稳定。AI 解析结果依赖稳定的 JSON 结构。如果返回值字段名经常变化AI 就很容易误解数据。所以尽量把返回内容做一次标准化至少保证id、title、url这类核心字段永远存在。7. 运行验证与效果确认配置好 MCP Server 之后不能只在客户端里看一眼就完事。建议按以下顺序验证。7.1 用 MCP Inspector 独立调试MCP Inspector 是官方提供的调试工具可以让你不借助 AI 客户端单独检查 MCP Server 是否正常工作npx modelcontextprotocol/inspector node /绝对路径/dist/server.js打开 Inspector 后你会看到服务连接状态、工具列表、可调用的方法。先点击list_tools确认工具注册成功再选择一个工具传参调用观察返回结果。如果这一步有问题说明 Server 本身或环境变量有问题可以直接在终端看到报错。7.2 在客户端里对话验证Inspector 通过后再回到 Claude Desktop 或 Cursor。重启客户端确认工具已加载然后发起一个明确的任务比如请搜索我的 Cosmos 素材库中所有包含“春季主视觉”的收藏项并列出标题和链接。如果 AI 能调用工具并给出结构化结果说明链路已经跑通。这一步失败时不要急着怀疑 AI先确认是否真的调用了工具再看工具返回的原始内容。7.3 如何判断接入成功一个合格的接入需要同时满足几个条件客户端能发现 MCP Server 及其工具。工具调用后有非错误的返回结果。AI 能根据返回结果给出自然语言回答。连续多次调用不会出现偶发崩溃。如果只是“工具被发现了但一调用就报错”那说明 Server 还没真正可用。这时应该先看两处日志MCP Server 进程的标准输出以及 Cosmos API 的返回状态码。401 是凭证问题404 大概率是接口路径问题超时则可能是网络或限流。8. 常见问题与排查思路问题现象可能原因排查方式解决方案客户端里看不到 cosmos 工具配置文件路径错误、进程启动失败查看客户端日志检查 JSON 是否合法使用绝对路径先手动运行命令验证调用工具返回 401Token 无效或未注入到环境变量检查 env 配置终端打印 Token 是否存在重新生成 Token确认拼写无误调用工具返回 404接口路径与 API 版本不匹配抓取网络请求查看真实请求 URL对照项目 README 或 API 文档修正路径工具调用超时数据量大或接口限流查看服务端日志和网络耗时减小 limit 参数调整客户端超时设置第一次运行很慢npx 需要远程下载包观察网络状态耐心等待改为本地 clone 安装后运行AI 返回结果乱码JSON 编码不一致检查返回内容的 charsetPython 使用 ensure_asciiFalse统一 UTF-8Token 被误提交到代码仓库开发时把 Token 写死在代码里检查 Git 历史立即撤销 Token改用环境变量注入排错的核心原则是“从外到内”先确认 MCP Server 在客户端外部能跑通再检查客户端配置最后排查数据接口。如果一上来就改 AI 提示词大概率解决不了问题。9. 最佳实践、安全边界与工程建议9.1 凭证安全是第一优先级接入非官方 MCP Server本质上是把你账户的数据访问能力交给一段社区代码。所以在使用前至少要确认三件事项目是否开源代码是否可审查。凭证是否只保存在本机环境变量而不是发送到第三方服务器。Server 是否只实现了最小必要的数据读取逻辑而不是无脑导走全部数据。如果在公司环境使用建议用最小权限的专用账号测试不要把核心业务素材库直接暴露给未经评审的工具。如果要在生产工作流中落地必须有审批、审计和回滚方案。9.2 合理控制工具暴露范围MCP Server 暴露的工具越多AI 能做的操作越多出事的概率也越大。建议遵循最小暴露原则默认只开放搜索和查询类工具写操作单独标注风险。如果项目本身支持编辑功能也要让 AI 在调用写操作前先明确告知用户最好是在配置层禁止掉写操作。9.3 注意限流、缓存与错误处理Cosmos.so 的接口如果有配额限制MCP Server 就需要考虑限流和缓存。常见做法是对搜索结果做短时间缓存对频繁查询的收藏列表做内存缓存对超时和限流做指数退避重试。这些细节虽然不影响“能跑通”但决定了“在生产环境能不能稳定跑”。9.4 日志与审计MCP Server 运行在本机也要有基本日志。建议记录工具调用时间、参数、返回码但不要记录完整 Token 和敏感素材内容。日志级别的设计可以参考常见规范INFO 记录工具调用摘要ERROR 记录异常信息DEBUG 记录详细参数和返回值生产环境默认不开启 DEBUG。9.5 先测试、再灰度、后全量如果这是公司内部要推广的 AI 工作流不要第一天就让所有设计师接入。正确节奏是先用测试环境账号验证功能再找两三个核心用户试用收集实际误用场景最后再全员推广。每个阶段都要有退出条件比如接口频繁报错、Token 泄露或功能不满足预期时随时可以停用对应 MCP Server。10. 总结与后续学习方向回到开头那个问题为什么 Unofficial Cosmos.so MCP 值得关注因为它背后是一个正在快速蔓延的技术趋势——AI 不再只是“聊天”而是开始连接真实世界的数据系统。通过这篇文章你应该已经理解了MCP 是什么为什么会出现非官方的 MCP Server以及在 Claude Desktop、Cursor 里如何配置和验证。更进一步你还看到了一个最小 MCP Server 的完整代码这意味着你不只是会用还可以自己动手改造。如果你接下来想继续深入建议按这个顺序来先把你最常用的一款设计工具或知识库工具接上 MCP跑通一个真实任务。再把这篇文章里的最小实现改成你自己的数据源比如公司内部的素材库或 CMS。最后研究一下 MCP 的 Resources 和 Prompts 能力让 AI 不仅会“调工具”还能直接“读资源”和“按工作流执行”。接入非官方项目时多看代码、少轻信描述在生产环境落地时多设边界、少放权限。这套习惯比任何工具本身都重要。