使用说明

项目简介

这是 Optiaxiom 项目组实现的 MCP 服务器端，用于向 AI 助手（如 Claude Code、Cursor 等）提供 Axiom 设计系统的元数据、资源和工具执行能力。核心通过 MCP 协议提供统一的数据接口，服务端使用 JSON-RPC 进行请求/响应交互，默认传输方式为标准输入输出（stdio），便于嵌入式或管道式工作流集成。

主要功能点

• 提供组件、图标与设计令牌等元数据的查询与获取能力：
  • 获取所有组件、按名称获取具体组件、按名称获取指南、获取设计 Tokens 等。
  • 提供组件和指南的资源接口，如 axioms://component/{name} 与 axiom://guide/{name}。
• 支持资源类工具（Tools）注册与执行，涵盖：
  • get_component、list_components、search_components、get_tokens、search_icons 等工具。
  • 通过评分、过滤和排序实现对组件/图标的智能检索。
• 内置数据来源：
  • 组件、指南、图标、Tokens 等元数据通过数据加载器 (#mcp/data) 提供，便于离线与静态数据驱动的查询。
• 会话与传输多样性：
  • 虽然实现以 stdio 为默认传输，但 MCP 服务器也具备对接其他传输方式的能力（若客户端支持 SSE/WebSocket 等）。
• 可执行的服务器入口：
  • 服务器暴露为命令行后端，支持通过全局 CLI 启动，与客户端通过 stdio 通信。

安装步骤

• 全局安装（推荐用于快速测试与集成）：
  • 全局安装 MCP 服务器命令行工具后即可启动服务与客户端对接。命令来自仓库说明，通常为 optiaxiom-mcp（具体名称以实际打包为准）。
• 本地运行（从源码构建/测试）：
  • 在仓库根目录或对应包中安装依赖并构建后运行入口。
• 运行方式摘要（不涉及具体代码块，便于理解）：
  • 通过全局命令行工具启动 MCP 服务器，服务器将通过 STDIO 与客户端建立通信通道。
  • 服务器启动后会在标准错误输出中打印“启动信息”，表示 MCP 服务器已就绪。

服务器配置（给 MCP 客户端的配置示例）

以下为 MCP 客户端需要的配置信息（以 JSON 形式呈现，客户端无需关心服务器端实现细节）： { "serverName": "@optiaxiom/mcp", "command": "optiaxiom-mcp", "args": [] } 说明：

• serverName：服务器的唯一标识，基于本实现的包名，通常为 "@optiaxiom/mcp"。
• command：启动服务器的命令名称，通常为全局安装后的二进制名称，示例为 "optiaxiom-mcp"。
• args：启动服务器时的附加参数，当前实现默认使用 STDIO 传输，不强制额外参数。 注：该配置是给 MCP 客户端在启动时按需注入的启动信息，客户端通过该信息来启动并连接服务器。

基本使用方法

• 启动服务器：通过全局命令行工具启动 MCP 服务器，确保与对端客户端的 STDIO 工作流对接就绪。
• 客户端交互：LLM 客户端通过 MCP 的 JSON-RPC 请求向服务器发送“获取组件信息”、“搜索组件”、“获取 Tokens”等请求，服务器返回结构化的 JSON-RPC 响应数据。
• 常用交互模式：
  • 列出所有主组件及简要描述，帮助客户端发现可用的组件集合。
  • 按名称读取组件的完整信息（包括描述、示例、导入语句等）。
  • 进行模糊检索与排序，以便挑选最相关的组件或图标。
  • 获取设计Tokens，帮助将设计系统的颜色、字号、阴影等值映射到目标环境中。
• 注意事项：
  • MCP 客户端与服务器之间的通信基于 JSON-RPC，经由进程间通信（如 STDIO）传输数据。
  • 该实现将元数据和资源以稳定的接口暴露，便于 LLM 客户端在对话中引用组件信息和 Tokens。