@neural-ng/mcp-server

Read-only Angular UI expert interface for NeuralNg component discovery, contract-backed composition, usage validation, project-consistent guidance and compact theme workflows.

The server is separate from @neural-ng/core. Angular applications never load an MCP runtime in the browser. Theme tools return recipes, validation results, diffs and compile summaries; they do not write files or execute shell commands.

Run

Since rc.4, the catalog covers Editor, theme tools accept native objects, empty queries support bounded browsing and project inspection reports CSS risk hints.

Current release: 1.0.0 (stable MCP interface). Requires Node.js 24.x. Pin the version for reproducible agent environments; @latest selects the latest published release.

npx -y @neural-ng/mcp-server@1.0.0

Generic MCP client configuration:

{
  "command": "npx",
  "args": ["-y", "@neural-ng/mcp-server@1.0.0"]
}

The process uses stdio. Standard output is reserved for MCP JSON-RPC messages; fatal diagnostics are written to standard error.

Tool output contracts

Since 1.0.0-rc.3, tools expose output contracts, the validator accepts native arrays and project inspection separates scan coverage from semantic confidence.

All 20 tools advertise an outputSchema in tools/list. The server validates successful structuredContent before returning it. Invalid output becomes a tool error rather than a success. Tool-handler errors keep isError: true and the separate {error: {schemaVersion: 1, message}} contract; they are not successful instances of the advertised result schema.

Existing result envelopes and schema versions are retained. New fields are additive; consumers must tolerate unknown fields. Required-field removals or type changes require an explicit result-schema version change. Snapshot tests lock the published JSON schema shapes, alongside actual-output and negative tests.

Resources

Agent capability discovery:

• neural://server/capabilities — versioned tool groups, result schemas, inspection limits, safety guarantees and compatibility guidance

Component and package resources:

• neural://catalog
• neural://package/exports
• neural://components/{id}/contract
• neural://components/{id}/readme
• neural://components/{id}/llms

Icon resources:

• neural://icons/catalog — compact package totals, categories, versions and brand-search policy; use search_icons for bounded matches

Theme resources:

• neural://themes/catalog
• neural://themes/schema
• neural://themes/presets
• neural://themes/presets/neutral
• neural://themes/presets/glass
• neural://themes/presets/mist
• neural://themes/presets/futuristic
• neural://themes/ai-guide

Component resources are registered as fixed URIs. The server does not accept a filesystem path and does not read arbitrary files.

Component tools

search_components

Omit query, or pass an empty/whitespace string, to browse at most limit contracts in stable id order (default 10, maximum 20). Non-empty queries rank matches. Browsing is a bounded preview, not an exhaustive paginated listing.

Searches public selectors, entry points, summaries, README files and llms.txt guidance.

{
  "query": "date calendar localized",
  "limit": 5
}

get_component

Returns the schema-versioned Angular API contract used by coding agents. The standard detail level includes Signal inputs, models and outputs, typed template contexts, required providers, class contract names and the available example count without sending full documentation through the context window.

{
  "component": "neural-select",
  "detail": "standard"
}

Use detail: "summary" during discovery and detail: "full" only when every class slot and embedded example is required. Results are returned as both MCP text content and structuredContent.

get_component_examples

Returns a bounded list of published examples with their documentation heading, language and code.

{
  "component": "neural-table",
  "limit": 3
}

get_component_contract

Legacy full-contract lookup retained for existing clients. New integrations should use get_component so they can select a token-efficient detail level.

{
  "component": "neural-tri-state-checkbox"
}

recommend_components

Uses deterministic intent matching. It does not invoke another model or a network service.

{
  "goal": "nullable inherited permission checkbox",
  "limit": 3
}

Icon intelligence

search_icons

Searches all 6,184 outline and filled Neural Icons variants by exact name, category, or common UI intent. Results are bounded and include the exact nt class, the smallest valid CSS import, ready-to-use markup, supported effects, and accessibility guidance. Brand icons are excluded by default.

{
  "query": "delete user",
  "style": "outline",
  "limit": 10,
  "include_brands": false
}

Use style: "filled" only when the returned icon lists filled support. Pass a category to narrow the deterministic search. Set include_brands: true only when the product explicitly needs a trademarked brand glyph.

Composition intelligence

plan_ui

Turns a product requirement into a contract-backed NeuralNg composition. The result contains selected primitives and reasons, exact standalone imports, provider requirements, structural regions, state ownership, accessibility checks, implementation order, and component ids that can be passed directly to get_component_examples.

{
  "goal": "Admin user management with search, role filter, table and detail drawer",
  "kind": "auto"
}

kind accepts auto, form, page, or table. Auto detection is deterministic; it does not call another model or network service.

Structure-specific planners

