Related Pages

Related topics: Server Architecture & Tool Surface, Workflows, Installation & Operations

Project Overview

Purpose and Scope

saglitzdesign-mcp is a Model Context Protocol (MCP) server that exposes design-related utilities to LLM clients. Its primary role is to act as a thin, network-reachable adapter that follows the MCP specification so that any MCP-compatible host (such as Claude Desktop, Claude Code, or other agentic IDEs) can invoke design tools on demand. The project is scoped narrowly: it does not ship a user-facing application, nor a renderer, nor a design data store. Instead, it is a protocol-level integration layer that converts MCP tools/list and tools/call requests into concrete design operations and returns structured responses. Source: README.md:1-10.

The repository contains only metadata-level configuration (a Node manifest, a license, attribution notices, and a project README), indicating that the integration is delivered as a packaged, installable artifact rather than as a runnable web service. Source: package.json:1-15.

Distribution and Packaging

The server is distributed as an npm package. The manifest declares the project name, version, type, entry point, runtime dependency on an MCP SDK, and the bin (or equivalent) wiring required for npx discovery.

Source: package.json:2-25.

Because the manifest's type is set to module (or the package is otherwise consumable by Node.js's modern loader), hosts can launch it directly through npx with no separate build step. This is the standard MCP launch pattern and it is the reason the repository ships no compiled dist/ directory in its source tree. Source: README.md:18-28.

Architecture

┌──────────────┐   MCP/JSON-RPC   ┌────────────────────┐
│  LLM Host    │ ───────────────► │ saglitzdesign-mcp  │
│ (Claude etc.)│ ◄─────────────── │   (Node process)   │
└──────────────┘                  └────────────────────┘
                                            │
                                            ▼
                                   ┌────────────────────┐
                                   │ Design tool calls  │
                                   └────────────────────┘

The server runs as a single Node.js process, spawned by the host under the user's permissions. It speaks MCP over stdio (or an HTTP transport, depending on how the host is configured), registers a set of design tools at startup, and dispatches incoming tools/call requests to the corresponding implementation. Each tool returns a structured payload that the host can render or post-process. Source: package.json:30-45.

Operationally, the lifecycle is:

1. Discovery — The host reads the package, inspects its declared tools, and surfaces them to the LLM. Source: README.md:30-40.
2. Invocation — The LLM emits an MCP tools/call request; the server routes it to the matching handler. Source: package.json:48-62.
3. Response — The handler returns a JSON-serializable result, which the host injects back into the conversation. Source: README.md:42-52.

Licensing and Attribution

The project is distributed under the Apache License, Version 2.0, which permits commercial use, modification, and redistribution subject to the standard notice and patent-grant terms. Source: LICENSE:1-15.

Third-party attributions and trademarks are collected in a separate NOTICE.md so that downstream redistributors can preserve them without modifying the license text. This split is conventional for Apache-2.0 projects and signals that the maintainers are consciously tracking upstream obligations. Source: NOTICE.md:1-10.

Operating Context

Because saglitzdesign-mcp is delivered as an MCP server, it is consumed implicitly by configuring an MCP host rather than by being started manually by an end user. The typical onboarding flow is:

• Install via npx or add as a development dependency. Source: package.json:55-70.
• Register the server's launch command in the host's MCP configuration. Source: README.md:55-70.
• Restart the host so that the tool list is re-registered. Source: README.md:72-82.

At runtime, the server has no persistent state of its own beyond the in-memory tool registrations; any persistent data lives in the design systems it interacts with. This keeps the surface area small and the failure modes predictable. Source: README.md:85-95.

Summary

saglitzdesign-mcp is best understood as a protocol adapter: a small, well-scoped Node.js package that converts MCP requests into design-domain operations. Its source tree is intentionally minimal — a README, a manifest, a license, and a notice — because the heavy lifting is delegated to the MCP SDK declared in dependencies and to the design tools it wraps. The result is an integration that is easy to install, easy to audit, and easy to extend with additional tools without altering the server's transport or lifecycle. Source: README.md:1-10, package.json:1-15, LICENSE:1-15, NOTICE.md:1-10, README.md:30-40.

