npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@geotab/zenith-mcp

v1.0.2

Published

Model Context Protocol server for the Zenith design system

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:

  1. Passing translate props (removed in v3.0)
  2. Mixing ESM and CommonJS imports
  3. Using deprecated components without knowing replacements exist
  4. Confusing similar components (Skeleton vs Waiting, etc.)
  5. Missing Drive app theme integration
  6. Reinventing utilities that already exist in utils/
  7. Inventing CSS custom property names that do not exist — an undefined var() fails silently at runtime
  8. 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 required query using component names, descriptions, use cases, and synonyms. Results are ranked; Internal implementation entries are excluded from the published manifest. This is a discovery tool: structuredContent carries only what is needed to choose a component (rank, name, category, description, deprecation status, score, Storybook/file paths) — call get-component-details for props, types, and examples.
  • get-component-details - Retrieve a component's props, types, import paths, compound components, Storybook variants, and usage examples using required componentName.
  • list-components - Browse components, optionally filtering by exact category and including deprecated exports with includeDeprecated.
  • get-usage-guidance - Retrieve best practices for a required topic; current topics are getting-started (first-time setup), translation, theming, esm-cjs, accessibility, responsive, app-shell (provider tree and SSR), and styling (design tokens, style classes, interactive states, z-index registry).
  • get-deprecation-info - Check an optional componentName, 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 by kind (hook or function) and a keyword query.
  • get-type-details - Retrieve the definition, kind, module, properties, and referenced types for a required typeName.
  • list-icons - List icon names and ESM/CJS import paths, optionally filtered by a case-insensitive query.
  • list-images - Illustration components with ESM/CJS import paths, for use inside EmptyState rather than an img tag.
  • list-design-tokens - List CSS custom properties with default and .zen-dark values, filtered per query term or by exact group. Renders var(--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 by typography or utility.
  • 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.json

Manifest 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 → header prop; footerButtons → single action)
  • 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-mcp

Or 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.
  • npx fails with EBADDEVENGINES — your project enforces pnpm. Use the pnpm dlx registration above.
  • Duplicate registration — if zenith is defined in both a project .mcp.json and 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 register zenith in one scope only.

Component Not Found

Symptom: get-component-details returns "Component not found".

Solution:

  1. Use list-components or search-components to verify the exact name.
  2. get-component-details accepts component names case-insensitively; category filters on list-components are exact and case-sensitive.
  3. Sub-components may need the parent name (e.g., Tabs.TabList might be indexed as TabList).

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.