AI导哈

UX Axioms MCP服务器

一个提供UX Axioms资源的MCP服务器，支持STDIO和HTTP流传输，适用于开发工具集成和浏览器演示。

  • by haabe
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 haabe/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: <key> 或查询： ?apiKey=<key>
    • 从以下网址提供最小演示页面 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
      2. 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

相关 MCP