@geotab/zenith-mcp
v1.0.2
Published
Model Context Protocol server for the Zenith design system
Maintainers
Keywords
Readme
Zenith MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with structured access to Zenith component metadata, usage patterns, and migration guidance.
Overview
The Zenith MCP server enables AI coding assistants to discover and use Zenith components correctly by providing:
- Component discovery and search
- Detailed prop interfaces, types, and usage examples
- Icon names and import paths
- Supported translation locales
- Deprecation warnings and migration paths
- Utility hooks and helper functions
- Referenced TypeScript interfaces and type aliases
- Best-practice guidance for common integration mistakes
This server targets 8 common AI-generated code mistakes:
- Passing
translateprops (removed in v3.0) - Mixing ESM and CommonJS imports
- Using deprecated components without knowing replacements exist
- Confusing similar components (Skeleton vs Waiting, etc.)
- Missing Drive app theme integration
- Reinventing utilities that already exist in
utils/ - Inventing CSS custom property names that do not exist — an undefined
var()fails silently at runtime - Hardcoding font sizes and colours instead of using the
.zen-*classes and custom properties Zenith already emits
What It Provides
Tools
search-components- Search by requiredqueryusing component names, descriptions, use cases, and synonyms. Results are ranked; Internal implementation entries are excluded from the published manifest. This is a discovery tool:structuredContentcarries only what is needed to choose a component (rank, name, category, description, deprecation status, score, Storybook/file paths) — callget-component-detailsfor props, types, and examples.get-component-details- Retrieve a component's props, types, import paths, compound components, Storybook variants, and usage examples using requiredcomponentName.list-components- Browse components, optionally filtering by exactcategoryand including deprecated exports withincludeDeprecated.get-usage-guidance- Retrieve best practices for a requiredtopic; current topics aregetting-started(first-time setup),translation,theming,esm-cjs,accessibility,responsive,app-shell(provider tree and SSR), andstyling(design tokens, style classes, interactive states, z-index registry).get-deprecation-info- Check an optionalcomponentName, or omit it to list all deprecation entries and migration guidance. 6 high-impact migrations include before/after code examples (Dialog, Notification, Toolbar, FiltersBar, pageLayout, GroupsFilterRaw).list-utilities- List utilities, optionally filtering bykind(hookorfunction) and a keywordquery.get-type-details- Retrieve the definition, kind, module, properties, and referenced types for a requiredtypeName.list-icons- List icon names and ESM/CJS import paths, optionally filtered by a case-insensitivequery.list-images- Illustration components with ESM/CJS import paths, for use insideEmptyStaterather than animgtag.list-design-tokens- List CSS custom properties with default and.zen-darkvalues, filtered per query term or by exact group. Rendersvar(--name)so output is copy-pasteable.list-style-classes- List typography presets with resolved font values and mobile overrides, plus utility classes with their variants. Filterable bytypographyorutility.get-page-recipe- Complete, compilable page skeletons extracted from Storybook stories — omit the name to browse, provide one for full source.
Successful tool calls return both human-readable Markdown in content[0].text and manifest-backed JSON in structuredContent. Semantic no-match responses set isError: true and include a structured error object.
Manifest Contents and Fields
The mcp/mcp-manifest.json file is a generated build-time snapshot consumed when the server starts. Its top-level fields are:
| Field | Contents |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| version | Manifest version, mirroring package.json at generation time |
| generatedAt | ISO timestamp for manifest generation |
| components | Component entries |
| icons | Icon entries |
| designTokens | CSS custom properties |
| styleClasses | Typography presets and utility classes |
| images | Illustration components for empty states |
| pageRecipes | Complete page skeletons extracted from Storybook stories |
| locales | Supported locale codes |
| deprecatedComponents | Deprecation entries |
| usageGuidance | Guidance text keyed by the getting-started, translation, theming, esm-cjs, accessibility, responsive, app-shell, and styling topics |
| utilities | Public hooks and helper functions |
| types | Referenced interfaces and type aliases |
Entry counts are deliberately not documented here — the manifest is regenerated for each Zenith release, and any number written down goes stale. If you installed the package as a dependency, inspect its manifest with:
jq '{version, generatedAt, components: (.components|length), icons: (.icons|length), locales: (.locales|length), deprecated: (.deprecatedComponents|length), utilities: (.utilities|length), types: (.types|length), guidance: (.usageGuidance|keys)}' node_modules/@geotab/zenith-mcp/mcp-manifest.jsonManifest entry fields are:
| Entry | Fields |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| components[] | name, category, description, interface, props, extends, compoundComponents, storyVariants, storybookPath, storybookUrl, usageExample, deprecated, filePath, importPath, isSubComponent, parent, examples, library, whenToUse, relatedComponents, accessibilityNotes, enumValues |
| components[].props[] | name, type, description, optional, literalValues, enumSource |
| components[].storyVariants[] | storyId, name, componentName |
| components[].importPath | esm, cjs |
| components[].library | name, optional url |
| components[].props[].enumSource | name, importPath.esm, importPath.cjs |
| icons[] | name, filePath, importPath.esm, importPath.cjs |
| designTokens[] | name, value, darkValue, group, source, description |
| styleClasses[] | name, kind, theme, cssProperties, mobileCssProperties, description, variants, source |
| images[] | name, filePath, importPath.esm, importPath.cjs, props |
| pageRecipes[] | name, description, whenToUse, code, componentsUsed, source, storybookUrl |
| deprecatedComponents[] | name, type, replacement, since, reason, softDeprecated, migration, propMapping |
| deprecatedComponents[].propMapping[] | from, to |
| utilities[] | name, kind, module, importPath.esm, importPath.cjs, description, signature, returnType |
| types[] | name, kind, definition, properties, module |
Migration Examples
The get-deprecation-info tool provides before/after code examples for common migrations. 6 high-impact component migrations include complete refactoring examples:
- Dialog → Modal - Render-prop pattern to composition API
- Notification → Toast - Message merge (
title/text→headerprop;footerButtons→ singleaction) - Toolbar → Header - Action arrays to composed Button children
- FiltersBar → Filters - Direct component swap with same API
- pageLayout → Layout - CSS classes to Layout.Main/Sidebar composition
- GroupsFilterRaw → GroupsFilter - Prop simplification (
rawGroups→groups)
Each migration includes:
- Realistic code example showing deprecated usage
- Updated code example with the replacement component
- Prop mapping table (old prop → new prop)
- Migration notes highlighting gotchas and breaking changes
Use get-deprecation-info({ componentName: "Dialog" }) to see the full migration guide with code examples.
Installation
The server is distributed as a standalone package @geotab/zenith-mcp on npm.
Package Consumers (recommended)
Register the server with npx — no absolute paths, and it works from any working directory (including subagents and background agents).
Add to .mcp.json in your project root, or use the CLI:
claude mcp add zenith -- npx -y -p @geotab/zenith-mcp zenith-mcpOr edit .mcp.json manually:
{
"mcpServers": {
"zenith": {
"command": "npx",
"args": ["-y", "-p", "@geotab/zenith-mcp", "zenith-mcp"]
}
}
}Open Settings → Developer → Edit Config to edit claude_desktop_config.json:
{
"mcpServers": {
"zenith": {
"command": "npx",
"args": ["-y", "-p", "@geotab/zenith-mcp", "zenith-mcp"]
}
}
}Add to .vscode/mcp.json in your workspace or user mcp.json:
{
"servers": {
"zenith": {
"type": "stdio",
"command": "npx",
"args": ["-y", "-p", "@geotab/zenith-mcp", "zenith-mcp"]
}
}
}Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:
{
"mcpServers": {
"zenith": {
"command": "npx",
"args": ["-y", "-p", "@geotab/zenith-mcp", "zenith-mcp"]
}
}
}Add to settings.json (~/.config/zed/settings.json on macOS):
{
"context_servers": {
"zenith": {
"source": "custom",
"command": "npx",
"args": ["-y", "-p", "@geotab/zenith-mcp", "zenith-mcp"]
}
}
}Add to your global config (~/.config/opencode/opencode.json). OpenCode also supports a per-project
opencode.json in the repo root — configs are merged and the project entry wins, so register zenith
in one scope only.
Use the published package with npx:
{
"mcp": {
"zenith": {
"type": "local",
"command": ["npx", "-y", "-p", "@geotab/zenith-mcp", "zenith-mcp"],
"enabled": true
}
}
}Pin the MCP package version independently of the Zenith version (see Version Pinning below), e.g.
"command": ["npx", "-y", "-p", "@geotab/[email protected]", "zenith-mcp"].
The entry shape differs from the clients above: there is no args field — command is the full argv
array — and the entry sits under mcp, not mcpServers. OpenCode also accepts cwd and environment
options here; the zenith server needs neither, because it resolves its manifest relative to its own
file rather than the working directory.
Restart OpenCode after editing the config (registrations are read at startup), then verify with a real tool call:
"Search for a spinner component in Zenith"That calls search-components with the query spinner and returns Waiting and the other loading
components.
Using pnpm when npx is blocked
If your project enforces pnpm through devEngines, npx may fail with EBADDEVENGINES. Use pnpm dlx to run the published package without adding it to your project dependencies.
For Claude Code, Claude Desktop, and Cursor, which use the standard mcpServers configuration:
{
"mcpServers": {
"zenith": {
"command": "pnpm",
"args": ["dlx", "@geotab/zenith-mcp", "zenith-mcp"]
}
}
}VS Code uses servers:
{
"servers": {
"zenith": {
"type": "stdio",
"command": "pnpm",
"args": ["dlx", "@geotab/zenith-mcp", "zenith-mcp"]
}
}
}Zed uses context_servers:
{
"context_servers": {
"zenith": {
"source": "custom",
"command": "pnpm",
"args": ["dlx", "@geotab/zenith-mcp", "zenith-mcp"]
}
}
}OpenCode uses a command array instead:
{
"mcp": {
"zenith": {
"type": "local",
"command": ["pnpm", "dlx", "@geotab/zenith-mcp", "zenith-mcp"],
"enabled": true
}
}
}Version Pinning: The MCP package versions independently of Zenith. Pin the MCP version separately, e.g. "-p", "@geotab/[email protected]" with npx, or pnpm dlx @geotab/[email protected] zenith-mcp with pnpm.
Which Zenith version does the manifest describe? The server reports the MCP package version in its initialize response (serverInfo.version) and the Zenith library version in serverInfo.zenithVersion. Note: official SDK clients strip unknown serverInfo fields, so prefer reading the Zenith version from list-components' structuredContent.zenithVersion in code. The manifest's top-level version field reflects the Zenith version it describes. A manifest generated from Zenith 3.14.1 will have "version": "3.14.1" even if the MCP package itself is 1.0.0.
Why npx and not a file path: Claude Code launches stdio MCP servers with an undefined
working directory, so relative paths break and absolute paths aren't portable across
machines. npx resolves the package from the registry regardless of CWD — the same
mechanism the Playwright and chrome-devtools MCP servers use. If your project blocks npm
through devEngines, use the pnpm dlx form above instead.
Verifying Registration
After adding the configuration, restart your MCP client (e.g., Claude Desktop). The server should appear in the available tools list. Test it with:
"Search for a Button component in Zenith"Troubleshooting
- Tools missing in subagents/workflows — this is almost always a working-directory or duplicate-registration issue. Use the registry registration for your package manager above; do not use relative file paths.
npxfails withEBADDEVENGINES— your project enforces pnpm. Use thepnpm dlxregistration above.- Duplicate registration — if
zenithis defined in both a project.mcp.jsonand user-scope config (~/.claude.json/~/.claude/settings.json), remove one. Two entries can start two server instances or shadow each other unpredictably. The same rule applies to OpenCode: global and project configs are merged and the project entry wins, so registerzenithin one scope only.
Component Not Found
Symptom: get-component-details returns "Component not found".
Solution:
- Use
list-componentsorsearch-componentsto verify the exact name. get-component-detailsaccepts component names case-insensitively; category filters onlist-componentsare exact and case-sensitive.- Sub-components may need the parent name (e.g.,
Tabs.TabListmight be indexed asTabList).
Incomplete Metadata
Symptom: Component details are missing descriptions or Storybook links.
Context: Coverage is partial by design. Components with documentation and Storybook stories have richer details; others still appear in list-components and search-components with less detail.
