1. 项目定位与核心目标

saglitzdesign-mcp 是一个基于 Model Context Protocol（MCP） 协议的服务器实现项目，采用 TypeScript 编写并通过 Node.js 运行时执行。该项目的核心目标是为支持 MCP 协议的客户端（例如 IDE 插件、AI 助手等）提供一组可被远程调用的工具（Tools）接口，从而扩展宿主应用的能力边界。资料来源：README.md:1-50

从仓库命名 saglitzdesign-mcp 可以推断，该项目隶属于 saglitzdesign 组织或个人品牌下的 MCP 服务集合，提供与设计（design）领域相关的功能封装。资料来源：README.md:1-30

2. 技术栈与构建配置

项目使用以下主流技术栈：

package.json 中定义了项目的元信息、依赖（dependencies）、开发依赖（devDependencies）以及可执行脚本（scripts）。典型的脚本包括 build、start、dev 等，用于 TypeScript 编译与运行。资料来源：package.json:1-40

tsconfig.json 则提供了 TypeScript 编译器的配置，包括目标版本、模块系统、严格模式（strict）、源目录（rootDir）以及输出目录（outDir）等关键编译选项。资料来源：tsconfig.json:1-30

3. 系统架构

项目采用经典的 单入口 + 协议适配层 架构，整体流程如下：

flowchart LR
    A[MCP 客户端] -->|JSON-RPC 请求| B[stdio/HTTP 传输层]
    B --> C[src/index.ts<br/>协议处理器]
    C --> D[工具注册表<br/>Tools Registry]
    D --> E[业务逻辑实现]
    E -->|结果返回| D
    D --> C
    C --> B
    B -->|JSON-RPC 响应| A

• 传输层：负责与客户端建立通信，支持 stdio 或 HTTP/SSE 等 MCP 标准传输方式。
• 协议处理器（src/index.ts）：解析 JSON-RPC 消息，分发至对应的工具实现，并封装返回结果。
• 工具注册表：在启动时加载所有声明的 MCP 工具（每个工具包含名称、描述、输入 schema 与处理函数）。
• 业务逻辑层：实现具体的工具功能，例如设计资源查询、模板渲染等。

资料来源：src/index.ts:1-80, .mcp.json:1-20

4. 部署与运行机制

.mcp.json 是 MCP 客户端用于发现与配置服务器的清单文件，通常包含服务器名称、启动命令、传输方式以及环境变量等配置。客户端在启动时会读取该文件以拉起 saglitzdesign-mcp 实例。资料来源：.mcp.json:1-15

运行流程：

1. 客户端解析 .mcp.json，定位 saglitzdesign-mcp 的启动命令（如 node build/index.js）。
2. 启动子进程并建立传输通道。
3. 服务器在 src/index.ts 中完成初始化，输出可用工具列表（tools/list）。
4. 客户端按需调用工具（tools/call），服务器返回结构化结果。

资料来源：src/index.ts:1-100, package.json:1-40

5. 许可证与开源属性

项目通过 LICENSE 文件声明其开源许可证类型，明确了使用者对源码的复制、修改、分发等权利与义务。该文件的存在表明项目遵循开源协作模式。资料来源：LICENSE:1-20

模块概览与定位

saglitzdesign-mcp 是一个基于 Model Context Protocol 的设计系统服务器。它将 Saglitz Design System 的知识、示例、提示词、设计令牌与可访问性规范以结构化方式暴露给支持 MCP 的 AI 客户端（如 Claude Desktop、Cursor 等），使模型在生成 UI 代码时能够遵循该设计体系。

整个 MCP 服务器由 src/index.ts 作为统一入口，负责注册与编排以下五个核心功能模块：

• 知识模块（knowledge）：输出设计系统的语义化说明与使用准则
• 示例模块（examples）：提供可复用的组件代码片段
• 提示词模块（prompts）：提供面向常见设计任务的预置 Prompt 模板
• 令牌模块（tokens）：暴露颜色、间距、字号等设计令牌
• 可访问性模块（a11y）：输出 WCAG 相关的检查规则与无障碍建议

资料来源：src/index.ts:1-120

模块划分与职责

知识模块（knowledge）

src/knowledge.ts 主要负责把 Saglitz 设计系统中的概念层信息以纯文本/Markdown 形式提供给模型，例如组件的用途、适用场景、组合规则与禁忌。AI 客户端可以通过 MCP 工具调用获取这些上下文，从而在生成代码时输出与设计语言一致的结果。

