next-ui-mcp

An MCP server for helping AI coding agents build, evaluate, and validate ServiceNow Next Experience UI Framework components and projects more effectively.

Unofficial, community-maintained project. Not affiliated with, endorsed by, or supported by ServiceNow.

Why

Next Experience UI Framework components have two parts that must stay in sync: the component source (src/<name>/index.js) and the separate manifest (now-ui.json) that declares the component's public properties and dispatched events. AI agents (and humans) routinely edit one without updating the other. That is one important problem this server solves.

But the broader goal is to make AI-assisted development in this framework safer and more reliable across the full workflow:

• understand the framework contract and now-ui.json rules
• generate a correct component scaffold from the start
• prefer real platform components before inventing custom UI
• choose between direct use, composition, and custom implementation with evidence
• validate manifests and dependency setup
• inspect live instance API metadata instead of guessing from stale package docs
• use next-ui-storybook as the default local preview workflow, alongside runtime shims and instance-backed optionalDependencies
• reduce the common failure modes that cause AI-generated Next Experience UI Framework code to be structurally wrong or platform-incompatible

This MCP server is meant to act as a practical operating system for working with Next Experience UI Framework projects in AI-assisted development, with manifest sync as one critical piece of that larger workflow.

Available MCP tools

Guidance and scaffolding

• explain_now_ui_manifest — explains what now-ui.json is and how to keep it in sync with the component code.
• get_framework_guidance — returns bundled guidance for framework patterns, sample project structure, createCustomElement(...), manifest expectations, Storybook local development and migration, and instance-backed dependency usage. Use topic storybook-local-development for setup and adoption guidance.
• get_component_scaffold — returns the minimal stub files for a new component, including createCustomElement(...), .storybook/main.mjs, a component story, and a matching now-ui.json entry.

Platform component selection

• evaluate_platform_component_fit — decides whether an instance-backed HDS component should be used directly, wrapped/composed, or replaced with a custom implementation before scaffolding from scratch.
• search_instance_components — discovers which platform components exist on the configured instance.
• search_instance_icons — searches the icon library on the configured instance (the values accepted by icon properties such as now-button's) so agents pick real icon names instead of guessing. Names are read from the instance's now-icon package; append -outline or -fill to use one.
• recommend_instance_components — finds likely platform-component matches from a use case or desired properties/events.
• resolve_component_package — resolves a platform component tag to the exact npm package it belongs to without guessing.

Instance API and validation

• get_component_api — reads the real API of a platform component from the user's own ServiceNow instance, so an agent works from actual props, events, and slots rather than stale or incomplete public package metadata. Slot names come from sys_ux_macroponent.root_component_definition.availableSlots, with markup examples showing the slot attribute.
• analyze_project_dependencies — checks whether a project declares platform packages as optionalDependencies with version "instance" when needed.
• validate_now_ui_manifest — validates a now-ui.json file using the ServiceNow schema validation package and checks that every UI Builder component has a non-empty tileIcon path.

Using an snc profile instead of environment credentials (macOS)

If NEXT_UI_INSTANCE_URL is not set, the server falls back to an snc configure profile profile. Set NEXT_UI_SNC_PROFILE to pick one (default: default). The host and username are read from ~/.snc/config.json and the password from the macOS Keychain (service snc, account = profile name), so no secret has to be stored in your MCP client config. Only basic login-method profiles are supported.

"env": { "NEXT_UI_SNC_PROFILE": "default" }

Install

Add to your MCP client config (for example, .mcp.json at your project root for Claude Code or .cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "next-ui": {
      "command": "npx",
      "args": ["-y", "next-ui-mcp@latest"],
      "env": {
        "NEXT_UI_INSTANCE_URL": "https://your-instance.service-now.com",
        "NEXT_UI_INSTANCE_USER": "your-user",
        "NEXT_UI_INSTANCE_PASSWORD": "your-password"
      }
    }
  }
}

Ensure the file is added to your .gitignore since it contains credentials.

Instance requests time out after 20 seconds by default. Set NEXT_UI_INSTANCE_TIMEOUT_MS in the same env block to raise or lower that if your instance is slow or you want to fail faster.

Configure project instructions

Connecting the server makes its tools available, but project instructions tell the agent when to use them. Add these files to the consuming UI project's root, and commit them so the team shares the same policy.

Keep the shared instructions in AGENTS.md:

# ServiceNow UI Development

## HDS Policy

Prefer HDS components over custom equivalents.
Prefer composition or thin wrappers when an HDS component is a partial fit.
Custom UI requires a concrete functional or design gap.

## Required Workflow

For new UI and substantial changes to existing UI:
- Before implementation, use next-ui-mcp get_framework_guidance
  with topic "agent-workflow-contract" and follow its guidance.
- Discover HDS candidates using recommend_instance_components
  or search_instance_components.
- Evaluate plausible candidates with evaluate_platform_component_fit.
- Inspect selected components with get_component_api before using them.
- Follow MCP guidance for imports and instance-backed dependencies.
- Briefly explain any decision to create a custom equivalent.
- If MCP tools are unavailable or fail, report the limitation.
  Do not interpret failed discovery as proof that no HDS component exists.

Adjust the HDS policy to match the project:

• Strict: Use suitable HDS components; custom equivalents require a concrete capability gap.
• Preferred: Start with HDS; allow custom UI for documented functional or design requirements. This is the template's default.
• Selective: Specify which controls or areas must use HDS and where custom UI is acceptable. Keep that scope consistent with the required workflow.

For Copilot in VS Code, enable chat.useAgentsMdFile for the Local agent. Start a new chat and confirm AGENTS.md is discovered in Chat: Open Customizations and included in the response's References or instruction diagnostics. Merge this guidance with any existing project instructions instead of adding conflicting policies.

For Claude Code, add a root CLAUDE.md containing this import as a plain Markdown line, not inside a code fence:

@AGENTS.md

Claude Code expands the import automatically, keeping AGENTS.md as the single source of shared instructions. Recent versions can also load AGENTS.md directly, but the import supports older versions and sessions configured to load only CLAUDE.md. If CLAUDE.md already exists, add the import and preserve its existing instructions. Start a new session and use /context to confirm the project instructions loaded.

Configure and enable the MCP server separately in each client; instruction files do not connect it. Choosing a Claude model inside Copilot still uses Copilot's instruction loading, not Claude Code's.

To check the workflow, ask the agent to add a card containing a button. Verify that it calls component-discovery and API-inspection tools before implementing the UI. Instructions guide behavior but do not guarantee compliance.

Development

npm install
npm run build   # compile TypeScript -> dist/
npm run dev     # run directly from src/ via tsx, for local iteration

Contributing

PRs adding improvements to the guidance and instance-backed component discovery flow, are the main way this stays useful and current as the framework evolves. This project is meant to be centrally maintained in one place rather than copied into every project.

License

MIT