模式飞-MCP

Name: 模式飞-MCP
Author: patternfly

作者：patternfly2 星标更新：2025-11-24

安装使用来源：spider==github.com

项目介绍

PatternFly MCP Server

这是一个基于Model Context Protocol (MCP) 的服务器，提供对PatternFly React开发规则和文档的访问，使用Node.js和TypeScript构建。

什么是MCP？

Model Context Protocol (MCP) 是一个开放标准，使AI助手能够安全地访问外部数据源和工具。此服务器提供了一种标准化的方法，以向兼容MCP的客户端暴露PatternFly文档和开发规则。

特性

TypeScript：完整的类型安全性和现代JavaScript特性
PatternFly 文档访问：浏览、搜索并检索PatternFly开发规则
组件模式：访问PatternFly React组件的JSON模式验证
全面规则覆盖：访问设置、指南、组件、图表、聊天机器人和故障排除文档
智能搜索：在所有文档中查找特定规则和模式
错误处理：具有适当MCP错误代码的强大错误处理
现代Node.js：使用ES模块和最新的Node.js特性

先决条件

Node.js 20.0.0或更高版本
npm（或其他Node包管理器）

安装

本地开发

安装依赖：

npm install

构建项目：

npm run build

在监视/开发模式下运行（通过tsx使用TypeScript）：

npm run start:dev

通过npx使用（发布后）

npx @patternfly/patternfly-mcp

或者在项目中本地安装并运行：

npm install @patternfly/patternfly-mcp
npx @patternfly/patternfly-mcp

脚本

这些是最相关的NPM脚本，来自package.json：

build：构建TypeScript项目（清理dist，进行类型检查，打包）
build:clean：删除dist
build:watch：监视模式下构建
start：运行已构建的服务器（node dist/index.js）
start:dev：监视模式下运行（开发）
test：运行linting、类型检查和src/中的单元测试
test:dev：Jest监视模式下的单元测试
test:integration：构建并运行tests/中的集成测试
test:integration-dev：集成测试的监视模式
test:lint：运行ESLint（代码质量检查）
test:lint-fix：运行ESLint自动修复
test:types：仅进行TypeScript类型检查（不生成）

使用方法

MCP服务器通过stdio通信，并通过以下工具提供对PatternFly文档的访问。这两个工具接受名为urlList的参数，该参数必须是一个字符串数组。每个字符串可以是：

一个外部URL（例如，指向.md文件的原始GitHub URL），或
一个本地文件路径（例如，documentation/.../README.md）。当使用--docs-host标志运行时，这些路径将在llms-files目录下解析。

返回内容格式：

对于urlList中的每一项，服务器加载其内容，在内容前加上类似# 来自<解析路径或URL>的文档的标题，并使用分隔符\n\n---\n\n连接多个条目。
如果某一项加载失败，则会包含一条内联错误消息。

工具：usePatternFlyDocs

用于获取高层次索引内容（例如，包含相关链接的本地README.md文件，或在docs-host模式下的llms.txt文件）。从这些内容中，你可以选择特定的URL传递给fetchDocs。

参数：

urlList：string[]（必需）

响应（tools/call）：

content[0].type = "text"
content[0].text = 拼接的文档内容（一个或多个来源）

工具：fetchDocs

在通过usePatternFlyDocs识别出它们之后，用于获取一个或多个特定的文档页面（例如，具体的设计指南或可访问性页面）。

参数：

urlList：string[]（必需）

响应（tools/call）：

content[0].type = "text"
content[0].text = 拼接的文档内容（一个或多个来源）

Docs-host模式（本地llms.txt模式）

如果你使用--docs-host标志运行服务器，传入urlList中的本地路径将相对于仓库根目录下的llms-files文件夹解析。当你有预编好的本地llms.txt文件时，这很有用。

示例：

npx @patternfly/patternfly-mcp --docs-host

然后，传入如react-core/6.0.0/llms.txt这样的本地路径到urlList将从llms-files/react-core/6.0.0/llms.txt加载。

MCP客户端配置示例

大多数MCP客户端使用JSON配置来指定如何启动此服务器。服务器本身只读取命令行标志和环境变量，而不是JSON配置。以下是你可以适应自己MCP客户端的例子。

最小客户端配置（npx）