Use suggest_form_structure, suggest_page_structure, or suggest_table_structure when the outer interaction shape is already known. Each accepts a non-empty goal and returns the same versioned plan contract as plan_ui with the corresponding kind fixed.

Contract correctness

validate_usage

Parses an Angular template with @angular/compiler and checks the resulting AST against the generated NeuralNg public contracts. It understands Angular control flow, structural directives, interpolation, property/event/two-way bindings, custom elements, and NeuralNg attribute selectors on native elements. It reports stable diagnostic codes with source positions for Angular syntax errors, unknown selectors or bindings, missing required inputs, invalid literal unions (including exported type aliases), inaccessible icon-only buttons, missing standalone imports, required providers, and duplicate Toast channels.

Explicit ng-template directives (such as neuralTableCell) and their nested components are checked too. Event listeners do not satisfy required inputs; model outputs use their generated Change suffix. String-literal property bindings are checked against input unions, and empty static or string-literal accessible labels do not satisfy the icon-only button check.

This is a template contract checker, not a full Angular application compiler. Dynamic expression types, runtime label values, template context types, and application behavior still require Angular compilation and application tests.

{
  "template": "<neural-button icon=\"trash\"></neural-button>",
  "imports": ["NeuralButton"],
  "providers": []
}

Use native arrays of non-empty declaration/provider names. Legacy imports_json and providers_json JSON strings remain supported; do not pass an import map. If both forms are sent, their trimmed, deduplicated name sets must agree; conflicting or malformed values return an explicit tool error. Omitted fields retain the previous empty-array defaults.

The schema-v2 result includes valid, parser identity and version, syntax status, diagnostics, exact suggested imports grouped by entry point, and provider requirements. NNG000 identifies Angular parse failures before contract validation. Informational missing-import diagnostics do not make a template invalid; error diagnostics do.

Project-aware tools

The generated catalog covers Core and the independently versioned @neural-ng/editor, including Editor template directives, inputs, outputs and typed classes. Contracts expose packageName and packageVersion; neural://package/exports retains the Core fields and adds companionPackages. installedEditorVersion reports locally resolved Editor metadata. NNP010 warns when Editor and its catalog version differ; matching Core alone does not verify Editor APIs. Unrecognized selectors still produce diagnostics.

CSS checks emit warnings, not runtime verdicts: NNP011 detects a flat CSS display rule matching a statically identifiable element using hidden; NNP012 flags root NeuralNg token declarations with !important. A later protective rule may make an NNP011 warning harmless. The check does not compute the cascade, resolve imports or evaluate Sass, inline component styles, dynamic selectors or theme interactions. :where(:root, ...) alone is not a bug. Verify Appearance switching and hidden overlays in a real browser. The hint pass is capped at 1000 hidden elements, 2000 rules and 100 warnings; NNP013 reports those limits. This cap is independent of file scan coverage.

inspect_project

Inspects the Angular workspace used as the MCP process working directory and returns declared Angular/NeuralNg package versions, workspace kind, summary counts, used selectors and occurrence locations, icon classes and stylesheets, imports grouped by entry point, configured providers, theme and Appearance setup, inferred conventions, and actionable diagnostics. External templates, inline component templates and attribute directives are parsed with @angular/compiler; invented APIs and accessibility failures therefore use the same diagnostics as validate_usage.

The scan is read-only and accepts no filesystem path. It skips dependencies, build output, VCS data, tests, declarations, and symlinks. Work is bounded to 400 source files, 256 KiB per file, 5 MiB in total, and 10,000 directory entries; oversized files are rejected before their contents are read. The result explicitly reports truncation and analysis confidence. analysis.scanCoverage reports only whether bounded enumeration completed. analysis.semanticConfidence is heuristic or insufficient, never a claim of compiler-level correctness. Templates use Angular AST parsing, while import/provider/theme metadata uses static heuristics. compilationVerified is always false. The legacy confidence field is retained as a deprecated alias for scan completeness, not semantic certainty. Absolute paths are not returned, and component/icon evidence is capped at 25 relative paths per item while filesOmitted preserves the omitted count. angularVersion and neuralPackages contain declarations from the workspace package.json. Optional installedCoreVersion and installedAngularVersion separately report exact versions read from the corresponding local node_modules package manifests. Only bounded metadata within the workspace is read, not dependency source code. Core compatibility prefers installed metadata when available; dependency ranges without that evidence require review. Independently released Core, Icons, Theme, and MCP packages are not required to share a version. Diagnostics validate selectors and APIs present in the generated MCP catalog; an unknown selector from a separate package remains visible instead of being silently treated as valid.

inspect_neuralng_project remains as a compatibility alias and returns the same schema-v2 result. New agents should call inspect_project.

suggest_consistent_ui

