NeuralNg Angular UI Expert MCP

@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.1 (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.1

Generic MCP client configuration:

{

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

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": " ", "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 a