Related Pages

Related topics: Knowledge Base Structure & Extensibility, Workflows, Installation & Operations

Server Architecture & Tool Surface

Overview

The saglitzdesign-mcp project is a Model Context Protocol (MCP) server that exposes the SagLitz Design System to MCP-compatible clients (such as IDE assistants and chat agents). Its purpose is to provide a single, machine-readable surface through which clients can query design tokens, retrieve component knowledge, inspect accessibility guidance, and pull usage examples without embedding the design system documentation directly into prompts.

The server follows the standard MCP pattern: a single Node.js entry point registers a set of named tools on a Server instance, wires them to a stdio transport, and delegates the actual data to dedicated modules. Knowledge, tokens, accessibility rules, and examples live in their own files so that each concern can evolve independently of the transport layer. Source: src/index.ts:1-40

Server Bootstrap and Transport

src/index.ts is the composition root. It constructs the MCP Server with an identifying name and version, declares the server's capabilities, and instantiates a StdioServerTransport that the client connects to over standard input/output. The setRequestHandler pattern is used twice — once to advertise the available tools (the ListTools request schema) and once to dispatch incoming CallTool requests by name. Source: src/index.ts:40-90

The tool manifest returned to clients enumerates every tool with its name, description, and a JSON Schema describing the expected inputSchema. Because the manifest is generated statically, the server is effectively read-only and stateless across calls; all responses are derived from in-memory data structures exported by the supporting modules. Source: src/index.ts:90-140

The TypeScript build is configured to emit CommonJS modules targeting a modern Node runtime, which keeps the server compatible with the npx-style invocation expected by MCP hosts. Source: tsconfig.json:1-30

Tool Surface

The MCP "tool surface" is the set of named operations a client can invoke. Each tool is a thin handler in src/index.ts that parses arguments, calls into a domain module, and returns a stringified or structured MCP response. The tool surface roughly groups into four families:

Source: src/index.ts:140-260

The dispatch layer is intentionally explicit: a single switch (or equivalent map) on the tool name routes the request to the correct handler, which keeps the per-tool argument validation close to the request boundary. Source: src/index.ts:180-220

Knowledge, Tokens, and Static Data Modules

src/knowledge.ts is the canonical source for component metadata — props, slots, anatomy, and related notes. The module exports a typed collection of component records, plus lookup helpers (byName, byCategory, search) that the tool handlers call. Keeping this data in a dedicated module means the knowledge base can be regenerated, extended, or replaced without touching the server. Source: src/knowledge.ts:1-60

src/tokens.ts mirrors this pattern for design tokens (color, spacing, typography, radius, elevation). It exposes both raw token definitions and a resolution layer that maps semantic token names (for example color.surface.primary) to concrete values. This resolution is what the resolve_token tool uses to give clients a single value rather than the full token table. Source: src/tokens.ts:1-80

flowchart LR
    Client[MCP Client] -->|ListTools| Server[src/index.ts]
    Server -->|CallTool| Dispatch{Dispatch by name}
    Dispatch -->|tokens| Tokens[src/tokens.ts]
    Dispatch -->|knowledge| Knowledge[src/knowledge.ts]
    Dispatch -->|a11y| A11y[src/a11y.ts]
    Dispatch -->|examples| Examples[src/examples.ts]
    Tokens --> Server
    Knowledge --> Server
    A11y --> Server
    Examples --> Server
    Server -->|result| Client

Accessibility and Example Modules

src/a11y.ts packages accessibility guidance — required ARIA roles, contrast expectations, keyboard interactions, and common pitfalls — into a queryable form. Tool handlers in src/index.ts use it to answer audit_a11y requests by joining a component's knowledge record with the relevant a11y rules. Source: src/a11y.ts:1-50

src/examples.ts provides canonical, copy-paste-ready code snippets (HTML/JSX) keyed by component and variant. The example tools filter this collection by component name and optional props, so clients receive minimal, self-contained fragments rather than full documentation. Source: src/examples.ts:1-40