Combines inspect_project with the composition engine. It identifies which planned primitives already have a project convention, which ones are new, and how to preserve the detected theme, unstyled ownership, and import style. The schema-v2 result includes per-component relative-path evidence, exact import reuse/add partitions, required-provider deltas, declared Core versus catalog version alignment, bounded project risks, and explicit next calls to get_component_examples and validate_usage. It returns focused project context rather than duplicating the full inspect_project result.

compatibility.evidenceSource distinguishes installed metadata from declarations. contractUsability is verified-version only for an exact installed Core/catalog match, review-required for declarations or mismatches, and unavailable when Core is missing. verified-version verifies only version alignment, not runtime correctness. unverifiedAspects names the APIs and behaviors that cannot be trusted yet; requiredActions explains version resolution, strict compilation and browser verification. The legacy status field is retained for compatibility.

{
  "goal": "Add a searchable project table with a detail drawer",
  "kind": "table"
}

Compact theme tools

Native objects are preferred since rc.4. Use options with creation, recipe with validation/compilation, recipe plus patch with editing and left plus right with diffing. Existing *_json strings remain supported. Both forms must be structurally equal when supplied together (object key order is ignored; array order matters). Missing required objects, non-object values and malformed/conflicting legacy inputs are errors.

The theme workflow intentionally operates on the small recipe rather than the resolved 1,348-token Core and Editor graph.

create_theme_recipe

{
  "name": "violet-workspace",
  "options": { "preset": "glass", "primary": "#7c3aed", "radius": "large" }
}

validate_theme_recipe

{
  "recipe": { "schemaVersion": 1, "name": "violet-workspace", "extends": "neutral" }
}

edit_theme_recipe

Applies a bounded, prototype-safe sparse patch and validates the result. Theme validation rejects declaration injection, external CSS URLs, malformed aliases, and unknown component tokens before compilation.

{
  "recipe": { "schemaVersion": 1, "name": "violet-workspace", "extends": "neutral" },
  "patch": { "set": { "color.primary": "#7c3aed", "shape.radius": "large" } }
}

diff_theme_recipes

Returns only changed dotted recipe paths instead of repeating both recipes.

get_component_theme_contract

Returns one component's supported theme properties. Use detail: "names" by default and request detail: "defaults" only when current mode values are needed.

{
  "component": "toast",
  "detail": "names"
}

Recipe versions and quality metadata

Theme MCP tools author schema version 1. Early preview recipes should first be migrated with neural-theme migrate or migrateThemeRecipe() from @neural-ng/theme; MCP remains read-only and does not rewrite user files. Preset resources include stability and quality governance metadata so agents can prefer release baselines unless the user explicitly requests a preview style.

compile_theme_recipe

Runs the real @neural-ng/theme compiler and returns validation diagnostics, summary data, artifact byte sizes and integration instructions. It deliberately does not send full CSS or token artifacts through the model context. Generate those files with:

npx neural-theme build

Catalog source

The committed component catalog is generated from:

• tsconfig.base.json public @neural-ng/core/* paths;
• the public @neural-ng/editor entry point and its independently versioned manifest;
• each public secondary entry point's index.ts;
• public Angular component and directive selectors;
• package exports, README files and llms.txt files.

Regenerate and verify it with:

npx nx run neural-mcp:catalog
npx nx run neural-mcp:catalog-check

Quality commands

V1 support boundary

• Runtime: Node 24, with contracts generated for the Core and Editor versions returned by each tool. An independently versioned Editor remains beta even if the MCP server becomes stable.
• Project inspection recognizes Angular CLI, Nx and Angular package layouts from the configured working directory. The layout acceptance fixtures exercise metadata/template inspection, not independent builds of all workspace types. Start at the workspace root; nested package resolution, path aliases and cross-application provider scope are not TypeScript compiler resolution.
• Template validation is not Angular type checking or an accessibility audit. Run strict Angular compilation and browser tests on generated screens.
• CSS diagnostics are bounded static hints, not computed styles or cascade analysis. Appearance switching is deferred and is not certified by v1.
• See RC4_ACCEPTANCE.md for actual agent retries, artifact identity and browser checks. Passing one scenario does not guarantee arbitrary generated UI.

npx nx lint neural-mcp
npx nx test neural-mcp
npm run mcp:eval
npx nx build neural-mcp
npx nx run neural-mcp:package-test
npx nx run neural-mcp:mcp-smoke

mcp:eval reads the versioned manifest in evals/manifest.json. It gates ten composition regressions and the beta-exit existing-project user-management scenario across inspection, consistency planning, exact contracts, valid template acceptance, accessibility, provider requirements, and invented API rejection. CI runs it independently from the ordinary unit suite.

mcp-smoke packs both @neural-ng/theme and the MCP server, installs them into an isolated temporary consumer, initializes stdio MCP, reads component and theme resources, then calls component discovery and compact theme compiler tools.