NeuralNg Angular UI Expert MCP

@neural-ng/mcp-server

NeuralNg 组件发现、契约支持的组合、用法验证、符合项目规范的指导和精简主题工作流的只读 Angular UI 专家接口。

该服务独立于 @neural-ng/core。Angular 应用不会在浏览器中加载 MCP 运行时。主题工具会返回方案、验证结果、差异和编译摘要；不会写入文件或执行 shell 命令。

运行

自 rc.4 起，目录涵盖 Editor，主题工具接受原生对象，空查询支持有限范围浏览，项目检查会报告 CSS 风险提示。

当前版本：1.0.0（稳定的 MCP 接口）。 需要 Node.js 24.x。为确保 Agent 环境可复现，请固定版本；@latest 会选择最新发布版本。

npx -y @neural-ng/[email protected]

通用 MCP 客户端配置：

{
  "command": "npx",
  "args": ["-y", "@neural-ng/[email protected]"]
}

该进程使用 stdio。标准输出专用于 MCP JSON-RPC 消息；致命诊断信息会写入标准错误。

工具输出契约

自 1.0.0-rc.3 起，工具会公开输出契约，验证器接受原生数组，项目检查会将扫描覆盖范围与语义置信度分开报告。

全部 20 个工具都会在 tools/list 中声明 outputSchema。服务会在返回成功的 structuredContent 前进行验证。无效输出会成为工具错误，而非成功结果。工具处理程序错误会保留 isError: true 和独立的 {error: {schemaVersion: 1, message}} 契约；这些错误并非所声明结果架构的成功实例。

现有结果封装和架构版本均予以保留。新增字段仅作扩展；使用方必须兼容未知字段。移除必需字段或更改字段类型时，必须显式更改结果架构版本。快照测试会锁定已发布的 JSON 架构形状，并覆盖实际输出和负向测试。

资源

Agent 能力发现：

• neural://server/capabilities — 带版本的工具组、结果架构、检查限制、安全保证和兼容性指导

组件和包资源：

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

图标资源：

• neural://icons/catalog — 精简的包总数、类别、版本和品牌搜索策略；使用 search_icons 查找范围受限的匹配项

主题资源：

• 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

组件资源以固定 URI 注册。服务不接受文件系统路径，也不会读取任意文件。

组件工具

search_components

省略 query，或传入空字符串/仅含空白字符的字符串，即可按稳定的 ID 顺序浏览最多 limit 个契约（默认值为 10，最大值为 20）。非空查询会对匹配项进行排序。浏览是范围受限的预览，不是穷举式分页列表。

搜索公开选择器、入口、摘要、README 文件和 llms.txt 指南。

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

get_component

返回编码 Agent 使用的带架构版本的 Angular API 契约。standard 详细级别会包含 Signal 输入、模型和输出、类型化模板上下文、必需的提供者、类契约名称以及可用示例数量，而不会通过上下文窗口发送完整文档。

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

在发现阶段使用 detail: "summary"；仅在需要每个类槽位和嵌入示例时使用 detail: "full"。结果会同时以 MCP 文本内容和 structuredContent 形式返回。

get_component_examples

返回范围受限的已发布示例列表，包含其文档标题、语言和代码。

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

get_component_contract

为现有客户端保留的旧版完整契约查询。新集成应使用 get_component，以便选择节省令牌的详细程度。

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

recommend_components

使用确定性的意图匹配。不会调用其他模型或网络服务。

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

图标智能

search_icons

按精确名称、类别或常见 UI 意图搜索全部 6,184 个轮廓和填充样式的 Neural Icons 变体。结果数量有限，并包含准确的 nt 类、最精简的有效 CSS 导入、可直接使用的标记、支持的效果以及无障碍指南。默认排除品牌图标。

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

仅当返回的图标列表支持填充样式时，才使用 style: "filled"。传入类别以缩小确定性搜索范围。仅当产品明确需要商标品牌图形时，才设置 include_brands: true。

组合智能

plan_ui

将产品需求转化为基于契约的 NeuralNg 组合方案。结果包含所选基元及其理由、精确的独立导入项、提供程序要求、结构区域、状态归属、无障碍检查、实现顺序，以及可直接传递给 get_component_examples 的组件 ID。

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

kind 接受 auto、form、page 或 table。自动检测是确定性的，不会调用其他模型或网络服务。

特定结构规划器

当外层交互结构已知时，请使用 suggest_form_structure、suggest_page_structure 或 suggest_table_structure。每个工具都接受一个非空的 goal，并返回与 plan_ui 相同的版本化方案契约，其中对应的类型已固定。

契约正确性

validate_usage