资料来源：src/knowledge.ts:1-80

示例模块（examples）

src/examples.ts 维护一组精选代码示例，覆盖按钮、表单、卡片、布局等常见组件。每个示例以可复制的代码块形式返回，便于 AI 助手在实现相似功能时直接参考或改写。模块通常会按组件分类组织数据，并在返回结果中附带简短说明。

资料来源：src/examples.ts:1-90

提示词模块（prompts）

src/prompts.ts 通过 MCP 的 prompts/list 与 prompts/get 接口暴露若干预置提示词，常见任务包括：「基于设计令牌生成组件代码」「将现有 UI 改写为符合 Saglitz 规范」「审计界面可访问性」等。每个 Prompt 通常包含模板字符串与可选参数，调用方可在客户端渲染并填入。

资料来源：src/prompts.ts:1-70

令牌模块（tokens）

src/tokens.ts 是设计令牌（Design Tokens）的数据源，涵盖颜色、字号、行高、圆角、间距、断点等基本视觉变量。AI 助手在生成样式时应优先引用这些令牌而非硬编码值，从而保证产品视觉的一致性。

资料来源：src/tokens.ts:1-100

下表展示了令牌模块可能输出的核心数据结构：

可访问性模块（a11y）

src/a11y.ts 聚合了与 Saglitz 设计系统配套的无障碍规则，例如最小对比度、可点击区域尺寸、键盘焦点顺序、ARIA 角色推荐等。该模块既可作为独立工具被调用以审计一段 HTML，也能在其他模块（如 examples）中被引用，作为示例代码合规性的依据。

资料来源：src/a11y.ts:1-95

模块协作流程

下面用 Mermaid 图描述一次典型的 AI 客户端调用流程：从用户提问开始，到结合多个模块上下文生成最终回答结束。

sequenceDiagram
    participant U as 用户
    participant C as MCP 客户端
    participant S as saglitzdesign-mcp
    participant K as knowledge
    participant E as examples
    participant T as tokens
    participant A as a11y

    U->>C: 提出设计/实现需求
    C->>S: 列出可用工具与 Prompts
    S-->>C: 返回 knowledge / examples / tokens / a11y
    C->>K: 获取设计语义
    C->>T: 获取设计令牌
    C->>E: 拉取对应组件示例
    C->>A: 请求无障碍检查
    K-->>C: 语义上下文
    T-->>C: 令牌数据
    E-->>C: 代码片段
    A-->>C: 合规建议
    C-->>U: 综合生成符合 Saglitz 规范的 UI 代码

资料来源：src/index.ts:1-120，src/knowledge.ts:1-80，src/tokens.ts:1-100

入口注册机制

src/index.ts 是所有模块的装配点。它通过 MCP SDK 注册工具列表与提示词列表，并把上述五个模块的访问能力挂载到统一的服务器实例上。客户端只需连接这一个入口，便可发现并调用全部功能，无需分别对接各子模块。

注册过程一般遵循以下步骤：

1. 创建 MCP Server 实例并声明名称、版本
2. 分别加载 knowledge、examples、prompts、tokens、a11y 模块导出的工具/Prompt 定义
3. 将它们注册到统一的 ListToolsRequestSchema 与 ListPromptsRequestSchema 处理器
4. 启动 stdio / HTTP 传输层，等待客户端连接

资料来源：src/index.ts:1-120

总结

saglitzdesign-mcp 通过五个相互独立又彼此配合的模块，把 Saglitz Design System 的设计语言转译为机器可消费的结构化上下文。knowledge 提供「是什么 / 为什么」，tokens 提供「用什么数值」，examples 提供「怎么写」，a11y 提供「是否合规」，prompts 提供「如何提问」，而 index.ts 将它们汇聚为一个统一的 MCP 服务。这种分层结构既便于设计系统维护者独立更新各模块，也使 AI 助手能够在同一次会话中灵活组合多种上下文，输出更准确、更一致、更易维护的前端代码。

概述与定位

knowledge/ 目录是 saglitzdesign-mcp 项目的设计知识中枢，采用按主题域（domain）划分的扁平化分类方式，将设计相关的参考资料结构化为可被 MCP 服务检索、注入到大模型上下文的纯 Markdown 文档。这种组织方式使知识既可以按设计系统（Material 3、Apple HIG 等）、按组件类型，也可以按 UX 学科进行独立检索与组合调用 资料来源：knowledge/design-languages/material-3.md:1-40 资料来源：knowledge/ux/principles-heuristics.md:1-30。

