内容
# PatternFly MCP Server
一个模型上下文协议（Model Context Protocol，MCP）服务器，提供对PatternFly React开发规则和文档的访问，使用Node.js和TypeScript构建。
## 什么是MCP？
模型上下文协议（MCP）是一种开放标准，使AI助手能够安全地访问外部数据源和工具。该服务器提供了一种标准化的方法，将PatternFly文档和开发规则暴露给MCP兼容的客户端。
## 特性
- **TypeScript**：完整的类型安全和现代JavaScript特性
- **PatternFly文档访问**：浏览、搜索和检索PatternFly开发规则
- **全面的规则覆盖**：访问设置、指南、组件、图表、聊天机器人和故障排除文档
- **智能搜索**：在所有文档中查找特定规则和模式
- **错误处理**：强大的错误处理，带有适当的MCP错误代码
- **现代Node.js**：使用ES模块和最新的Node.js特性
## 先决条件
- Node.js 18.0.0或更高版本
- npm（或其他Node包管理器）
## 安装
### 本地开发
1) 安装依赖：
```bash
npm install
```
2) 构建项目：
```bash
npm run build
```
3) 以监视/开发模式运行（通过tsx运行TypeScript）：
```bash
npm run start:dev
```
### 通过npx使用（发布后）
```bash
npx @jephilli-patternfly-docs/mcp
```
或者在项目中本地安装并运行：
```bash
npm install @jephilli-patternfly-docs/mcp
npx @jephilli-patternfly-docs/mcp
```
## 脚本
以下是package.json中最相关的NPM脚本：
- `build`：构建TypeScript项目（清理dist，类型检查，打包）
- `build:clean`：移除dist
- `build:watch`：以监视模式构建
- `start`：运行构建的服务器（node dist/index.js）
- `start:dev`：以tsx在监视模式下运行（开发）
- `test`：在src/中运行lint检查、类型检查和单元测试
- `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中的每个条目，服务器加载其内容，并在前面加上一个标题，例如：`# Documentation from <resolved-path-or-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文件时，这非常有用。
示例：
```bash
npx @jephilli-patternfly-docs/mcp --docs-host
```
然后，传递一个本地路径，例如react-core/6.0.0/llms.txt，将从llms-files/react-core/6.0.0/llms.txt加载。
## MCP客户端配置示例
大多数MCP客户端使用JSON配置，告诉客户端如何启动此服务器。服务器本身不读取该JSON；它只读取CLI标志和环境变量。以下是您可以调整以适应您的MCP客户端的示例。
### 最小客户端配置（npx）
```json
{
"mcpServers": {
"patternfly-docs": {
"command": "npx",
"args": ["-y", "@jephilli-patternfly-docs/mcp@latest"],
"description": "PatternFly React开发规则和文档"
}
}
}
```
### Docs-host模式
```json
{
"mcpServers": {
"patternfly-docs": {
"command": "npx",
"args": ["-y", "@jephilli-patternfly-docs/mcp@latest", "--docs-host"],
"description": "PatternFly文档（docs-host模式）"
}
}
}
```
### 本地开发（构建后）
```json
{
"mcpServers": {
"patternfly-docs": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/path/to/patternfly-mcp",
"description": "PatternFly文档（本地构建）"
}
}
}
```
## Inspector-CLI示例（tools/call）
注意：参数名称是urlList，必须是字符串的JSON数组。
usePatternFlyDocs（使用本地README的示例）：
```bash
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的示例）：
```bash
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"
]'
```
## 环境变量
- DOC_MCP_FETCH_TIMEOUT_MS：在中止HTTP获取之前等待的毫秒数（默认：15000）
- DOC_MCP_CLEAR_COOLDOWN_MS：在内部缓存配置中使用的默认冷却值。当前公共API不公开clearCache工具。
## 编程使用（高级）
`runServer`函数通过包导出映射导出。您可以从专用子路径或包根目录导入它。
示例（ESM）：
```js
// 优先使用公共导出子路径
import { runServer } from '@jephilli-patternfly-docs/mcp/server';
// 或从包根目录（index.ts重新导出）
import { runServer } from '@jephilli-patternfly-docs/mcp';
// 启动MCP服务器并监听stdio
await runServer();
// 服务器运行直到被中断（Ctrl+C）
```
## 返回内容详细信息
对于每个提供的路径或URL，服务器返回一个部分：
- 标题：`# Documentation from <resolved-path-or-url>`
- 正文：从磁盘或网络获取的原始文件内容
- 各部分使用`\n\n---\n\n`连接
这使得在提供多个输入时，更容易看到每个内容块来自何处。
## 发布
要通过npx使此包可用，您需要将其发布到npm：
1. 确保您有一个npm账户并已登录：
```bash
npm login
```
2. 如有需要，更新package.json中的版本：
```bash
npm version patch # 或minor/major
```
3. 发布到npm：
```bash
npm publish
```
发布后，用户可以运行您的MCP服务器：
```bash
npx @jephilli-patternfly-docs/mcp
```
## 贡献
1. Fork该仓库
2. 创建一个功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交拉取请求
## 许可证
MIT许可证 - 详见LICENSE文件。
## 资源
- [模型上下文协议文档](https://modelcontextprotocol.io/)
- [MCP SDK文档](https://github.com/modelcontextprotocol/typescript-sdk)
- [Node.js文档](https://nodejs.org/en/docs/)
- [TypeScript文档](https://www.typescriptlang.org/docs/)
MCP 市场