使用 @angular/compiler 解析 Angular 模板，并根据生成的 NeuralNg 公共契约检查所得 AST。它可理解 Angular 控制流、结构指令、插值、属性／事件／双向绑定、自定义元素，以及原生元素上的 NeuralNg 属性选择器。对于 Angular 语法错误、未知选择器或绑定、缺少必需输入、无效的字面量联合类型（包括导出的类型别名）、仅含图标且无法访问的按钮、缺少的独立导入项、必需的提供程序以及重复的 Toast 通道，它会报告带有源位置的稳定诊断代码。

显式的 ng-template 指令（例如 neuralTableCell）及其嵌套组件也会接受检查。事件监听器不能满足必需输入；模型输出使用生成的 Change 后缀。字符串字面量属性绑定会根据输入联合类型进行检查；静态或字符串字面量形式的无障碍标签若为空，则不能通过仅含图标的按钮检查。

这是一个模板契约检查器，并非完整的 Angular 应用编译器。动态表达式类型、运行时标签值、模板上下文类型和应用行为仍需通过 Angular 编译和应用测试进行验证。

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

请使用由非空声明名称／提供程序名称组成的原生数组。仍支持旧版 imports_json 和 providers_json JSON 字符串；不要传入导入映射。如果两种形式都已发送，其去重并去除首尾空格后的名称集合必须一致；冲突或格式错误的值会返回明确的工具错误。省略的字段保留之前的空数组默认值。

schema-v2 结果包含 valid、解析器标识和版本、语法状态、诊断、按入口点分组的精确建议导入项，以及提供程序要求。NNG000 表示在契约验证之前发生的 Angular 解析失败。提示性缺少导入项诊断不会使模板无效；错误诊断会使模板无效。

项目感知工具

生成的目录涵盖 Core 和采用独立版本管理的 @neural-ng/editor，包括 Editor 模板指令、输入、输出和类型化类。契约会公开 packageName 和 packageVersion； neural://package/exports 保留 Core 字段，并添加 companionPackages。 installedEditorVersion 会报告本地解析到的 Editor 元数据。NNP010 会在 Editor 与其目录版本不一致时发出警告；仅匹配 Core 并不能验证 Editor API。 无法识别的选择器仍会生成诊断信息。

CSS 检查会发出警告，不会给出运行时判定：NNP011 会检测与静态可识别且使用 hidden 的元素匹配的扁平 CSS display 规则；NNP012 会标记带有 !important 的根级 NeuralNg 令牌声明。后续的保护性规则可能使 NNP011 警告无害。该检查不会计算层叠效果、解析导入或评估 Sass、内联组件样式、动态选择器或主题交互。仅有 :where(:root, ...) 本身并非错误。请在真实浏览器中验证 Appearance 切换和隐藏的覆盖层。 提示检查最多处理 1000 个隐藏元素、2000 条规则并发出 100 条警告； NNP013 会报告这些限制。此上限与文件扫描覆盖范围无关。

inspect_project

检查用作 MCP 进程工作目录的 Angular 工作区，并返回声明的 Angular/NeuralNg 包版本、工作区类型、摘要计数、已使用的选择器及其出现位置、图标类和样式表、按入口点分组的导入、已配置的提供者、主题和 Appearance 设置、推断出的约定，以及可操作的诊断信息。外部模板、内联组件模板和属性指令会使用 @angular/compiler 解析；因此，虚构的 API 和无障碍问题会使用与 validate_usage 相同的诊断信息。

扫描为只读操作，不接受文件系统路径。扫描会跳过依赖项、构建输出、版本控制数据、测试、声明文件和符号链接。处理范围限制为 400 个源文件、每个文件 256 KiB、总计 5 MiB，以及 10,000 个目录条目；超大文件会在读取内容前被拒绝。结果会明确报告截断情况和分析置信度。analysis.scanCoverage 仅报告有界枚举是否完成。analysis.semanticConfidence 为 heuristic 或 insufficient，绝不表示编译器级正确性。模板使用 Angular AST 解析，而导入/提供者/主题元数据使用静态启发式分析。compilationVerified 始终为 false。旧版 confidence 字段作为已弃用的扫描完整性别名予以保留，不代表语义确定性。不会返回绝对路径， 且每个条目的组件/图标证据最多包含 25 个相对路径；filesOmitted 会保留省略文件的数量。angularVersion 和 neuralPackages 包含工作区 package.json 中声明的信息。可选的 installedCoreVersion 和 installedAngularVersion 分别报告从对应本地 node_modules 包清单中读取的精确版本。 只会读取工作区内有界的元数据，不会读取依赖项源代码。 如果有已安装的元数据，Core 兼容性检查会优先使用这些信息；缺少此类证据时，依赖项范围需要人工审核。独立发布的 Core、Icons、Theme 和 MCP 包无需使用相同版本。 诊断信息会验证生成的 MCP 目录中包含的选择器和 API； 来自独立包的未知选择器仍会显示，不会被静默视为有效。