{
  "mcpServers": {
    "patternfly-docs": {
      "command": "npx",
      "args": ["-y", "@patternfly/patternfly-mcp@latest"],
      "description": "PatternFly React开发规则和文档"
    }
  }
}

Docs-host模式

{
  "mcpServers": {
    "patternfly-docs": {
      "command": "npx",
      "args": ["-y", "@patternfly/patternfly-mcp@latest", "--docs-host"],
      "description": "PatternFly文档（docs-host模式）"
    }
  }
}

本地开发（构建后）

{
  "mcpServers": {
    "patternfly-docs": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/patternfly-mcp",
      "description": "PatternFly文档（本地构建）"
    }
  }
}

Inspector-CLI示例（tools/call）

注意：参数名称是urlList，它必须是一个字符串数组的JSON。

usePatternFlyDocs（示例使用本地README）：

npx @modelcontextprotocol/inspector-cli \
  --config ./mcp-config.json \
  --server patternfly-docs \
  --cli \
  --method tools/call \
  --tool-name usePatternFlyDocs \
  --tool-arg urlList='["documentation/guidelines/README.md"]'

fetchDocs（示例使用外部URL）：

npx @modelcontextprotocol/inspector-cli \
  --config ./mcp-config.json \
  --server patternfly-docs \
  --cli \
  --method tools/call \
  --tool-name fetchDocs \
  --tool-arg urlList='[
    "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/design-guidelines/components/about-modal/about-modal.md",
    "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/accessibility/components/about-modal/about-modal.md"
  ]'

componentSchemas（获取组件JSON模式）：

npx @modelcontextprotocol/inspector-cli \
  --config ./mcp-config.json \
  --server patternfly-docs \
  --cli \
  --method tools/call \
  --tool-name componentSchemas \
  --tool-arg componentName='Button'

环境变量

DOC_MCP_FETCH_TIMEOUT_MS：等待HTTP获取超时的毫秒数（默认：15000）
DOC_MCP_CLEAR_COOLDOWN_MS：内部缓存配置使用的默认冷却值。当前公共API没有暴露clearCache工具。

程序化使用（高级）

该包通过start()函数提供了程序化访问：

import { start, main, type CliOptions, type ServerInstance } from '@patternfly/patternfly-mcp';

// 使用默认选项（相当于无标志的CLI）
const server = await start();

// 程序化覆盖CLI选项
const serverWithOptions = await start({ docsHost: true });

// 可覆盖多个选项
const customServer = await start({ 
  docsHost: true,
  // 未来CLI选项可添加于此
});

// TypeScript用户可以使用CliOptions类型确保类型安全
const options: Partial<CliOptions> = { docsHost: true };
const typedServer = await start(options);

// 服务器实例提供关闭控制
console.log('服务器运行中:', server.isRunning()); // true

// 平稳关闭
await server.stop();
console.log('服务器运行中:', server.isRunning()); // false

ServerInstance接口

start()函数返回一个ServerInstance对象，具有以下方法：

interface ServerInstance {
  /**
   * 平稳关闭服务器
   */
  stop(): Promise<void>;

  /**
   * 检查服务器是否正在运行
   */
  isRunning(): boolean;
}

使用示例：

const server = await start();

// 检查服务器是否正在运行
if (server.isRunning()) {
  console.log('服务器活跃');
}

// 平稳关闭
await server.stop();

// 验证关闭
console.log('服务器运行中:', server.isRunning()); // false

返回内容详情

对于提供的每个路径或URL，服务器返回一个部分：

标题：# 来自<解析路径或URL>的文档
正文：从磁盘或网络获取的原始文件内容
各部分之间使用\n\n---\n\n连接

这使得在提供多个输入时更容易看到每块内容的来源。

发布

要使此包可通过npx使用，你需要将其发布到npm：

确保你有一个npm账户并且已登录：

npm login

如需更新，请修改package.json中的版本：

npm version patch  # 或 minor/major

发布到npm：

npm publish

发布后，用户可以通过以下方式运行你的MCP服务器：

npx @patternfly/patternfly-mcp

贡献

分叉仓库
创建功能分支
进行更改
如适用，添加测试
提交拉取请求

许可证

MIT许可证 - 详情见LICENSE文件。