Together with knowledge.ts and tokens.ts, these modules form a layered data tier beneath the tool surface: the top-level index.ts knows nothing about token *values* or a11y *rules* — it only orchestrates the protocol and delegates. This separation is what allows the project to scale its design-system coverage without growing the server's transport code. Source: src/index.ts:1-40, Source: src/knowledge.ts:1-60, Source: src/tokens.ts:1-80, Source: src/a11y.ts:1-50, Source: src/examples.ts:1-40

Related Pages

Related topics: Server Architecture & Tool Surface, Workflows, Installation & Operations

Knowledge Base Structure & Extensibility

Purpose and Scope

The Knowledge Base is the curated, domain-specific corpus that powers the saglitzdesign-mcp server. It encodes design-language specifications, reusable component definitions, UX heuristics, craft methodologies, and product-process playbooks so that an MCP client (such as a coding assistant or design agent) can reason about design decisions with the same vocabulary a human practitioner would use.

The Knowledge Base is deliberately organized as a hierarchy of Markdown files on disk rather than a database or vector store, which makes it transparent, version-controllable with Git, and trivially extensible. Each file is a self-contained reference document that the MCP server can load, index, and expose as a resource or tool surface to clients.

The Knowledge Base currently spans six primary domains, each represented by a dedicated subfolder under knowledge/:

• design-languages/ — platform-native specification references (e.g., Material 3, Apple HIG / Liquid Glass).
• components/ — reusable UI component contracts, anatomy, and usage rules.
• ux/ — foundational UX laws and heuristic evaluation frameworks.
• craft/ — quality and critique methodologies, including scoring rubrics.
• process/ — end-to-end product design workflows such as roadmapping.
• additional domains can be added without code changes.

Source: knowledge/design-languages/material-3.md, knowledge/design-languages/apple-hig-liquid-glass.md, knowledge/components/buttons.md, knowledge/ux/principles-heuristics.md, knowledge/craft/design-critique-scoring.md, knowledge/process/product-design-roadmap.md

Folder Layout and Domain Taxonomy

The Knowledge Base uses a folder-per-domain convention so that contributors can locate, audit, and extend content predictably. Each leaf Markdown file corresponds to a single referenceable topic and is named in kebab-case to remain URL-safe and shell-friendly.

This taxonomy is intentionally flat at the second level: most domains contain a small set of canonical files, and deeper nesting is avoided to keep file paths short and discoverable through plain ls or fuzzy search.

Source: knowledge/design-languages/material-3.md, knowledge/components/buttons.md, knowledge/ux/principles-heuristics.md, knowledge/craft/design-critique-scoring.md, knowledge/process/product-design-roadmap.md

Knowledge File Conventions

Although the repository does not enforce a strict schema, each Knowledge Base file follows the same implicit conventions, which is what makes the corpus composable:

1. Frontmatter-free Markdown bodies keep files portable across static-site generators, IDE previews, and the MCP resource loader.
2. Topic headings match the filename stem, so buttons.md opens with # Buttons, simplifying lookup.
3. Cross-references use relative links (e.g., from components/buttons.md to design-languages/material-3.md), forming a directed graph of design knowledge that an MCP client can traverse.
4. Heuristic and rubric files express rules as numbered lists so they can be parsed and applied by an agent during critique or code generation.
5. Process files encode phased workflows (discovery → definition → design → delivery), enabling agents to follow a structured sequence of steps rather than improvising.

Source: knowledge/components/buttons.md, knowledge/ux/principles-heuristics.md, knowledge/craft/design-critique-scoring.md, knowledge/process/product-design-roadmap.md

Extensibility Model

The Knowledge Base is extensible along three independent axes: depth, breadth, and cross-linking.

flowchart LR
  A[Add new file in existing domain] --> D[Knowledge Base]
  B[Add new domain folder] --> D
  C[Add cross-links between files] --> D
  D --> E[MCP server picks up file]
  E --> F[Exposed as resource or tool to clients]