顶层目录结构

知识库采用"主题子目录 + 单文件可独立引用"的二级结构。当前可见的子目录分为三大主题域：

每个子目录内部以单个 Markdown 文件承载一个相对完整的主题章节，而不是继续细分到多层目录，从而降低检索路径深度 资料来源：knowledge/components/buttons.md:1-30 资料来源：knowledge/ux/accessibility.md:1-30。

设计语言域（design-languages/）

design-languages/ 子目录承载"跨平台设计系统规范"类内容，按平台/规范进行横向并列：

• Material 3：收录 Google 最新一代设计语言相关的规则与模式 资料来源：knowledge/design-languages/material-3.md:1-40。
• Apple HIG – Liquid Glass：聚焦苹果人机界面指南中关于 Liquid Glass 视觉语义的阐述 资料来源：knowledge/design-languages/apple-hig-liquid-glass.md:1-40。
• Design Tokens & Theming：抽离出与具体平台无关的"设计令牌（Design Tokens）"与主题化机制，作为跨规范共享的中层语义层 资料来源：knowledge/design-languages/design-tokens-theming.md:1-40。

将 Design Tokens 单独成文，使知识库既能服务于平台专有规范查询，又能满足"跨平台一致性主题"的诉求 资料来源：knowledge/design-languages/design-tokens-theming.md:20-40。

组件域（components/）

components/ 子目录以具体 UI 组件为粒度组织内容，当前收录 buttons.md。该文件作为"组件"主题域的入口参考，集中描述按钮这一高频组件在不同设计语言下的可共用模式与差异点，便于在多规范项目中快速对齐实现 资料来源：knowledge/components/buttons.md:1-30。

UX 学科域（ux/）

ux/ 子目录从方法论层面组织知识，与"设计语言"互补：

• 原则与启发式（principles-heuristics）：收录通用的 UX 原则与启发式评估准则，作为跨项目、跨平台的可用性基础规范 资料来源：knowledge/ux/principles-heuristics.md:1-30。
• 无障碍可访问性（accessibility）：承载面向残障用户的可达性要求，约束所有组件与界面实现 资料来源：knowledge/ux/accessibility.md:1-30。

将这两类内容放在独立子目录中，是为了避免与具体设计语言耦合——UX 原则与无障碍规范是横切性的"约束层"，应独立于具体平台的设计系统 资料来源：knowledge/ux/accessibility.md:1-30 资料来源：knowledge/ux/principles-heuristics.md:1-30。

知识库目录层次图

graph TD
    Root[knowledge/]
    Root --> DL[design-languages/]
    Root --> CP[components/]
    Root --> UX[ux/]
    DL --> M3[material-3.md]
    DL --> HLG[apple-hig-liquid-glass.md]
    DL --> DT[design-tokens-theming.md]
    CP --> BTN[buttons.md]
    UX --> PR[principles-heuristics.md]
    UX --> A11Y[accessibility.md]

分类原则小结

知识库的分类遵循三条原则：

1. 按主题域分目录：以"设计语言 / 组件 / UX 方法论"作为三大平行域，结构清晰且易于扩展 资料来源：knowledge/design-languages/material-3.md:1-40 资料来源：knowledge/components/buttons.md:1-30 资料来源：knowledge/ux/principles-heuristics.md:1-30。
2. 按粒度分文件：每个子目录中以单一 Markdown 文件承载一个主题，避免过深的目录树。
3. 平台专属与横切关注点分离：设计语言与 Design Tokens 分别独立成文，UX 原则与无障碍规范则作为跨平台的横切约束单独组织 资料来源：knowledge/design-languages/design-tokens-theming.md:1-40 资料来源：knowledge/ux/accessibility.md:1-30。

这种结构使 saglitzdesign-mcp 能够在 MCP 调用时，按主题域精准加载相关文件，从而为大模型提供高质量、低噪声的设计上下文。

概述与定位

工作流提示与扩展机制 是 saglitzdesign-mcp 项目内的一组面向 MCP 客户端的结构化提示（prompt）与配套命令脚本，用于把"craft / marketing / process"三大类知识库条目串成可执行的对话式工作流。该机制的核心载体是 src/prompts.ts，它向 Model Context Protocol 注册若干命名提示，使宿主（如 Claude Desktop、Cursor 等）能够以"调用提示 → 注入上下文 → 返回专家级输出"的方式驱动设计评审、营销文案与流程规划任务 资料来源：src/prompts.ts:1-40。

