PrimeUIX MCP

Shared Model Context Protocol (MCP) v2 server core for PrimeUI libraries. Framework-specific packages load normalized generated docs (mcp-data.json and manifest.json) and use this package to register a compact resource-first MCP surface.

Requires Node.js 22 or newer.

import { createPrimeMcpServer } from '@primeuix/mcp';

const server = await createPrimeMcpServer({
    name: '@primevue/mcp',
    version: '5.0.0-alpha.1',
    loadMcpData: async () => mcpData,
    loadManifest: async () => manifest,
    readResource: async (resource) => readGeneratedFile(resource.path)
});

Default tools are limited to:

• list
• search
• get_component
• get_guide
• get_example
• get_setup
• validate_usage
• version

Generated docs are exposed through MCP resources and resource templates for component docs, component API JSON, guide docs, examples, llms.txt, llms-full.txt, and index.json. Workflow prompts are registered with the current SDK registerPrompt API.

Normalized components, guides, sections, and resources may declare an optional absolute HTTP(S) publicUrl. Setup guides may additionally declare a canonical environment and environmentAliases. Tool results keep resourceUri as the offline citation and add publicUrl only when supplied by normalized artifact metadata.

Component search results include an artifact-backed exampleSections inventory. Each entry reports the exact section ID, hasCode, its source resource, and a nextCall containing arguments accepted by get_example. Component results expose the same routing inventory, while nextCall arguments retain the component's mode when the generated artifact requires mode-specific routing.

get_component and validate_usage preserve their single-item inputs and outputs. They also accept bounded batches:

{ "components": [{ "component": "Button" }, { "component": "Table", "sections": ["paginator"] }] }

{
    "usages": [
        { "component": "Button", "code": "<Button />" },
        { "component": "Button", "mode": "tailwind", "code": "<Button variant=\"default\" />" }
    ]
}

Each list accepts 1–10 items. Batch results preserve input order and report per-item success or structured error status; malformed or unknown items do not fail unrelated items. Duplicate items are processed independently. Empty and over-limit lists fail before item work begins.

Usage validation treats metadata completeness as an explicit state. A property value is checked only when its exact generated type is a closed union made entirely of string literals (plus optional null or undefined); extensible strings, named types, bindings, expressions, spreads, wrappers, and conflicting mode evidence are not promoted to hard errors. PrimeNG onX output names are checked only when the exact generated component API contains a well-formed data.emits collection; other unknown listener names may be DOM events and remain non-fatal. Current Vue listener fallthrough and React inherited event props do not prove closed event contracts, so unknown listener names also remain non-fatal there. Diagnostics use deterministic invalid-enum-value and unknown-output codes with artifact resource evidence and never repeat the rejected literal value.

PrimeReact Tailwind currently reuses an API source whose enum values conflict with accepted Tailwind examples. Its enum metadata is therefore classified as incomplete rather than inferred complete from a non-empty property list. Styled and Tailwind modes remain isolated, and requests without a mode do not receive enum or event errors when more than one generated mode matches.

The old broad tool modules are deprecated reference code only. The v2 server factory does not register them and does not provide a legacy runtime fallback.

Search benchmark

The shared core builds one immutable search index lazily for each server instance. The committed benchmark uses the accepted local PrimeVue, PrimeNG, and PrimeReact package artifacts, three warmups, eleven repeated samples, and per-operation medians:

corepack pnpm --filter @primeuix/mcp build
corepack pnpm --filter @primeuix/mcp benchmark

benchmarks/baseline.json records the pre-change environment, accepted artifact commits, and medians. A comparison is valid only when the explicit Node, platform, architecture, OS release, and CPU metadata match. Search must be at most 75% of baseline; component retrieval and validation may regress by at most 10%. The harness uses real monotonic durations and batched fast operations, with no sleeps or mocked timers.

After building the core, run corepack pnpm --filter @primeuix/mcp test:real-artifacts to exercise routing, batching, validation, and the unchanged eight-tool inventory against the accepted local PrimeVue, PrimeNG, and PrimeReact artifacts. PrimeReact coverage is mode-specific for styled, Tailwind, primitive, and headless components.

License

Licensed under the PrimeUI License - Copyright (c) PrimeTek Informatics