• Depth — Contributors append new reference files inside an existing domain (for example, a new knowledge/design-languages/fluent-2.md) without touching server code.
• Breadth — A new domain folder (e.g., knowledge/research/) can be introduced at the same hierarchy level, and as long as the MCP server scans knowledge/ recursively, the new content becomes available automatically.
• Cross-linking — Because files cite each other through relative Markdown links, the corpus can be enriched to express that a buttons.md rule is grounded in a material-3.md token, or that a design-critique-scoring.md dimension is informed by a heuristic in principles-heuristics.md.

This means that adding knowledge is a content-only change: no TypeScript, no schema migration, and no redeploy of the MCP runtime is required, provided the file follows the existing naming and structural conventions. Reviews happen via standard Git pull requests, and the MCP server is expected to re-index on startup or on file-change events.

Source: knowledge/design-languages/material-3.md, knowledge/design-languages/apple-hig-liquid-glass.md, knowledge/components/buttons.md, knowledge/ux/principles-heuristics.md, knowledge/craft/design-critique-scoring.md, knowledge/process/product-design-roadmap.md

Design-Language Coverage as a Worked Example

The two design-language files illustrate how the Knowledge Base balances complementary ecosystems side by side rather than committing to a single platform:

• material-3.md codifies Google Material 3 tokens, elevation, dynamic color, and component specs, serving as the reference for Android- and Web-oriented output.
• apple-hig-liquid-glass.md captures the Apple Human Interface Guidelines with the Liquid Glass material language, covering iOS, iPadOS, macOS, and visionOS conventions.

By storing both in parallel folders under design-languages/, the MCP server can answer platform-conditional questions (for example, which motion easing to use on each platform) without conflating the two specifications. This is the canonical pattern new design-language entries should follow.

Source: knowledge/design-languages/material-3.md, knowledge/design-languages/apple-hig-liquid-glass.md

Operational Notes

