MCP

Launch the published @by/experience-system-mcp package from Artifactory through an MCP client, and use its experience-system and governance tools in product projects.

Use this page when you want AI tooling in a product repository to query the Blue Yonder Experience System directly instead of relying on copied snippets or stale local notes. The published @by/experience-system-mcp package runs a stdio-based Model Context Protocol server that exposes generated component metadata, usage helpers, validation, and centralized governance rules.

Before you configure it

Your machine or CI environment must already be configured for the BY Artifactory npm registry in .npmrc.
You do not need the full plat-byx-design-system monorepo checked out, and the recommended setup does not require adding the package as a project dependency first.
Use a recent Node.js version that matches your project policy; the published package runs through its bundled by-experience-system-mcp bin.

Recommended MCP client configuration

For long-lived MCP client setup, point the client at the published package through npx and the next dist-tag. This avoids checking a local node_modules path into MCP config while keeping the launcher shape the same across projects.

{
  "mcpServers": {
    "by-experience-system": {
      "command": "npx",
      "args": ["-y", "@by/experience-system-mcp@next"]
    }
  }
}

Use this as the default recommendation for Cursor, VS Code MCP, Claude Code, and similar MCP-capable tools.

Optional local install

If your team wants the MCP package version pinned in the consumer project's lockfile, install it as a development dependency and point the client at the bundled Node launcher instead.

pnpm add -D @by/experience-system-mcp

Configure your MCP client

Use the local-install path only when your team explicitly wants lockfile-managed version control for the MCP package.

{
  "mcpServers": {
    "by-experience-system": {
      "command": "node",
      "args": ["./node_modules/@by/experience-system-mcp/run.cjs"]
    }
  }
}

Use forward slashes in the path even on Windows. If your client supports workspace variables, the equivalent absolute path under the workspace is even better.

Client compatibility

The exact settings file varies by tool, but the same launch contract applies across MCP-compatible clients:

Client	Recommended command	Notes
Cursor	`npx` + `-y @by/experience-system-mcp@next`	Recommended default because it avoids repo-local paths in shared MCP config.
VS Code MCP	`npx` + `-y @by/experience-system-mcp@next`	Use the same command/args pair in the MCP server entry exposed by your team’s MCP UI.
Codex / other MCP clients	`npx` + `-y @by/experience-system-mcp@next`	Map the same pair into whatever `command` / `args` fields the client provides.
Any client with strict pinning needs	`node` + `./node_modules/@by/experience-system-mcp/run.cjs`	Use this only when you intentionally want the version controlled by the consumer lockfile.

Alternative launchers

If a shell, script, or MCP client prefers a different package runner, these launch the same published package without adding a local dependency first:

npx --yes @by/experience-system-mcp@next

For shared documentation and team setup, prefer the npx -y @by/experience-system-mcp@next configuration shown above because it is the broadest cross-client contract.

What the server exposes

The published package ships generated governance, migration, and registry artifacts plus a small MCP server over stdio. Today, consumer projects get these tool families:

Tool	Use when you need to…
`list_components`	discover available `@by/experience-system` components by keyword from installed instructions, workspace exports, or live docs fallback
`get_component`	inspect one component’s lazily loaded metadata and example references
`get_component_docs`	fetch the published Fumadocs markdown for one component on demand
`get_component_api`	load props/type metadata for one component without loading the whole registry
`get_component_example`	retrieve one component’s example references and read local source only when available
`search_registry`	search installable registry items by keyword, type, or dependency
`get_registry_item`	inspect one registry item, including files, dependencies, and install hint
`get_public_docs`	fetch the public `llms.txt` or `llms-full.txt` docs exports with optional keyword filtering
`get_migration_guidance`	answer version-aware migration questions using local migration matrix data first, then registry skills, then Fumadocs docs
`generate_usage`	ask for a ready-to-use React snippet grounded in live docs markdown or installed package metadata
`validate_usage`	check a JSX snippet against the available component API
`list_governance_rules`	browse normalized experience-system governance rules by category, enforcement, or source skill
`get_governance_rule`	fetch one governance rule with provenance and MCP mapping details

Behind those tools, the package reads generated runtime artifacts bundled in the published package and combines them with installed package metadata or live docs endpoints when needed:

registry-items.json — lightweight installable registry item index
governance-rules.json — normalized governance rules extracted from repository skills
governance-audit.md — human-readable governance crosswalk for maintainers and auditors
migration-guidance.json — version-aware migration guidance bundle built from local migration matrix entries, registry skills, and published migration docs
@by/experience-system/instructions/manifest.json — installed component metadata when the consumer package exposes it
/system/components/<slug>.mdx — live component docs markdown from the design site
/llms.txt and /llms-full.txt — LLM-oriented docs exports from the design site

Typical workflow in a product project

Add the npx -y @by/experience-system-mcp@next MCP client configuration to the repo or user config your team standardizes on.
If your team prefers lockfile-managed pinning instead, install @by/experience-system-mcp as a dev dependency and use the local node ./node_modules/@by/experience-system-mcp/run.cjs launcher.
Restart the MCP-capable tool so it discovers the new server.
Use the MCP tools during implementation, for example:

list components before choosing a primitive
inspect prop metadata before wiring JSX
search the registry before installing a recipe or primitive wrapper
fetch the live docs page for a specific component when you need canonical guidance
ask for migration guidance when upgrading a component, icon, token, pattern, deprecated surface, or major version
generate a starter snippet, then adapt it to your app
validate a usage example before opening a PR
query governance rules when an agent needs BY-specific constraints

Updating the package in consumer projects

Treat the MCP package like any other versioned developer tool:

if your client config uses @by/experience-system-mcp@next, restart the MCP client after a new next publish when you want to pick up the latest release-channel changes
if your team uses the optional local-install path, update @by/experience-system-mcp, commit the lockfile change in the consuming repo, and restart the MCP client
if you need strict reproducibility, replace @next in the config with an exact published version

Run the same recommended command manually to confirm registry auth and package resolution:

npx --yes @by/experience-system-mcp@next

If that works but your client still fails, compare the client config with the exact command: "npx" / args: ["-y", "@by/experience-system-mcp@next"] pair above.
If your client environment blocks npx, fall back to the optional local-install path and the node ./node_modules/@by/experience-system-mcp/run.cjs launcher.

Tool output looks outdated

If you use the @next launch config, restart the MCP client after a newer next build is published.
If you use a pinned local install or exact version, upgrade @by/experience-system-mcp so the registry, governance, migration, and docs-backed behavior match the latest release you want.

Live docs fetches fail

Verify the design site is reachable from your environment.
If you need another environment, set BY_DESIGN_SYSTEM_DOCS_BASE_URL before launching the MCP server.
The default docs base URL is https://blueyonder.design/.

Getting started — BY Design System adoption checklist for application teams
Installation — Install @by/experience-system and @by/icons in product apps
Skills — Registry-published skills and LLM reference files for AI workflows