@synergy-design-system/mcp

v3.4.0

Published

2 hours ago

MCP Server for the Synergy Design System

Downloads

1,633

0High
0Medium
0Low

schilchsickag

kirchsusickag

klaarse_sickag

SDS Synergy Design System SICK SICK Design System UI UI MCP Server Synergy MCP Server

@synergy-design-system/mcp

The @synergy-design-system/mcp package provides a Model Context Protocol (MCP) server for the Synergy Design System. It exposes Synergy components, setup guidance, tokens, styles, templates, icons, and migration content to AI assistants over stdio or http.

Data is provided via the low level @synergy-design-system/metadata package.

Quick Start

Installation

npm install --save-dev @synergy-design-system/mcp

Running the Server

The package ships a syn-mcp binary:

# Run via stdio (default, for editor integration)
npx @synergy-design-system/mcp

# Or if installed globally
syn-mcp

# Start with an explicit runtime config
syn-mcp --config ./synergy-mcp.json

# Start HTTP server on default port 9119
syn-mcp --interface http

# Start HTTP server on a custom port
syn-mcp --interface http --port 3000

# Listen on all IPv4 interfaces for container/cloud deployment
syn-mcp --interface http --host 0.0.0.0

# Start HTTPS server with TLS certificates
syn-mcp --interface http --tls-key ./server.key --tls-cert ./server.crt

# Enable local tool-call logging to a directory
syn-mcp --log ./logs

# Explicitly disable logging (also disabled when omitted)
syn-mcp --log false

Available CLI flags:

--help, -h: Show usage information
--version, -v: Print the package version
--config <path>: Load runtime defaults from a synergy-mcp.json file
--interface <stdio|http>: Server interface (default: stdio)
--port <number>: HTTP server port (default: 9119, only used with --interface http)
--host <address>: HTTP bind address (default: 127.0.0.1)
--log <value>: Local tool-call log directory path, or false / null to disable
--tls-key <path>: Path to TLS private key file (enables HTTPS)
--tls-cert <path>: Path to TLS certificate file (enables HTTPS)
--compression <none|toon>: Response compression mode (default: none; experimental)

VS Code Integration

To integrate with VS Code and AI assistants, add this configuration to your settings.json under mcp.servers:

{
  "mcp": {
    "servers": {
      "synergy": {
        "type": "stdio",
        "command": "npx",
        "args": ["@synergy-design-system/mcp"],
      },
    },
  },
}

# Enable experimental toon format compression for responses
syn-mcp --compression toon

Claude Desktop Integration

For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "synergy": {
      "command": "npx",
      "args": ["@synergy-design-system/mcp"]
    }
  }
}

Runtime Configuration

The server can read optional runtime defaults from a synergy-mcp.json file passed via --config.

Server Interface

You can run the server in two modes:

stdio (default): Communicate via stdin/stdout with the parent process. This is the recommended mode for editor and CLI integrations.
http: Run as an HTTP/HTTPS server listening on a specified port. This enables standalone deployments.

Configuration File

Example:

{
  // Server interface mode: "stdio" (default) or "http"
  "interface": "http",

  // HTTP server port (only used when interface is "http")
  "port": 3000,

  // HTTP bind address.
  // Use 127.0.0.1 for local-only access or 0.0.0.0 for container/cloud deployments.
  "host": "127.0.0.1",

  // TLS configuration (optional, enables HTTPS)
  // Both keyPath and certPath must be provided together
  "tls": {
    "keyPath": "./server.key",
    "certPath": "./server.crt",
  },

  // Include custom ai rules for each tool.
  "includeAiRules": true,

  // Optional logging providers
  "logging": {
    "localFile": {
      // Base folder for logs (YY-MM-DD/SESSION.json)
      // Set to null to disable local file logging
      "path": "./logs",
    },
  },

  // Response compression mode (experimental!)
  // "none" (default): No compression
  // "toon": Encode structured data to compact toon text format
  "compression": "none",

  // Default parameters for each endpoint can be overridden
  "tools": {
    "assetInfo": {
      "iconset": "current",
    },
    "componentInfo": {
      // Set to angular, react or vue, depending on your framework
      "framework": "vanilla",
      // Defines which type of information to return.
      // full = filtered source files,
      // examples = markdown examples,
      // interface = markdown API overview.
      // Note that examples and interface are only available
      // for vanilla components at the moment.
      "layer": "full",
    },
    "tokenInfo": {
      // If you are preferring scss, use "sass" here
      "type": "css",
    },
  },
}