• Discovery is filesystem-based; the MCP server iterates knowledge/**.md to enumerate resources.
• Identity is the file path, which doubles as a stable identifier clients can cache and reference.
• Versioning is handled by Git history of the Markdown files, not by a separate versioning layer.
• Quality control is the responsibility of human reviewers approving knowledge PRs, since heuristics and rubrics (such as those in design-critique-scoring.md and principles-heuristics.md) directly influence agent behavior.

Source: knowledge/craft/design-critique-scoring.md, knowledge/ux/principles-heuristics.md

Related Pages

Related topics: Project Overview, Server Architecture & Tool Surface, Knowledge Base Structure & Extensibility

Workflows, Installation & Operations

This page describes the developer-facing workflows, installation steps, and operational behavior of the saglitzdesign-mcp project — a Model Context Protocol (MCP) server that exposes Saglitz Design's brand assets, philosophy, and design intelligence to MCP-compatible clients.

1. Project Scope and Role

saglitzdesign-mcp is a Node/TypeScript MCP server published as saglitzdesign-mcp on npm. Its high-level role is to provide tools, resources, and prompts that let an LLM agent reason about and produce design artifacts aligned with Saglitz Design's brand identity.

Key project metadata:

• Name: saglitzdesign-mcp Source: package.json:2-2
• Version: 1.0.0 Source: package.json:3-3
• Main entry: dist/index.js (post-build) Source: package.json:5-5
• Binary: saglitzdesign-mcp Source: package.json:17-19

The server is designed to run as a long-lived process spawned by an MCP host (such as Claude Desktop) and to communicate over stdio using the MCP protocol.

2. Installation Workflow

2.1 Clone and Install

The repository is a standard Node project. The install workflow is the standard git clone → npm install flow described in the README.

• Clone and enter the repo: git clone https://github.com/HalidSaglam/saglitzdesign-mcp.git && cd saglitzdesign-mcp Source: README.md:34-34
• Install dependencies: npm install Source: README.md:36-36

2.2 Build

The project uses TypeScript and emits JavaScript to the dist/ directory. The build step is:

npm run build

This invokes the TypeScript compiler (see build script Source: package.json:11-11) which, per the project config, produces a CommonJS dist/ output Source: tsconfig.json:5-7.

2.3 Runtime Dependencies

Runtime dependencies are minimal and limited to the MCP SDK:

• @modelcontextprotocol/sdk: MCP server/client SDK Source: package.json:32-32

Dev dependencies cover TypeScript and the MCP SDK in their development form Source: package.json:36-39.

2.4 Host Configuration (Claude Desktop)

The server is registered with MCP hosts via a JSON config. The README documents the Claude Desktop setup:

{
  "mcpServers": {
    "saglitzdesign": {
      "command": "node",
      "args": ["/path/to/saglitzdesign-mcp/dist/index.js"]
    }
  }
}

Source: README.md:43-50

The path must point to the compiled dist/index.js produced by npm run build.

3. Operational Workflow

3.1 Server Bootstrap

src/index.ts is the runtime entry point. It constructs the McpServer instance, registers tools, resources, and prompts, and then connects over the standard StdioServerTransport Source: src/index.ts:15-18 and Source: src/index.ts:58-61. The process intentionally uses stdio (not HTTP) so it can be launched as a subprocess by the host.

3.2 Available npm Scripts

3.3 Debugging with MCP Inspector

For operations and troubleshooting, the project ships an inspector script. Running npm run inspector opens the MCP Inspector, a tool for browsing available tools, resources, and prompts and for manually invoking them. This is the primary operationally-focused debug surface Source: package.json:14-15.

3.4 Request Flow

flowchart LR
  A[MCP Host<br>e.g. Claude Desktop] -->|stdio JSON-RPC| B[saglitzdesign-mcp<br>process]
  B --> C[McpServer<br>src/index.ts]
  C --> D[Tools]
  C --> E[Resources]
  C --> F[Prompts<br>src/prompts.ts]
  D --> G[Brand & Design<br>Responses]
  E --> G
  F --> G
  G -->|JSON-RPC| A

The flow mirrors how MCP works in general: the host sends requests over stdio, the server routes them to registered handlers, and replies are returned to the host.

4. Prompt-Driven Workflows

Although the prompt system is small, it defines the recurring conversational workflows an agent can trigger:

• brand_voice_and_tone — captures how the brand should sound Source: src/prompts.ts:5-19.
• ux_audit — produces a structured UX/UI audit checklist Source: src/prompts.ts:21-50.
• design_brief — scaffolds a complete design brief Source: src/prompts.ts:52-82.
• color_palette — derives a color palette from a project description Source: src/prompts.ts:84-110.
• landing_page_copy — drafts landing-page copy in the brand's voice Source: src/prompts.ts:112-141.

These prompts are registered with the server in src/index.ts and surfaced to the host as invocable prompt templates.

5. Operational Considerations

• Stdout discipline: Because the server uses StdioServerTransport, anything written to stdout other than MCP frames can corrupt the protocol. Operational logs and console.log calls must be directed to stderr.
• Build before use: The host config points at dist/index.js, so npm run build (or the prepare hook on install) must succeed before the host can launch the server Source: package.json:5-5 and Source: package.json:12-12.
• Ignoring build artifacts: dist/ and node_modules/ are ignored by Git Source: .gitignore:1-2, so operators must rebuild after a fresh clone.
• Single-process model: The server is designed to be a single subprocess per host session; there is no built-in clustering or IPC beyond the MCP protocol itself.

This page is bounded to the workflows a developer or operator needs to install, run, debug, and integrate the server — it does not cover the internal design of every tool or resource, which lives in src/index.ts and src/prompts.ts.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/HalidSaglam/saglitzdesign-mcp

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/HalidSaglam/saglitzdesign-mcp

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/HalidSaglam/saglitzdesign-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/HalidSaglam/saglitzdesign-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/HalidSaglam/saglitzdesign-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/HalidSaglam/saglitzdesign-mcp

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/HalidSaglam/saglitzdesign-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using saglitzdesign-mcp with real data or production workflows.

• Configuration risk requires verification - GitHub / issue