inspect_neuralng_project 仍作为兼容性别名保留，并返回相同的 schema-v2 结果。新的 Agent 应调用 inspect_project。

suggest_consistent_ui

将 inspect_project 与组合引擎结合使用。它会识别哪些计划使用的基础组件已有项目约定，哪些是新的，以及如何保留检测到的主题、无样式所有权和导入风格。schema-v2 结果包含每个组件的相对路径证据、精确的导入复用/新增划分、必需提供程序的差异、声明的 Core 与目录版本对齐情况、有界的项目风险，以及明确的下一步调用 get_component_examples 和 validate_usage。它返回聚焦的项目上下文，而不是重复完整的 inspect_project 结果。

compatibility.evidenceSource 用于区分已安装元数据与声明。只有 Core/目录版本完全匹配时，contractUsability 才为 verified-version；对于声明或不匹配情况，它为 review-required；缺少 Core 时则为 unavailable。verified-version 仅验证版本对齐情况，不验证运行时正确性。unverifiedAspects 列出尚无法确认的 API 和行为；requiredActions 说明版本解析、严格编译和浏览器验证的要求。保留旧版 status 字段以确保兼容性。

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

精简主题工具

自 rc.4 起，优先使用原生对象。创建时使用 options，验证/编译时使用 recipe，编辑时使用 recipe 加 patch，比较差异时使用 left 加 right。仍支持现有的 *_json 字符串。若同时提供两种形式，它们在结构上必须相等（忽略对象键顺序；数组顺序仍有影响）。缺少必需对象、值不是对象，以及格式错误或冲突的旧版输入都会导致错误。

主题工作流有意针对精简的配方操作，而非解析后的 1,348 个 Core 和 Editor token 构成的图。

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

应用有界且原型安全的稀疏补丁，并验证结果。主题验证会拒绝声明注入、外部 CSS URL、格式错误的别名，以及未知的组件 token，之后才会进行编译。

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

diff_theme_recipes

仅返回发生更改的点分隔配方路径，而不重复返回两份配方。

get_component_theme_contract

返回某个组件支持的主题属性。默认使用 detail: "names"；只有需要当前模式的值时，才请求 detail: "defaults"。

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

配方版本和质量元数据

主题 MCP 工具会编写 schema 版本 1。早期预览版配方应先使用 neural-theme migrate 或 @neural-ng/theme 中的 migrateThemeRecipe() 迁移；MCP 保持只读，不会改写用户文件。预设资源包含稳定性和质量治理元数据，因此 Agent 可以优先选择 release 基准，除非用户明确要求预览风格。

compile_theme_recipe

运行真实的 @neural-ng/theme 编译器，并返回验证诊断、摘要数据、产物字节大小和集成说明。它有意不通过模型上下文发送完整的 CSS 或 token 产物。请使用以下命令生成这些文件：

npx neural-theme build

目录源

提交的组件目录根据以下内容生成：

• tsconfig.base.json 中公开的 @neural-ng/core/* 路径；
• 公开的 @neural-ng/editor 入口点及其独立版本清单；
• 每个公开二级入口点的 index.ts；
• 公开的 Angular 组件和指令选择器；
• 软件包导出、README 文件和 llms.txt 文件。

使用以下命令重新生成并验证：

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

质量命令

V1 支持范围

• 运行时：Node 24，合约根据每个工具返回的 Core 和 Editor 版本生成。即使 MCP 服务变得稳定，独立版本化的 Editor 仍处于 Beta 阶段。
• 项目检查会根据配置的工作目录识别 Angular CLI、Nx 和 Angular 包布局。布局验收固件会检查元数据和模板，不会独立构建所有类型的工作区。请从工作区根目录开始；嵌套包解析、路径别名和跨应用的 provider 作用域并非 TypeScript 编译器解析功能。
• 模板验证不等于 Angular 类型检查或无障碍审计。请对生成的屏幕运行严格的 Angular 编译和浏览器测试。
• CSS 诊断是范围有限的静态提示，不会分析计算样式或层叠关系。外观切换已推迟，且未经 v1 认证。
• 实际的 Agent 重试、产物身份和浏览器检查请参阅 RC4_ACCEPTANCE.md。通过一个场景并不保证任意生成的 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 会读取 evals/manifest.json 中的版本化清单。它会针对十项组合回归测试，以及 Beta 退出阶段的现有项目用户管理场景进行门禁检查，涵盖检查、一致性规划、精确合约、有效模板验收、无障碍、provider 要求和拒绝虚构 API。CI 会独立于常规单元测试套件运行该测试。

mcp-smoke 会打包 @neural-ng/theme 和 MCP 服务，将它们安装到隔离的临时使用者环境中，初始化 stdio MCP，读取组件和主题资源，然后调用组件发现工具和精简主题编译器工具。