CLI Override Precedence

CLI flags take precedence over configuration file values:

# Config file specifies port 3000, but CLI overrides it to 8080
syn-mcp --config ./synergy-mcp.json --port 8080

# Config file specifies a local-only bind, but CLI overrides it for deployment
syn-mcp --config ./synergy-mcp.json --host 0.0.0.0

# Config enables logging, but CLI disables it for this run
syn-mcp --config ./synergy-mcp.json --log false

Tool-call logging

Tool-call logging is provider-based. The built-in local file provider writes one JSON entry per line to:

YY-MM-DD/SESSION.json

Each entry includes:

timestamp
toolName
parameters
durationMs
sessionId (stdio when no session id exists)
transport (stdio or http)
success and optional errorMessage
tokenCount (optional, populated when tiktoken is available)

Optional Token Counting

The MCP server can automatically count output tokens for each tool call when the optional tiktoken dependency is available.

Installation:

Token counting is an optional feature. To enable it, install tiktoken:

npm install tiktoken
# or
pnpm add tiktoken

The MCP package declares tiktoken as both a dev dependency (for build/test) and optional dependency (for runtime). When installed, token counts are automatically computed and logged for every successful tool call.

Behavior:

If tiktoken is installed, tokenCount is populated with the output token count for the tool response using the o200k_base encoding.
If tiktoken is not available, tokenCount will be omitted from log entries.
Token counting failure does not fail the tool call; it only results in tokenCount being absent from the log entry.

Example log entry with tokenCount:

{
  "durationMs": 187.69,
  "parameters": {},
  "sessionId": "stdio",
  "success": true,
  "timestamp": "2026-04-22T09:21:47.533Z",
  "tokenCount": 421,
  "toolName": "asset-list",
  "transport": "stdio"
}

Notes:

Logging is disabled by default.
Use --log <path> or set logging.localFile.path in config to enable.
--log false and --log null explicitly disable local file logging.
Token counting is always optional and non-blocking; the server runs fine without it.

HTTP Server Endpoint

When running in HTTP mode, the MCP protocol is served at the /mcp path:

http://127.0.0.1:9119/mcp
https://127.0.0.1:3000/mcp

Non-/mcp paths return HTTP 404.

Metadata cache behavior in HTTP mode

The MCP server reads data via @synergy-design-system/metadata, which now uses a process-local cache for index, entity, and layer file reads. In HTTP mode this reduces repeated filesystem reads across requests and sessions inside the same process.

Operationally, treat metadata as immutable for the process lifetime and roll out updates via restart/redeploy. If you run multiple replicas, each replica maintains its own in-memory cache.

For public or containerized deployments, bind to all interfaces explicitly:

syn-mcp --interface http --host 0.0.0.0

Example deployment patterns:

# Docker / Kubernetes: listen on all interfaces inside the container
syn-mcp --interface http --host 0.0.0.0 --port 3000

# Reverse proxy / load balancer forwards external traffic to the MCP endpoint
# https://mcp.example.com/mcp  ->  http://127.0.0.1:3000/mcp
syn-mcp --interface http --host 127.0.0.1 --port 3000

In general:

Use 127.0.0.1 when the server should only be reachable through the local machine or a reverse proxy on the same host.
Use 0.0.0.0 when the runtime environment needs the process to accept traffic from outside its own network namespace, such as Docker, Kubernetes, ECS, or EC2.

This lets you change per-tool defaults without modifying the MCP server code.

Features

Metadata-backed component docs: Retrieve component data directly from @synergy-design-system/metadata.
Setup guidance: Return package setup instructions for components, framework adapters, tokens, styles, fonts, assets, and migrations.
Asset and icon discovery: Browse icon sets and search icons across the Synergy asset libraries.
Token access: Read CSS, JavaScript, and Sass token outputs.
Styles and templates: Retrieve CSS utility guidance and static template content.
Migration guidance: Access both DaVinci migration guides and Synergy package migration documents.
AI response rules: Optionally prepends package-local guidance files from rules/ to selected tool responses.
MCP stdio transport: Ready for editor, assistant, and CLI integrations.

Available Resources

The MCP server currently registers 5 resources. Resources expose static, read-only data that does not change during server runtime. Clients that support MCP resources can read them directly without calling a tool.

Resource identifier reference (exact values used by the server):

synergy://components/list → name: component-list
synergy://assets/list → name: asset-list
synergy://component-clusters/list → name: component-clusters-list
synergy://styles/list → name: styles-list
synergy://templates/list → name: templates-list