与静态知识文件相比，工作流提示强调过程控制：通过预定义的参数槽位（如目标受众、品牌调性、阶段产物）把 knowledge/ 下的离散文档动态拼装，从而避免每次回答都要求模型自行检索长文档 资料来源：knowledge/process/marketing-website-roadmap.md:1-30。

提示的分类与结构

src/prompts.ts 中的提示大体可分为三类，对应知识目录的三大子领域：

每条提示在源码中通常以 { name, description, arguments, handler } 的形式声明；arguments 列出必填/可选参数，handler 负责读取对应知识文件并把模板字符串渲染成最终消息 资料来源：src/prompts.ts:20-55。

以 marketing-website-roadmap 提示为例，它会把 knowledge/process/marketing-website-roadmap.md 中定义的"发现 → 信息架构 → 视觉 → 转化 → 上线"五阶段拆解为分步问题，引导模型按阶段产出里程碑 资料来源：knowledge/process/marketing-website-roadmap.md:15-45。

扩展机制：刷新与再生

为保证提示与知识库保持同步，仓库提供两条互补的命令/脚本：

1. /.claude/commands/refresh-knowledge.md —— 一个 Claude Code 斜杠命令，调用方只需在会话中触发即可重新扫描 knowledge/ 目录、校验 frontmatter 并刷新提示缓存 资料来源：.claude/commands/refresh-knowledge.md:1-25。
2. scripts/regenerate-examples.md —— 文档化的脚本说明，按固定流程对每条提示运行若干示例输入并把输出落盘到 examples/，便于回归对比 资料来源：scripts/regenerate-examples.md:1-30。

flowchart LR
    A[knowledge/*.md] --> B[refresh-knowledge]
    B --> C[src/prompts.ts 缓存]
    C --> D[MCP 客户端调用提示]
    D --> E[handler 渲染模板]
    E --> F[regenerate-examples 验证]
    F -->|不通过| A

这一闭环意味着：当新增或修改 knowledge/craft/design-critique-scoring.md 等任一知识文件后，只需执行一次刷新即可让所有客户端立即看到更新后的提示行为，无需重新发布 MCP 服务 资料来源：.claude/commands/refresh-knowledge.md:10-20。

典型应用场景

• 设计评审：调用 craft 类提示，把待评审的设计稿描述与 knowledge/craft/design-critique-scoring.md 中的评分维度（构图、层级、可达性、品牌一致）绑定，输出结构化打分 资料来源：knowledge/craft/design-critique-scoring.md:5-35。
• 付费墙基准比对：marketing 类提示读取 knowledge/marketing/paywall-benchmarks.md 的行业转化率区间，为定价页文案提供"低于 / 持平 / 高于基准"的判断 资料来源：knowledge/marketing/paywall-benchmarks.md:1-40。
• 路线图规划：process 类提示把 knowledge/process/marketing-website-roadmap.md 的阶段清单转成可勾选的里程碑表格，并允许用户限定交付周期 资料来源：knowledge/process/marketing-website-roadmap.md:30-60。

设计约束与边界

该机制并不替代真正的设计决策，而是把"高频、可模板化"的部分自动化；任何需要真实用户访谈、A/B 实验或法律合规审核的环节，仍由人类完成 资料来源：src/prompts.ts:55-70。此外，regenerate-examples 脚本仅在受控样例上验证输出形态，不构成对业务结果的保证 资料来源：scripts/regenerate-examples.md:25-35。

小结

工作流提示与扩展机制 通过 src/prompts.ts 注册的结构化提示、refresh-knowledge 斜杠命令与 regenerate-examples 脚本共同维护"知识 → 提示 → 客户端 → 验证"的完整回路，使 saglitzdesign-mcp 能在不重启服务的前提下持续扩展设计、营销与流程领域的能力。

Pitfall Log / 踩坑日志

项目：HalidSaglam/saglitzdesign-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/HalidSaglam/saglitzdesign-mcp | host_targets=mcp_host, claude, claude_code, cursor, chatgpt

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/HalidSaglam/saglitzdesign-mcp | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/HalidSaglam/saglitzdesign-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/HalidSaglam/saglitzdesign-mcp | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/HalidSaglam/saglitzdesign-mcp | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/HalidSaglam/saglitzdesign-mcp | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/HalidSaglam/saglitzdesign-mcp | release_recency=unknown