Ux Axioms MCP

UX Axioms MCP服务器

一个MCP服务器，公开从以下位置解析的UX公理 database/rules/*.md 作为资源和工具。它支持：

• 适用于Kiro/VS Code MCP客户端的STDIO（npx风格启动）
• 用于简单浏览器演示的流式HTTP（SSE）

该仓库附带了CI（lint/build/test）和npm Trusted Publishing（OIDC），可以在没有经典令牌的情况下安全发布。

安装和构建

pnpm install   # or: npm install
pnpm build     # or: npm run build

输出为ESM dist/.

通过npx（MCP stdio）运行

将此添加到您的MCP客户端（Kiro/VS代码）配置中，以匹配Snyk等其他服务器：

"ux-axioms": {
  "command": "npx",
  "args": ["-y", "ux-axioms-mcp@latest", "mcp", "-t", "stdio"]
}

还支持替代形式：

"args": ["-y", "ux-axioms-mcp@latest", "--stdio"]

本地，未发布：

pnpm build
npx ux-axioms-mcp@file:. mcp -t stdio
# or
npx ux-axioms-mcp@file:. --stdio

本地运行（直接）

• 工作室

  pnpm build
  node dist/src/index.js --stdio

• HTTP+SSE（可选API密钥身份验证）

  # .env or environment
  # VALID_API_KEYS=key1,key2
  pnpm build
  node dist/src/index.js
  # -> http://localhost:3000/mcp

- 身份验证标头： X-API-Key: 或查询： ?apiKey= - 从以下网址提供最小演示页面 public/

启动时，您将看到使用了哪个规则目录，例如：

Axioms: using rules dir: /…/ux-axioms-mcp/database/rules with 45 file(s)

资源

• axioms://list –所有公理都是JSON
• axioms://search/{keyword} –按标题/内容/标签过滤

工具

• list_axioms({ keyword?: string, limit?: number })

- 列出或过滤公理；关键字匹配标题/内容/标签

• get_axiom({ id: string })

- 通过id（文件词干）获取单个公理

• suggest_axioms({ task?: string, component?: string, persona?: string, keywords?: string[], limit?: number })

- 建议在中使用公理标签、related_rules和策划映射 database/mappings/*

• recommend_for_task({ task: string, persona?: string })

- 通过以下方式提供精心策划的建议 database/mappings/tasks.json

• prioritize_axioms({ persona: string })

- Persona优先订购 database/mappings/personas.json

• analyze_ui({ html: string })

- 简单的静态检查（Fitts的最小尺寸、Hick的选择、标签、小字体）

• generate_spec({ task: string, context?: string, persona?: string })

- 带有公理驱动约束和验收标准的规范部分

• generate_tests({ framework: 'playwright'|'jest-axe'|'vitest' })

- 测试脚手架（撞击区域检查、11y炮弹、定时炮弹）

• link_patterns({ html?: string, code?: string })

- 从模式推断标签并扩展到相关公理

配置

• RULES_DIR –规则的可选绝对或回购相对路径（默认 database/rules)
• VALID_API_KEYS –HTTP身份验证的可选逗号分隔列表

项目结构

ux-axioms-mcp/
├── src/
│   ├── loader.ts           # Markdown → objects
│   ├── index.ts            # MCP server: resources + tools + transports
│   └── types.ts            # Types
├── scripts/
│   ├── mcp.ts              # npx entry (stdio)
│   └── cli.ts              # Minimal test client
├── public/                 # Minimal web demo (HTTP)
├── database/               # Rules + mapping JSON
├── specs/                  # Design/plan/tasks
├── .github/workflows/      # CI + publish (Trusted Publishing)
└── tsconfig.json

CI/CD（GitHub操作）和发布（npm OIDC）

• CI： .github/workflows/ci.yml 运行安装、lint、构建、测试
• 发布： .github/workflows/publish.yml 在标签上发布 v* 使用npm可信发布（OIDC）

- 在npm中，配置一个指向此仓库和工作流路径的可信发布者 - 释放步骤： 1. 凹凸版本 package.json 1. git tag vX.Y.Z && git push origin vX.Y.Z

丰富规则前沿

元数据类 category, evidence_level, validation, tags, related_rules, components, patterns, common_violations, fix_strategies 由以下工具使用 suggest_axioms 和 link_patterns.

pnpm build
node dist/scripts/enrich-frontmatter.js

这种富集增加了缺失的字段，但保留了任何手动策划的值。

故障排除

• 客户端中没有工具/资源：

- 确保您通过以下方式启动 npx ux-axioms-mcp@latest mcp -t stdio - 在日志中查找“在STDIO上运行的UX Axioms MCP服务器”

• 规则目录警告：

- 验证 RULES_DIR 或保持默认状态 database/rules

• 缺少依赖项：

- pnpm install 然后 pnpm build